diff --git a/source/_figures/gce/02-storage-browser.png b/source/_figures/gce/02-storage-browser.png index 704f94b8..72db76fd 100644 Binary files a/source/_figures/gce/02-storage-browser.png and b/source/_figures/gce/02-storage-browser.png differ diff --git a/source/_figures/gce/03-create-bucket.png b/source/_figures/gce/03-create-bucket.png index 36a1da38..ad00ca00 100644 Binary files a/source/_figures/gce/03-create-bucket.png and b/source/_figures/gce/03-create-bucket.png differ diff --git a/source/_figures/gce/30-create-vm.png b/source/_figures/gce/30-create-vm.png index 528a461e..49854b5f 100644 Binary files a/source/_figures/gce/30-create-vm.png and b/source/_figures/gce/30-create-vm.png differ diff --git a/source/_figures/gce/30-vm-none.png b/source/_figures/gce/30-vm-none.png index e043ef03..3c118f49 100644 Binary files a/source/_figures/gce/30-vm-none.png and b/source/_figures/gce/30-vm-none.png differ diff --git a/source/_figures/increase-virtual-disk-size/01-increase-virtual-disk-size-original.png b/source/_figures/increase-virtual-disk-size/01-increase-virtual-disk-size-original.png new file mode 100644 index 00000000..db6ec855 Binary files /dev/null and b/source/_figures/increase-virtual-disk-size/01-increase-virtual-disk-size-original.png differ diff --git a/source/_figures/increase-virtual-disk-size/01-increase-virtual-disk-size.png b/source/_figures/increase-virtual-disk-size/01-increase-virtual-disk-size.png new file mode 100644 index 00000000..63a23b1c Binary files /dev/null and b/source/_figures/increase-virtual-disk-size/01-increase-virtual-disk-size.png differ diff --git a/source/_figures/increase-virtual-disk-size/02-increase-virtual-disk-size-original.png b/source/_figures/increase-virtual-disk-size/02-increase-virtual-disk-size-original.png new file mode 100644 index 00000000..91443668 Binary files /dev/null and b/source/_figures/increase-virtual-disk-size/02-increase-virtual-disk-size-original.png differ diff --git a/source/_figures/increase-virtual-disk-size/02-increase-virtual-disk-size.png b/source/_figures/increase-virtual-disk-size/02-increase-virtual-disk-size.png new file mode 100644 index 00000000..207888c5 Binary files /dev/null and b/source/_figures/increase-virtual-disk-size/02-increase-virtual-disk-size.png differ diff --git a/source/_themes/otc_tcs_sphinx_theme/layout.html b/source/_themes/otc_tcs_sphinx_theme/layout.html index 94f4617f..c9741d66 100644 --- a/source/_themes/otc_tcs_sphinx_theme/layout.html +++ b/source/_themes/otc_tcs_sphinx_theme/layout.html @@ -47,6 +47,10 @@

*Other names and brands may be claimed as the property of others.

