{% 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
*************