Merge branch 'master' of github.com:clearlinux/clear-linux-documentation into rtd-theme

Signed-off-by: Kevin Putnam <kevin.putnam@intel.com>
This commit is contained in:
Kevin Putnam
2019-07-08 12:25:57 -07:00
8 changed files with 201 additions and 136 deletions
+2 -2
View File
@@ -1,7 +1,7 @@
.. _faq:
Frequently Asked Questions (FAQ)
################################
FAQ
###
Below is a list of commonly asked questions with answers sourced from the
|CL-ATTR| team and `Clear Linux community forums`_.
@@ -70,8 +70,8 @@ Confirm network connection
==========================
Confirm there is a network connection before launching the installer.
Choose a method: `Wired Connection`, or `WiFi Connected`.
This guide shows an example of a **Wired Connection**.
Choose a method: `Wired Connection`, or `WiFi Connected`. This guide shows
an example of a **Wired Connection**.
#. In the upper right of the top menu bar, select the square icon to view
Network settings, shown in Figure 2.
@@ -243,6 +243,16 @@ Use this method to safely install |CL| on media with available space, or
alongside existing partitions, and accept the `Default partition schema`_.
If enough free space exists, safe installation is allowed.
.. note::
|CL| allows installation alongside another OS. Typically, when you boot
your system, you can press an `F key` to view and select a bootable
device or partition during the BIOS POST stage. Some BIOSes present the
|CL| partition, and you can select and boot it. However, other
BIOSes may only show the primary partition, in which case you will not be
able boot |CL|. Be aware of this possible limitation.
Destructive Installation
------------------------
@@ -3,7 +3,7 @@
Run |CL-ATTR| as a KVM guest OS
###############################
This section explains how to run |CL-ATTR| in a virtualized environment using
This guide explains how to run |CL-ATTR| in a virtualized environment using
:abbr:`KVM (Kernel-based Virtual Machine)`.
Install QEMU-KVM
@@ -13,12 +13,7 @@ Install QEMU-KVM
`Intel®Virtualization Technology for Directed I/O`_ (Intel® VT-d) in the
host machine’s BIOS.
#. Log in, open a terminal emulator, and get root privilege on the host
machine:
.. code-block:: bash
sudo -s
#. Log in and open a terminal emulator.
#. Install `QEMU*-KVM` on the host machine. Below are some example distros.
@@ -26,31 +21,25 @@ Install QEMU-KVM
.. code-block:: bash
swupd bundle-add kvm-host
sudo swupd bundle-add kvm-host
* |CL| option: Add this bundle to lanch the GUI upon boot.
* On Ubuntu\* 18.04 LTS Desktop:
.. code-block:: bash
swupd bundle-add desktop-autostart
sudo apt-get install qemu-kvm
* On Ubuntu\* 16.04 LTS Desktop:
* On Mint\* 19.1 “Cinnamon” Desktop:
.. code-block:: bash
apt-get install qemu-kvm
sudo apt-get install qemu-kvm
* On Mint\* 18.1 “Serena” Desktop:
* On Fedora\* 30 Workstation:
.. code-block:: bash
apt-get install qemu-kvm
* On Fedora\* 25 Workstation:
.. code-block:: bash
dnf install qemu-kvm
sudo dnf install qemu-kvm
Download and launch the virtual machine
***************************************
@@ -67,26 +56,26 @@ Download and launch the virtual machine
.. code-block:: bash
unxz clear-<version>-kvm.img.xz
unxz -v clear-<version>-kvm.img.xz
#. Download the `OVMF file`_ file that provides UEFI support for
virtual machines.
#. Download the 3 OVMF files (`OVMF.fd`, `OVMF_CODE.fd`, `OVMF_VARS.fd`) that
provides UEFI support for virtual machines.
.. code-block:: bash
curl -O https://cdn.download.clearlinux.org/image/OVMF.fd
#. Copy :file:`OVMF.fd` to the working directory, as shown below.
.. code-block:: bash
cp OVMF.fd <working_directory>
curl -O https://cdn.download.clearlinux.org/image/OVMF_CODE.fd
curl -O https://cdn.download.clearlinux.org/image/OVMF_VARS.fd
.. note::
Replace <working_directory> with your own.
The default OVMF files from |CL| may not work for some distro version(s).
You may get an `ASSERT` in the `debug.log` file when starting the VM.
If that is the case, use the distro-specific-OVMF files instead.
For example, the |CL| OVMF files work for Ubuntu 18.04 LTS, but not for Ubuntu 19.04 LTS.
Installing and using the OVMF files for Ubuntu 19.04 LTS resolved the `ASSERT` issue.
#. Download the sample `QEMU-KVM launcher`_ script from the
#. Download the `QEMU-KVM launcher`_ script from the
`image <https://cdn.download.clearlinux.org/image/>`_ directory. This script
will launch the |CL| VM and provide console interaction within the same
terminal emulator window.
@@ -105,7 +94,7 @@ Download and launch the virtual machine
.. code-block:: bash
./start_qemu.sh clear-<version>-kvm.img
sudo ./start_qemu.sh clear-<version>-kvm.img
#. Log in as ``root`` user and set a new password.
@@ -123,21 +112,28 @@ launched from, follow these steps.
PermitRootLogin yes
EOF
#. Start SSH server in the |CL| VM:
#. Enable and start SSH server in the |CL| VM:
.. code-block:: bash
systemctl enable sshd
systemctl start sshd
#. From the host, SSH into the |CL| VM. The port number ``10022`` is defined
in the ``start_qemu.sh`` script.
#. Determine the IP address of the host on which you will launch the VM.
Substitute <ip-addr-of-kvm-host> in the next step with this information.
.. code-block:: bash
ssh -p 10022 root@localhost
ip a
Add the GNOME Display Manager (GDM)
***********************************
#. SSH into the |CL| VM using the default port of `10022`:
.. code-block:: bash
ssh -p 10022 root@<ip-addr-of-kvm-host>
Optional: Add the GNOME Display Manager (GDM)
*********************************************
To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps:
@@ -145,90 +141,90 @@ To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps:
.. code-block:: bash
shutdown now
poweroff
#. Install a VNC viewer on the host machine. Below are some example distros.
#. Install the Spice viewer on the local host or remote system. Below are some
example distros.
* On Clear Linux:
.. code-block:: bash
swupd bundle-add tigervnc
sudo swupd bundle-add virt-viewer
* On Ubuntu\* 16.04 LTS Desktop:
* On Ubuntu\* 18.04 LTS Desktop:
.. code-block:: bash
apt-get install vncviewer
sudo apt-get install virt-viewer
* On Mint\* 18.1 “Serena” Desktop:
* On Mint\* 19.1 “Cinnamon” Desktop:
.. code-block:: bash
apt-get install vncviewer
sudo apt-get install virt-viewer
* On Fedora\* 25 Workstation:
* On Fedora\* 30 Workstation:
.. code-block:: bash
dnf install tigervnc
sudo dnf install virt-viewer
#. Modify the :file:`start_qemu.sh` script to increase memory (``-m``), add
graphics driver (``-vga``), and add VNC (``-vnc``, ``-usb``, and
``-device``) support.
#. Modify the :file:`start_qemu.sh` script to increase memory (`-m`), add
graphics driver (`-vga`), and add Spice (`-spice`, `-usb`, and
`-device`) support.
.. code-block:: console
qemu-system-x86_64 \
-enable-kvm \
-bios OVMF.fd \
${UEFI_BIOS} \
-smp sockets=1,cpus=4,cores=2 -cpu host \
-m 4096 \
-vga qxl \
-vnc :0 -nographic \
-nographic \
-spice port=5924,disable-ticketing \
-usb \
-device usb-tablet \
-device usb-tablet,bus=usb-bus.0 \
-drive file="$IMAGE",if=virtio,aio=threads,format=raw \
-netdev user,id=mynet0,hostfwd=tcp::${VMN}0022-:22,hostfwd=tcp::${VMN}2375-:2375 \
-device virtio-net-pci,netdev=mynet0 \
-debugcon file:debug.log -global isa-debugcon.iobase=0x402 $@
#. Due to changes in the :file:`start_qemu.sh` script from the previous step,
the UEFI :file:`NvVars`
information for the previously-booted |CL| VM will need to be reset.
using the same OVMF files will result in the VM not booting properly and
you end up in the the UEFI shell. The easiest way to avoid this is to delete
the OVMF files and restore the originals before relaunching the VM.
#. Relaunch the |CL| VM. The UEFI shell will appear.
.. code-block:: bash
./start_qemu.sh clear-<version>-kvm.img
#. At the UEFI shell, delete the :file:`NvVars` file:
.. code-block:: bash
Shell> del FS0:\NvVars
#. Exit out of the UEFI shell:
.. code-block:: bash
Shell> reset -s
#. Relaunch the |CL| VM:
.. code-block:: bash
./start_qemu.sh clear-<version>-kvm.img
#. From the host machine, open a new terminal emulator window and VNC into the
|CL| VM:
#. Increase the size of the VM by 10GB to accommodate the GDM installation:
.. code-block:: bash
vncviewer 0.0.0.0
qemu-img resize -f raw clear-<version>-kvm.img +10G
#. Log in as ``root`` user into the |CL| VM.
#. Relaunch the |CL| VM:
.. code-block:: bash
sudo ./start_qemu.sh clear-<version>-kvm.img
#. Determine the IP address of the host on which you will launch the VM.
Substitute <ip-addr-of-kvm-host> in the next step with this information.
.. code-block:: bash
ip a
#. From the local host or remote system, open a new terminal emulator window
and connect into the |CL| VM using the Spice viewer:
.. code-block:: bash
remote-viewer spice://<ip-address-of-kvm-host>:5924
#. Log in as `root` user into the |CL| VM.
#. Follow these steps to `resize the partition`_ of the virtual disk of the VM.
#. Add GDM to the |CL| VM:
@@ -236,19 +232,20 @@ To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps:
swupd bundle-add desktop-autostart
#. Reboot the |CL| VM to enable GDM:
#. Reboot the |CL| VM to start GDM:
.. code-block:: bash
reboot
#. Go through GDM's out-of-box experience (OOBE).
#. Go through the GDM out-of-box experience (OOBE).
#. The default aspect ratio of the GDM GUI for the |CL| VM is 4:3. To change
it, use GDM's ``Displays`` setting tool (located at the top-right corner).
#. The default aspect ratio of the GDM GUI for the |CL| VM is 4:3. To change
it, use GDM's `Devices > Displays` setting tool (located at the top-right corner).
.. _Intel® Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html
.. _Intel®Virtualization Technology for Directed I/O: https://software.intel.com/en-us/articles/intel-virtualization-technology-for-directed-io-vt-d-enhancing-intel-platforms-for-efficient-virtualization-of-io-devices
.. _QEMU-KVM launcher: https://cdn.download.clearlinux.org/image/start_qemu.sh
.. _OVMF file: https://cdn.download.clearlinux.org/image/OVMF.fd
.. _resize the partition: https://clearlinux.org/documentation/clear-linux/guides/maintenance/increase-virtual-disk-size#id8
+12 -3
View File
@@ -79,7 +79,7 @@ The method below uses the command line tool *nmcli* to modify network
connection.
#. Identify the existing connection name.
#. Identify the existing connection name:
.. code:: bash
@@ -114,7 +114,15 @@ connection.
:file:`/etc/NetworkManager/system-connections/*.nmconnection`. can be edited
directly.
#. Verify your static IP address details have been set
#. Restart the NetworkManager server to reload the DNS servers:
.. code-block:: bash
sudo systemctl restart NetworkManager
#. Verify your static IP address details have been set:
.. code-block:: bash
@@ -167,7 +175,8 @@ created manually.
sudo systemctl restart systemd-networkd
#. Verify your static IP address details have been set
#. Verify your static IP address details have been set:
.. code-block:: bash
+13 -11
View File
@@ -23,12 +23,13 @@ Background
Software that is compiled and packaged for general usage in an operating
system typically only contains components that are used to execute the
program, like binaries and libraries. Extra developer data like the the
actual source code and symbol information are separated and excluded for
program, such as binaries and libraries. Extra developer data, such as the
actual source code and symbol information, are separated and excluded for
efficiency.
The debug information helps relate binary code to human readable source code
lines and variables. Most of the time this auxiliary information is not needed
lines and variables. Most of the time, this auxiliary information
is not needed;
however without it, debugging a program results in limited visibility.
@@ -50,15 +51,16 @@ installed.
clr-debug-info.
#. Start a debugging session against a program using a debugger, like GDB.
For example, to debug *gnome-control-center*:
#. Start a debugging session against a program using a debugger, such as GDB.
For example, to debug *gnome-control-center* execute the following
command:
.. code:: bash
gdb /usr/bin/gnome-control-center
As the program is stepped through and debug information is needed, the
clr_debug_daemon will obtain it in the background.
As you step through the program and debug information is needed, the
clr_debug_daemon obtains it in the background.
Implementation
@@ -68,20 +70,20 @@ The implementation of the |CL| debug system is open source and available on
GitHub at: https://github.com/clearlinux/clr-debug-info/
.. figure:: figures/debug-diagram.png
:scale: 75%
:width: 400px
:alt: Debug system communication flow
Figure 1: The communication flow of the |CL| debug system
The |CL| debug system implements a :abbr:`FUSE (filesystem in userspace)`
filesystem mounted at :file:`/usr/lib/debug` and :file:`/usr/src/debug`. The
FUSE filesystem starts automatically. Its status can be verified with
FUSE filesystem starts automatically. You can verify its status by executing
:command:`systemctl status clr_debug_fuse.service`.
The *clr_debug_daemon* is responsible for fetching the appropriate package
debug content from the server and making it available for any debugging
programs needed it. It is socket activated whenever a request to the local
FUSE filesystem occurs. Its status can be verified with :command:`systemctl
programs that need it. It is socket activated whenever a request to the local
FUSE filesystem occurs. You can verify its status with :command:`systemctl
status clr_debug_daemon.service`.
+13 -13
View File
@@ -15,9 +15,9 @@ Description
:command:`swupd` has two main functions:
#. Manages software and replaces APT or YUM, by installing bundles
#. Manage software and replace APT or YUM, by installing bundles
rather than packages.
#. Checks for system updates and installs them.
#. Check for system updates and install them.
:command:`swupd` manages overlapping dependencies behind the scenes, ensuring
that all software is compatible across the system. It can be used to verify
@@ -25,27 +25,27 @@ the OS, clean cached files, and fix issues.
:ref:`Bundles <bundles>` contain everything needed to deliver a software
capability. They are the smallest granularity component that is
managed by |CL|. A bundle comes with all of its dependencies, rather than
managed by |CL|. A bundle comes with all of its dependencies rather than
downloading a cascade of package dependencies when installing a piece of
software.
Versioning
==========
Using package managers to keep track of software version compatibility or
Using package managers to monitor software version compatibility or
compare multiple systems on many Linux distributions can be cumbersome.
With |CL| :command:`swupd`, versioning happens at the individual file-level.
With |CL| :command:`swupd`, versioning happens at the individual file level.
This means |CL| generates an entirely new OS version with any set of software
changes to the system (including software downgrades or removals). This
changes to the system, including software downgrades or removals. This
rolling release versioning model is similar to :command:`git` internal version
tracking, where any of the individual file commits are tracked and move the
pointer forward when changed.
A number that represents the **current** release of the OS describes the
versions of all the software on the OS. Each build is composed of a specific
set of bundles made from a particular version of packages. This matters on a
daily basis to system administrators, who need to determine which of their
set of bundles made from a particular version of packages. On a daily basis,
this matters to system administrators who need to determine which of their
systems do not have the latest security fixes, or which combinations of
software have been tested. Every release of the same number is guaranteed to
contain the same versions of software, so there's no ambiguity between two
@@ -59,8 +59,8 @@ checks for updates against a version server. The content server provides the
file and metadata content for all versions and can be the same as the
version server. The content url server provides metadata in the form of
*manifests*, which list and describe file contents, symlinks,
and directories. Additionally, the actual content is
provided to clients in the form of archive files.
and directories. Additionally, the actual content is provided to clients
in the form of archive files.
Software updates with |CL| are also efficient. Unlike package-based
distributions, :command:`swupd` only updates files that have changed, rather
@@ -121,7 +121,7 @@ a system is obtained by one of the following methods:
Bundle search
=============
:command:`swupd` search downloads manifest data and searches for
:command:`swupd` searches download manifest data for
bundles that match the term. Enter only one term, or hyphenated term, per
search. Use the command :command:`man swupd` to learn more.
@@ -187,7 +187,7 @@ on demand.
.. _swupd-guide-example-install-bundle:
Example 2: Find and install Kata\* Containers
Example 2: Find and install Kata Containers\*
=============================================
Kata Containers is a popular container implementation. Unlike other
@@ -199,7 +199,7 @@ improved security.
`one bundle`_ to use `Kata Containers`_: `containers-virt`, despite a
number of dependencies. Also, check out our tutorial: :ref:`kata`.
#. Find the right bundle.
#. Find the correct bundle.
To return all possible matches for the search string, enter
:command:`swupd search`, followed by 'kata':
+12 -3
View File
@@ -53,8 +53,9 @@ Stack features
.. note::
Performance test results for the Deep Learning Reference Stack were
obtained using `runc` as the runtime.
The Deep Learning Reference Stack is a collective work, and each piece of software within the work has its own license. Please see the `terms of use`_ for more details about licensing and usage of the Deep Learning Reference Stack.
Prerequisites
=============
@@ -107,6 +108,12 @@ For multi-node testing, replicate these steps for each node. These steps
provide a template to run other benchmarks, provided that they can invoke
TensorFlow.
.. note::
Performance test results for the Deep Learning Reference Stack and for this tutorial were
obtained using `runc` as the runtime.
#. Download either the `Eigen`_ or the `Intel MKL-DNN`_ Docker image
from `Docker Hub`_.
@@ -243,7 +250,7 @@ Images
You must add `launcher.py`_ to the Docker image to include the Deep
Learning Reference Stack and put the benchmarks repo in the correct
location. Note that this tutorial uses Kubeflow v0.4.0, and cannot guarantee results if you use a different version.
location. Note that this tutorial uses Kubeflow v0.4.0, and cannot guarantee results if you use a different version.
From the Docker image, run the following:
@@ -495,6 +502,8 @@ Related topics
.. _launcher.py: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow
.. _terms of use: https://clearlinux.org/stacks/deep-learning/terms-of-use
.. _Release notes on Github\*: https://github.com/clearlinux/dockerfiles/blob/master/stacks/dlrs/releasenote.md
.. _Intel® quantization tools: https://github.com/IntelAI/tools/blob/master/tensorflow_quantization/README.md#quantization-tools
+53 -15
View File
@@ -14,10 +14,15 @@ automatically at system boot if a compatible card is detected.
These instructions show how to use the proprietary NVIDIA drivers which
require a manual installation.
.. note::
.. warning::
Software installed outside of :ref:`swupd <swupd-about>` is not updated with |CL|
updates and must be updated and maintained manually.
Software installed outside of :ref:`swupd <swupd-about>` is not updated
with |CL| updates and must be updated and maintained manually.
For example, the file :file:`/usr/lib/libGL.so` conflicts between the one
provided by the mesa package in |CL| and the one NVIDIA provides. If a |CL|
update overwrites these files, a reinstallation of the NVIDIA driver might
be required.
@@ -107,17 +112,20 @@ needs to be disabled before installation can continue.
Configure the Dynamic Linker
============================
Configure Alternative Software Paths
====================================
The NVIDIA installer will be directed to install files under
:file:`/opt/nvidia` as much as possible to keep its contents isolated from the
rest of the |CL| system files under :file:`/usr`. The dynamic linker will
need to be configured to use the NVIDIA-provided libraries.
rest of the |CL| system files under :file:`/usr`. The dynamic linker and X
server will need to be configured to use the content under
:file:`/opt/nvidia`.
#. Configure the dynamic linker to look for and cache shared libraries under
:file:`/opt/nvidia/lib` and :file:`/opt/nvidia/lib32`.
:file:`/opt/nvidia/lib` and :file:`/opt/nvidia/lib32` in addition to the
default paths.
.. code-block:: bash
@@ -125,7 +133,26 @@ need to be configured to use the NVIDIA-provided libraries.
sudo mkdir /etc/ld.so.conf.d
printf "/opt/nvidia/lib \n/opt/nvidia/lib32 \n" | sudo tee --append /etc/ld.so.conf.d/nvidia.conf
#. Reload the dynamic linker run-time bindings and library cache.
.. code-block:: bash
sudo ldconfig
#. Create a Xorg configuration file to search for modules under
:file:`/opt/nvidia` in addition to the default path.
.. code-block:: bash
sudo mkdir -p /etc/X11/xorg.conf.d/
sudo tee /etc/X11/xorg.conf.d/nvidia-files-opt.conf > /dev/null <<'EOF'
Section "Files"
ModulePath "/usr/lib64/xorg/modules"
ModulePath "/opt/nvidia/lib64/xorg/modules"
EndSection
EOF
Install the NVIDIA Drivers
@@ -152,17 +179,22 @@ Install the NVIDIA Drivers
--utility-prefix=/opt/nvidia \
--opengl-prefix=/opt/nvidia \
--compat32-prefix=/opt/nvidia \
--compat32-libdir=lib32 \
--compat32-libdir=lib32 \
--x-prefix=/opt/nvidia \
--x-module-path=/opt/nvidia/lib64/xorg/modules \
--x-library-path=/opt/nvidia/lib64 \
--x-sysconfig-path=/etc/X11/xorg.conf.d \
--documentation-prefix=/opt/nvidia \
--application-profile-path=/etc/nvidia \
--no-precompiled-interface \
--no-nvidia-modprobe \
--no-distro-scripts \
--force-libglx-indirect \
--glvnd-egl-config-path=/etc/glvnd/egl_vendor.d \
--egl-external-platform-config-path=/etc/egl/egl_external_platform.d \
--dkms \
--silent
#. The graphical interface may automatically start after the NVIDIA driver
is loaded. Return to the working terminal and log back in if necessary.
@@ -171,7 +203,7 @@ Install the NVIDIA Drivers
.. code-block:: bash
lsmod | grep ^nvidia
lsmod | grep ^nvidia
#. Run a |CL| system verification to restore files that the NVIDIA installer
@@ -185,7 +217,8 @@ Install the NVIDIA Drivers
The NVIDIA software places some files under the :file:`/usr` subdirectory
which are not managed by |CL| and conflict with the |CL| stateless design.
Although a limited version of :command:`swupd repair` is ran above,
Although a limited version of :command:`swupd repair` is run above,
other uses of the :command:`swupd repair` command should be avoided
with the proprietary NVIDIA drivers installed.
@@ -198,7 +231,7 @@ The proprietary NVIDIA drivers are installed manually outside of :ref:`swupd
Updating the NVIDIA drivers follows the same steps as initial installation,
however the desktop environment must first be stopped so that the drivers are
not in use.
not in use.
#. Follow the steps in `Download the NVIDIA Drivers for Linux`_ section to get
the latest NVIDIA drivers.
@@ -241,14 +274,19 @@ Uninstalling the NVIDIA Drivers
The NVIDIA drivers and associated software can be uninstalled and nouveau
driver restored by:
#. Remove the previously created file :file:`/etc/modprobe.d` that
prevents nouveau from loading.
#. Remove the :file:`modprobe.d` file that prevents nouveau from loading.
.. code-block:: bash
sudo rm /etc/modprobe.d/disable-nouveau.conf
#. Remove the :file`xorg.conf.d` file that adds a search path for X modules.
.. code:: bash
sudo rm /etc/X11/xorg.conf.d/nvidia-files-opt.conf
#. Run the :command:`sudo /opt/nvidia/bin/nvidia-uninstall`
#. Follow the prompts on the screen and reboot the system.