+
{% endblock %} diff --git a/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css b/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css index 4df47ff6..829183f5 100644 --- a/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css +++ b/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css @@ -489,17 +489,36 @@ div.linenodiv:before { /*add extra new line to make sure code and line numbers a margin: 10px; border: 10px; background: white; + position: relative; } .column.featurecard { background: #CCE9F5; } +.column.squarecard { + height: 320px; +} + +.column.smallcard { + height: 150px; +} + +.endlink { + position: absolute; + bottom: 10px; + right: 10px; +} + .column.verticalcard { height: 615px; overflow: auto; } +.multicolumns.three { + max-width: 1200px; +} + /* Clear floats after the columns */ .multicolumns:after { content: ""; @@ -521,9 +540,29 @@ div.linenodiv:before { /*add extra new line to make sure code and line numbers a /*End support for multi-column sections*/ +/*Start fix for changes made to definition lists in sphinx/rtd post version 2.0*/ + +.rst-content dl:not(.docutils) dt { + border-top: none; + background: none; +} + +/*end fix to definition lists*/ + +/*start formatting support for horizontal bullet list without bullets in footer*/ +ul.footer__menu_list { + display: inline-flex; +} + +li.footer__menu_list { + margin-right: 30px; +} +/*end footer bullet list support*/ /*Add drop shadow to figures*/ div.figure.dropshadow img { box-shadow: 10px 10px 10px LightGray; -} \ No newline at end of file +} + +/*end figure drop shadow*/ diff --git a/source/conf.py b/source/conf.py index cccfdd64..5d8e37a3 100644 --- a/source/conf.py +++ b/source/conf.py @@ -54,7 +54,7 @@ master_doc = 'index' # General information about the project. #project = u'Clear Linux* project' project = u'Clear Linux* Project Docs' -copyright = u'2019.' +copyright = u'2020.' author = u'many' # The version info for the project you're documenting, acts as replacement for diff --git a/source/get-started/bare-metal-install-server.rst b/source/get-started/bare-metal-install-server.rst index 13316682..a1b9e423 100644 --- a/source/get-started/bare-metal-install-server.rst +++ b/source/get-started/bare-metal-install-server.rst @@ -38,12 +38,8 @@ Install |CL| on your target system ********************************** Ensure that your system is configured to boot UEFI. The installation method -described below requires a wired Internet connection with DHCP. +described below requires a wired or wireless Internet connection with DHCP. -.. note:: - - Alternatively, you can install |CL| over a wireless connection by first - using `nmtui`. Follow the `nmtui` instructions shown in Figure 2. Follow these steps to install |CL| on the target system: @@ -90,6 +86,12 @@ Launch the |CL| Installer Figure 2: root login +#. .. note:: + + If a wireless connection is needed, connect to the network using + :command:`nmtui` before lauching the installer. See the documentation on + :ref:`configuring Wifi with nmtui ` for more details. + #. At the :guilabel:`root` prompt, enter :command:`clr-installer` and press :kbd:`Enter`. @@ -488,7 +490,8 @@ Add New User .. note: - The User Name must be alphanumeric and can include spaces, commas, underscores or hyphens. Maximum length is 64 characters. + The User Name must be alphanumeric and can include spaces, commas, + underscores or hyphens. Maximum length is 64 characters. .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-19.png :scale: 100% diff --git a/source/get-started/cloud-install/gce.rst b/source/get-started/cloud-install/gce.rst index 8a684c47..431ecb17 100644 --- a/source/get-started/cloud-install/gce.rst +++ b/source/get-started/cloud-install/gce.rst @@ -229,12 +229,10 @@ Setup |CL| VM on GCP Figure 18: Set SSH key for remote login - .. warning:: + .. note:: The username is assigned from characters preceding ``@`` in the email - address, included in the SSH key. The dot symbol "." is not allowed, - because it is an invalid character while creating user accounts in - |CL|. + address, included in the SSH key. * Click the :guilabel:`Create` button to create the |CL| VM. diff --git a/source/guides/clear/index.rst b/source/guides/clear/index.rst new file mode 100644 index 00000000..16198365 --- /dev/null +++ b/source/guides/clear/index.rst @@ -0,0 +1,79 @@ +.. _cl-guides: + +|CL-ATTR| +######### + +.. note:: + + As of 22 May 2019 :file:`mixin` is no longer supported. + +.. container:: multicolumns three + + .. container:: column smallcard featurecard + + :ref:`swupd-guide` + Learn how to manage software and system updates in |CL|. + + .. container:: column smallcard featurecard + + :ref:`debug` + Discover how to use :command:`clr-debug-info` to leverage your + network to debug system software. + + .. container:: column smallcard featurecard + + :ref:`telem-guide` + Learn how you can opt-in to allow |CL| to collect data to identify + and fix bugs. + + .. container:: column smallcard + + :ref:`autoproxy` + Discover how |CL| makes working behind a corporate proxy smoother. + + .. container:: column smallcard + + :ref:`autospec` + Learn about :command:`autospec` and how it used to automatically + include and maintain open source software in |CL|. + + .. container:: column smallcard + + :ref:`bundles-guide` + Find out what a bundle is and why it is an important part of + what makes |CL| secure and high performance. + + .. container:: column smallcard + + :ref:`compatible-kernels` + Learn about all of the kernels available as installable bundles. + + .. container:: column smallcard + + :ref:`ister` + Find out how |CL| uses this template-based installer to produce + images for each release. + + .. container:: column smallcard + + :ref:`mixer` + Learn how the |CL| team generates official update content and + releases. + + .. container:: column smallcard + + :ref:`security` + Learn how |CL| is designed to ensure the security of updates and + software. + + .. container:: column smallcard + + :ref:`stateless` + |CL| is stateless is designed to need little to no user + configuration. + +.. toctree:: + :glob: + :hidden: + + * \ No newline at end of file diff --git a/source/guides/clear/mixer.rst b/source/guides/clear/mixer.rst index 04812076..0bac3382 100644 --- a/source/guides/clear/mixer.rst +++ b/source/guides/clear/mixer.rst @@ -296,14 +296,14 @@ inherit upstream bundles. .. code-block:: bash - mixer build bundles + sudo mixer build bundles #. First, browse to web server from Example 1. The web page appears yet has no update content. Build the update content: .. code-block:: bash - mixer build update + sudo mixer build update After that is completed, on your web server, you can see the update content for mix version 10. @@ -330,15 +330,15 @@ Next, let’s create a new version of the mix. We’ll add a new bundle. .. code-block:: bash - mixer build bundles - mixer build update + sudo mixer build bundles + sudo mixer build update #. Optionally, you can build delta-packs, which help reduce client update time: .. code-block:: bash - mixer build delta-packs --from 10 --to 20 + sudo mixer build delta-packs --from 10 --to 20 Refresh your web server to see the update content for mix version 20. @@ -559,7 +559,7 @@ bundle that we added to our mix in Example 2. .. code-block:: bash - mixer build all + sudo mixer build all .. note:: :command:`mixer build all` runs both :command:`mixer build bundles` and :command:`mixer build update` in one step. diff --git a/source/guides/index.rst b/source/guides/index.rst index 829a974e..95b678c3 100644 --- a/source/guides/index.rst +++ b/source/guides/index.rst @@ -3,55 +3,75 @@ Guides ###### -The following guides provide step-by-step instructions on using |CL|. +.. rst-class:: colh2 -.. note:: +Featured Guides - As of 22 May 2019 :file:`mixin` is no longer supported. +.. container:: multicolumns three -.. _cl-guides: + .. container:: column smallcard + + :ref:`stateless` + |CL| is stateless is designed to need little to no user + configuration. -Clear Linux -=========== + .. container:: column smallcard + + :ref:`mixer` + Learn how the |CL| team generates official update content and + releases. + + .. container:: column smallcard + + :ref:`dars` + Learn how to use the :abbr:`DARS (Data Analytics Reference Stack)`, + and build your own DARS container image. + + .. container:: column smallcard + + :ref:`dbrs` + Learn about the hardware and installation requirements of + :abbr:`DBRS (Database Reference Stack)`, and how to use |CL| + to host it. + + .. container:: column smallcard + + :ref:`cpu-performance` + Learn how to modify CPU power and performance settings for your + usecase. + + .. container:: column smallcard + + :ref:`developer-workstation` + Set your workstation up with all bundles needed to + start your |CL| development project. + + .. container:: column smallcard + + :ref:`vnc` + Learn how to use VNC to connect to a remote |CL| host. + + .. container:: column smallcard + + :ref:`openssh-server` + Learn how to set up the SSH service. + + .. container:: column smallcard + + :ref:`kernel-modules` + Learn how to correctly and reliably add kernel modules manually. + + .. container:: column smallcard + + :ref:`kernel-development` + Learn how to compile a Linux\* kernel from source using |CL| + development tooling. .. toctree:: - :maxdepth: 1 - :glob: + :hidden: - clear/* - -Maintenance -=========== - -.. toctree:: - :maxdepth: 1 - :glob: - - maintenance/* - -Network -======= - -.. toctree:: - :maxdepth: 1 - :glob: - - network/* - -Kernel -======= - -.. toctree:: - :maxdepth: 1 - :glob: - - kernel/* - -Stacks -======= - -.. toctree:: - :maxdepth: 1 - :glob: - - stacks/* + clear/index + maintenance/index + network/index + kernel/index + stacks/index diff --git a/source/guides/kernel/index.rst b/source/guides/kernel/index.rst new file mode 100644 index 00000000..d2ef3e9e --- /dev/null +++ b/source/guides/kernel/index.rst @@ -0,0 +1,9 @@ +.. _kernel-guides: + +Kernel +###### + +.. toctree:: + :glob: + + * \ No newline at end of file diff --git a/source/guides/maintenance/cpu-performance.rst b/source/guides/maintenance/cpu-performance.rst index 53709f15..8c7b76d1 100644 --- a/source/guides/maintenance/cpu-performance.rst +++ b/source/guides/maintenance/cpu-performance.rst @@ -193,6 +193,52 @@ group: After adding a new group, you must log out and log back in for the new group to take effect. +Enhanced thermal configuration +=============================== + +Better thermal control and performance can be achieved by providing platform +specific configuration to thermald. + +`Linux DPTF Extract Utility`_ is a companion tool to thermald, This tool can +make use of :abbr:`Intel® Dynamic Platform and Thermal Framework (`Intel DPTF)` +technology, and convert to the thermal_conf.xml configuration format used +by thermald. It's a closed-source project, and unable to be packaged as bundle +in Clear Linux OS, so we need to follow below steps to generate configuration. + +Intel DPTF requires BIOS support, it's typically used by laptops. +The first step is to make sure your machine's BIOS has DPTF feature +and is enabled. + +Then generate thermal configuration as below: + +.. code:: bash + + sudo swupd bundle-add acpica-unix2 # install acpi tools + git clone https://github.com/intel/dptfxtract.git + cd dptfxtract + sudo acpidump > acpi.out + acpixtract -a acpi.out + sudo ./dptfxtract *.dat + +thermald configuration files will be generated and saved to +:command:`/etc/thermal/` folder. Restart thermald service to take effect. + +.. code:: bash + + sudo systemctl restart thermald.service + +check whether the configuration is in used. + +.. code:: bash + + sudo systemctl status thermald.service + +if the output contains below line, it means configuration already applied: + +.. code:: bash + + thermald[*]: [WARN]Using generated /etc/thermald/thermal-conf.xml.auto + .. _`Intel P-state driver`: https://www.kernel.org/doc/Documentation/cpu-freq/intel-pstate.txt @@ -205,3 +251,7 @@ group: .. _`ThermalMonitor`: https://github.com/intel/thermal_daemon/tree/master/tools/thermal_monitor .. _`Intel® Turbo Boost Technology`: https://www.intel.com/content/www/us/en/architecture-and-technology/turbo-boost/turbo-boost-technology.html + +.. _`Linux DPTF Extract Utility`: https://github.com/intel/dptfxtract + +.. _`Intel DPTF`: https://software.intel.com/en-us/articles/2-in-1-tablet-mode-game-performance-with-intel-dynamic-platform-and-thermal-framework-intel diff --git a/source/guides/maintenance/figures/increase-virtual-disk-size-1.png b/source/guides/maintenance/figures/increase-virtual-disk-size-1.png deleted file mode 100644 index a4692c9a..00000000 Binary files a/source/guides/maintenance/figures/increase-virtual-disk-size-1.png and /dev/null differ diff --git a/source/guides/maintenance/figures/increase-virtual-disk-size-2.png b/source/guides/maintenance/figures/increase-virtual-disk-size-2.png deleted file mode 100644 index 90b1eb28..00000000 Binary files a/source/guides/maintenance/figures/increase-virtual-disk-size-2.png and /dev/null differ diff --git a/source/guides/maintenance/increase-virtual-disk-size.rst b/source/guides/maintenance/increase-virtual-disk-size.rst index e633f506..f2f22719 100644 --- a/source/guides/maintenance/increase-virtual-disk-size.rst +++ b/source/guides/maintenance/increase-virtual-disk-size.rst @@ -1,103 +1,111 @@ .. _increase-virtual-disk-size: -Increase virtual disk size of an image +Increase Virtual Disk Size of an Image ###################################### -This guide describes how to increase the disk size of your prebuilt |CL-ATTR| -image if you need more capacity. +|CL-ATTR| pre-built images come in different sizes, ranging from 300 MB to 20 +GB. This guide describes how to increase the disk size of your pre-built +image if you need more capacity. We will use the :ref:`KVM image` as +an example to demonstrate the process of increasing disk size and expanding +the last partition to take up the added space. .. contents:: :local: :depth: 1 -Determine the partition order and sizes of the prebuilt image -************************************************************* +Determine disk size and list of partitions +****************************************** -|CL| prebuilt images come in different sizes, ranging from 300 MB to 20 -GB. +There are two methods to find the disk size and the list of partitions of +a pre-built |CL| image. -There are two methods to find the order and sizes of partitions virtual disk -of your prebuilt |CL| image. +Method 1: Use :command:`lsblk` on the VM +======================================== -In both examples, the prebuilt Hyper-V image has a disk size of 8.5 GB with -:file:`/dev/sda3` being the partition for the root filesystem (/) - -Checking :command:`lsblk` on the VM -=================================== - -The first method is to boot up your :abbr:`VM (Virtual Machine)` and -execute the :command:`lsblk` command as shown below: +The first method is to boot up your VM and execute the :command:`lsblk` +command as shown below: .. code-block:: bash - sudo lsblk + lsblk An example output of the :command:`lsblk` command: .. code-block:: console + :emphasize-lines: 4,7 - NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT - sda 8:0 0 8.5G 0 disk - ├─sda1 8:1 0 512M 0 part - ├─sda2 8:2 0 32M 0 part [SWAP] - └─sda3 8:3 0 8G 0 part / + NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT + fd0 2:0 1 4K 0 disk + sr0 11:0 1 1024M 0 rom + vda 254:0 0 8.6G 0 disk + ├─vda1 254:1 0 510M 0 part + ├─vda2 254:2 0 33M 0 part [SWAP] + └─vda3 254:3 0 8G 0 part / An example of this can also be seen in Figure 1. -Checking :file:`config.json` used to build the image -==================================================== +Method 2: Look at the image configuration YAML file +=================================================== -The second method to determine partition to check the :file:`config.json` -file used to create prebuilt image, located in the `releases`_ repository. -For example, to find the size of the Hyper-V\* image version number 20450, +The second method to look at the image configuration YAML file that was +used to produce the image. + +For example, to find the size of the KVM image version number 31880, follow these steps: #. Go to the `releases`_ repository. -#. Drill down into the `20450 > clear > config > image` directory. -#. Open the :file:`hyperv-config.json` file. -#. Locate the `PartitionLayout` key. - - The example shows 512 MB for the EFI partition, 32 MB for the swap - partition, and 8 GB for the root partition. +#. Drill down into the `31880 > clear > config > image` directory. +#. Download and open the :file:`kvm.yaml` file. +#. Locate the `targetMedia` section. + The example shows a total disk size of 8.54 GB, 512 MB for the EFI + partition, 32 MB for the swap partition, and 8 GB for the root partition. .. code-block:: console + :linenos: + :emphasize-lines: 3,9,13,18 - "PartitionLayout" : [ { "disk" : "hyperv.img", - "partition" : 1, - "size" : "512M", - "type" : "EFI" }, - { "disk" : "hyperv.img", - "partition" : 2, - "size" : "32M", - "type" : "swap" }, - { "disk" : "hyperv.img", - "partition" : 3, - "size" : "8G", - "type" : "linux" } ], + targetMedia: + - name: ${bdevice} + size: "8.54G" + type: disk + children: + - name: ${bdevice}1 + fstype: vfat + mountpoint: /boot + size: "512M" + type: part + - name: ${bdevice}2 + fstype: swap + size: "32M" + type: part + - name: ${bdevice}3 + fstype: ext4 + mountpoint: / + size: "8G" + type: part Increase virtual disk size ************************** -Once you have determined the disk and partition to be increased, you are -ready to perform the actual increase of the disk, partition, and filesystem. -Power off VM and increase virtual disk size -=========================================== +Before you can expand the last partition of your image, you must make +space available by increasing the virtual disk size. After that, you +can resize the last partition and finally resize the filesystem. +Follow these steps: -To increase the virtual disk size for a prebuilt image, perform the steps -below: +Increase virtual disk size +========================== -#. Shut down your VM if it is running. -#. Use the process defined by your hypervisor or cloud provider to increase +#. Shut down your VM. +#. Use the process defined by your hypervisor or cloud provider to increase the virtual disk size of your |CL| VM. -#. Power up the VM. +#. Power up your VM. +Resize the last partition of the virtual disk +============================================= -Resize the partition of the virtual disk -======================================== - -#. Log in to an account with root privileges. -#. Open a terminal emulator. +#. Log in. +#. Open a terminal window. #. Add the :command:`storage-utils` bundle to install the :command:`parted` and :command:`resize2fs` tools. @@ -105,7 +113,7 @@ Resize the partition of the virtual disk sudo swupd bundle-add storage-utils -#. Launch the `parted` tool. +#. Launch the :command:`parted` tool. .. code-block:: bash @@ -113,21 +121,20 @@ Resize the partition of the virtual disk #. In the `parted` tool, perform these steps: - #. Press :command:`p` to print the partitions table. + a. Press :command:`p` to print the partitions table. #. If the warning message below is displayed, enter :command:`Fix`. .. code-block:: console - Warning: Not all of the space available to :file:`/dev/sda` appears to be - used, you can fix the GPT to use all of the space (an extra ... + Warning: Not all of the space available to :file:`/dev/sda` appears + to be used, you can fix the GPT to use all of the space (an extra ... blocks) or continue with the current setting? Fix/Ignore? - #. Enter :command:`resizepart [partition number]` where - *[partition number]* is the partition number of the partition to modify. - #. Enter :command:`yes` when prompted. - #. Enter the new End size. + #. Enter :command:`resizepart ` where + ** is the number of the partition to modify. + #. Enter the new `End` size. .. note:: @@ -139,36 +146,37 @@ Resize the partition of the virtual disk An example of this can be seen in Figure 1. #. Enter :command:`q` to exit `parted` when you are finished resizing the - image. + partition. - Figure 1 depicts the described steps to resize the partition of the virtual disk from 8.5GB to 20GB. + Figure 1 depicts the described steps to resize the partition of the + virtual disk from 8.5 GB to 30 GB. - .. figure:: figures/increase-virtual-disk-size-1.png + .. rst-class:: dropshadow + + .. figure:: ../../_figures/increase-virtual-disk-size/01-increase-virtual-disk-size.png :scale: 100 % :alt: Increase root partition size - Figure 1: Increase root partition size. + Figure 1: Increase root partition size Resize the filesystem ===================== -#. Enter :command:`sudo resize2fs -p /dev/[modified partition name]` where - *[modified partition name]* is the partition that was changed in the `parted` +#. Enter :command:`sudo resize2fs -p /dev/` where + ** is the partition that was changed in the `parted` tool. -#. Run the :command:`df -h` to verify that the filesystem size has - increased. +#. Run :command:`lsblk` to verify that the filesystem size has increased. - Figure 2 depicts the described steps to resize the partition of the virtual - disk from 8.5GB to 20GB. + Figure 2 depicts the described steps to resize the filesystem of the virtual + disk from 8.5 GB to 30 GB. - .. figure:: figures/increase-virtual-disk-size-2.png + .. rst-class:: dropshadow + + .. figure:: ../../_figures/increase-virtual-disk-size/02-increase-virtual-disk-size.png :scale: 100 % :alt: Increase root filesystem with resize2fs - Figure 2: Increase root filesystem size after partition has been expanded. + Figure 2: Increase root filesystem with :command:`resize2fs` -**Congratulations!** You have resized the disk, partition, and filesystem. At -this point, the increase in disk capacity is usable. - -.. _releases: https://cdn.download.clearlinux.org/releases/ \ No newline at end of file +.. _releases: https://cdn.download.clearlinux.org/releases/ diff --git a/source/guides/maintenance/index.rst b/source/guides/maintenance/index.rst new file mode 100644 index 00000000..a8770180 --- /dev/null +++ b/source/guides/maintenance/index.rst @@ -0,0 +1,9 @@ +.. _maintain-guides: + +Maintenance +########### + +.. toctree:: + :glob: + + * \ No newline at end of file diff --git a/source/guides/network/index.rst b/source/guides/network/index.rst new file mode 100644 index 00000000..12264a2b --- /dev/null +++ b/source/guides/network/index.rst @@ -0,0 +1,9 @@ +.. _network-guides: + +Network +####### + +.. toctree:: + :glob: + + * \ No newline at end of file diff --git a/source/guides/network/wifi.rst b/source/guides/network/wifi.rst index 93808db8..bb8dd525 100644 --- a/source/guides/network/wifi.rst +++ b/source/guides/network/wifi.rst @@ -3,23 +3,29 @@ Configure Wi-Fi ############### -We recommend using `NetworkManager `_ to manage network connections. If you -choose to connect to Wi-Fi while using the -:ref:`live installer ` image, your Wi-Fi settings -will be added to your system during the installation process. +We recommend using `NetworkManager +`_ to +manage wireless network connections. If you choose to connect to Wi-Fi while +using the :ref:`live installer ` image, your Wi-Fi +settings will be added to your system during the installation process. -NetworkManager provides three simple methods for configuring Wi-Fi. +NetworkManager provides three simple methods for configuring Wi-Fi: Desktop, +CLI, and TUI. NetworkManager uses :command:`wpa_supplicant`, which can also be +used on its own for a more lightweight installation. .. contents:: :local: :depth: 1 +Using Network Manager +********************* + Desktop GUI (Graphical User Interface) -************************************** +====================================== 1. Click anywhere on the icons at the right side of the top of the screen to - bring up a menu and click on :guilabel:`Wi-Fi Not Connected` then - choose :guilabel:`Select Network`. + bring up a menu and click on :guilabel:`Wi-Fi Not Connected` then choose + :guilabel:`Select Network`. .. figure:: /_figures/wifi/wifi-1.1.png @@ -43,7 +49,7 @@ Desktop GUI (Graphical User Interface) .. figure:: /_figures/wifi/wifi-5.png CLI (Command Line Interface) -**************************** +============================ #. List the available Wi-Fi networks @@ -72,8 +78,10 @@ CLI (Command Line Interface) To avoid having the Wi-Fi password stored in bash history, consider using the TUI. +.. _wifi-nm-tui: + TUI (Text-based User Interface) -******************************* +=============================== #. Launch the NetworkManager Text User Interface @@ -102,8 +110,184 @@ TUI (Text-based User Interface) .. figure:: /_figures/wifi/nmtui_5.png + +Using wpa_supplicant +******************** + +wpa_suppliant can be used directly, without NetworkManager, to associate a +wireless adapter with an access point. After association is established, an IP +address needs to be assigned or obtained. + + +Associate with a wireless access point +====================================== + +#. Make sure NetworkManager is stopped and disabled by masking the service. + + .. code-block:: bash + + sudo systemctl stop NetworkManager.service + sudo systemctl mask NetworkManager.service + + +#. Stop the wpa_supplicant.service, which may have been started by NetworkManager. + + .. code-block:: bash + + sudo systemctl stop wpa_supplicant.service + +#. Create a ``wpa_supplicant`` configuration directory. + + .. code-block:: bash + + sudo mkdir -p /etc/wpa_supplicant + +#. Determine your wireless interface name. + + .. code-block:: bash + + iw dev + + Use the name following "Interface" on the first line (eg. wlp1s0) + + .. code-block:: console + :emphasize-lines: 1 + + Interface wlp1s0 + ifindex 3 + wdev 0x1 + addr 00:xx:xx:38:34:7a + type managed + txpower 0.00 dBm + + Set the $INTERFACE_NAME environment variable to take advantage of copying + and pasting commands. + + .. code-block:: bash + + export INTERFACE_NAME=wlp1s0 + +#. Create a minimal configuration file called + :file:`/etc/wpa_supplicant/wpa_supplicant-$INTERFACE_NAME.conf` + and add the following: + + .. code-block:: bash + + sudo tee /etc/wpa_supplicant/wpa_supplicant-$INTERFACE_NAME.conf > /dev/null <<'EOF' + ctrl_interface_group=wheel + ctrl_interface=/run/wpa_supplicant + update_config=1 + EOF + +#. Start the wpa_supplicant service to complete the configuration process. + + .. code-block:: bash + + sudo systemctl start wpa_supplicant@$INTERFACE_NAME.service + +#. Use :command:`wpa_cli` (interactive mode) to scan for available networks. + In this example, our network is named *Network1*. + + .. code-block:: bash + :emphasize-lines: 1,2,5,7 + + sudo wpa_cli + > scan + OK + <3>CTRL-EVENT-SCAN-STARTED + <3>CTRL-EVENT-SCAN-RESULTS + > scan_results + bssid / frequency / signal level / flags / ssid + 00:xx:xx:73:7b:46 5180 -55 [WPA2-PSK-CCMP][ESS] Network1 + 00:xx:xx:83:fa:70 5240 -76 [WPA2-EAP-CCMP][ESS] Network2 + 00:xx:xx:4f:e9:2c 2412 -67 [WPA2-PSK-CCMP][ESS][P2P] Printer + 00:xx:xx:af:fe:3e 5765 -79 [WPA2-PSK-CCMP][ESS] Network3 + 00:xx:xx:e9:eb:29 2412 -76 [WPA2-PSK-CCMP][ESS] Network4 + 00:xx:xx:26:4a:b9 2412 -79 [WPA2-PSK-CCMP][ESS][P2P] Printer2 + 00:xx:xx:b9:0d:d4 2462 -79 [WPA2-PSK-CCMP][ESS] Network5 + +#. Set up your network connection replacing *Network1* with your wireless + SSID name and *Network1Password* with the password for your network. + + .. code-block:: bash + :emphasize-lines: 1,3,5,7 + + > add_network + 0 + > set_network 0 ssid "Network1" + OK + > set_network 0 psk "Network1Password" + OK + > enable_network 0 + OK + <3>CTRL-EVENT-SCAN-STARTED + <3>CTRL-EVENT-SCAN-RESULTS + <3>SME: Trying to authenticate with 00:xx:xx:5d:d9:26 (SSID='Network1' freq=5180 MHz) + <3>Trying to associate with 00:xx:xx:5d:d9:26 (SSID='Network1' freq=5180 MHz) + <3>Associated with 00:xx:xx:5d:d9:26 + <3>CTRL-EVENT-SUBNET-STATUS-UPDATE status=0 + <3>WPA: Key negotiation completed with 00:xx:xx:5d:d9:26 [PTK=CCMP GTK=CCMP] + <3>CTRL-EVENT-CONNECTED - Connection to 00:xx:xx:5d:d9:26 completed [id=0 id_str=] + +#. Save the configuration and quit out of :command:`wpa_cli`. + + .. code-block:: bash + + > save_config + OK + > quit + +.. note:: + + The network password is saved as plaintext in + :file:`/etc/wpa_supplicant/wpa_supplicant-$INTERFACE_NAME.conf`. Use + `wpa_passphrase + `_ + for a more secure method. + +Assign an IP address +==================== + +After the wireless adapter has been associated with wireless access point, an +IP address needs to be assigned for access to the network. + +The example below uses ``systemd-networkd`` to request an IP address from the +access point via DHCP. Another network manager can be used if preferred. If +there is a static IP address you'd like to assign, see the +:ref:`assign-static-ip` documentation. + +#. Create the :file:`/etc/systemd/network` directory + + .. code-block:: bash + + sudo mkdir -p /etc/systemd/network + +#. Create a :file:`/etc/systemd/network/25-wireless-$INTERFACE_NAME.network` file + with a Match and Network section. + + .. code-block:: bash + + printf "[Match]\nName=$INTERFACE_NAME\n\n[Network]\nDHCP=ipv4" | sudo tee /etc/systemd/network/25-wireless-$INTERFACE_NAME.network + +#. Restart the ``systemd-networkd.service``. + + .. code-block:: bash + + sudo systemctl restart systemd-networkd.service + + +#. Enable the ``systemd-networkd`` and ``wpa_supplicant`` services to start automatically + on future boots. + + .. code-block:: bash + + sudo systemctl enable --now systemd-networkd.service + sudo systemctl enable --now wpa_supplicant@$INTERFACE_NAME.service + + Other resources *************** * NetworkManager CLI `documentation `_. -* Additional CLI `examples `_. \ No newline at end of file +* Additional CLI `examples `_. +* wpa_supplicant `advanced usage documentation `_ diff --git a/source/guides/stacks/dbrs.rst b/source/guides/stacks/dbrs.rst index 39c318c0..6df4cfb5 100644 --- a/source/guides/stacks/dbrs.rst +++ b/source/guides/stacks/dbrs.rst @@ -619,7 +619,7 @@ To start a redisfailover instance in Kubernetes run the following .. _Quick Start Guide: https://software.intel.com/en-us/articles/quick-start-guide-configure-intel-optane-dc-persistent-memory-on-linux -.. _Managing NVDIMMs: https://docs.pmem.io/ndctl-users-guide/managing-nvdimms +.. _Managing NVDIMMs: https://docs.pmem.io/ndctl-user-guide/managing-nvdimms .. _Configure, Manage, and Profile: https://software.intel.com/en-us/articles/configure-manage-and-profile-intel-optane-dc-persistent-memory-modules diff --git a/source/guides/stacks/dlrs.rst b/source/guides/stacks/dlrs.rst index 80b6dd8c..dd9913f7 100644 --- a/source/guides/stacks/dlrs.rst +++ b/source/guides/stacks/dlrs.rst @@ -20,18 +20,15 @@ customized solutions, and enables you to quickly prototype and deploy Deep Learning workloads. Use this guide to run benchmarking workloads on your solution. -The Deep Learning Reference Stack is available in the following versions: +The latest release of the Deep Learning Reference Stack (`DLRS V5.0`_ ) supports the following features: -* `Intel MKL-DNN-VNNI`_, which is optimized using Intel® Math Kernel Library - for Deep Neural Networks (Intel® MKL-DNN) primitives and introduces support - for Intel® AVX-512 Vector Neural Network Instructions (VNNI). -* `Intel MKL-DNN`_, which includes the TensorFlow framework optimized using - Intel® Math Kernel Library for Deep Neural Networks (Intel® MKL-DNN) - primitives. -* `Eigen`_, which includes `TensorFlow`_ optimized for Intel® architecture. -* `PyTorch with OpenBLAS`_, which includes PyTorch with OpenBlas. -* `PyTorch with Intel MKL-DNN`_, which includes PyTorch optimized using Intel® - Math Kernel Library (Intel® MKL) and Intel MKL-DNN. +* TensorFlow* 1.15 and TensorFlow* 2.0, an end-to-end open source platform for machine learning (ML). +* PyTorch* 1.3, an open source machine learning framework that accelerates the path from research prototyping to production deployment. +* PyTorch Lightning* which is a lightweight wrapper for PyTorch designed to help researchers set up all the boilerplate state-of-the-art training. +* Transformers* , a state-of-the-art Natural Language Processing (NLP) for TensorFlow 2.0 and PyTorch. +* Intel® OpenVINO™ model server version 2019_R3, delivering improved neural network performance on Intel processors, helping unlock cost-effective, real-time vision applications. +* Intel Deep Learning Boost (DL Boost) with AVX-512 Vector Neural Network Instruction (Intel AVX-512 VNNI) designed to accelerate deep neural network-based algorithms. +* Deep Learning Compilers (TVM* 0.6), an end-to-end compiler stack. .. important:: @@ -41,9 +38,14 @@ The Deep Learning Reference Stack is available in the following versions: * Intel® AVX-512 images require an Intel® Xeon® Scalable Platform * VNNI requires a 2nd generation Intel® Xeon® Scalable Platform + Releases ******** +Refer to the `Deep Learning Reference Stack website`_ for information and download links for the different versions and offerings of the stack. + + +* `DLRS V5.0`_ release announcement. * `DLRS V4.0`_ release announcement, including benchmark results. * `DLRS V3.0`_ release announcement, including benchmark results. * `DLRS V2.0`_ including PyTorch benchmark results. @@ -60,7 +62,7 @@ Releases Version compatibility ===================== -We validated the steps in this guide against the following software package versions: +We validated the steps in this guide against the following software package versions, unless otherwise stated: * |CL| 26240 (Minimum supported version) * Docker 18.06.1 @@ -373,96 +375,8 @@ Submitting PyTorch Jobs ======================= We provide `DLRS PytorchJob`_ examples that use the Deep Learning Reference Stack as the base image for creating the container(s) that will run training workloads in your Kubernetes cluster. -Select one form the list below: -Using Kubeflow Seldon and OpenVINO* with the Deep Learning Reference Stack -************************************************************************** - -`Seldon Core`_ is an open source platform for deploying machine learning models on a Kubernetes cluster. Seldon Core is supported in the `DLRS V4.0`_ release. - -Pre-requisites -============== -* A running :ref:`kubernetes` cluster - -.. note:: - - Instead of using Arrikto's configuration manifest as shown in the preceding example, you should use the manifest provided by `Istio`_, for this example, as Seldon deployments depend on it. - -#. Install deployment tools - - .. code-block:: bash - - INSTALL_DIR=$HOME/install_dir - BIN_DIR=${INSTALL_DIR}/bin - SRC_DIR=${INSTALL_DIR}/source - export PATH=${BIN_DIR}:$PATH - - mkdir -p ${BIN_DIR} && mkdir ${SRC_DIR} - cd ${SRC_DIR} - -#. Install Helm* - - .. code-block:: bash - - wget https://get.helm.sh/helm-v2.14.3-linux-amd64.tar.gz && tar xf helm-v2.14.3-linux-amd64.tar.gz - mv linux-amd64/helm ${BIN_DIR}/helm - - -#. Clean the environment - - .. code-block:: bash - - rm -rf ${SRC_DIR}/* - -#. Prepare the DLRS image - - The DLRS base image needs to be rebuilt with the `Dockerfile_openvino_base`_ to add Seldon and the OpenVINO inference engine. - - .. code-block:: bash - - docker build -f Dockerfile_openvino_base -t dlrs_openvino_base:0.1 . - -#. Mount pre-trained models into a persistent volume - - This will also apply all PV manifests to the cluster - - .. code-block:: bash - - kubectl apply -f storage/pv-volume.yaml - kubectl apply -f storage/model-store-pvc.yaml - kubectl apply -f storage/pv-pod.yaml - -#. Start a shell for the container used as pv: - - .. code-block:: bash - - kubectl exec -it hostpath-pvc -- /bin/bash - -#. Save pre-trained models - - Now that you're inside the running container, fetch your pre-trained models and save them at `/opt/ml` - - .. code-block:: bash - - root@hostpath-pvc:/# cd /opt/ml - root@hostpath-pvc:/# # Copy your models here - root@hostpath-pvc:/# # exit - -#. Deploy the model server - - Now you're ready to deploy the model server using the Helm chart provided. - - .. code-block:: bash - - helm install -- name=seldonov-model-server \ - --namespace kubeflow \ - --set openvino.image=dlrs_openvino_base:0.1 \ - --set openvino.model.path=/opt/ml/ \ - --set openvino.model.name= \ - --set openvino.model.input=data \ - --set openvino.model.output=prob - dlrs-seldon/helm/seldon-model-server Using the Intel® OpenVINO Model Optimizer @@ -616,6 +530,138 @@ This example walks through the basic instructions for using the inference engine +Using Seldon and OpenVINO* model server with the Deep Learning Reference Stack +****************************************************************************** + +`Seldon Core`_ is an open source platform for deploying machine learning models on a Kubernetes cluster. In this section we will walk through using a Seldon server with OpenVINO to serve a model. + +Pre-requisites +============== +* A running :ref:`kubernetes` cluster +* An existing Kubeflow deployment +* Helm +* A pre-trained model + +Please refer to: + +* :ref:`kubernetes` +* `Getting Started with Kubeflow`_ +* `Installing Helm`_ + + +.. note:: + + This document was validated with Kubernetes v1.14.8, Kubeflow v0.7, and Helm v3.0.1 + +Prepare the model +================= + +There are several methods to add a model to a Seldon server; we will cover two of them. First a model will be stored in a persistent volume by creating a persistent volume claim and a pod, then copying the model into the pod. Second, a model will be built directly into the base image. Adding a model to a volume is perhaps more traditional in Kubernetes, but some cloud providers have access rules that disallow a private cluster, and adding the model to the image avoids the issue in that scenario. + + +Mount pre-trained models into a persistent volume +------------------------------------------------- + +We will create a small pod to get the model into a volume. + +#. Apply all PV manifests to the cluster + + .. code-block:: bash + + kubectl apply -f storage/pv-volume.yaml + kubectl apply -f storage/model-store-pvc.yaml + kubectl apply -f storage/pv-pod.yaml + +#. Use :command:`kubectl cp` to move the model into the pod, and therefore into the volume + + .. code-block:: bash + + kubectl cp ./ pv-pod:/home + +#. In the running container, fetch your pre-trained models and save them in the :file:`/opt/ml` directory path. + + .. code-block:: bash + + root@hostpath-pvc:/# cd /opt/ml + root@hostpath-pvc:/# # Copy your models here + root@hostpath-pvc:/# # exit + + + +Add the pre-trained model to the image +-------------------------------------- + +A custom DLRS image is provided to serve OpenVINO through Seldon. Add a curl command to download your publicly hosted model and save it in :file:`/opt/ml` in the container filesystem. For example, if you have a model on GCP, use this command: + + .. code-block:: bash + + curl -o "[SAVE_TO_LOCATION]" \ + "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]/o/[OBJECT_NAME]?alt=media" + + +Prepare the DLRS image +====================== + +A base image with Seldon and the OpenVINO inference engine should be created using the :file:`Dockerfile_openvino_base` dockerfile. + + .. code-block:: bash + + cd docker + docker build -f Dockerfile_openvino_base -t dlrs_openvino_base . + cd .. + + +Deploy the model server +======================= + +Now you're ready to deploy the model server using the Helm chart provided. + + .. code-block:: bash + + cd helm + helm install dlrs-seldon seldon-model-server \ + --namespace kubeflow \ + --set openvino.image=dlrs_openvino_base \ + --set openvino.model.path=/opt/ml \ + --set openvino.model.name= \ + --set openvino.model.input=data \ + --set openvino.model.output=prob + + +This will create your SeldonDeployment + +Extended example with Seldon using Source to Image +================================================== + +`Source to Image (s2i)`_ is a tool to create docker images from source code. + +#. Install source to image (s2i) + + .. code-block:: bash + + cd ${SRC-DIR} + wget https://github.com/openshift/source-to-image/releases/download/v1.1.14/source-to-image-v1.1.14-874754de-linux-amd64.tar.gz + tar xf source-to-image-v1.1.14-874754de-linux-amd64.tar.gz + mv s2i ${BIN_DIR}/s2i && ln -s s2i ${BIN_DIR}/sti + +#. Clone the seldon-core repository + + .. code-block:: bash + + git clone https://github.com/SeldonIO/seldon-core.git ${SRC_DIR}/seldon-core + +#. Create the new image + + Using the DLRS image created above, you can build another image for deploying the Image Transformer component that consumes imagenet classificatin models. + + .. code-block:: bash + + cd ${SRC_DIR}/seldon-core/examples/models/openvino_imagenet_ensemble/resources/transformer/ + s2i -E environment_grpc . dlrs_openvino_base:0.1 imagenet_transformer:0.1 + + Use this newly created image for deploying the Image Transformer component of the `OpenVino Imagenet Pipelines`_ example from Seldon. + + Use Jupyter Notebook ******************** @@ -829,7 +875,7 @@ Related topics .. _flannel: https://github.com/coreos/flannel -.. _Getting Started with Kubeflow: https://www.kubeflow.org/docs/started/getting-started/ +.. _Getting Started with Kubeflow: https://github.intel.com/verticals/usecases/blob/56717f4642ecd958dc93bbc361c551dfc578d3ed/kubeflow/README.md#getting-started-with-kubeflow .. _Eigen: https://hub.docker.com/r/clearlinux/stacks-dlrs-oss/ @@ -845,6 +891,8 @@ Related topics .. _DLRS V4.0: https://clearlinux.org/news-blogs/deep-learning-reference-stack-v4 +.. _DLRS V5.0: https://clearlinux.org/blogs-news/deep-learning-reference-stack-v50-now-available + .. _dlrs-tfjob: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow/dlrs-tfjob .. _Logging Architecture: https://kubernetes.io/docs/concepts/cluster-administration/logging/ @@ -861,7 +909,7 @@ Related topics .. _DLRS Terms of Use: https://clearlinux.org/stacks/deep-learning/terms-of-use -.. _DLRS Release notes: https://github.com/clearlinux/dockerfiles/blob/master/stacks/dlrs/releasenote.md +.. _DLRS Release notes: https://github.com/intel/stacks/tree/master/dlrs .. _Seldon Core: https://docs.seldon.io/projects/seldon-core/en/latest/ @@ -899,3 +947,11 @@ Related topics .. _DLRS TFJob: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow/dlrs-tfjob .. _DLRS PytorchJob: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow/dlrs-pytorchjob + +.. _Installing Helm: https://helm.sh/docs/intro/install/ + +.. _OpenVino Imagenet Pipelines: https://docs.seldon.io/projects/seldon-core/en/stable/examples/openvino_ensemble.html + +.. _Source to Image (s2i): https://docs.seldon.io/projects/seldon-core/en/latest/wrappers/s2i.html + +.. _Deep Learning Reference Stack website: https://clearlinux.org/stacks/deep-learning diff --git a/source/guides/stacks/index.rst b/source/guides/stacks/index.rst new file mode 100644 index 00000000..d60db977 --- /dev/null +++ b/source/guides/stacks/index.rst @@ -0,0 +1,9 @@ +.. _stacks-guides: + +Stacks +###### + +.. toctree:: + :glob: + + * \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index 002df3b9..f140bb68 100644 --- a/source/index.rst +++ b/source/index.rst @@ -53,27 +53,26 @@ .. container:: column featurecard - .. toctree:: - :caption: Documentation Contents - :maxdepth: 1 - - get-started/index - about - guides/index - tutorials/index - reference/index - FAQ/index - collaboration/collaboration - - **Need some help?** + **Community** | `Ask the Clear Linux experts `_ | `Clear Linux Forum `_ - | `IRC-based support `_ + | `Freenode IRC: #clearlinux `_ .. container:: video .. raw:: html - \ No newline at end of file + + +.. toctree:: + :hidden: + + get-started/index + about + guides/index + tutorials/index + reference/index + FAQ/index + collaboration/collaboration diff --git a/source/tutorials/multi-boot/dual-boot-linux.rst b/source/tutorials/multi-boot/dual-boot-linux.rst index 5c7bb770..ebda2fcf 100644 --- a/source/tutorials/multi-boot/dual-boot-linux.rst +++ b/source/tutorials/multi-boot/dual-boot-linux.rst @@ -1,14 +1,16 @@ .. _dual-boot-linux: -Dual-boot |CL-ATTR| with Another GRUB-based Linux\* Distro +Dual-boot |CL-ATTR| with Any GRUB-based Linux\* Distro ########################################################## -In this tutorial, we show how to install another GRUB-based Linux\* distro -alongside |CL|. To do so, we resize the existing Linux root partition to -make enough room to install |CL|. Then we configure the |CL| bootloader, -:command:`systemd-boot`, which enables you to dual-boot |CL| and an existing -Linux distro. Although we use Ubuntu\* 19.04 Desktop as the example here, -these instructions also work for other distros such as Mint Linux, Kubuntu\*, Fedora\*, CentOS\*, among others. +In this tutorial, we show how to install |CL| alongside any GRUB-based +Linux\* distro. To do so, we resize the existing Linux root partition to +make room to install |CL|. Then we show 3 methods to dual-boot |CL| +with an existing Linux distro. + +Although we use Ubuntu\* 19.04 Desktop as the example here, +these instructions also work for other distros such as Mint\*, Kubuntu\*, +Fedora\*, CentOS\*, among others. .. contents:: :local: @@ -37,6 +39,8 @@ Install |CL| with Advanced Installation #. Complete the :guilabel:`Required Options` until you reach :guilabel:`Select Installation Media`. See Figure 1. + .. rst-class:: dropshadow + .. figure:: ../../_figures/multi-boot/dual-boot-linux-01.png :scale: 100% :alt: Required options @@ -47,6 +51,8 @@ Install |CL| with Advanced Installation #. Select the “Advanced Installation” option. See Figure 2. + .. rst-class:: dropshadow + .. figure:: ../../_figures/multi-boot/dual-boot-linux-02.png :scale: 100% :alt: Advanced Installation @@ -60,6 +66,8 @@ Install |CL| with Advanced Installation a. Select the Ubuntu root partition (in this example: /dev/sda2). Right-click it and select “Resize/Move”. See Figure 3. + .. rst-class:: dropshadow + .. figure:: ../../_figures/multi-boot/dual-boot-linux-03.png :scale: 100% :alt: Ubuntu root partition @@ -76,6 +84,8 @@ Install |CL| with Advanced Installation The resulting free space appears in the “Free space following (MiB)”. Click the “Resize/Move” button. See Figure 4. + .. rst-class:: dropshadow + .. figure:: ../../_figures/multi-boot/dual-boot-linux-04.png :scale: 100% :alt: Resize Ubuntu root @@ -84,6 +94,8 @@ Install |CL| with Advanced Installation #. Click the green checkmark button to proceed. See Figure 5. + .. rst-class:: dropshadow + .. figure:: ../../_figures/multi-boot/dual-boot-linux-05.png :scale: 100% :alt: New unallocated space @@ -97,12 +109,16 @@ Install |CL| with Advanced Installation #. Set the name to “CLR_BOOT”. See Figure 6 and Figure 7. + .. rst-class:: dropshadow + .. figure:: ../../_figures/multi-boot/dual-boot-linux-06.png :scale: 100% :alt: Name CLR_BOOT partition Figure 6: Name CLR_BOOT partition + .. rst-class:: dropshadow + .. figure:: ../../_figures/multi-boot/dual-boot-linux-07.png :scale: 100% :alt: Resulting CLR_BOOT main screen @@ -122,6 +138,8 @@ Install |CL| with Advanced Installation #. Click the “Add” button. See Figure 8. + .. rst-class:: dropshadow + .. figure:: ../../_figures/multi-boot/dual-boot-linux-08.png :scale: 100% :alt: Create CLR_SWAP partition @@ -139,6 +157,8 @@ Install |CL| with Advanced Installation #. Click the “Add” button. See Figure 9. + .. rst-class:: dropshadow + .. figure:: ../../_figures/multi-boot/dual-boot-linux-09.png :scale: 100% :alt: Create CLR_ROOT partition @@ -148,6 +168,8 @@ Install |CL| with Advanced Installation #. Click the green checkmark button to create the newly-defined partitions. See Figure 10. + .. rst-class:: dropshadow + .. figure:: ../../_figures/multi-boot/dual-boot-linux-10.png :scale: 100% :alt: Partitions to be created @@ -157,6 +179,8 @@ Install |CL| with Advanced Installation #. Close the GParted window, and the |CL| installer will reappear with the newly-defined partitions to use. See Figure 11. + .. rst-class:: dropshadow + .. figure:: ../../_figures/multi-boot/dual-boot-linux-11.png :scale: 100% :alt: |CL| installer partitions defined @@ -166,23 +190,36 @@ Install |CL| with Advanced Installation #. Complete the remaining steps of :guilabel:`Required Options` to to install |CL|. Complete any :guilabel:`Advanced Options` as desired. -Ways to boot |CL| -***************** +Boot |CL| Using One of Three Methods +************************************ -Although we installed |CL| last, Ubuntu is still the default boot OS. There are several ways to boot |CL|: - -#. Use your BIOS “Boot Menu” to select and boot |CL|. - This is temporary and will not make |CL| the default boot OS. +Although we installed |CL| last, Ubuntu is still the default boot OS. +There are three methods to boot |CL|: #. Make systemd-boot, the boot loader that |CL| uses, the default - boot loader to boot |CL| and chain-boot GRUB; therefore, boot - Ubuntu. Follow the next section to implement this. + boot loader to boot |CL| and also chain-boot GRUB; therefore, boot + Ubuntu. See `boot-clr-method-1`_. -Make systemd-boot Default Bootloader and chain-boot GRUB -******************************************************** +#. Use GRUB to chain-boot systemd-boot, therefore boot |CL|. + See `boot-clr-method-2`_. + +#. Use your BIOS “Boot Menu” to select and boot |CL|. + Refer to your system's manual on how to bring up the "Boot Menu". + +.. _boot-clr-method-1: + +Method 1: Use systemd-boot to Boot |CL| and also Chain-boot GRUB +================================================================ + +systemd-boot is the bootloader used by |CL|. Because |CL| was installed +after a GRUB-based distro, GRUB is still the default bootloader. +In this method, we make systemd-boot the default bootloader instead and +also provide a path to chain-boot GRUB. #. Boot up the |CL| installer image. + #. Open a terminal window. + #. Identify the EFI system partition, Ubuntu root partition, and |CL| root partition. @@ -214,15 +251,15 @@ Make systemd-boot Default Bootloader and chain-boot GRUB The above example output contains these partitions: - * /dev/sda1 is the EFI system partition originally created by Ubuntu + * ``/dev/sda1`` is the EFI system partition originally created by Ubuntu and shared with |CL| - * /dev/sda2 is the Ubuntu root partition - * /dev/sda3 is the swap partition for |CL| - * /dev/sda4 is the |CL| root partition + * ``/dev/sda2`` is the Ubuntu root partition + * ``/dev/sda3`` is the swap partition for |CL| + * ``/dev/sda4`` is the |CL| root partition The remaining steps will work with these partitions. -#. Mount these partitions +#. Mount these partitions. .. code-block:: bash @@ -230,7 +267,7 @@ Make systemd-boot Default Bootloader and chain-boot GRUB sudo mount /dev/sda4 /mnt/clearlinux/ sudo mount /dev/sda1 /mnt/clearlinux/boot -#. Make systemd-boot the default bootloader +#. Make systemd-boot the default bootloader. .. code-block:: bash @@ -276,6 +313,110 @@ Make systemd-boot Default Bootloader and chain-boot GRUB Figure 12: systemd-boot menu showing GRUB +.. _boot-clr-method-2: + +Method 2: Use GRUB to Boot |CL| +=============================== + +In this method, we keep GRUB as the default bootloader, but configure it +to chain-boot systemd-boot, thus allowing us to boot |CL|. Again, we're using +Ubuntu as our working example. + +#. Boot up Ubuntu. + +#. Open a terminal window. + +#. Set a timeout value for the GRUB menu so it will be visible at boot time and + allow you select one which OS to boot. + + a. sudoedit :file:`/etc/default/grub` + + .. code-block:: bash + + sudoedit /etc/default/grub + + #. Set the ``GRUB_TIMEOUT`` variable to a desired value. + +#. Create a menu entry for systemd-boot bootloader. + + a. Identify the UUID for EFI system partition that systemd-boot resides on. + The example below shows the UUID for the EFI system on /dev/sda1 is + "A5A0-337D". + + .. code-block:: bash + + sudo blkid + + Example output: + + .. code-block:: console + :emphasize-lines: 1 + + /dev/sda1: UUID="A5A0-337D" TYPE="vfat" PARTLABEL="CLR_BOOT" PARTUUID="ee664fec-1ade-40d0-9ce4-c08805003c8d" + /dev/sda2: UUID="219969c5-1106-4e9f-b6f5-8188d7d94b8b" TYPE="ext4" PARTUUID="00bdf0dc-264d-493c-bf23-a85105011175" + /dev/sda3: UUID="65221b07-33cb-40b7-9812-ea484c7606c9" TYPE="swap" PARTLABEL="CLR_SWAP" PARTUUID="5a7926b4-bd11-4bad-b932-cc31c0a75d27" + /dev/sda4: UUID="0bedd545-58a7-4f34-b22a-c50bb4a1c2f5" TYPE="ext4" PARTLABEL="CLR_ROOT" PARTUUID="2d60cd03-5739-4cd5-adcc-51a107cde388" + + #. sudoedit :file:`/etc/grub.d/40_custom` and add a menu entry + for |CL| using UUID from the previous step (for example): + + .. code-block:: console + :linenos: + :emphasize-lines: 7-10 + + #!/bin/sh + exec tail -n +3 $0 + # This file provides an easy way to add custom menu entries. Simply type the + # menu entries you want to add after this comment. Be careful not to change + # the 'exec tail' line above. + + menuentry 'Clear Linux OS' { + search --fs-uuid --no-floppy --set=root A5A0-337D + chainloader (${root})/EFI/org.clearlinux/bootloaderx64.efi + } + + #. Update GRUB. + + .. code-block:: bash + + sudo update-grub + +#. Reboot. + +#. At the GRUB boot menu, select :guilabel:`Clear Linux OS` to boot |CL|. + +#. Log in. + +#. Open a terminal window. + +#. By default, any future calls to :command:`clr-boot-manager`, such as + after a kernel update by :command:`swupd` or setting the timeout + value for systemd-boot, will modify the UEFI boot order + which will result in making systemd-boot the first boot + entry and you won't be able to boot Ubuntu any longer. And in order + to boot Ubuntu first, you must change the UEFI boot order back. + To prevent :command:`clr-boot-manager` from touching the UEFI boot + order, which is especially important in a dual-boot setup, + follow these steps: + + .. code-block:: bash + + sudo mkdir -p /etc/kernel + sudo tee -a /etc/kernel/update_efi_vars << EOF + false + EOF + +.. tip:: + + The default installation of |CL| does not set a timeout value for + systemd-boot. Thus, you will not see the systemd-boot menu and the + default kernel will boot right away. + To set a timeout value (for example: 25 seconds), enter: + + .. code-block:: bash + + sudo clr-boot-manager set-timeout 25 + .. _download the live desktop image: https://clearlinux.org/downloads .. _Downloads: https://clearlinux.org/downloads diff --git a/source/tutorials/multi-boot/multi-boot.rst b/source/tutorials/multi-boot/multi-boot.rst index 44bb5042..5f4d2ce7 100644 --- a/source/tutorials/multi-boot/multi-boot.rst +++ b/source/tutorials/multi-boot/multi-boot.rst @@ -17,4 +17,4 @@ Detailed procedures :maxdepth: 1 dual-boot-win - + dual-boot-linux diff --git a/source/tutorials/yubikey-u2f.rst b/source/tutorials/yubikey-u2f.rst index 3d3c9805..2a8c1e89 100644 --- a/source/tutorials/yubikey-u2f.rst +++ b/source/tutorials/yubikey-u2f.rst @@ -18,7 +18,7 @@ One-Time Password (OTP), Smart card, FIDO2, and Universal 2nd Factor (U2F). A list of `websites that accept U2F authentication with the YubiKey`_ is available on the Yubico website. See the Yubico website to learn more about -the Yubikey: https://www.yubico.com/getstarted/meet-the-yubikey/ +the Yubikey: https://www.yubico.com/getstarted/ Prerequisites *************