diff --git a/source/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst b/source/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst index e6aa1a42..25d1ada5 100644 --- a/source/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst +++ b/source/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst @@ -3,18 +3,18 @@ Install |CL-ATTR| from the live desktop ####################################### -The live desktop allows you to boot |CL-ATTR| in a GNOME desktop without -modifying the host system, offering you the chance to explore developing -on |CL| or install it. In this document, we show how to install |CL| on a -target system. +This page explains how to boot the |CL-ATTR| live desktop image, from which +you can install |CL| or explore without modifying the host system. -.. contents:: :local: +.. contents:: + :local: :depth: 1 System requirements ******************* -Assure that your target system supports the installation: +Before installing |CL|, verify that the host system supports the +installation: * :ref:`system-requirements` * :ref:`compatibility-check` @@ -22,7 +22,7 @@ Assure that your target system supports the installation: Preliminary steps ***************** -#. `Visit our Downloads page`_. +#. Visit our `Downloads`_ page. #. Download the file :file:`clear--live-desktop.iso`, also called the |CL| Desktop. @@ -31,6 +31,10 @@ Preliminary steps is the latest |CL| auto-numbered release. +#. Verify and decompress the file per your OS. + + * :ref:`download-verify-decompress` + #. Follow your OS instructions to create a bootable USB drive. * :ref:`bootable-usb` @@ -72,12 +76,13 @@ Software (optional) Explore |CL| bundles and other software. Double-click the :guilabel:`Software` icon from the Activities menu, shown in Figure 2. -Assure a network connection exists before launching `Software`. +Ensure a network connection exists before launching the Software application. .. note:: - `Software` application is *only intended for exploring* available bundles, - applications, and images. Do not attempt to install them. + While running the |CL| live desktop image, the Software application is + intended only for exploration. Do not attempt to install applications during + exploration. Launch the |CL| installer ========================= @@ -517,26 +522,21 @@ Create partitions per requirements in Table 1. - Mount Point - Default size - * - ``VFAT(FAT32)`` + * - **VFAT(FAT32)** - boot - /boot - 150MB - * - ``linux-swap`` + * - **linux-swap** - swap - - 256MB - * - ``ext[234] or XFS`` + * - **ext[234] or XFS** - root - / - *Size depends upon use case/desired bundles.* -Next steps -********** - -:ref:`guides` - -.. _Visit our downloads page: https://clearlinux.org/downloads +.. _Downloads: https://clearlinux.org/downloads diff --git a/source/get-started/bare-metal-install-server/bare-metal-install-server.rst b/source/get-started/bare-metal-install-server/bare-metal-install-server.rst index b6ad7c4f..7e0225de 100644 --- a/source/get-started/bare-metal-install-server/bare-metal-install-server.rst +++ b/source/get-started/bare-metal-install-server/bare-metal-install-server.rst @@ -3,7 +3,8 @@ Install |CL-ATTR| on bare metal with live server ################################################ -These instructions guide you through installing |CL-ATTR| on bare metal from a bootable USB drive using a live server image. +This page explains how to install |CL-ATTR| on bare metal from a bootable USB +drive using a live server image. .. contents:: :local: @@ -12,7 +13,8 @@ These instructions guide you through installing |CL-ATTR| on bare metal from a b System requirements ******************* -Assure that your target system supports the installation: +Before installing |CL|, verify that the host system supports the +installation: * :ref:`system-requirements` * :ref:`compatibility-check` @@ -23,12 +25,14 @@ Download the latest |CL| live server image Get the latest |CL| installer image from the `Downloads`_ page. Look for the :file:`clear-[version number]-live-server.iso` file. +#. Verify and decompress the file per your OS. + + * :ref:`download-verify-decompress` + #. Follow your OS instructions to create a bootable USB drive. * :ref:`bootable-usb` -#. After downloading the image, verify and decompress the file per your OS. - Install |CL| on your target system ********************************** @@ -817,23 +821,29 @@ Finish installation Default partition schema ======================== -To add partitions manually, see `Advanced configuration`_ below, and create -partitions per requirements in Table 1. +Create partitions per requirements in Table 1. -.. list-table:: **Table 1. Disk Partition Setup** - :widths: 33, 33, 33 +.. list-table:: **Table 1. Default partition schema** + :widths: 25, 25, 25, 25 :header-rows: 1 * - FileSystem + - Label - Mount Point - - Minimum size - * - ``VFAT`` + - Default size + + * - ``VFAT(FAT32)`` + - boot - /boot - - 150M - * - ``swap`` + - 150MB + + * - ``linux-swap`` + - swap - - 256MB - * - ``root`` + + * - ``ext[234] or XFS`` + - root - / - *Size depends upon use case/desired bundles.* @@ -856,5 +866,4 @@ entering :guilabel:`Configure Installation Media`: - Windows\* OS: :command:`diskpart`, then :command:`list disk` - macOS\* platform: :command:`diskutil list` -.. _Autoproxy: https://clearlinux.org/features/autoproxy .. _Downloads: https://clearlinux.org/downloads diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-01.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-01.png index 69b6a24e..23ba879a 100644 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-01.png and b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-01.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-02.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-02.png index 3f1833c7..89ad86e6 100644 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-02.png and b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-02.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-03.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-03.png index 2fbe4cea..e037b30e 100644 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-03.png and b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-03.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-04.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-04.png index 6a01685f..ea4d9f69 100644 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-04.png and b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-04.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-05.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-05.png index a0bd62a2..27147973 100644 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-05.png and b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-05.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-06.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-06.png index eeb4b36e..d8157359 100644 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-06.png and b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-06.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-07.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-07.png index 0a86cdbb..89686569 100644 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-07.png and b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-07.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-08.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-08.png index 4f46b24e..891e3366 100644 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-08.png and b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-08.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-09.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-09.png index 7d2111fa..0644ac29 100644 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-09.png and b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-09.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-10.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-10.png index 7ef566b2..4f6687c7 100644 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-10.png and b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-10.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-11.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-11.png index 2387eb46..1eba9c88 100644 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-11.png and b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-11.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-12.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-12.png deleted file mode 100644 index 7ea29cc7..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-12.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-13.png b/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-13.png deleted file mode 100644 index 7d2111fa..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-13.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/vmw-player-preconf.rst b/source/get-started/virtual-machine-install/vmw-player-preconf.rst index 0e2287d2..a9dc90cb 100644 --- a/source/get-started/virtual-machine-install/vmw-player-preconf.rst +++ b/source/get-started/virtual-machine-install/vmw-player-preconf.rst @@ -69,13 +69,12 @@ this command: Visit :ref:`image-types` for additional information about all available |CL| images. -.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst +.. include:: ../../guides/maintenance/download-verify-decompress.rst :Start-after: verify-windows: We also provide instructions for other operating systems: * :ref:`download-verify-decompress-linux` -* :ref:`download-verify-decompress-mac` Create and configure a new VM ***************************** @@ -307,8 +306,3 @@ For other guides on using the VMWare Player and ESXi, see: .. _VMware ESXi: https://www.vmware.com/products/esxi-and-esx.html .. _VMware Workstation 14 Player: https://www.vmware.com/products/workstation-player.html .. _VMware Workstation Player Documentation: https://docs.vmware.com/en/VMware-Workstation-Player/index.html -.. _image: https://cdn.download.clearlinux.org/image - - - - diff --git a/source/get-started/virtual-machine-install/vmw-player.rst b/source/get-started/virtual-machine-install/vmw-player.rst index af317287..a1028274 100644 --- a/source/get-started/virtual-machine-install/vmw-player.rst +++ b/source/get-started/virtual-machine-install/vmw-player.rst @@ -4,7 +4,7 @@ Install |CL-ATTR| as a VMware\* Workstation Player guest OS ########################################################### This page explains how to create a new VM and install |CL| on it with the -VMware Workstation 14 Player hypervisor. +VMware Workstation Player hypervisor. .. contents:: :local: @@ -13,16 +13,10 @@ VMware Workstation 14 Player hypervisor. Overview ******** -`VMware Workstation 14 Player`_ is a type 2 hypervisor. It runs on top of -another operating system such as Windows\* or Linux\*. With VMware ESXi, you can -create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)` on -your local system. - -Installing |CL| into a new VM provides you flexibility when configuring the VM. -You can configure the VM's size, number of partitions, installed bundles, etc. - -If you prefer to use a pre-configured |CL| VMware image instead, see our -:ref:`vmw-player-preconf` guide. +`VMware Workstation Player`_ is a type 2 hypervisor. It runs on top of +Windows\* or Linux\* operating systems. With VMware ESXi, you can +create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)` +on your local system. VMware offers a type 1 hypervisor called `VMware ESXi`_ designed for the cloud environment. For information on how to install |CL| as guest OS on @@ -30,8 +24,12 @@ it, see :ref:`vmware-esxi-install-cl`. .. note:: - Screenshots in this document show VMware Workstation 14 Player for Windows. - Menus and prompts in the Linux version have minor wording differences. + The screenshots on this document show the Windows version of the + VMware Workstation 15 Player. The menus and prompts are similar to those + in other versions and for the Linux OS save some minor wording differences. + +If you prefer to use a pre-configured |CL| VMware image instead, +see our :ref:`vmw-player-preconf` guide. Install the VMware Workstation Player hypervisor ************************************************ @@ -40,10 +38,15 @@ Install the VMware Workstation Player hypervisor :abbr:`Intel® VT-d (Intel® Virtualization Technology for Directed I/O)` in your system's BIOS. -#. `VMware Workstation 14 Player`_ is available for Windows and Linux. +#. `VMware Workstation Player`_ is available for Windows and Linux. Download your preferred version. -#. Install VMware Workstation 14 Player following the instructions + .. note:: + + By default, selecting download means you receive the latest version + of this application. Commands may differ based on the version. + +#. Install VMware Workstation Player following the instructions appropriate for your system's OS: * On supported Linux distros: @@ -64,21 +67,15 @@ Install the VMware Workstation Player hypervisor For additional help, see the `VMware Workstation Player Documentation`_. -Download the latest |CL| installer ISO -************************************** +Download the latest |CL| installer +********************************** -Get the latest |CL| installer ISO image from the `image`_ repository. -Look for :file:`clear-[version number]-installer.iso.xz`. +Get the latest installer with |CL| OS Desktop from the `downloads`_ page. Visit :ref:`image-types` for additional information about all available |CL| images. -.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst - :Start-after: verify-windows: - -We also provide instructions for other operating systems: - -* :ref:`download-verify-decompress-linux` -* :ref:`download-verify-decompress-mac` +We also provide instructions for downloading and verifying a Clear Linux ISO. +For more information, refer to :ref:`download-verify-decompress`. Create and configure a new VM ***************************** @@ -90,9 +87,9 @@ Create and configure a new VM .. figure:: figures/vmw-player/vmw-player-01.png :scale: 100% - :alt: VMware Workstation 14 Player - Create a new virtual machine + :alt: VMware Workstation Player - Create a new virtual machine - Figure 1: VMware Workstation 14 Player - Create a new virtual + Figure 1: VMware Workstation Player - Create a new virtual machine #. On the :guilabel:`Welcome to the New Virtual Machine Wizard` screen, @@ -101,9 +98,9 @@ Create and configure a new VM .. figure:: figures/vmw-player/vmw-player-02.png :scale: 100% - :alt: VMware Workstation 14 Player - Select |CL| installer ISO + :alt: VMware Workstation Player - Select |CL| installer ISO - Figure 2: VMware Workstation 14 Player - Select |CL| installer ISO + Figure 2: VMware Workstation Player - Select |CL| installer ISO #. Click the :guilabel:`Browse` button and select the decompressed |CL| installer ISO. @@ -116,13 +113,13 @@ Create and configure a new VM .. figure:: figures/vmw-player/vmw-player-03.png :scale: 100% - :alt: VMware Workstation 14 Player - Select guest operating system type + :alt: VMware Workstation Player - Select guest operating system type - Figure 3: VMware Workstation 14 Player - Select guest operating system + Figure 3: VMware Workstation Player - Select guest operating system type #. Set the :guilabel:`Version` setting to - :guilabel:`Other Linux 3.x or later kernel 64-bit`. + :guilabel:`Other Linux 4.x or later kernel 64-bit`. #. Click the :guilabel:`Next` button. @@ -131,9 +128,9 @@ Create and configure a new VM .. figure:: figures/vmw-player/vmw-player-04.png :scale: 100% - :alt: VMware Workstation 14 Player - Name virtual machine + :alt: VMware Workstation Player - Name virtual machine - Figure 4: VMware Workstation 14 Player - Name virtual machine + Figure 4: VMware Workstation Player - Name virtual machine #. Click the :guilabel:`Next` button. @@ -142,13 +139,14 @@ Create and configure a new VM .. figure:: figures/vmw-player/vmw-player-05.png :scale: 100% - :alt: VMware Workstation 14 Player - Set disk capacity + :alt: VMware Workstation Player - Set disk capacity - Figure 5: VMware Workstation 14 Player - Set disk capacity + Figure 5: VMware Workstation Player - Set disk capacity .. note:: - A minimal |CL| installation can exist on 600MB of drive space. - See :ref:`system-requirements` for more details. + + For optimal performance with the |CL| Desktop image, we recommend 32GB + of drive space. See :ref:`system-requirements` for more details. #. Click the :guilabel:`Next` button. @@ -157,17 +155,17 @@ Create and configure a new VM .. figure:: figures/vmw-player/vmw-player-06.png :scale: 100% - :alt: VMware Workstation 14 Player - Customize hardware + :alt: VMware Workstation Player - Customize hardware - Figure 6: VMware Workstation 14 Player - Customize hardware + Figure 6: VMware Workstation Player - Customize hardware #. Select :guilabel:`Memory` and set the size to 2GB. See Figure 7. .. figure:: figures/vmw-player/vmw-player-07.png :scale: 100% - :alt: VMware Workstation 14 Player - Set memory size + :alt: VMware Workstation Player - Set memory size - Figure 7: VMware Workstation 14 Player - Set memory size + Figure 7: VMware Workstation Player - Set memory size .. note:: The |CL| installer ISO needs a minimum of 2GB of RAM. @@ -180,9 +178,9 @@ Create and configure a new VM .. figure:: figures/vmw-player/vmw-player-08.png :scale: 100% - :alt: VMware Workstation 14 Player - Set virtualization engine option + :alt: VMware Workstation Player - Set virtualization engine option - Figure 8: VMware Workstation 14 Player - Set virtualization engine + Figure 8: VMware Workstation Player - Set virtualization engine option #. Under the :guilabel:`Virtualization engine` section, @@ -200,9 +198,9 @@ Install |CL| into the new VM .. figure:: figures/vmw-player/vmw-player-09.png :scale: 100% - :alt: VMware Workstation 14 Player - Power on virtual machine + :alt: VMware Workstation Player - Power on virtual machine - Figure 9: VMware Workstation 14 Player - Power on virtual machine + Figure 9: VMware Workstation Player - Power on virtual machine #. Follow the :ref:`install-on-target-start` guide to complete the installation of |CL|. @@ -221,67 +219,61 @@ Detach the |CL| installer ISO from the VM .. figure:: figures/vmw-player/vmw-player-10.png :scale: 100% - :alt: VMware Workstation 14 Player - Edit CD/DVD settings + :alt: VMware Workstation Player - Edit CD/DVD settings - Figure 10: VMware Workstation 14 Player - Edit CD/DVD settings + Figure 10: VMware Workstation Player - Edit CD/DVD settings -#. Go to :menuselection:`Removable Devices-->CD/DVD (IDE)-->Settings`. - -#. On the :guilabel:`Device status` section, uncheck the - :guilabel:`Connected` and the :guilabel:`Connect at power on` settings. - See Figure 11. - - .. figure:: figures/vmw-player/vmw-player-11.png - :scale: 100% - :alt: VMware Workstation 14 Player - Disconnect CD/DVD - - Figure 11: VMware Workstation 14 Player - Disconnect CD/DVD +#. Go to :menuselection:`Removable Devices-->CD/DVD (IDE)-->Disconnect`. #. Click the :guilabel:`OK` button. -#. To power off the VM, click the :guilabel:`Player` menu. See Figure 12. - - .. figure:: figures/vmw-player/vmw-player-12.png - :scale: 100% - :alt: VMware Workstation 14 Player - Power off virtual machine - - Figure 12: VMware Workstation 14 Player - Power off virtual machine - -#. Go to :guilabel:`Power` and select :guilabel:`Shut Down Guest`. - Enable UEFI boot support ************************ -|CL| needs UEFI support to boot. To enable UEFI, add the -following line to the end of your VM's :file:`.vmx` file: +|CL| needs UEFI support to boot. To enable UEFI: -.. code-block:: console +#. Power off the VM. click the :guilabel:`Player` menu. See Figure 11. - firmware = "efi" - -.. note:: - - Depending on the OS, you can typically find the VMware VM files under: - - * On Linux distros: :file:`/home/username/vmware` - * On Windows: :file:`C:\\Users\\username\\Documents\\Virtual Machines` - -Power on the VM -*************** - -After configuring the settings above, power on your |CL| virtual machine. - -#. On the :guilabel:`VMware Workstation Player` home screen, select your - VM. See Figure 13. - - .. figure:: figures/vmw-player/vmw-player-13.png + .. figure:: figures/vmw-player/vmw-player-11.png :scale: 100% - :alt: VMware Workstation 14 Player - Power on virtual machine + :alt: VMware Workstation Player - Power off virtual machine - Figure 13: VMware Workstation 14 Player - Power on virtual machine + Figure 11: VMware Workstation Player - Power off virtual machine + +#. Go to :guilabel:`Power` and select :guilabel:`Shut Down Guest`. + +#. Add the following line to the end of your VM's :file:`.vmx` file: + + .. code-block:: console + + firmware = "efi" + + .. note:: + + Depending on the OS, you can typically find the VMware VM files under: + + * On Linux distros: :file:`/home/username/vmware` + * On Windows: :file:`C:\\Users\\username\\Documents\\Virtual Machines` + + +#. After configuring the settings above, power on your |CL| virtual machine. + On the :guilabel:`VMware Workstation Player` home screen, select your + VM. See Figure 9. #. Click :guilabel:`Play virtual machine`. +#. Install Open VM Tools. You may want to install the `open-vm-tools` in + your virtual machine. The Open Virtual Machine Tools (open-vm-tools) are + the open source implementation of VMware Tools for Linux guest operating + systems. In |CL| you can use the following to install the bundle in your VM + + .. code-block:: console + + sudo swupd bundle-add os-cloudguest-vmware + sudo systemctl enable --now open-vm-tools + +More information is available on the `VMWare Tools Product Documentation`_ site. + Related topics ************** @@ -293,10 +285,12 @@ For other guides on using the VMWare Player and ESXi, see: .. _VMware ESXi: https://www.vmware.com/products/esxi-and-esx.html -.. _VMware Workstation 14 Player: +.. _VMware Workstation Player: https://www.vmware.com/products/workstation-player.html .. _VMware Workstation Player Documentation: https://docs.vmware.com/en/VMware-Workstation-Player/index.html -.. _image: https://cdn.download.clearlinux.org/image +.. _downloads: https://clearlinux.org/downloads + +.. _VMWare Tools Product Documentation: https://docs.vmware.com/en/VMware-Tools/10.1.0/com.vmware.vsphere.vmwaretools.doc/GUID-8B6EA5B7-453B-48AA-92E5-DB7F061341D1.html diff --git a/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst b/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst index ac7129fa..902548a4 100644 --- a/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst +++ b/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst @@ -38,14 +38,8 @@ Download the latest |CL| installer ISO Get the latest |CL| installer ISO image from the `image`_ repository. Look for :file:`clear-[version number]-installer.iso.xz`. -.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst - :Start-after: incl-decompress-image: - :end-before: incl-decompress-image-end: - -For alternative instructions on other operating systems, see: - -* :ref:`download-verify-decompress-mac` -* :ref:`download-verify-decompress-windows` +We also provide instructions for downloading and verifying a Clear Linux ISO. +For more information, refer to :ref:`download-verify-decompress`. Upload the |CL| installer ISO to the VMware server ************************************************** diff --git a/source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst b/source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst index 373c545f..f19165d5 100644 --- a/source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst +++ b/source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst @@ -41,14 +41,8 @@ this command: Visit :ref:`image-types` for additional information about all available |CL| images. -.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst - :Start-after: incl-decompress-image: - :end-before: incl-decompress-image-end: - -For alternative instructions on other operating systems, see: - -* :ref:`download-verify-decompress-mac` -* :ref:`download-verify-decompress-windows` +We also provide instructions for downloading and verifying a Clear Linux ISO. +For more information, refer to :ref:`download-verify-decompress`. Upload the |CL| image to the VMware server ****************************************** @@ -107,10 +101,10 @@ hypervisor. The steps in this section can also be referenced from the VMware documentation on `Cloning and converting virtual machine disks with vmkfstools`_ #. SSH into the `vSphere Management Assistant`_ appliance that is managing - the ESXi host or connect to the vSphere hosting using the `vSphere CLI`_. - + the ESXi host or connect to the vSphere hosting using the `vSphere CLI`_. + .. note:: - + If there is no :abbr:`vMA (vSphere Management Assistant)` appliance or :abbr:`vCLI (vSphere CLI)` configured and available, you can temporarily enable SSH directly on the ESXi host by following the steps described in `Enable the Secure Shell (SSH) in the VMware Host Client`_ . diff --git a/source/guides/deploy-at-scale.rst b/source/guides/deploy-at-scale.rst index 938c47f8..3c5270c8 100644 --- a/source/guides/deploy-at-scale.rst +++ b/source/guides/deploy-at-scale.rst @@ -3,30 +3,33 @@ Deploy at Scale ############### -Once you are comfortable with |CL-ATTR| :ref:`concepts `, your -next step as a system administrator is to understand how to deploy |CL| -at scale in your environment. - -In this document the term *endpoint* refers to a system targeted for -|CL| installation, whether that is a datacenter system or unit deployed in -field. - -.. note:: - - This is not a replacement or blueprint for designing your own IT - operating environment. - - Your |CL| deployment should complement the existing environment and - available tools. It is assumed foundational core IT dependencies of your - environment, such as your network, are healthy and scaled to suit the - deployment. +This guide describes deployment considerations and strategies when deploying +|CL-ATTR| at scale in your environment. .. contents:: :local: - :depth: 2 + :depth: 1 -Pick a |CL| usage and update strategy -===================================== +Overview +******** + +In this guide the term *endpoint* refers to a system targeted for |CL| +installation, whether that is a datacenter system or unit deployed in field. + +.. note:: + + This guide is not a replacement or blueprint for designing your own IT + operating environment. + + Implementation details for a scale deployment are beyond the scope of this + guide. + + Your |CL| deployment should complement your existing environment and + available tools. It is assumed core IT dependencies of your environment, + such as your network, are healthy and scaled to suit the deployment. + +Pick a usage and update strategy +******************************** Different business scenarios call for different deployment methodologies. |CL| offers the flexibility to continue consuming the upstream |CL| @@ -36,27 +39,27 @@ act as your own :abbr:`OSV (Operating System Vendor)`. Below is an overview of some considerations. Create your own Linux distribution (mix) ----------------------------------------- +======================================== This approach forks away from the |CL| upstream and has you act as your own -:abbr:`OSV (Operating System Vendor)` by leveraging the `mixer process`_ to +:abbr:`OSV (Operating System Vendor)` by leveraging the :ref:`mixer` process to create customized images based on |CL|. This is a level of responsibility that requires having more infrastructure and processes to adopt. In return, -this approach *offers you a high degree of control and customization*. +this approach *offers you a high degree of control and customization*. Consider: * Development systems that generate bundles and updates should have - sufficient performance for the task and separate from the swupd update + sufficient performance for the task and be separate from the swupd update webservers that serve update content to production machines. -* swupd update webservers that serve update content to - production machines (see `mixer process`_ for more information) should be - appropriately scaled. +* swupd update webservers that serve update content to production machines + should be appropriately scaled. Specific implementation details for a scalable, + resilient web server are beyond the scope of this document. - Your swupd update server is just like any other web application. - |WEB-SERVER-SCALE| + (See :ref:`mixer` for more information about update servers.) Adopt an agile methodology --------------------------- +========================== + The cloud, and other scaled deployments, are all about flexibility and speed. It only makes sense that any |CL| deployment strategy should follow suit. @@ -76,48 +79,47 @@ other software development lifecycle. Below are some pointers: * Setup a path to production for building |CL| based images. At minimum this should include: - * A development clr-on-clr environment to test building packages and - bundles for |CL| systems. + * A development clr-on-clr environment to test building packages and + bundles for |CL| systems. - * A pre-production environment to deploy |CL| versions to before - production + * A pre-production environment to deploy |CL| versions to before + production * Employ a continuous integration and continuous deployment (CI/CD) philosophy in order to: - - Automatically pull custom packages as they are updated from their - upstream projects or vendors. + - Automatically pull custom packages as they are updated from their + upstream projects or vendors. - - Generate |CL| bundles and potentially bootable images with your - customizations, if any. + - Generate |CL| bundles and potentially bootable images with your + customizations, if any. - - Measure against metrics and indicators which are relevant to your - business (e.g. performance, power, etc) from release to release. + - Measure against metrics and indicators which are relevant to your + business (e.g. performance, power, etc) from release to release. - - Integrate with your organization's governance processes, such as change - control. + - Integrate with your organization's governance processes, such as change + control. -Versioning Infrastructure -------------------------- +Versioning infrastructure +========================= |CL| version numbers are very important as they apply to the whole -infrastructure stack from OS components to libraries and -applications. +infrastructure stack from OS components to libraries and applications. -Good record keeping is important, so you should keep a detailed registry -and history of previously deployed versions and their contents. +Good record keeping is important, so you should keep a detailed registry and +history of previously deployed versions and their contents. -With a glance at the |CL| version numbers deployed, you should be -able to tell if your Clear systems are patched against a -particular security vulnerability or incorporate a critical new feature. +With a glance at the |CL| version numbers deployed, you should be able to +tell if your Clear systems are patched against a particular security +vulnerability or incorporate a critical new feature. Pick an image distribution strategy -=================================== +*********************************** Once you have decided on a usage and update strategy, you should understand -*how* |CL| will be deployed to your endpoints. In a large scale -deployment, interactive installers should be avoided in favor of automated -installations or prebuilt images. +*how* |CL| will be deployed to your endpoints. In a large scale deployment, +interactive installers should be avoided in favor of automated installations +or prebuilt images. There are many well-known ways to install an operating system at scale. Each have their own benefits, and one may lend itself easier in your environment @@ -127,41 +129,40 @@ See the available :ref:`image-types`. Below are some common ways to install |CL| to systems at scale: -Baremetal ---------- +Bare metal +========== -Preboot Execution Environments (PXE) or other -out-of-band booting options are one way to distribute |CL| -to physical baremetal systems on a LAN. +Preboot Execution Environments (PXE) or other out-of-band booting options are +one way to distribute |CL| to physical bare metal systems on a LAN. This option works well if your customizations are fairly small in size and infrastructure can be stateless. -The |CL| `downloads page`_ offers a live image that can be deployed as +The |CL| `Downloads`_ page offers a live image that can be deployed as a PXE boot server if one doesn't already exist in your environment. Also see documentation on how to :ref:`bare-metal-install-server`. -Cloud Instances or Virtual Machines ------------------------------------ +Cloud instances or virtual machines +=================================== Image templates in the form of cloneable disks are an effective way to distribute |CL| for virtual machine environments, whether on-premises or hosted by a Cloud Solution Provider (CSP). -When used in concert with cloud VM migration features, -this can be a good option for allowing your applications a degree of high -availability and workload mobility; VMs can be restarted on a cluster of -hypervisor host or moved between datacenters transparently. +When used in concert with cloud VM migration features, this can be a good option +for allowing your applications a degree of high availability and workload +mobility; VMs can be restarted on a cluster of hypervisor host or moved between +datacenters transparently. -The |CL| `downloads page`_ offers example prebuilt VM images and is -readily available on popular CSPs. Also see -documentation on how to :ref:`virtual-machine-install`. +The |CL| `Downloads`_ page offers example prebuilt VM images and is readily +available on popular CSPs. Also see documentation on how to +:ref:`virtual-machine-install`. Containers ----------- +========== -Containerization platforms allow images to be pulled from a -repository and deployed repeatedly as isolated containers. +Containerization platforms allow images to be pulled from a repository and +deployed repeatedly as isolated containers. Containers with a |CL| image can be a good option to blueprint and ship your application, including all its dependencies, as an artifact while @@ -170,16 +171,17 @@ applications. |CL| is capable of running a Docker host, has a container image which can be pulled from DockerHub, or can be built as a customized container. -For more information visit the `containers page`_. +For more information visit the `Containers`_ page. Considerations with stateless systems -===================================== +************************************* + An important |CL| concept is statelessness and partitioning of system data from user data. This concept can change the way you think about an at scale deployment. Backup strategy ---------------- +=============== A |CL| system and its infrastructure should be considered a commodity and be easily reproducible. Avoid focusing on backing up the operating system @@ -187,16 +189,16 @@ itself or default values. Instead, focus on backing up what's important and unique - the application and data. In other words, only focus on backing up critical areas like -`/home`, `/etc`, and `/var`. +:file:`/home`, :file:`/etc`, and :file:`/var`. -Meaningful Logging & Telemetry ------------------------------- +Meaningful logging & telemetry +============================== Offload logging and telemetry from endpoints to external servers, so it is persistent and can be accessed on another server when an issue occurs. * Remote syslogging in |CL| is available through the - `systemd journal-remote service`_ + `systemd-journal-remote.service`_ * |CL| offers a :ref:`telem-guide`, which can be a powerful tool for a large deployment to quickly crowdsource issues of interest. Take @@ -204,11 +206,12 @@ persistent and can be accessed on another server when an issue occurs. and the kind of data that would be valuable, and expose events appropriately. - Your telemetry server is just like any other web application. - |WEB-SERVER-SCALE| + Like any web server, the telemetry server should be appropriately scaled and + resilient. Specific implementation details for a scalable, resilient web + server are beyond the scope of this document. -Orchestration and Configuration Management ------------------------------------------- +Orchestration and configuration management +========================================== In cloud environments, where systems can be ephemeral, being able to configure and maintain generic instances is valuable. @@ -217,8 +220,8 @@ configure and maintain generic instances is valuable. through the *os-cloudguest* bundles which allow you to configure many Day 1 tasks such as setting hostname, creating users, or placing SSH keys in an automated way at boot. For more information on -automating configuration during deployment of |CL| endpoints see -the `documentation on bulk provisioning`_ . +automating configuration during deployment of |CL| endpoints see the +:ref:`bulk-provision` guide. A configuration management tool is useful for maintaining consistent system and application-level configuration. Ansible\* is offered through the @@ -226,7 +229,7 @@ and application-level configuration. Ansible\* is offered through the tool. Cloud-native applications -------------------------- +========================= An Infrastructure OS can design for good behavior, but it is ultimately up to applications to make agile design choices. Applications deployed @@ -239,13 +242,10 @@ Continuously test its use; Automate its use by redeploying |CL| and application on new hosts. This naturally minimizes configuration drift, challenges your monitoring systems, and business continuity plans. -.. _`mixer process`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/mixer -.. _`downloads page`: https://clearlinux.org/downloads/ -.. _`containers page`: https://clearlinux.org/downloads/containers -.. _`systemd journal-remote service`: https://www.freedesktop.org/software/systemd/man/systemd-journal-remote.service.html -.. _`native telemetry solution`: https://clearlinux.org/features/telemetry +.. _`Downloads`: https://clearlinux.org/downloads/ +.. _`Containers`: https://clearlinux.org/downloads/containers +.. _`systemd-journal-remote.service`: https://www.freedesktop.org/software/systemd/man/systemd-journal-remote.service.html .. _`micro-config-drive`: https://github.com/clearlinux/micro-config-drive -.. _`documentation on bulk provisioning`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/bulk-provision .. |WEB-SERVER-SCALE| replace:: There are many well-known ways to achieve a scalable and resilient web diff --git a/source/guides/guides.rst b/source/guides/guides.rst index ac082ca5..7493228d 100644 --- a/source/guides/guides.rst +++ b/source/guides/guides.rst @@ -28,12 +28,21 @@ Network network/* - Kernel -====== +======= .. toctree:: :maxdepth: 1 :glob: - kernel/* \ No newline at end of file + kernel/* + +Stacks +======= + +.. toctree:: + :maxdepth: 1 + :glob: + + stacks/* + stacks/dlrs/* diff --git a/source/guides/kernel/kernel-development.rst b/source/guides/kernel/kernel-development.rst index cab3e0a5..fd3e4f54 100644 --- a/source/guides/kernel/kernel-development.rst +++ b/source/guides/kernel/kernel-development.rst @@ -3,18 +3,21 @@ Kernel development ################## -This guide shows how to obtain and compile a Linux* kernel source -using |CL-ATTR| development tooling. - -The :ref:`compatible-kernels` available in |CL| aim to be performant and -practical. In some cases, it may be necessary to modify the kernel to suit your -specific needs or test new kernel code as a developer. +This guide shows how to obtain and compile a Linux\* kernel source using +|CL-ATTR| development tooling. .. contents:: :local: :depth: 1 :backlinks: top +Overview +******** + +The :ref:`compatible-kernels` available in |CL| aim to be performant and +practical. In some cases, it may be necessary to modify the kernel to suit your +specific needs or test new kernel code as a developer. + `Source RPMs (SRPMS)`_ are also available for all |CL| kernels, and can be used for development instead. @@ -26,7 +29,7 @@ useful to others, consider submitting a request to include it in the |CL| kernels.If your change request is accepted, you do not need to maintain your own modified kernel. -Make enhancement requests to the |CL| `Distribution Project`_ on GitHub. +Make enhancement requests to the |CL| `Distribution Project`_ on GitHub\*. Set up kernel development environment ************************************* @@ -52,6 +55,7 @@ Install the |CL| development tooling framework Clone the kernel package ======================== + Clone the existing kernel package repository from |CL| as a starting point. #. Clone the Linux kernel package from |CL|. Using the @@ -71,7 +75,7 @@ Clone the existing kernel package repository from |CL| as a starting point. cd ~/clearlinux/packages/linux -The "linux" package is the kernel that comes with |CL| in the `kernel-native` +The "linux" package is the kernel that comes with |CL| in the :command:`kernel-native` bundle. Alternatively, you can use a different kernel variant as the base for modification. For a list of kernel package names which you can clone instead, see the `clearlinux-pkgs`_ repo on GitHub. @@ -79,7 +83,8 @@ see the `clearlinux-pkgs`_ repo on GitHub. .. note:: The latest version of the |CL| kernel package is pulled as a starting - point. An older version can pulled by switching to different git tag by using :command:`git checkout tag/`. + point. An older version can pulled by switching to different git tag by using + :command:`git checkout tag/`. Change the kernel version ========================= @@ -118,12 +123,16 @@ provided by autospec are not available and changes must be made manually. %define ktarget native .. note:: - - Consider changing the Name from *linux* in the RPM spec file to easily identify a modified kernel. + - Consider changing the Name from *linux* in the RPM spec file to easily + identify a modified kernel. - - Consider changing the ktarget from *native* in the RPM spec file to easily identify a modified kernel. + - Consider changing the ktarget from *native* in the RPM spec file to + easily identify a modified kernel. #. Commit and save the changes to the file. +.. _pull-copy-kernel-source: + Pull a copy of the Linux kernel source code =========================================== @@ -162,16 +171,16 @@ build. These customizations are optional. Modify kernel configuration =========================== -The kernel source has many configuration options available to pick support for different hardware and software features. +The kernel source has many configuration options available to pick support for +different hardware and software features. These configuration values must be provided in the :file:`.config` file at compile time. You will need to make modifications to the :file:`.config` file, and include it in the kernel package. -#. Make sure you have followed the steps to - `Pull a copy of the Linux kernel source code`_ and are in the kernel - source working directory. +#. Make sure you have followed the steps to :ref:`pull-copy-kernel-source` + and are in the kernel source working directory. #. If you have an existing :file:`.config` file from an old kernel, copy it @@ -226,9 +235,8 @@ consider using a patch management tool in addition to Git such as `Quilt`_. -#. Make sure you have followed the steps to - `Pull a copy of the Linux kernel source code`_ and are in the kernel - source working directory. +#. Make sure you have followed the steps to :ref:`pull-copy-kernel-source` and + are in the kernel source working directory. #. Initialize the kernel source directory as a new git repo and create a @@ -399,7 +407,7 @@ machine for testing. This approach works well for individual development or testing. For a more scalable and customizable approach, consider using the :ref:`mixer` to provide a custom kernel with updates. -1. Install the kernel onto the local system by extracting the RPM with the +#. Install the kernel onto the local system by extracting the RPM with the :command:`rpm2cpio` command. .. code-block:: bash diff --git a/source/guides/kernel/kernel-modules-dkms.rst b/source/guides/kernel/kernel-modules-dkms.rst index c3be4dd0..bda29de0 100644 --- a/source/guides/kernel/kernel-modules-dkms.rst +++ b/source/guides/kernel/kernel-modules-dkms.rst @@ -3,16 +3,21 @@ Add kernel modules with DKMS ############################ -Certain kernel modules are enabled by default in |CL-ATTR|. To use additional -kernel modules that are not part of the Linux source tree, you may need to -build out-of-tree kernel modules. Use this guide to add kernel modules with -:abbr:`DKMS (Dynamic Kernel Module System)` or refer to -:ref:`kernel-modules`. +This guide describes how to add kernel modules with +:abbr:`DKMS (Dynamic Kernel Module System)`. .. contents:: :local: :depth: 1 :backlinks: top +Overview +******** + +Certain kernel modules are enabled by default in |CL-ATTR|. To use additional +kernel modules that are not part of the Linux source tree, you may need to +build out-of-tree kernel modules. Use this guide to add kernel modules with +:abbr:`DKMS (Dynamic Kernel Module System)` or refer to :ref:`kernel-modules`. + Description *********** @@ -34,12 +39,12 @@ Install DKMS .. _kernel-modules-dkms-install-begin: -The *kernel-native-dkms* bundle provides the :command:`dkms` program and +The :command:`kernel-native-dkms` bundle provides the :command:`dkms` program and Linux kernel headers, which are required for compiling kernel modules. -The *kernel-native-dkms* bundle also: +The :command:`kernel-native-dkms` bundle also: -* Adds a systemd update trigger +* Adds a `systemd` update trigger (:file:`/usr/lib/systemd/system/dkms-new-kernel.service`) to automatically run DKMS to rebuild modules after a kernel upgrade occurs with :ref:`swupd update `. @@ -254,8 +259,7 @@ The instructions below show a generic example: sudo dkms add -m #. Build the kernel module using DKMS. If the build encounters errors, - you may - need to edit the :file:`dkms.conf` file. + you may need to edit the :file:`dkms.conf` file. .. code-block:: bash diff --git a/source/guides/kernel/kernel-modules.rst b/source/guides/kernel/kernel-modules.rst index 74c4cdc3..eae7f04a 100644 --- a/source/guides/kernel/kernel-modules.rst +++ b/source/guides/kernel/kernel-modules.rst @@ -3,16 +3,20 @@ Add kernel modules manually ########################### -Certain kernel modules are enabled by default in |CL-ATTR|. To use additional -kernel modules that are not part of the Linux source tree, you may need to -build out-of-tree kernel modules. Use this guide to add kernel modules -manually, or refer to :ref:`kernel-modules-dkms`. - +This guide describes how to add kernel modules manually. .. contents:: :local: :depth: 1 :backlinks: top +Overview +******** + +Certain kernel modules are enabled by default in |CL-ATTR|. To use additional +kernel modules that are not part of the Linux source tree, you may need to +build out-of-tree kernel modules. Use this guide to add kernel modules +manually, or refer to :ref:`kernel-modules-dkms`. + Description *********** @@ -56,8 +60,7 @@ If the kernel module you need is already open source (for example, in the Linux upstream) and likely to be useful to others, consider submitting a request to add or enable it in the |CL| kernel. -Make enhancement requests to the |CL| -`Distribution Project `_ on GitHub. +Make enhancement requests to the |CL| 'Distribution Project'_ on GitHub. .. _kernel-modules-availability-end: @@ -102,8 +105,8 @@ Build and install kernel module kernel dev bundle contains the kernel headers, which are required for compiling kernel modules. For example: - * `linux-dev` for developing against the native kernel. - * `linux-lts-dev` for developing against the LTS kernel. + * :command:`linux-dev` for developing against the native kernel. + * :command:`linux-lts-dev` for developing against the LTS kernel. .. code-block:: bash @@ -217,5 +220,4 @@ Related topic * :ref:`kernel-modules-dkms` -.. _`on GitHub`: https://github.com/clearlinux/distribution - +.. _`Distribution Project`: https://github.com/clearlinux/distribution diff --git a/source/guides/maintenance/architect-lifecycle.rst b/source/guides/maintenance/architect-lifecycle.rst index f166e542..ed328711 100644 --- a/source/guides/maintenance/architect-lifecycle.rst +++ b/source/guides/maintenance/architect-lifecycle.rst @@ -3,18 +3,8 @@ Architect the life-cycle of |CL-ATTR| ##################################### -This guide provides DevOps with a model to architect the life-cycle of a |CL| -derivative that integrates custom software and content using distinct -workflows. - -Maintaining a |CL| derivative requires: - -* Monitoring upstream |CL| for new releases -* Building software packages and staging -* Employing CI/CD automation for building releases -* Integrating Quality Assurance for testing and validation - -This guide provides the foundation of the recommended infrastructure. +This guide describes the basic, recommended infrastructure and workflow for +maintaining a |CL-ATTR| derivative. .. contents:: :local: @@ -36,11 +26,16 @@ Prerequisites Description *********** +Maintaining a |CL| derivative requires: + +* Monitoring upstream |CL| for new releases +* Building software packages and staging +* Employing CI/CD automation for building releases +* Integrating Quality Assurance for testing and validation + Coordinated infrastructure is deployed to automate the life-cycle of your |CL| derivative. We divide deployment of this infrastucture in two -parts: *Content Workflow*; and *Release Workflow*, shown in Figure 1. Distro -Factory manages the *Release Workflow* while capturing the requirements for -maintaining a long-term release cadence. +parts: *Content Workflow*; and *Release Workflow*, shown in Figure 1. .. figure:: figures/architect-lifecycle-1.png :scale: 100% @@ -48,35 +43,35 @@ maintaining a long-term release cadence. Figure 1: Architect the life-cycle -Content workflow +Content Workflow **************** -The *Content Workflow* (Figure 1) orchestrates the processes used to manage +The Content Workflow (Figure 1) orchestrates the processes used to manage the creation of content for the distribution. This includes everything from detecting a new release in a custom software repository to generating RPM package files. The RPM files serve as intermediary artifacts that track software -dependencies and provide file-level data consumed in a *Release Workflow*. The +dependencies and provide file-level data consumed in a Release Workflow. The `Watcher Pipeline`_ checks |CL| and a content provider, such as Koji, to determine if a new release is necessary. -Release workflow +Release Workflow **************** -The *Release Workflow* (Figure 1) gathers the content of the RPMs and +The Release Workflow (Figure 1) gathers the content of the RPMs and ensures it can be consumed by :ref:`mixer `. A content web server hosts the |CL| derivative, to which targets connect for updating their OSes. -As an integral part of this toolchain, the *Release Pipeline* enables these +As an integral part of this toolchain, the `Release Pipeline`_ enables these derivatives to incorporate |CL| content into their own custom -content. The *Watcher Pipeline* triggers the `Release Pipeline`_ to create +content. The Watcher Pipeline triggers the Release Pipeline to create new releases. Implementation ************** -Distro factory implements the *Release workflow*. To get started on a full -implementation, visit |CL| `Distro Factory`_ documentation. +The |CL| Distro Factory manages the Release Workflow. For detailed information +about Distro Factory deployment, refer to the `clr-distro-factory`_ GitHub\* repo. -.. _Distro Factory: https://github.com/clearlinux/clr-distro-factory/wiki#clear-linux-distro-factory +.. _clr-distro-factory: https://github.com/clearlinux/clr-distro-factory/wiki#clear-linux-distro-factory .. _Release Pipeline: https://github.com/clearlinux/clr-distro-factory/wiki/Release diff --git a/source/guides/maintenance/assign-static-ip.rst b/source/guides/maintenance/assign-static-ip.rst index 9028fbfc..14fc8694 100644 --- a/source/guides/maintenance/assign-static-ip.rst +++ b/source/guides/maintenance/assign-static-ip.rst @@ -3,9 +3,9 @@ Assign a static IP address ########################## -By default, your |CL-ATTR| system automatically gets an IP address from your -network via DHCP. If you do not have a DHCP server on your network or simply -want to use a static IP address, follow the steps in this guide. + +This guide explains how to assign a static IP address. This may be helpful in +scenarios such as a network with no DHCP server. .. contents:: :local: @@ -14,20 +14,20 @@ want to use a static IP address, follow the steps in this guide. Identify which program is managing the interface ************************************************ -New installations of |CL| use NetworkManager as the default network interface +New installations of |CL-ATTR| use NetworkManager as the default network interface manager for all network connections. .. note:: - * The *cloud* |CL| images continue to use systemd-networkd to manage + * The cloud |CL| images continue to use `systemd-networkd` to manage network connections. - * In earlier |CL| versions, systemd-network was used to manage Ethernet + * In earlier |CL| versions, `systemd-network` was used to manage Ethernet interfaces and NetworkManager was used for wireless interfaces. -Before defining a configuration for assigning a static IP address, you should -verify which program is managing the network interface. +Before defining a configuration for assigning a static IP address, verify which +program is managing the network interface. #. Check the output of :command:`nmcli device` to see if NetworkManager is managing the device. @@ -37,23 +37,23 @@ verify which program is managing the network interface. nmcli device status If the STATE column for the device shows *connected* or *disconnected*, the - network configuration is being managed by NetworkManager and the instructions - for :ref:`using NetworkManager ` should be used. + network configuration is being managed by NetworkManager, then use the + instructions for :ref:`using NetworkManager `. - If the STATE column for the device shows *unmanaged*, check to see if the - device is being managed by systemd-networkd + If the STATE column for the device shows *unmanaged*, then check if the + device is being managed by systemd-networkd. #. Check the output of :command:`networkctl list` to see if - systemd-networkd is managing the device. + `systemd-networkd` is managing the device. .. code-block:: bash networkctl list If the SETUP column for the device shows *configured*, the network - configuration is being managed by systemd-networkd and the instructions for - :ref:`using systemd-networkd ` should be used. + configuration is being managed by `systemd-networkd`, then use the + instructions for :ref:`using systemd-networkd `. .. _nm-static-ip: @@ -75,7 +75,7 @@ NetworkManager: * nm-connection-editor - a graphical user interface -The method below uses the command line tool *nmcli* to modify network +The method below uses the command line tool nmcli to modify network connection. @@ -85,20 +85,20 @@ connection. nmcli connection show - The output will look like this: + Sample output: .. code:: bash NAME UUID TYPE DEVICE Wired connection 1 00000000-0000-0000-0000-000000000000 802-3-etherneten01 - If a connection does not exist, it will need to be created with - :command:`nmcli connection add`. + If a connection does not exist, create it with the + :command:`nmcli connection add` command. #. Modify the connection to use a static IP address. Replace the variables in - brackets with the appropriate values. *[CONNECTION_NAME]* should be - replaced with the NAME from the command above. + brackets with the appropriate values. Replace *[CONNECTION_NAME]* with the + NAME from the command above. .. code:: @@ -132,7 +132,7 @@ connection. .. _networkd-static-ip: -Using systemd-networkd +Using systemd-networkd ********************** Network connections managed by systemd-networkd are stored as files with the @@ -141,16 +141,16 @@ Network connections managed by systemd-networkd are stored as files with the Files to manipulate network connections managed by systemd-networkd must be created manually. -#. Create the :file:`/etc/systemd/network` directory if it doesn't exist already: +#. Create the :file:`/etc/systemd/network` directory if it does not already exist: .. code-block:: bash sudo mkdir -p /etc/systemd/network #. Create a :file:`.network` file and add the following content. Replace the - variables in brackets with the appropriate values. *[INTERFACE_NAME]* - should be replaced with LINK from the output of :command:`networkctl list` - ran previously. + variables in brackets with the appropriate values. Replace *[INTERFACE_NAME]* + with LINK from the output of the :command:`networkctl list` command that was + run previously. .. code-block:: bash @@ -169,7 +169,7 @@ created manually. `_ for more configuration options. -#. Restart the systemd-networkd service: +#. Restart the `systemd-networkd` service: .. code-block:: bash diff --git a/source/guides/maintenance/bulk-provision.rst b/source/guides/maintenance/bulk-provision.rst index 9d3affc2..535ea48a 100644 --- a/source/guides/maintenance/bulk-provision.rst +++ b/source/guides/maintenance/bulk-provision.rst @@ -3,16 +3,23 @@ Bulk provision ############## -The |CL-ATTR| can be automatically provisioned in bulk using a combination of -the |CL| installer, **Ister**, and :abbr:`ICIS (Ister Cloud Init Service)`. -This guide covers how to perform a bulk provision of |CL| using **Ister** -and **ICIS**. +This guide explains how to perform a bulk provision of |CL-ATTR| using a +combination of the |CL| installer, Ister, and +:abbr:`ICIS (Ister Cloud Init Service)`. -To configure a bulk provision, Ister configuration files and cloud-init -files must be defined. Hosting the configuration files in **ICIS** allows -**Ister** to use them during the installation. The Ister configuration -files allow us to customize the installation process. The cloud-init\* -files allow us to customize the instance of the installation. +.. contents:: + :local: + :depth: 1 + +Overview +******** + +To configure a bulk provision: + +* Define Ister configuration files to customize the installation process +* Define cloud-init\* files to customize the installation instance +* Host the configuration files in ICIS to allow Ister to use them during + the installation Figure 1 depicts the flow of information between a PXE server and a PXE client that needs to be set up to perform a bulk provision. @@ -23,7 +30,7 @@ client that needs to be set up to perform a bulk provision. Figure 1: Bulk provision information flow Prerequisites -============= +************* Before performing a bulk provision, verify you have a PXE server capable of performing network boots of |CL|. Please refer to our @@ -38,16 +45,16 @@ preparations have been made: on any computer performing the installation. Configuration -============= +************* -#. Install **ICIS** by following the getting started guide on the - `ICIS`_ GitHub repository. +#. Install ICIS by following the getting started guide on the + `ICIS`_ GitHub\* repository. #. Create an Ister installation file and save it to the :file:`static/ister` directory within the web hosting directory for - **ICIS**. The installation file is a JSON block and provides **Ister** + ICIS. The installation file is a JSON block and provides Ister with the steps it needs to perform an installation. The file outlines - what partitions, file systems, and mount points **Ister** should set + what partitions, file systems, and mount points Ister should set up. Lastly, the file outlines which bundles to install. See our :ref:`bundles` document for the list of available bundles. The following example shows the contents of an Ister installation file: @@ -82,14 +89,14 @@ Configuration .. important:: - Every Ister installation file hosted on **ICIS** must contain the - the ``IsterCloudInitSvc`` parameter as well as the ``os-cloudguest`` - bundle. These entries allow **Ister** to customize an instance of of an + Every Ister installation file hosted on ICIS must contain the + the `IsterCloudInitSvc` parameter as well as the :command:`os-cloudguest` + bundle. These entries allow Ister to customize an instance of of an install. #. Create an Ister configuration file to define the location of the Ister installation file. Save it to the :file:`static/ister` directory - within the web hosting directory of **ICIS**. The following example shows + within the web hosting directory of ICIS. The following example shows an Ister configuration file: .. code-block:: none @@ -97,10 +104,10 @@ Configuration template=http://192.168.1.1:60000/icis/static/ister/ister.json #. Modify the iPXE boot script by adding a kernel parameter to the command line - for booting the network image. Add the kernel parameter ``isterconf`` with - the location of the Ister configuration file hosted on **ICIS** as the + for booting the network image. Add the kernel parameter `isterconf` with + the location of the Ister configuration file hosted on ICIS as the kernel parameter value. The following example shows an iPXE boot script - with the ``isterconf`` parameter: + with the `isterconf` parameter: .. code-block:: none @@ -111,7 +118,7 @@ Configuration .. note:: - After the network image of |CL| boots, **Ister** inspects the + After the network image of |CL| boots, Ister inspects the parameters used during boot in :file:`/proc/cmdline` to find the location of the Ister configuration file. @@ -121,13 +128,13 @@ Configuration customization options provided by cloud-init after an installation. #. Save the cloud-init document to the :file:`static/roles` directory within - the web hosting directory for **ICIS** with the name of a role you would + the web hosting directory for ICIS with the name of a role you would like to create. For example, a role may be "database", "web", or "ciao". #. After creating the roles, also known as cloud-init files, assign roles to MAC addresses of PXE clients. To do so, modify the :file:`config.txt` file - in the ``static`` directory within the web hosting directory of **ICIS**. - The following example shows one such assignment: + in the :file:`static` directory within the web hosting directory of ICIS. + The following example shows an example assignment: .. code-block:: none @@ -145,11 +152,11 @@ Configuration #. Verify the following URLs are accessible on your local network: - * ``http://192.168.1.1:60000/icis/static/ister/ister.conf`` - * ``http://192.168.1.1:60000/icis/static/ister/ister.json`` - * ``http://192.168.1.1:60000/icis/get_config/`` - * ``http://192.168.1.1:60000/icis/get_role/`` - * ``http://192.168.1.1:60000/ipxe/ipxe_boot_script.txt`` + * http://192.168.1.1:60000/icis/static/ister/ister.conf + * http://192.168.1.1:60000/icis/static/ister/ister.json + * http://192.168.1.1:60000/icis/get_config/ + * http://192.168.1.1:60000/icis/get_role/ + * http://192.168.1.1:60000/ipxe/ipxe_boot_script.txt #. Power on the PXE client and watch it boot and install |CL|. diff --git a/source/guides/maintenance/cpu-performance.rst b/source/guides/maintenance/cpu-performance.rst index 3a400e3c..299514e7 100644 --- a/source/guides/maintenance/cpu-performance.rst +++ b/source/guides/maintenance/cpu-performance.rst @@ -3,6 +3,15 @@ CPU Power and Performance ######################### +This guide explains the CPU power and performance mechanisms in |CL-ATTR|. + +.. contents:: + :local: + :depth: 1 + +Overview +******** + Modern x86 :abbr:`CPUs (central processing units)` employ a number of features and technologies to balance performance, energy, and thermal efficiencies. @@ -11,11 +20,12 @@ the faster the program finishes execution, the faster the CPU can return to a low energy idle state. It is important to understand and evaluate all of these technologies when troubleshooting or considering changing the defaults. -.. contents:: :local: - :depth: 1 +.. contents:: + :local: + :depth: 1 CPU power saving mechanisms -=========================== +*************************** C-states and P-states are both CPU power saving mechanisms that are entered under different operating conditions. The tradeoff is a slightly longer time @@ -24,7 +34,7 @@ to exit these states when the CPU is needed once again. .. _c-states-section: C-states (idle states) ----------------------- +====================== C-states are hardware sleep states that are entered when it is determined that the CPU is idle and not executing instructions. @@ -57,11 +67,11 @@ or completely disabled with :command:`idle=poll`. .. _p-states-section: P-states (performance states) ------------------------------ +============================= -P-states, also known as *SpeedStep* on Intel processors or *Cool'n'Quiet* on -AMD processors, are states entered while the CPU is active and executing -instructions. +P-states, also known as *Intel SpeedStep® technology* on Intel processors or +*Cool'n'Quiet* on AMD processors, are states entered while the CPU is active and +executing instructions. P-states aim to reduce power utilization by adjusting CPU clock frequency and voltages based on CPU demand. @@ -69,9 +79,9 @@ voltages based on CPU demand. P-states can typically be limited or disabled in a system's firmware (UEFI/BIOS). Turbo boost -~~~~~~~~~~~ +----------- -`Turbo Boost technology`_, found on some modern Intel CPUs, allows core(s) on +`Intel® Turbo Boost Technology`_, found on some modern Intel CPUs, allows core(s) on a processor to temporarily operate at a higher than rated CPU clock frequency to accommodate demanding workloads if the CPU is under defined power and thermal thresholds. @@ -87,7 +97,7 @@ be disabled within |CL| with the command: echo 1 | sudo tee /sys/devices/system/cpu/intel_pstate/no_turbo Linux CPU clock frequency scaling -================================= +********************************* The CPUFreq subsystem in Linux allows the OS to control :ref:`C-states ` and :ref:`P-states ` @@ -95,12 +105,12 @@ via CPU drivers and governors that provide algorithms that define how and when to enter these states. Scaling driver --------------- +============== -Linux uses the `Intel P-state driver`_, *intel_pstate*, for modern Intel +Linux uses the `Intel P-state driver`_, :command:`intel_pstate`, for modern Intel processors from the Sandy Bridge generation or newer. Other processors may -default to the *acpi-cpufreq* driver which reads values from the systems UEFI -or BIOS. +default to the :command:`acpi-cpufreq*` driver which reads values from the systems +UEFI or BIOS. To view the current CPU frequency scaling driver run this command in a terminal: @@ -109,7 +119,7 @@ To view the current CPU frequency scaling driver run this command in a terminal: cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_driver Scaling governor ----------------- +================ |CL| sets the CPU governor to *performance* which calls for the CPU to operate at maximum clock frequency. In other words, P-state P0. While this may sound @@ -146,7 +156,7 @@ The list of all governors can be found in the Linux kernel documentation on The intel_pstate driver only supports *performance* and *powersave* governors. Thermal management -================== +****************** `thermald`_ is a Linux thermal management daemon used to prevent the overheating of platforms. When temperature thresholds are exceeded, thermald @@ -169,8 +179,9 @@ For more information, see the thermald man page: man thermald `ThermalMonitor`_ is a GUI application that can visually graph and log -temperatures from thermald. To use ThermalMonitor, add the desktop-apps-extras -bundle and add your user account to the power group: +temperatures from thermald. To use ThermalMonitor, add the +:command:`desktop-apps-extras` bundle and add your user account to the power +group: .. code:: bash @@ -180,8 +191,8 @@ bundle and add your user account to the power group: .. note:: - After adding a new group you must log out and log back in for the new group - to take affect. + After adding a new group, you must log out and log back in for the new group + to take effect. .. _`Intel P-state driver`: https://www.kernel.org/doc/Documentation/cpu-freq/intel-pstate.txt @@ -194,4 +205,4 @@ bundle and add your user account to the power group: .. _`ThermalMonitor`: https://github.com/intel/thermal_daemon/tree/master/tools/thermal_monitor -.. _`Turbo Boost technology`: https://www.intel.com/content/www/us/en/architecture-and-technology/turbo-boost/turbo-boost-technology.html +.. _`Intel® Turbo Boost Technology`: https://www.intel.com/content/www/us/en/architecture-and-technology/turbo-boost/turbo-boost-technology.html diff --git a/source/guides/maintenance/developer-workstation.rst b/source/guides/maintenance/developer-workstation.rst index 0e6e1a32..2e487536 100644 --- a/source/guides/maintenance/developer-workstation.rst +++ b/source/guides/maintenance/developer-workstation.rst @@ -3,28 +3,31 @@ Developer Workstation ##################### -*Developer Workstation* helps you find the :ref:`bundles-about` you need to -start your |CL-ATTR| development project. +This guide helps you find the minimum set of bundles needed to start your +|CL-ATTR| development project. -Before continuing, we recommend that you learn how to use -:ref:`swupd `. Visit our :ref:`swupd-about` page to understand -how |CL| simplifies software versioning compared to other Linux\* -distributions. +Before continuing, review the :ref:`swupd ` guide to learn more +about the swupd tool and how |CL| simplifies software versioning compared to +other Linux\* distributions. + +.. contents:: + :local: + :depth: 1 Workstation Setup ***************** -This guide helps you understand the minimum bundles required to get started. -After installing them, you can add more bundles relevant to your use case. -To run any process required for |CL| development, you can add the -large bundle :ref:`*os-clr-on-clr* `. However, given how -many packages this bundle contains, you may want instead to deploy a leaner -OS with only those bundles relevant to your project. Developer Workstation -responds to this need. +After installing the minimum set of bundles required to get started, you can add +more bundles relevant to your specific use case. + +To run any process required for |CL| development, you can add the large bundle +:ref:`*os-clr-on-clr* `. However, given how many packages this +bundle contains, you may want to deploy a leaner OS with only bundles relevant to +your project. Use Table 1, *Developer Profiles*, to identify the *minimum required bundles* to get started developing based on your role or project. -While your role may not neatly fit in one of these categories, consider using +While your role may not neatly fit in one of these categories, consider Table 1 as a starting point. .. list-table:: **Table 1. Developer Profiles** @@ -36,48 +39,48 @@ Table 1 as a starting point. - *System Administrator* - *Client/Cloud/Web Developer* - * - `editors` + * - :command:`editors` - ✓ - ✓ - ✓ - * - `network-basic` + * - :command:`network-basic` - ✓ - ✓ - ✓ - * - `openssh-server` + * - :command:`openssh-server` - ✓ - ✓ - ✓ - * - `webserver-basic` + * - :command:`webserver-basic` - - ✓ - ✓ - * - `application-server` + * - :command:`application-server` - - ✓ - ✓ - * - `database-basic` + * - :command:`database-basic` - - ✓ - ✓ - * - `desktop-autostart` + * - :command:`desktop-autostart` - ✓ - ✓ - ✓ - * - `dev-utils` + * - :command:`dev-utils` - - - ✓ -`swupd` search -************** +swupd search +************ We recommend learning about :ref:`swupd `, to learn the commands to search for and add bundles relevant to your project. @@ -85,8 +88,8 @@ commands to search for and add bundles relevant to your project. The guide provides an :ref:`example ` that shows you how to: -* Use `swupd` to search for bundles -* Use `swupd` to add bundles +* Use swupd to search for bundles +* Use swupd to add bundles Core Concepts ************* @@ -94,10 +97,9 @@ Core Concepts We recommend that you understand these core concepts in |CL| *before* developing your project. -* :ref:`Bundles ` -* :ref:`Software update ` -* :ref:`Mixer ` -* :ref:`Autospec ` +* :ref:`Software update ` +* :ref:`Mixer ` +* :ref:`Autospec ` Other resources for developers ----------------------------------- diff --git a/source/guides/maintenance/download-verify-decompress.rst b/source/guides/maintenance/download-verify-decompress.rst index d1e1b6de..1dc74083 100644 --- a/source/guides/maintenance/download-verify-decompress.rst +++ b/source/guides/maintenance/download-verify-decompress.rst @@ -32,7 +32,7 @@ support verification, each released |CL| image has a corresponding SHA512 checksum file designated with the suffix `-SHA512SUMS`. #. Download the corresponding SHA512 checksum file of your |CL| `image`_. -#. Start a terminal emulator. +#. Open a Terminal. #. Go to the directory with the downloaded image and checksum files. #. Verify the integrity of the image and compare it to its original checksum with the command: @@ -58,7 +58,7 @@ Released |CL| images are compressed with either GNU zip (*.gz*) or XZ (*.xz*). The compression type depends on the target platform or environment. To decompress the image, follow these steps: -#. Start a terminal emulator. +#. Open a Terminal. #. Go to the directory with the downloaded image. To decompress an XZ image, enter: diff --git a/source/guides/maintenance/enable-user-space.rst b/source/guides/maintenance/enable-user-space.rst index 0c1fc9e7..e51fa59e 100644 --- a/source/guides/maintenance/enable-user-space.rst +++ b/source/guides/maintenance/enable-user-space.rst @@ -3,7 +3,7 @@ Create and enable a new user space ################################## -This section provides steps to complete the following basic setup tasks for +This guide provides steps to complete the following basic setup tasks for a newly installed |CL-ATTR| system: .. contents:: @@ -14,7 +14,7 @@ Create a new user ***************** To create a new user and set a password for that user, enter the following -commands as a `root` user: +commands as a root user: .. code-block:: bash @@ -26,28 +26,28 @@ including the password for that user. The :command:`passwd` command prompts you to enter a new password. Retype the new password for the new user account just created. -Add the new user to the `wheel` group +Add the new user to the *wheel* group ************************************* Before logging off as root and logging into your new user account, -enable the :command:`sudo` command for your new ``. +enable the :command:`sudo` command for your new . To be able to execute all applications with root privileges, add the -`` to the `wheel group`_. + to the `wheel group`_. -#. Add `` to the `wheel` group: +#. Add to the wheel group: .. code-block:: bash usermod -G wheel -a -#. Log out of root and into the new ``. +#. Log out of root and into the new . To log off as root, enter :command:`exit`. -#. Enter the new `` and the password created earlier. +#. Enter the new and the password created earlier. - You will now be in the home directory of ``. + You will now be in the home directory of . Install and update the OS software to its current version ********************************************************* @@ -65,13 +65,13 @@ Add a bundle ************ Software applications are installed as bundles using the command -:command:`swupd bundle-add`. Experienced Linux* users might compare `swupd` +:command:`swupd bundle-add`. Experienced Linux users might compare swupd to running :command:`apt-get` or :command:`yum install` for package -management. Yet |CL| manages packages at the level of bundles, which +management. However |CL| manages packages at the level of bundles, which are integrated stacks of packages. -For example, the `sysadmin-basic` bundle installs the majority of applications -useful to a system administrator. To install it, enter: +For example, the :command:`sysadmin-basic` bundle installs the majority of +applications useful to a system administrator. To install it, enter: .. code-block:: bash diff --git a/source/guides/maintenance/fix-broken-install.rst b/source/guides/maintenance/fix-broken-install.rst index 1ffe275d..33765b89 100644 --- a/source/guides/maintenance/fix-broken-install.rst +++ b/source/guides/maintenance/fix-broken-install.rst @@ -1,20 +1,31 @@ .. _fix-broken-install: -Fix a broken installation of |CL-ATTR| -###################################### +Fix a broken installation +######################### -This guide explains how to fix a broken installation of |CL| using a live -desktop image on a USB. It's assumed you already installed |CL| on a -target system, but your operating system does not boot or function properly. +This guide explains how to fix a broken installation of |CL-ATTR| using a live +desktop image on a USB. -This process can only verify and fix files that :ref:`swupd` -owns in :file:`/usr`. Files outside of this path, such as /home/, /etc, -/var, etc., cannot be repaired by this process. +.. contents:: + :local: + :depth: 1 + +Overview +******** + +This guide assumes you have installed |CL| on a target system, but the OS +does not boot or function properly. + +The process described in this guide can only verify and fix files that +:ref:`swupd` owns in :file:`/usr`. Files outside of this path, such +as :file:`/home/`, :file:`/etc`, :file:`/var`, etc., cannot be repaired by this +process. Prerequisites ************* -* :ref:`Download and install the live desktop image on a USB ` +* Download and install the live desktop image on a USB. See + :ref:`bare-metal-install-desktop` for install instructions. Boot a live desktop image to fix target system ********************************************** @@ -30,7 +41,7 @@ Mount root partition, verify, and fix #. Open a Terminal window. -#. Assure the system is connected to the network. +#. Ensure the system is connected to the network. #. Mount the system’s root partition. @@ -40,9 +51,9 @@ Mount root partition, verify, and fix lsblk - We'll use `/dev/sda3/` as the root partition example. + We'll use :file:`/dev/sda3/` as the root partition example. - #. Next, mount the partition to the `/mnt` folder. + #. Next, mount the partition to the :file:`/mnt` folder. .. code-block:: bash diff --git a/source/guides/maintenance/hostname.rst b/source/guides/maintenance/hostname.rst index ce539009..ce0c225c 100644 --- a/source/guides/maintenance/hostname.rst +++ b/source/guides/maintenance/hostname.rst @@ -1,10 +1,17 @@ .. _hostname: -Modify hostname on |CL-ATTR| -############################ +Modify hostname +############### -This guide describes how to modify and view the hostname of your -|CL-ATTR| system. +This guide describes how to modify and view the hostname of your |CL-ATTR| +system. + +.. contents:: + :local: + :depth: 1 + +Overview +******** By default, |CL| installations have a machine generated name, which is a long string of letters and numbers. The generated name is fine for computers @@ -22,8 +29,8 @@ Set your hostname ***************** |CL| uses the :command:`hostnamectl` command to display and modify the machine -name. :command:`hostnamectl` is part of the **os-core** bundle, which provides -a basic Linux\* user space and utilities. +name. :command:`hostnamectl` is part of the :command:`os-core` bundle, which +provides a basic Linux\* user space and utilities. This example sets the hostname to *telemetry-test-2-h15*, to identify a |CL| telemetry test machine on the second floor at grid location H15. diff --git a/source/guides/maintenance/increase-virtual-disk-size.rst b/source/guides/maintenance/increase-virtual-disk-size.rst index 36344aec..e633f506 100644 --- a/source/guides/maintenance/increase-virtual-disk-size.rst +++ b/source/guides/maintenance/increase-virtual-disk-size.rst @@ -1,25 +1,29 @@ .. _increase-virtual-disk-size: -Increase virtual disk size of a |CL-ATTR| image -############################################### +Increase virtual disk size of an image +###################################### -|CL-ATTR| prebuilt images come in different sizes, ranging from 300 MB to 20 -GB. This guide describes how to increase the size of your prebuilt |CL| image -if you need more capacity. +This guide describes how to increase the disk size of your prebuilt |CL-ATTR| +image if you need more capacity. -.. contents:: This guide will cover: +.. contents:: + :local: + :depth: 1 Determine the partition order and sizes of the prebuilt image ************************************************************* +|CL| prebuilt images come in different sizes, ranging from 300 MB to 20 +GB. + There are two methods to find the order and sizes of partitions virtual disk of your prebuilt |CL| image. -In both examples, the prebuilt Hyper-V image has a disk size of 8.5 GB with / -dev/sda3 being the partition for the root filesystem (/) +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: @@ -41,7 +45,7 @@ An example output of the :command:`lsblk` command: An example of this can also be seen in Figure 1. Checking :file:`config.json` used to build the image ----------------------------------------------------- +==================================================== The second method to determine partition to check the :file:`config.json` file used to create prebuilt image, located in the `releases`_ repository. @@ -77,25 +81,24 @@ 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: --------------------------------------------- +Power off VM and increase virtual disk size +=========================================== To increase the virtual disk size for a prebuilt image, perform the steps below: #. Shut down your VM if it is running. -#. Use the process defined by your hypervisor - or cloud provider to increase +#. Use the process defined by your hypervisor or cloud provider to increase the virtual disk size of your |CL| VM. #. Power up the VM. -Resize the partition of the virtual disk: ------------------------------------------ +Resize the partition of the virtual disk +======================================== #. Log in to an account with root privileges. #. Open a terminal emulator. -#. Add the |CL| `storage-utils` bundle to install the +#. Add the :command:`storage-utils` bundle to install the :command:`parted` and :command:`resize2fs` tools. .. code-block:: bash @@ -115,7 +118,7 @@ Resize the partition of the virtual disk: .. code-block:: console - Warning: Not all of the space available to /dev/sda appears to be + 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? @@ -124,14 +127,14 @@ Resize the partition of the virtual disk: #. 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 the new End size. .. note:: If you want a partition to take up the remaining disk space, then enter the total size of the disk. When you print the partitions table with the :command:`p` command, the total disk size is shown - after the `Disk` label. + after the :guilabel:`Disk` label. An example of this can be seen in Figure 1. @@ -146,16 +149,18 @@ Resize the partition of the virtual disk: Figure 1: Increase root partition size. -Resize the filesytem --------------------- +Resize the filesystem +===================== #. Enter :command:`sudo resize2fs -p /dev/[modified partition name]` where - *[modified partition name]* is the partition that was changed in `parted`. + *[modified partition name]* is the partition that was changed in the `parted` + tool. #. Run the :command:`df -h` 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 partition of the virtual + disk from 8.5GB to 20GB. .. figure:: figures/increase-virtual-disk-size-2.png :scale: 100 % @@ -163,7 +168,7 @@ Resize the filesytem Figure 2: Increase root filesystem size after partition has been expanded. -Congratulations! You have resized the disk, partition, and filesystem. At +**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 diff --git a/source/guides/maintenance/query-upstream.rst b/source/guides/maintenance/query-upstream.rst new file mode 100644 index 00000000..65bd614f --- /dev/null +++ b/source/guides/maintenance/query-upstream.rst @@ -0,0 +1,226 @@ +.. _query-upstream: + +Query package info from upstream repository +########################################### + +This guide describes how to query package information from the |CL| upstream +repositories. This guide is intended for developers and advanced users. + +.. contents:: + :local: + :depth: 1 + :backlinks: top + +Overview +******** + +In |CL-ATTR|, the :ref:`swupd` tool manages software +dependencies and installs bundles instead of packages. Although a bundle is +a collection of one or more packages, |CL| does not work with packages on +the client side. However, on the upstream/factory side, |CL| does work with +packages using a process called *mixing*. + +Currently, :command:`swupd` does not report which packages are installed, +provide package version information, or return other package details. This +guide describes a method for retrieving package information from the |CL| +upstream repositories using :abbr:`DNF(Dandified Yum)` commands. + +Prerequisites +************* + +This guide assumes you have installed |CL| on your host system. +For detailed instructions on installing |CL| on a bare metal system, visit +the :ref:`bare metal installation guide `. + +Before you install any new packages, update |CL| with the following command: + +.. code-block:: bash + + sudo swupd update + +Configure DNF +************* + +#. Install the DNF bundle with the command: + + .. code-block:: bash + + sudo swupd bundle-add dnf + +#. Create a :file:`dnf.conf` file with the commands: + + .. code-block:: bash + + sudo mkdir -p /etc/dnf + sudo curl -L https://github.com/clearlinux/common/raw/master/conf/dnf.conf --output /etc/dnf/dnf.conf + + +#. Edit the :file:`/etc/dnf/dnf.conf` file and set the **baseurl** variable + for binary and source RPMs as shown in lines 3 and 9 in the following + example. + + .. code-block:: bash + :linenos: + :emphasize-lines: 3,9 + + [clear] + name=Clear + baseurl=https://cdn.download.clearlinux.org/releases/$releasever/clear/x86_64/os/ + enabled=1 + gpgcheck=0 + [clear-source] + name=Clear sources + failovermethod=priority + baseurl=https://cdn.download.clearlinux.org/releases/$releasever/clear/source/SRPMS/ + enabled=1 + gpgcheck=0 + +#. Initialize the RPM database with the command: + + .. code-block:: bash + + sudo rpm --initdb + + +DNF command usage examples +************************** + +.. contents:: :local: + :depth: 1 + :backlinks: top + +List all binary and source RPMs in the current release +====================================================== + +Command: + +.. code-block:: bash + + dnf repoquery --releasever=current + +Sample output: + +.. code-block:: console + + Clear 5.1 MB/s | 13 MB 00:02 + Clear sources 1.8 MB/s | 1.7 MB 00:00 + AVB-AudioModules-0:4.1.0-1.src + AVB-AudioModules-0:4.1.0-1.x86_64 + AVB-AudioModules-data-0:4.1.0-1.x86_64 + AVB-AudioModules-dev-0:4.1.0-1.x86_64 + AVB-AudioModules-lib-0:4.1.0-1.x86_64 + AVB-AudioModules-license-0:4.1.0-1.x86_64 + AVBStreamHandler-0:1.1.0-21.src + AVBStreamHandler-0:1.1.0-21.x86_64 + AVBStreamHandler-abi-0:1.1.0-21.x86_64 + AVBStreamHandler-bin-0:1.1.0-21.x86_64 + AVBStreamHandler-data-0:1.1.0-21.x86_64 + AVBStreamHandler-dev-0:1.1.0-21.x86_64 + AVBStreamHandler-lib-0:1.1.0-21.x86_64 + AVBStreamHandler-license-0:1.1.0-21.x86_64 + ... + + +Show version information for a package in current release +========================================================= + +This example queries version information for the zstd package. + +Command: + +.. code-block:: bash + + dnf repoquery --releasever=current zstd + +Sample output: + +.. code-block:: console + + Last metadata expiration check: 0:02:30 ago on Tue 16 Jul 2019 03:03:34 PM PDT. + zstd-0:1.4.0-46.src + zstd-0:1.4.0-46.x86_64 + + +Show version information for a package in a specific release +============================================================ + +This example queries version information for the zstd package in release +21000. + +Command: + +.. code-block:: bash + + dnf repoquery --releasever=21000 zstd + +Sample output: + +.. code-block:: console + + Clear + 2.7 MB/s | 3.9 MB 00:01 + Clear sources + 628 kB/s | 559 kB 00:00 + zstd-0:1.3.3-20.src + zstd-0:1.3.3-20.x86_64 + +Show only version and release information for a package in a specific release +============================================================================= + +This example queries version and release information for the zstd package in +release 15000. + +Command: + +.. code-block:: bash + + dnf repoquery --releasever=15000 --qf="%{VERSION}\n%{RELEASE}" zstd + +Sample output: + +.. code-block:: console + + Clear + 3.4 MB/s | 3.9 MB 00:01 + Clear sources + 345 kB/s | 528 kB 00:01 + 1.1.4 + 5 + +Show the binary package for a specified binary file +=================================================== + +This example returns the binary package that contains the +:file:`/usr/bin/zip` binary file. + +Command: + +.. code-block:: bash + + dnf repoquery --releasever=current --whatprovides /usr/bin/zip + +Sample output: + +.. code-block:: console + + Last metadata expiration check: 0:04:47 ago on Tue 16 Jul 2019 03:03:34 PM PDT. + zip-bin-0:3.0-23.x86_64 + +Show the source package for a specified binary file +=================================================== + +This example returns the source package that contains the +:file:`/usr/bin/zip` binary file. + +Command: + +.. code-block:: bash + + dnf repoquery --releasever=current --whatprovides /usr/bin/zip --srpm + +Sample output: + +.. code-block:: console + + Last metadata expiration check: 0:05:50 ago on Tue 16 Jul 2019 03:03:34 PM PDT. + zip-0:3.0-23.src diff --git a/source/guides/maintenance/restart.rst b/source/guides/maintenance/restart.rst index c39d2941..ddd4a17c 100644 --- a/source/guides/maintenance/restart.rst +++ b/source/guides/maintenance/restart.rst @@ -3,15 +3,17 @@ Restart system services after an OS update ########################################## -|CL-ATTR| includes a :command:`clr-service-restart` tool that shows which -system daemons require a restart. +This guide describes how to use the :command:`clr-service-restart` tool. .. contents:: :local: :depth: 1 -Description -*********** +Overview +******** + +|CL-ATTR| includes a :command:`clr-service-restart` tool that shows which +system daemons require a restart. :command:`clr-service-restart` reads various files in the :file:`procfs` filesystem provided by the kernel and relies on :command:`systemd` to @@ -23,22 +25,22 @@ How it works :command:`clr-service-restart` implements a whitelist to identify which daemons can be restarted. As a system administrator, you can customize the -default |CL| OS whitelist using *allow* or *disallow* options for restarting -system services. When a software update occurs, :command:`clr-service-restart` -consults the whitelist to see if a service daemon is allowed to be restarted -or not. +default |CL| OS whitelist using :command:`allow` or :command:`disallow` options +for restarting system services. When a software update occurs, +:command:`clr-service-restart` consults the whitelist to see if a service daemon +is allowed to be restarted or not. Basic options ************* -:command:`clr-service-restart` has three basic options: allow, disallow, and -default. +:command:`clr-service-restart` has three basic options: :command:`allow`, +:command:`disallow`, and :command:`default`. allow ===== -The *allow* option identifies a daemon to restart after an OS software +The :command:`allow` option identifies a daemon to restart after an OS software update. The :command:`clr-service-restart` daemon creates a symlink in :file:`/etc/clr-service-restart` as a record. The example below tells :command:`clr-service-restart` to restart the *tallow* daemon after an @@ -51,7 +53,7 @@ OS software update. disallow ======== -The *disallow* option tells :command:`clr-service-restart` not to +The :command:`disallow` option tells :command:`clr-service-restart` not to restart the specified daemon even if the OS defaults permit the daemon to be restarted. The :command:`clr-service-restart` daemon creates a symlink in :file:`/etc/clr-service-restart` that points to :file:`/dev/null` as a @@ -65,9 +67,9 @@ restart the *rngd* daemon after an OS software update. default ======= -The *default* option makes :command:`clr-service-restart` revert back to the -OS defaults and delete any symlink in :file:`/etc/clr-service-restart`. The -example below tells :command:`clr-service-restart` to restart *rngd* +The :command:`default` option makes :command:`clr-service-restart` revert back +to the OS defaults and delete any symlink in :file:`/etc/clr-service-restart`. +The example below tells :command:`clr-service-restart` to restart *rngd* automatically again, because *rngd* is whitelisted for automatic service restarts by default in |CL|. @@ -82,7 +84,7 @@ Monitor options :command:`swupd` automatically. Review the journal output to verify that services are restarted after an OS software update. -If you pass both options (*-a* and *-n*) described below, +If you pass both options (:command:`-a` and :command:`-n`) described below, :command:`clr-service-restart` displays a complete list of system services that require a restart. Use both options to verify that all desired daemons are restarted. @@ -91,8 +93,8 @@ are restarted. -n option ========= -The *-n* option makes :command:`clr-service-restart` perform no restarts. Instead -it displays the services that could potentially be restarted. When used, +The :command:`-n` option makes :command:`clr-service-restart` perform no restarts. +Instead it displays the services that could potentially be restarted. When used, :command:`clr-service-restart` outputs a list of messages showing: * Which service needs a restart. @@ -103,17 +105,17 @@ it displays the services that could potentially be restarted. When used, -a option ========= -The *-a* option makes :command:`clr-service-restart` consider all system services, -not only the ones that are whitelisted. Because the default whitelist in |CL| -is relatively short, you can use this option to restart all impacted services -when you log in on the system. +The :command:`-a` option makes :command:`clr-service-restart` consider all system +services, not only the ones that are whitelisted. Because the default whitelist +in |CL| is relatively short, you can use this option to restart all impacted +services when you log in on the system. Example ******* In the example below, :command:`clr-service-restart` is invoked with both the -*-a* and *-n* options, which displays a complete list of system services that -require a restart. +:command:`-a` and :command:`-n` options, which displays a complete list of system +services that require a restart. Command: diff --git a/source/guides/maintenance/time.rst b/source/guides/maintenance/time.rst index 25ee141b..caa0be16 100644 --- a/source/guides/maintenance/time.rst +++ b/source/guides/maintenance/time.rst @@ -3,12 +3,13 @@ Set the time ############ -|CL-ATTR| uses the `systemd-timesyncd.service` daemon to synchronize time. - -This guide describes how to reset the time in your |CL| system when +This guide describes how to reset the time in your |CL-ATTR| system when the default :abbr:`NTP (Network Time Protocol)` servers cannot be reached. -#. Install the `sysadmin-basic` bundle. +|CL| uses the `systemd-timesyncd.service` daemon to synchronize time. + + +#. Install the :command:`sysadmin-basic` bundle. .. code-block:: bash diff --git a/source/guides/maintenance/validate-signatures.rst b/source/guides/maintenance/validate-signatures.rst index b506ba3a..f9d2fd21 100644 --- a/source/guides/maintenance/validate-signatures.rst +++ b/source/guides/maintenance/validate-signatures.rst @@ -3,22 +3,32 @@ Validate signatures ################### -|CL-ATTR| offers a way to validate the content of an image or an update. All + +This guide describes how to validate the contents of a |CL-ATTR| image. + +.. contents:: + :local: + :depth: 1 + +Overview +******** + +Validating the contents of an image is a manual process and is the same process +that :ref:`swupd-guide` performs internally. + +|CL| offers a way to validate the content of an image or an update. All validation of content works by creating and signing a hash. A valid signature creates a chain of trust. A broken chain of trust, seen as an invalid signature, means the content is not valid. -This guide covers how to validate the contents of an image, which is a manual -process and is the same process ``swupd`` performs internally to -validate an update. .. _image-content-validation: Image content validation -======================== +************************ -For the outlined steps, the installer image of the latest release of |CL| is -used for illustrative purposes. You may use any image of |CL| you choose. +In the steps below, we used the installer image of the latest release +of |CL|. You may use any image of |CL| you choose. #. Download the image, the signature of the SHA512 sum of the image, and the |CL| certificate used for signing the SHA512 sum. @@ -52,7 +62,7 @@ used for illustrative purposes. You may use any image of |CL| you choose. sha512sum clear-$(curl https://cdn.download.clearlinux.org/latest)-installer.img.xz > sha512sum.out #. Ensure the signature of the SHA512 sum of the image was created using the - |CL| certificate. This validates the image is trusted and it has not + |CL| certificate. This confirms that the image is trusted and has not been modified. .. code-block:: console @@ -61,21 +71,21 @@ used for illustrative purposes. You may use any image of |CL| you choose. .. note:: - The `-purpose any` option is required when using OpenSSL 1.1. If using - an earlier version of OpenSSL, omit this option to perform signature - validation. The `openssl version` command may be used to determine the - version of OpenSSL in use. + The :command:`-purpose any` option is required when using OpenSSL 1.1. + If you use an earlier version of OpenSSL, omit this option to perform + signature validation. The :command:`openssl version` command may be used + to determine the version of OpenSSL in use. -#. The output should contain ``Verification successful``. If the output - contains ``bad_signature`` anywhere, then the image is not trustworthy. +#. The output should contain "Verification successful". If the output + contains "bad_signature" anywhere, then the image is not trustworthy. Update content validation -========================= +************************* -``swupd`` validates all update content automatically before applying the -update content. The process ``swupd`` follows internally is illustrated here +**swupd** validates all update content automatically before applying the +update content. The process swupd follows internally is illustrated here with manual steps using the latest |CL| release. There is no need to perform -these steps manually when performing a ``swupd update``. +these steps manually when performing a :command:`swupd update`. #. Download the :abbr:`MoM (top-level manifest)`, the signature of the MoM, and the Swupd certificate used for signing the signature of the MoM. @@ -89,22 +99,22 @@ these steps manually when performing a ``swupd update``. # Swupd certificate curl -O https://cdn.download.clearlinux.org/releases/$(curl https://cdn.download.clearlinux.org/latest)/clear/Swupd_Root.pem -#. Generate the SHA256 sum of the Swupd certificate. +#. Generate the SHA256 sum of the swupd certificate. .. code-block:: console sha256sum Swupd_Root.pem -#. Ensure the generated SHA256 sum of the Swupd certificate matches following - SHA256 sum to verify the integrity of the certificate. +#. Confirm that the generated SHA256 sum of the swupd certificate matches the + SHA256 sum shown below to verify the integrity of the certificate. .. code-block:: console ff06fc76ec5148040acb4fcb2bc8105cc72f1963b55de0daf3a4ed664c6fe72c Swupd_Root.pem -#. Ensure the signature of the MoM was created using the Swupd certificate. - This signature validates the update content is trustworthy and has not been - modified. +#. Confirm that the signature of the MoM was created using the Swupd + certificate. This signature validates the update content is trustworthy and + has not been modified. .. code-block:: console @@ -112,10 +122,10 @@ these steps manually when performing a ``swupd update``. .. note:: - The `-purpose any` option is required when using OpenSSL 1.1. If using - an earlier version of OpenSSL, omit this option to perform signature - validation. The `openssl version` command may be used to determine the - version of OpenSSL in use. + The :command:`-purpose any` option is required when using OpenSSL 1.1. + If you use an earlier version of OpenSSL, omit this option to perform + signature validation. The :command:`openssl version` command may be used + to determine the version of OpenSSL in use. .. note:: @@ -123,7 +133,7 @@ these steps manually when performing a ``swupd update``. MoM is signed directly because it is small in size compared to an image of |CL|. -#. The output should contain ``Verification successful``. If the output - contains ``bad_signature`` anywhere, then the MoM cannot be trusted. +#. The output should contain "Verification successful". If the output + contains "bad_signature" anywhere, then the MoM cannot be trusted. Because the MoM contains a list of hashes for bundle manifests, if the MoM cannot be trusted, then the bundle content cannot be trusted. diff --git a/source/guides/network/custom-clear-container.rst b/source/guides/network/custom-clear-container.rst index 88ac8e7c..d3657c10 100644 --- a/source/guides/network/custom-clear-container.rst +++ b/source/guides/network/custom-clear-container.rst @@ -3,9 +3,13 @@ Build a custom |CL-ATTR| based Docker container image ####################################################### -The official base |CL-ATTR| container image is published on Docker\* Hub and -is updated on a regular basis. This guide contains the steps to build a -custom container image. +This guide contains the steps to build a custom container image. The official +base |CL-ATTR| container image is published on Docker\* Hub and is updated on a +regular basis. + +.. contents:: + :local: + :depth: 1 Prerequisites ************* @@ -82,24 +86,25 @@ Build the base container image swupd bundle-add containers-basic systemctl start docker -#. Use `os-install` to download and install the bundles. +#. Use :command:`os-install` to download and install the bundles. .. code-block:: bash swupd os-install --url https://cdn.download.clearlinux.org/update --statedir "$PWD"/swupd-state --no-boot-update --version 29790 -B os-core-update,editors,network-basic base - The `swupd` example uses the following flags: + The swupd example uses the following flags: - * :command:`os-install` tells `swupd` to download and install. + * :command:`os-install` tells swupd to download and install. * :command:`-V / --version` specifies the version of the |CL| bundles. * :command:`--url` specifies the URL of the bundles repository. * :command:`--statedir` specifies the state directory where downloaded bundles and any state information are stored. - * :command:`--no-boot-update` tells `swupd` to skip updating boot files because + * :command:`--no-boot-update` tells swupd to skip updating boot files because boot files are not required for a container. - For more information on `swupd` flags, enter the :command:`swupd os-install -h` command. + For more information on swupd flags, enter the :command:`swupd os-install -h` + command. Example output: @@ -138,7 +143,7 @@ Build the base container image .. note:: - The `WARNING` message is expected and can be ignored. + The WARNING message is expected and can be ignored. #. Create a tarball and compress it. @@ -269,7 +274,7 @@ Example output: .. note:: - The `WARNING` message can be ignored because systemd does not run inside + The WARNING message can be ignored because systemd does not run inside a container. Remove a bundle diff --git a/source/guides/network/dpdk.rst b/source/guides/network/dpdk.rst index 51f9d202..5b1ccc65 100644 --- a/source/guides/network/dpdk.rst +++ b/source/guides/network/dpdk.rst @@ -3,12 +3,19 @@ Use DPDK to send packets between platforms ########################################## -This document describes how to send packets between two platforms in the -simple configuration shown in :ref:`Figure 1 `. The example uses the -:abbr:`Data Plane Development Kit (DPDK)`, which is a set of libraries, -drivers, sample applications, and tools for fast packet processing. +This guide describes how to send packets between two platforms. -.. _f1: +.. contents:: + :local: + :depth: 1 + +Overview +******** + +Figure 1 shows how to send packets between two platforms in a simple +configuration. The example uses the :abbr:`Data Plane Development Kit (DPDK)`, +which is a set of libraries, drivers, sample applications, and tools for fast +packet processing. .. figure:: ./figures/pktgen_lw3fd.png :align: center @@ -16,18 +23,18 @@ drivers, sample applications, and tools for fast packet processing. Figure 1: Environment for l3fwd DPDK application - This example uses the following DPDK components: +This example uses the following DPDK components: -* pktgen: Traffic generator. See `pktgen documentation`_ for details. +* pktgen: Traffic generator. See `pktgen`_ documentation for details. * l3fwd: Layer 3 forwarding example application. See - `l3fwd documentation`_ for details. + `l3fwd`_ documentation for details. Prerequisites ************* * Two platforms using |CL-ATTR| release `13330`_ or higher. -* Both images must include the :file:`kernel-native bundle`. -* Install the :file:`network-basic-dev` bundle with the command: +* Both images must include the :command:`kernel-native` bundle. +* Install the :command:`network-basic-dev` bundle with the command: .. code-block:: bash @@ -107,7 +114,7 @@ NICs to DPDK modules to run DPDK applications. sudo modprobe vfio-pci #. Check the NIC status to determine which network cards are not - busy. When another application is using them, the status shows `Active`, + busy. When another application is using them, the status shows "Active", and those NICs cannot be bound. .. code-block:: bash @@ -160,9 +167,7 @@ Set up the physical environment (Platforms A and B) *************************************************** Connect the NICs on Platform A to the NICs on Platform B using the network -cables as shown in :ref:`Figure 2`. - -.. _f2: +cables as shown in figure 2. .. figure:: ./figures/pyshical_net.png @@ -174,7 +179,7 @@ Run l3fwd application (Platform B) The `l3fwd` application is one of the DPDK examples available when you install the :file:`dpdk-dev` bundle. `l3fwd` forwards packets from one -NIC to another. For details, refer to the `l3fwd documentation`_. +NIC to another. For details, refer to the `l3fwd`_ documentation. #. Open the l3fwd example directory. @@ -247,7 +252,7 @@ Run pktgen application (Platform A) Pktgen> start 0-1 -For more details, see the `pktgen documentation`_. +For more details, see the `pktgen`_ documentation. Appendix A: Use pass-through for virtual machines ************************************************* @@ -343,5 +348,5 @@ machines control the NICs on the host. .. _dpdk.org NICs: http://dpdk.org/doc/nics .. _pktgen tar package: http://dpdk.org/browse/apps/pktgen-dpdk/refs .. _DPDK guide: http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html -.. _l3fwd documentation: http://dpdk.org/doc/guides/sample_app_ug/l3_forward.html -.. _pktgen documentation: http://pktgen-dpdk.readthedocs.io/en/latest/index.html +.. _l3fwd: http://dpdk.org/doc/guides/sample_app_ug/l3_forward.html +.. _pktgen: http://pktgen-dpdk.readthedocs.io/en/latest/index.html diff --git a/source/guides/network/ipxe-install.rst b/source/guides/network/ipxe-install.rst index 1e12fd3c..70e6e7fa 100644 --- a/source/guides/network/ipxe-install.rst +++ b/source/guides/network/ipxe-install.rst @@ -1,10 +1,17 @@ .. _ipxe-install: -Install |CL-ATTR| over the network with iPXE -############################################ +Install over the network with iPXE +################################## This guide describes how to install |CL-ATTR| using :abbr:`PXE (Pre-boot -Execution Environment)`. +Execution Environment)` over the network. + +.. contents:: + :local: + :depth: 1 + +Overview +******** PXE is an industry standard that describes client-server interaction with network-boot software and uses the DHCP and TFTP protocols. This guide shows one @@ -35,7 +42,7 @@ Prerequisites Before booting with iPXE, make the following preparations. Connect the PXE server and PXE clients to a switch on a private network, as -shown in Figure 2. +shown in figure 2. .. figure:: ./figures/network-boot-setup.png :alt: Network topology @@ -63,7 +70,8 @@ Configuration To set up |CL| using iPXE automatically, use the :file:`configure-ipxe.sh` script included with :abbr:`ICIS (Ister Cloud Init Service)`. For additional -instructions on the script, refer to the guide on the `ICIS GitHub repository`_. +instructions on the script, refer to the guide on the `ister-cloud-init-svc`_ +GitHub\* repository. To set up |CL| manually, perform the steps below. @@ -89,7 +97,7 @@ To set up |CL| manually, perform the steps below. sudo -s -#. Add the `pxe-server` bundle to your |CL| system. The bundle contains all +#. Add the :command:`pxe-server` bundle to your |CL| system. The bundle contains all files needed to run a PXE server. .. code-block:: bash @@ -130,8 +138,8 @@ To set up |CL| manually, perform the steps below. boot EOF -#. The `pxe-server` bundle contains a lightweight web-server known as - `nginx`. Create a configuration file for `nginx` to serve |CL| to PXE +#. The :command:`pxe-server` bundle contains a lightweight web-server known as + nginx. Create a configuration file for nginx to serve |CL| to PXE clients with the following contents: .. code-block:: console @@ -152,18 +160,18 @@ To set up |CL| manually, perform the steps below. .. note:: - Create a separate `nginx` configuration file to serve network-bootable - images on a non-standard port number. This action saves existing `nginx` + Create a separate nginx configuration file to serve network-bootable + images on a non-standard port number. This action saves existing nginx configurations. -#. Start `nginx` and enable the startup on boot option. +#. Start nginx and enable the startup on boot option. .. code-block:: bash sudo systemctl start nginx sudo systemctl enable nginx -#. The `pxe-server` bundle contains a lightweight DNS server which +#. The :command:`pxe-server` bundle contains a lightweight DNS server which conflicts with the DNS stub listener provided in `systemd-resolved`. Disable the DNS stub listener and temporarily stop `systemd-resolved`. @@ -221,7 +229,7 @@ To set up |CL| manually, perform the steps below. sudo echo net.ipv4.ip_forward=1 > /etc/sysctl.d/80-nat-forwarding.conf sudo echo 1 > /proc/sys/net/ipv4/ip_forward -#. The `pxe-server` bundle contains iPXE firmware images that allow computers +#. The :command:`pxe-server` bundle contains iPXE firmware images that allow computers without an iPXE implementation to perform an iPXE boot. Create a TFTP hosting directory and populate the directory with the iPXE firmware images with the following commands: @@ -231,7 +239,7 @@ To set up |CL| manually, perform the steps below. sudo mkdir -p $tftp_root sudo ln -sf /usr/share/ipxe/undionly.kpxe $tftp_root/undionly.kpxe -#. The `pxe-server` bundle contains a lightweight TFTP, DNS, and DHCP +#. The :command:`pxe-server` bundle contains a lightweight TFTP, DNS, and DHCP server known as `dnsmasq`. Create a configuration file for `dnsmasq` to listen on a dedicated IP address for those functions. PXE clients on the private network will use this IP address. @@ -252,7 +260,7 @@ To set up |CL| manually, perform the steps below. tftp-root=$tftp_root EOF -#. Add the options to host a DHCP server for PXE clients to the `dnsmasq` +#. Add the options to host a DHCP server for PXE clients to the :file:`dnsmasq` configuration file. .. code-block:: console @@ -328,5 +336,5 @@ server that enables PXE clients to boot and install |CL| over the network. .. _iPXE: http://ipxe.org/ -.. _ICIS GitHub repository: +.. _ister-cloud-init-svc: https://github.com/clearlinux/ister-cloud-init-svc diff --git a/source/guides/network/network-bonding.rst b/source/guides/network/network-bonding.rst index 1f19f0eb..41ba15b9 100644 --- a/source/guides/network/network-bonding.rst +++ b/source/guides/network/network-bonding.rst @@ -3,19 +3,21 @@ Combine multiple interfaces with network bonding ################################################ +This guide describes how to configure systemd to use the :command:`bonding` +driver. + Network bonding combines multiple network interfaces into a single logical interface to provide redundancy and bandwidth aggregation. -|CL-ATTR| includes Linux bonding_ and team_ drivers. This guide describes how -to configure systemd to use the `bonding` driver. +|CL-ATTR| includes the Linux `Bonding driver`_ and `Team driver`_ . The example demonstrates how to: -* Bond all four ports of a quad-port NIC in `802.3ad` mode. +* Bond all four ports of a quad-port NIC in 802.3ad mode. * Enable jumbo frames to optimize large data transfers on the local network. -Your NICs and network switch must support `802.3ad` mode and jumbo frames. The +Your NICs and network switch must support 802.3ad mode and jumbo frames. The example explains how to configure your NICs for both features. Your switch may require additional configuration. See your switch documentation for details. @@ -54,13 +56,13 @@ require additional configuration. See your switch documentation for details. MIIMonitorSec=1s LACPTransmitRate=fast - Refer to the systemd.netdev_ manpage for :file:`30-bond1.netdev` file + Refer to the `systemd.netdev`_ manpage for :file:`30-bond1.netdev` file syntax. This example is based on Example 9 on the manpage. Modify the example for your configuration. #. Configure the slave interfaces. Create a text file named :file:`30-bond1-enp1s0.network`. Assign the slave interfaces to the virtual - `bond1` device and use the syntax shown in systemd.network_. + `bond1` device and use the syntax shown in `systemd.network`_. .. code-block:: console @@ -117,16 +119,12 @@ require additional configuration. See your switch documentation for details. systemctl restart systemd-networkd The `MTUBytes` settings do not take effect until you reboot or manually - apply the settings with a utility such as `ifconfig`. + apply the settings with a utility such as ifconfig. -.. _bonding: - https://www.kernel.org/doc/Documentation/networking/bonding.txt +.. _Bonding driver: https://www.kernel.org/doc/Documentation/networking/bonding.txt -.. _team: - https://www.kernel.org/doc/Documentation/networking/team.txt +.. _Team driver: https://www.kernel.org/doc/Documentation/networking/team.txt -.. _systemd.netdev: - https://www.freedesktop.org/software/systemd/man/systemd.netdev.html +.. _systemd.netdev: https://www.freedesktop.org/software/systemd/man/systemd.netdev.html -.. _systemd.network: - https://www.freedesktop.org/software/systemd/man/systemd.network.html +.. _systemd.network: https://www.freedesktop.org/software/systemd/man/systemd.network.html diff --git a/source/guides/network/vnc.rst b/source/guides/network/vnc.rst index ac0138a0..a734a782 100644 --- a/source/guides/network/vnc.rst +++ b/source/guides/network/vnc.rst @@ -1,42 +1,40 @@ .. _vnc: -Remote-desktop to a |CL-ATTR| host using VNC -############################################## +Remote-desktop to a host using VNC +################################## -:abbr:`VNC (Virtual Network Computing)` is a client-server GUI-based tool -that allows you to connect via remote-desktop to your |CL-ATTR| host. +This guide describes how to use :abbr:`VNC (Virtual Network Computing)` to +connect to a remote |CL-ATTR| host. -This guide shows you how to: +VNC is a client-server GUI-based tool that allows you to connect via +remote-desktop to your |CL| host. -* Install the VNC server and misc. components on your |CL| host. -* Configure a VNC-server-start method on your |CL| host. -* Install a VNC viewer app and an SSH client on your client system. -* Establish a VNC connection to your |CL| host. -* Terminate a VNC connection to your |CL| host. -* Encrypt VNC traffic through an SSH tunnel. +.. contents:: + :local: + :depth: 1 Install the VNC server and misc. components on your host ******************************************************** To configure VNC to work on your |CL| host, install these bundles: -* `desktop-autostart`: Installs :abbr:`GDM (Gnome Desktop Manager)`, sets +* :command:`desktop-autostart`: Installs :abbr:`GDM (Gnome Desktop Manager)`, sets it to start automatically on boot, and installs TigerVNC Viewer. -* `vnc-server`: Installs the TigerVNC server. +* :command:`vnc-server`: Installs the TigerVNC server. Follow these steps: #. Log into your |CL| host and get root privileges. - .. code-block:: console + .. code-block:: bash - $ sudo -s + sudo -s #. Install the |CL| bundles. - .. code-block:: console + .. code-block:: bash - # swupd bundle-add desktop-autostart vnc-server + swupd bundle-add desktop-autostart vnc-server #. Reboot your |CL| host. @@ -51,9 +49,9 @@ your |CL| host: :header-rows: 1 * - Attribute - - `Method 1`: Manually start a VNC session - - `Method 2`: Automatically start a VNC session via a systemd service script - - `Method 3`: Create multi-user logins with authentication through GDM + - Method 1: Manually start a VNC session + - Method 2: Automatically start a VNC session via a systemd service script + - Method 3: Create multi-user logins with authentication through GDM * - Description - This is the traditional method where you SSH into the |CL| host, manually start a VNC session to get a display ID, and connect to it by @@ -86,7 +84,7 @@ Although all three methods can coexist on the same |CL| host, we recommend you pick a method that suits your needs. For simplicity, the rest of this guide refers to these methods as -`Method 1`, `Method 2`, and `Method 3`. +Method 1, Method 2, and Method 3. Method 1: Manually start a VNC session ====================================== @@ -99,16 +97,14 @@ You (and each user) must perform these steps to initialize your VNC settings. first time starting VNC, it adds default configuration files and asks you to set a VNC password. - .. code-block:: console + .. code-block:: bash - $ vncserver + vncserver Example output: .. code-block:: console - $ vncserver - You will require a password to access your desktops. Password: @@ -124,19 +120,20 @@ You (and each user) must perform these steps to initialize your VNC settings. Log file is /home/vnc-user-a/.vnc/clr-linux:2.log Upon completion, you can find the default configuration files and the - password file hidden in the `.vnc` directory in your home directory. + password file hidden in the :file:`.vnc` directory in your home directory. - Also, a VNC session starts and shows a unique display ID, which is the - number following the hostname and the colon `:`. In the above example, the display ID is 2. In a later step, you will supply the display ID to + A VNC session starts and shows a unique display ID, which is the + number following the hostname and the colon ":". In the above example, the + display ID is 2. In a later step, you will supply the display ID to your VNC viewer app for connection. #. Kill the active VNC session for the time being with the :command:`vncserver -kill :[display ID]` command. Substitute [display ID] with your active VNC session display ID. For example: - .. code-block:: console + .. code-block:: bash - $ vncserver -kill :2 + vncserver -kill :2 .. note:: @@ -159,29 +156,29 @@ preassigned unique display ID. #. Log in and get root privileges. - .. code-block:: console + .. code-block:: bash - $ sudo -s + sudo -s #. Make sure the user accounts already exist. Use the following command to list all users. - .. code-block:: console + .. code-block:: bash - # cut -d: -f1 /etc/passwd + cut -d: -f1 /etc/passwd #. Create the path :file:`/etc/systemd/system`. - .. code-block:: console + .. code-block:: bash - # mkdir -p /etc/systemd/system + mkdir -p /etc/systemd/system #. Create a systemd service script file :file:`vncserver@:[X].service`, where [X] is the display ID, for each user in :file:`/etc/systemd/system` Each user must be assigned a unique display ID. Be sure the correct - username is entered in the `User` field. The example below shows user - `vnc-user-b` who is assigned the display ID `5`. + username is entered in the :guilabel:`User` field. The example below shows user + vnc-user-b who is assigned the display ID 5. .. code-block:: console @@ -211,20 +208,20 @@ preassigned unique display ID. #. Start the VNC service script and set it to start automatically on boot for each user. Replace the [X] with the display ID. - .. code-block:: console + .. code-block:: bash - # systemctl daemon-reload - # systemctl start vncserver@:[X].service - # systemctl enable vncserver@:[X].service + systemctl daemon-reload + systemctl start vncserver@:[X].service + systemctl enable vncserver@:[X].service #. After starting the services, verify they are running. - .. code-block:: console + .. code-block:: bash - # systemctl | grep vnc + systemctl | grep vnc The example below shows 2 VNC sessions that were successfully started for - users `vnc-user-b` with display ID 5 and `vnc-user-c` with display ID 6. + users vnc-user-b with display ID 5 and vnc-user-c with display ID 6. .. code-block:: console @@ -239,19 +236,21 @@ Method 3: Multi-user logins with authentication through GDM For this method, VNC is configured as a systemd service that listens on port 5900 and GDM is configured to accept access requests from VNC. When you -make a VNC connection to your |CL| host, you are presented with the GDM login screen and you authenticate as if you are local. You must have root privileges to perform this configuration. +make a VNC connection to your |CL| host, you are presented with the GDM login +screen and you authenticate as if you are local. You must have root privileges +to perform this configuration. #. Log in and get root privileges. - .. code-block:: console + .. code-block:: bash - $ sudo -s + sudo -s #. Create the path :file:`/etc/systemd/system`. - .. code-block:: console + .. code-block:: bash - # mkdir -p /etc/systemd/system + mkdir -p /etc/systemd/system #. Create a systemd socket file :file:`xvnc.socket` and add the following: @@ -290,9 +289,9 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc #. Create the path :file:`/etc/gdm`. - .. code-block:: console + .. code-block:: bash - # mkdir -p /etc/gdm + mkdir -p /etc/gdm #. Create a GDM :file:`custom.conf` file and add the following: @@ -309,17 +308,17 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc #. Start the VNC socket script and set it to start automatically on boot. - .. code-block:: console + .. code-block:: bash - # systemctl daemon-reload - # systemctl start xvnc.socket - # systemctl enable xvnc.socket + systemctl daemon-reload + systemctl start xvnc.socket + systemctl enable xvnc.socket #. After starting the socket, verify it is running. - .. code-block:: console + .. code-block:: bash - # systemctl | grep vnc + systemctl | grep vnc The example below shows the xvnc.socket is running. @@ -330,13 +329,13 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc xvnc.socket loaded active listening XVNC Server on port 5900 system-xvnc.slice loaded active active system-xvnc.slice -See the `vncserver` Man page for additional information. +See the vncserver Man page for additional information. Install a VNC viewer app and an SSH client on your client system **************************************************************** You need a VNC viewer app on your client system to connect to your |CL| host. -An SSH client is only needed if you chose to use `Method 1` or you plan to +An SSH client is only needed if you chose to use Method 1 or you plan to encrypt your VNC traffic, which is discussed later in this guide. Perform the steps below to add these apps to your client system. @@ -346,27 +345,27 @@ Install a VNC viewer app On |CL|: -.. code-block:: console +.. code-block:: bash - # swupd bundle-add desktop-autostart + swupd bundle-add desktop-autostart -On Ubuntu, Mint: +On Ubuntu\*, Mint\*: -.. code-block:: console +.. code-block:: bash - # apt-get install xtightvncviewer + apt-get install xtightvncviewer -On Fedora: +On Fedora\*: -.. code-block:: console +.. code-block:: bash - # dnf install tigervnc + dnf install tigervnc -On Windows: +On Windows\*: * Install `RealVNC for Windows`_ -On macOS: +On macOS\*: * Install `RealVNC for macOS`_ @@ -380,17 +379,17 @@ Install an SSH client Establish a VNC connection to your host *************************************** -Depending on the VNC-server-configuration method chosen, use the appropriate VNC connection: +Depending on the VNC-server-configuration method chosen, use the appropriate VNC +connection: -If you chose `Method 1`, you must take a few extra steps by -using SSH to connect to your |CL| host and then manually launching VNC. +* If you chose Method 1, you must take a few extra steps by using SSH to connect + to your |CL| host and then manually launching VNC. -If you chose `Method 2`, get your preassigned VNC display ID from your -system administrator first and then proceed to the -:ref:`connect-to-vnc-session` section below. +* If you chose Method 2, get your preassigned VNC display ID from your system + administrator first and then proceed to the :ref:`connect-to-vnc-session` + section below. -If you chose `Method 3`, proceed to the -:ref:`connect-to-vnc-session` below. +* If you chose Method 3, proceed to the :ref:`connect-to-vnc-session` below. SSH into your host and launch VNC @@ -400,9 +399,9 @@ SSH into your host and launch VNC #. On Linux distros and macOS: - .. code-block:: console + .. code-block:: bash - $ ssh [username]@[clear-linux-host-ip-address] + ssh [username]@[clear-linux-host-ip-address] #. On Windows: @@ -420,20 +419,17 @@ SSH into your host and launch VNC Figure 1: Putty - configure SSH session settings -#. Log in with your |CL| username and password. Do not use your VNC - password. +#. Log in with your |CL| username and password. Do not use your VNC password. #. Start a VNC session. - .. code-block:: console + .. code-block:: bash - $ vncserver + vncserver Example output: .. code-block:: console - $ vncserver - New 'clr-linux:3 (vnc-user-c)' desktop is clr-linux:3 Starting applications specified in /home/vnc-user-c/.vnc/xstartup @@ -449,9 +445,9 @@ SSH into your host and launch VNC To specify a display ID, enter a unique number that is not already in use after the colon. For example: - .. code-block:: console + .. code-block:: bash - $ vncserver :8 + vncserver :8 #. You can now end the SSH connection by logging out. This does not terminate your active VNC session. @@ -461,38 +457,38 @@ SSH into your host and launch VNC Connect to your VNC session =========================== -For `Method 1` and `Method 2`, you must connect to a specific active session +For Method 1 and Method 2, you must connect to a specific active session or display ID using one of two options: * Use a fully-qualified VNC port number, which consists of the default VNC server port (5900) plus the display ID * Use the display ID -For example, if the display ID is 3, it can be specified as `5903` or just -as `3`. For `Method 3`, VNC does not expect a display ID. Use `5900`. For simplicity, the instructions below use the fully-qualified VNC port -number. +For example, if the display ID is 3, it can be specified as 5903 or just +as 3. For Method 3, VNC does not expect a display ID. Use 5900. For simplicity, +the instructions below use the fully-qualified VNC port number. **On Linux distros:** #. Open a terminal emulator and enter: - .. code-block:: console + .. code-block:: bash - $ vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port number] + vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port number] #. Enter your credentials. - * For `Method 1` and `Method 2`, enter your VNC password. No username is + * For Method 1 and Method 2, enter your VNC password. No username is required. - * For `Method 3`, enter your |CL| account username and password through + * For Method 3, enter your |CL| account username and password through GDM. .. note:: - With `Method 3`, you cannot remotely log into your |CL| host through + With Method 3, you cannot remotely log into your |CL| host through VNC if you are logged in locally and vice versa. -**On Windows and macOS using `RealVNC` app:** +**On Windows and macOS using RealVNC app:** #. Start the RealVNC viewer app. See Figure 2. #. Enter the IP address of the |CL| host and the fully-qualified @@ -511,20 +507,21 @@ number. #. Enter your credentials. - * For `Method 1` and `Method 2`, enter your VNC password. No username is + * For Method 1 and Method 2, enter your VNC password. No username is required. - * For `Method 3`, enter your |CL| account username and password through + * For Method 3, enter your |CL| account username and password through GDM. .. note:: - With `Method 3`, you cannot remotely log into your |CL| host through + With Method 3, you cannot remotely log into your |CL| host through VNC if you are logged in locally and vice versa. -`Optional: Configure RealVNC Image Quality` -------------------------------------------- +Optional: Configure RealVNC Image Quality +----------------------------------------- -To increase the RealVNC viewer image quality, manually change the `ColorLevel` value. Follow these steps: +To increase the RealVNC viewer image quality, manually change the :guilabel:`ColorLevel` +value. Follow these steps: #. Right-click a connection node and select :guilabel:`Properties...`. See Figure 3. @@ -549,7 +546,7 @@ To increase the RealVNC viewer image quality, manually change the `ColorLevel` v Terminate a VNC connection to your host *************************************** -For `Method 1` and `Method 2`, once started, a VNC session remains active +For Method 1 and Method 2, once started, a VNC session remains active on your |CL| host even if you close your VNC viewer app. If you want to truly terminate an active VNC session, follow these steps: @@ -558,24 +555,24 @@ truly terminate an active VNC session, follow these steps: #. Find the active VNC session display ID with the command :command:`vncserver -list`. - .. code-block:: console + .. code-block:: bash - $ vncserver -list + vncserver -list #. Terminate it with the :command:`vncserver -kill` command followed by a colon and the display ID. - .. code-block:: console + .. code-block:: bash - $ vncserver -kill :[display ID] + vncserver -kill :[display ID] -#. For `Method 3`, only the system administrator can stop and disable the +#. For Method 3, only the system administrator can stop and disable the VNC service by using these commands: - .. code-block:: console + .. code-block:: bash - # systemctl stop xvnc.socket - # systemctl disable xnvc.socket + systemctl stop xvnc.socket + systemctl disable xnvc.socket Encrypt VNC traffic through an SSH tunnel @@ -590,10 +587,11 @@ from RealVNC Viewer. Figure 6: RealVNC Viewer - Connection not encrypted warning -To add security, VNC traffic can be routed through an SSH tunnel. This is accomplished by following these steps: +To add security, VNC traffic can be routed through an SSH tunnel. This is +accomplished by following these steps: #. Configure the VNC server to only accept connection from localhost by - adding the `-localhost` option. + adding the :command:`-localhost` option. #. Set up an SSH tunnel between your client system and your |CL| host. Your client system will forward traffic from the localhost (the client) destined for a specified fully-qualified VNC port number (on the client) @@ -604,7 +602,7 @@ To add security, VNC traffic can be routed through an SSH tunnel. This is accomp Configure VNC to only accept connection from localhost ====================================================== -For `Method 1`: +For Method 1: #. Edit the :file:`config` file located in :file:`$HOME/.vnc` and uncomment the `# localhost` line. It should look like this: @@ -624,10 +622,10 @@ For `Method 1`: #. If an active session exists, kill it, and then restart it. -For `Method 2`: +For Method 2: #. Edit the systemd service script :file:`vncserver@:[X].service` located in - :file:`/etc/systemd/system` and add `-localhost` to the `ExecStart` + :file:`/etc/systemd/system` and add :command:`-localhost` to the `ExecStart` line. The example below uses vncserver@:5.service: .. code-block:: console @@ -650,12 +648,12 @@ For `Method 2`: #. Restart the service script: - .. code-block:: console + .. code-block:: bash - # systemctl daemon-load - # systemctl restart vncserver@:5.service + systemctl daemon-load + systemctl restart vncserver@:5.service -For `Method 3`: +For Method 3: #. No change is needed to the :file:`xvnc@service` script. @@ -663,17 +661,18 @@ For `Method 3`: accepts connections from localhost by using the :command:`netstat` command like this: - .. code-block:: console + .. code-block:: bash - $ netstat -plant + netstat -plant .. note:: - Add the |CL| `network-basic` bundle to get the :command:`netstat` + Add the |CL| :command:`network-basic` bundle to get the :command:`netstat` command. Figure 7 shows two VNC sessions (5901 and 5905) accepting connections from -any host as specified by the `0.0.0.0`'s. This is before the `-localhost` option was used. +any host as specified by the `0.0.0.0`'s. This is before the +:command:`-localhost` option was used. .. figure:: figures/vnc/vnc-7.png :scale: 100 % @@ -681,7 +680,9 @@ any host as specified by the `0.0.0.0`'s. This is before the `-localhost` optio Figure 7: VNC sessions (5901 and 5905) accepting connections from any host -Figure 8 shows two VNC sessions (5901 and 5905) only accepting connections from localhost as specified by `127.0.0.1`'s. This is after the `-localhost` option was used. +Figure 8 shows two VNC sessions (5901 and 5905) only accepting connections from +localhost as specified by `127.0.0.1`'s. This is after the +:command:`-localhost` option was used. .. figure:: figures/vnc/vnc-8.png :scale: 100 % @@ -696,9 +697,9 @@ Set up an SSH tunnel from your client system to your |CL| host #. Open terminal emulator and enter: - .. code-block:: console + .. code-block:: bash - $ ssh -L [client port number]:localhost:[fully-qualified VNC port number] \ + ssh -L [client port number]:localhost:[fully-qualified VNC port number] \ -N -f -l [username] [clear-linux-host-ip-address] #. Enter your |CL| account password (not your VNC password). @@ -763,9 +764,9 @@ your VNC session. #. Open terminal emulator and enter: - .. code-block:: console + .. code-block:: bash - $ vncviewer localhost:[client port number] + vncviewer localhost:[client port number] **On Windows and macOS using `RealVNC`:** diff --git a/source/tutorials/dars.rst b/source/guides/stacks/dars.rst similarity index 92% rename from source/tutorials/dars.rst rename to source/guides/stacks/dars.rst index a134c938..8e1a6848 100644 --- a/source/tutorials/dars.rst +++ b/source/guides/stacks/dars.rst @@ -3,7 +3,7 @@ Data Analytics Reference Stack ############################## -This tutorial shows you how to use the Data Analytics Reference Stack +This guide shows you how to use the Data Analytics Reference Stack (DARS), and to optionally build your own images with the baseline Dockerfiles provided in the `DARS repository`_. Our assumption is that |CL-ATTR| is the host. However, any system that supports Docker\* containers can be used to @@ -30,15 +30,16 @@ not be the latest released by |CL|. .. note:: - The Data Analytics Reference Stack is a collective work, and each piece of software within the work has its own license. Please see the `terms of use`_ for more details about licensing and usage of the Data Analytics Reference Stack. - - + The Data Analytics Reference Stack is a collective work, and each piece + of software within the work has its own license. Please see the `terms + of use`_ for more details about licensing and usage of the Data Analytics + Reference Stack. Using the Docker Images *********************** To immediately start using the latest stable DARS images, pull directly -from `Docker Hub`_. For this tutorial we'll use the `Dars with MKL`_ version of the stack. +from `Docker Hub`_. For this guide we'll use the `Dars with MKL`_ version of the stack. Once you have downloaded the image, you can run it with @@ -99,7 +100,6 @@ You can use any of the resulting images to launch fully functional containers. If you need to customize the containers, you can edit the provided :file:`Dockerfile`. - .. _DARS repository: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dars .. _Docker Hub: https://hub.docker.com/ .. _OpenBLAS: http://www.openblas.net/ diff --git a/source/tutorials/dlrs/dlrs.rst b/source/guides/stacks/dlrs/dlrs.rst similarity index 94% rename from source/tutorials/dlrs/dlrs.rst rename to source/guides/stacks/dlrs/dlrs.rst index 49dd3930..ea09e94f 100644 --- a/source/tutorials/dlrs/dlrs.rst +++ b/source/guides/stacks/dlrs/dlrs.rst @@ -3,7 +3,7 @@ Deep Learning Reference Stack ############################# -This tutorial describes how to run benchmarking workloads for TensorFlow\*, +This guide describes how to run benchmarking workloads for TensorFlow\*, PyTorch\*, and Kubeflow in |CL-ATTR| using the Deep Learning Reference Stack. .. contents:: @@ -13,11 +13,12 @@ PyTorch\*, and Kubeflow in |CL-ATTR| using the Deep Learning Reference Stack. Overview ******** -We created the Deep Learning Reference Stack to help AI developers deliver the -best experience on Intel® Architecture. This stack reduces complexity common -with deep learning software components, provides flexibility for customized -solutions, and enables you to quickly prototype and deploy Deep Learning -workloads. Use this tutorial to run benchmarking workloads on your solution. +We created the Deep Learning Reference Stack to help AI developers deliver +the best experience on Intel® Architecture. This stack reduces complexity +common with deep learning software components, provides flexibility for +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: @@ -103,7 +104,7 @@ We validated these steps against the following software package versions: .. note:: - The Deep Learning Reference Stack was developed to provide the best user experience when executed on a |CL| host. However, as the stack runs in a container environment, you should be able to complete the following sections of this tutorial on other Linux* distributions, provided they comply with the Docker*, Kubernetes* and Go* package versions listed above. Look for your distribution documentation on how to update packages and manage Docker services. + The Deep Learning Reference Stack was developed to provide the best user experience when executed on a |CL| host. However, as the stack runs in a container environment, you should be able to complete the following sections of this guide on other Linux* distributions, provided they comply with the Docker*, Kubernetes* and Go* package versions listed above. Look for your distribution documentation on how to update packages and manage Docker services. TensorFlow single and multi-node benchmarks ******************************************* @@ -115,9 +116,7 @@ TensorFlow. .. note:: - Performance test results for the Deep Learning Reference Stack and for this tutorial were - obtained using `runc` as the runtime. - + Performance test results for the Deep Learning Reference Stack and for this guide were obtained using `runc` as the runtime. #. Download either the `Eigen`_ or the `Intel MKL-DNN`_ Docker image from `Docker Hub`_. @@ -194,12 +193,12 @@ single node. Kubeflow multi-node benchmarks ****************************** -The benchmark workload runs in a Kubernetes cluster. The tutorial uses +The benchmark workload runs in a Kubernetes cluster. The guide uses `Kubeflow`_ for the Machine Learning workload deployment on three nodes. .. warning:: - If you choose the Intel® MKL-DNN or Intel® MKL-DNN-VNNI image, your platform must support the Intel® AVX-512 instruction set. Otherwise, an *illegal instruction* error may appear, and you won’t be able to complete this tutorial. + If you choose the Intel® MKL-DNN or Intel® MKL-DNN-VNNI image, your platform must support the Intel® AVX-512 instruction set. Otherwise, an *illegal instruction* error may appear, and you won’t be able to complete this guide. Kubernetes setup @@ -255,7 +254,7 @@ Images You must add `launcher.py`_ to the Docker image to include the Deep Learning Reference Stack and put the benchmarks repo in the correct -location. Note that this tutorial uses Kubeflow v0.4.0, and cannot guarantee results if you use a different version. +location. Note that this guide uses Kubeflow v0.4.0, and cannot guarantee results if you use a different version. From the Docker image, run the following: @@ -362,8 +361,8 @@ Run a TFJob This replicates and deploys three test setups in your Kubernetes cluster. -Results of running this tutorial -================================ +Results of running this guide +============================= You must parse the logs of the Kubernetes pod to retrieve performance data. The pods will still exist post-completion and will be in diff --git a/source/tutorials/dlrs/figures/dlrs-fig-1.png b/source/guides/stacks/dlrs/figures/dlrs-fig-1.png similarity index 100% rename from source/tutorials/dlrs/figures/dlrs-fig-1.png rename to source/guides/stacks/dlrs/figures/dlrs-fig-1.png diff --git a/source/tutorials/dlrs/figures/dlrs-fig-2.png b/source/guides/stacks/dlrs/figures/dlrs-fig-2.png similarity index 100% rename from source/tutorials/dlrs/figures/dlrs-fig-2.png rename to source/guides/stacks/dlrs/figures/dlrs-fig-2.png diff --git a/source/tutorials/dlrs/figures/dlrs-fig-3.png b/source/guides/stacks/dlrs/figures/dlrs-fig-3.png similarity index 100% rename from source/tutorials/dlrs/figures/dlrs-fig-3.png rename to source/guides/stacks/dlrs/figures/dlrs-fig-3.png diff --git a/source/tutorials/dlrs/figures/dlrs-fig-4.png b/source/guides/stacks/dlrs/figures/dlrs-fig-4.png similarity index 100% rename from source/tutorials/dlrs/figures/dlrs-fig-4.png rename to source/guides/stacks/dlrs/figures/dlrs-fig-4.png diff --git a/source/tutorials/dlrs/figures/dlrs-fig-5.png b/source/guides/stacks/dlrs/figures/dlrs-fig-5.png similarity index 100% rename from source/tutorials/dlrs/figures/dlrs-fig-5.png rename to source/guides/stacks/dlrs/figures/dlrs-fig-5.png diff --git a/source/tutorials/greengrass.rst b/source/guides/stacks/greengrass.rst similarity index 94% rename from source/tutorials/greengrass.rst rename to source/guides/stacks/greengrass.rst index 311a905b..4d780f28 100644 --- a/source/tutorials/greengrass.rst +++ b/source/guides/stacks/greengrass.rst @@ -6,36 +6,36 @@ Enable AWS Greengrass\* and OpenVINO™ toolkit Hardware accelerated Function-as-a-Service (FaaS) enables cloud developers to deploy inference functionalities [1] on Intel® IoT edge devices with accelerators (CPU, Integrated GPU, Intel® FPGA, and Intel® Movidius™ -technology). These functions provide a great developer experience and seamless -migration of visual analytics from cloud to edge in a secure manner using a -containerized environment. Hardware-accelerated FaaS provides the best-in-class -performance by accessing optimized deep learning libraries on Intel® IoT -edge devices with accelerators. +technology). These functions provide a great developer experience and +seamless migration of visual analytics from cloud to edge in a secure manner +using a containerized environment. Hardware-accelerated FaaS provides the +best-in-class performance by accessing optimized deep learning libraries on +Intel® IoT edge devices with accelerators. -This tutorial demonstrates how to: +This guide demonstrates how to: * Set up the Intel® edge device with |CL-ATTR| * Install the OpenVINO™ toolkit and Amazon Web Services\* (AWS\*) Greengrass\* software stacks -* Use AWS Greengrass\* and AWS Lambda\* to deploy the FaaS samples from the cloud +* Use AWS Greengrass\* and AWS Lambda\* to deploy the FaaS samples from + the cloud Refer to the following topics: .. contents:: :local: :depth: 1 - Supported platforms ******************* * Operating System: |CL| latest release -* Hardware: Intel® core platforms (This tutorial supports inference on CPU only.) +* Hardware: Intel® core platforms (that support inference on CPU only) Sample description ================== The AWS Greengrass samples are located at `Edge-Analytics-FaaS`_. This -tutorial uses the 1.0 version of the source code. +guide uses the 1.0 version of the source code. |CL| provides the following AWS Greengrass samples: @@ -117,9 +117,9 @@ Locate sample models -------------------- There are two types of provided models that can be used in conjunction with -AWS Greengrass for this tutorial: classification or object detection. +AWS Greengrass for this guide: classification or object detection. -To complete this tutorial using an image classification model, +To complete this guide using an image classification model, download the BVLC AlexNet model files `bvlc_alexnet.caffemodel`_ and `deploy.prototxt`_ to the default model_location at :file:`/usr/share/openvino/models`. Any custom pre-trained classification models can be used with the @@ -203,7 +203,7 @@ cloud and edge. Create and package Lambda function ********************************** -#. Complete steps 1-4 of the AWS Greengrass tutorial at `Create and Package a Lambda Function`_. +#. Complete steps 1-4 of the AWS Greengrass guide at `Create and Package a Lambda Function`_. .. note:: @@ -271,7 +271,7 @@ configuring the Lambda function for AWS Greengrass. * - PARAM_MODEL_XML - /, where is user specified and contains IR.xml, the Intermediate Representation file from Intel® Model Optimizer. - For this tutorial, should be set to '/usr/share/openvino/models' + For this guide, should be set to '/usr/share/openvino/models' or one of its subdirectories. * - PARAM_INPUT_SOURCE - /input.webm to be specified by user. Holds both input and @@ -292,8 +292,7 @@ configuring the Lambda function for AWS Greengrass. .. note:: - The optional topic filter field is the topic mentioned inside the Lambda - function. In this tutorial, sample topics include the following: + The optional topic filter field is the topic mentioned inside the Lambda function. In this guide, sample topics include the following: :command:`openvino/ssd` or :command:`openvino/classification` Add local resources diff --git a/source/guides/telemetrics/telem-guide.rst b/source/guides/telemetrics/telem-guide.rst index 09610cd7..aa68b3aa 100644 --- a/source/guides/telemetrics/telem-guide.rst +++ b/source/guides/telemetrics/telem-guide.rst @@ -3,10 +3,7 @@ Telemetrics ########### -Telemetrics in |CL-ATTR| is a client and server solution used to collect -data from running |CL| systems to help quickly identify and fix bugs in the -OS. Both client and server are customizable, and an API is available on the -client side for instrumenting your code for debug and analysis. +This guide describes the |CL-ATTR| telemetry solution. .. important:: @@ -17,17 +14,22 @@ client side for instrumenting your code for debug and analysis. The telemetry functionality adheres to `Intel privacy policies`_ regarding the collection and use of :abbr:`PII (Personally Identifiable Information)` - and is open source. - Specifically, no intentionally identifiable information about the user or - system owner is collected. + and is open source. + + No intentionally identifiable information about the user or system owner is + collected. .. contents:: :local: :depth: 1 +Overview +******** -Description -*********** +Telemetrics in |CL| is a client and server solution used to collect +data from running |CL| systems to help quickly identify and fix bugs in the +OS. Both client and server are customizable, and an API is available on the +client side for instrumenting your code for debug and analysis. Telemetry, one of the key features of |CL|, enables developers to observe and proactively address issues in the OS before end users are impacted. @@ -57,7 +59,7 @@ Enabling the client is covered in this guide. Architecture ============ -|CL| telemetry has two fundamental components, which are shown in figure 1: +|CL| telemetry has two fundamental components, which are shown in Figure 1: * Client: generates and delivers records to the backend server via the network. @@ -125,7 +127,7 @@ Scenarios #. Save record data locally: - You can configure the telemetry client to save records locally. This is + You can configure the telemetry client to save records locally. This is convenient when you want instant feedback during a development cycle, or to track system issues if you believe there is a machine specific problem. The client can be set not to send records at all, or to both keep the records @@ -141,7 +143,7 @@ Scenarios #. Instrument your code with the libtelemetry API: - The ``telemetrics`` bundle includes the libtelemetry C library, which + The :command:`telemetrics` bundle includes the libtelemetry C library, which exposes an API used by the telemprobd and telempostd daemons. You can use these in your applications as well. The API documentation is found in the :file:`telemetry.h` file in `Telemetrics client`_ repository. @@ -228,10 +230,10 @@ system. To change how records are managed, copy the default :file:`/usr/share/defaults/telemetrics/telemetrics.conf` file to -:file:`/etc/telemetrics/telemetrics.conf` and edit it. The changes in the +:file:`/etc/telemetrics/telemetrics.conf` and edit it. The changes in the :file:`/etc/telemetrics/telemetrics.conf` file will override the defaults in the :file:`/usr/share/defaults/telemetrics/telemetrics.conf` file. You may need -``root`` permissions to create and edit files in :file:`/etc`. For each +root permissions to create and edit files in :file:`/etc`. For each example, and for any time you make changes to the configuration file, you must restart the client daemons to pick up the changes: @@ -249,15 +251,15 @@ Use :command:`-h` or :command:`--help` to view usage options. #. Keep a local copy and send records to backend server: To keep a local copy of the telemetry record and also send it on to the - backend server, we will need to change the :guilabel:` - record_retention_enabled` configuration key value to :guilabel:`true`. - + backend server, we will need to change the + :guilabel:`record_retention_enabled` configuration key value to + :guilabel:`true`. #. Keep all records -- don't send to backend server: To keep records on the system without sending them to a backend server, set the :guilabel:`record_server_delivery_enabled` key value to - :guilabel:`false`. Note that you will also need to ensure the + :guilabel:`false`. Note that you will also need to ensure the :guilabel:`record_retention_enabled` configuration key value is set to :guilabel:`true` or the system will not keep local copies. @@ -266,9 +268,9 @@ Use :command:`-h` or :command:`--help` to view usage options. This assumes you have set up a custom server according to the next example. The server is identified by the :guilabel:`server` setting, and by default - records are sent to the |CL| server :guilabel:`server=https://clr. - telemetry.intel.com/v2/collector`. To change this, you can use an IP - address or fully qualified domain name. + records are sent to the |CL| server + :guilabel:`server=https://clr.telemetry.intel.com/v2/collector`. To change + this, you can use an IP address or fully qualified domain name. Set up a back-end server to collect telemetry records @@ -303,13 +305,13 @@ using the :ref:`bare-metal-install-server` getting started guide and: #. Before you install the telemetrics backend with the :file:`deploy.sh` script file in the next step, here is an explanation of the options to be specified: - * *-a install* to perform an install - * *-d clr* to install to a |CL| distro - * *-H localhost* to set the domain to localhost + * :command:`-a install` to perform an install + * :command:`-d clr` to install to a |CL| distro + * :command:`-H localhost` to set the domain to localhost .. caution:: The :file:`deploy.sh` shell script has minimal error checking and makes - several changes to your system. Be sure that the options you define on + several changes to your system. Be sure that the options you define on the cmdline are correct before proceeding. #. Run the shell script from the :file:`$HOME/telemetrics-backend/scripts` @@ -358,26 +360,24 @@ using the :ref:`bare-metal-install-server` getting started guide and: passwd: password updated successfully Enter `postgres` for the current value of the password and then enter a new - password, retype it to verify the new password and the - :guilabel:`PostgreSQL` database password will be updated. + password, retype it to verify the new password and the :guilabel:`PostgreSQL` + database password will be updated. #. After the installation is complete, you can use your web browser to view the - new server by opening the browser on the system and typing in ``localhost`` - in the address bar. You should see a web page similar to the one shown in - figure 1: + new server by opening the browser on the system and typing in localhost + in the address bar. You should see a web page similar to the one shown in + Figure 2 below. .. figure:: figures/telemetry-backend-1.png :alt: Telemetry UI - Figure 1: :guilabel:`Telemetry UI` - - + Figure 2: :guilabel:`Telemetry UI` Create records with telem-record-gen ==================================== The telemetrics bundle provides a record generator tool called -``telem-record-gen``. This tool can be used to create records from shell +`telem-record-gen`. This tool can be used to create records from shell scripts or the command line when writing a probe in C is not desirable. Records are sent to the backend server, and can also be echoed to stdout. @@ -470,7 +470,7 @@ Set a static machine id The machine id reported by the telemetry client is rotated every three days for privacy reasons. If you wish to have a static machine id for testing -purposes, you can opt in by creating a file named "opt-in-static-machine-id" +purposes, you can opt in by creating a file named `opt-in-static-machine-id` in the directory :file:`/etc/telemetrics/`. #. Create a directory `telemetrics`. @@ -489,7 +489,7 @@ in the directory :file:`/etc/telemetrics/`. .. note:: - The `machine id` is different than the system hostname. + The machine ID is different than the system hostname. Instrument your code with the libtelemetry API ============================================== @@ -499,8 +499,8 @@ Prerequisites Confirm that the telemetrics header file is located on the system at :file:`usr/include/telemetry.h` The `latest version`_ of the file can also be -found on github for reference, but installing the `telemetry` bundle will -install the header file that matches your |CL| version. +found on github for reference, but installing the :command:`telemetry` bundle +will install the header file that matches your |CL| version. #. Includes and variables: @@ -560,9 +560,8 @@ install the header file that matches your |CL| version. Type: char pointer Value: The payload to set - - -#. For this example, we'll set the payload to “hello” by using ``asprintf()``: +#. For this example, we'll set the payload to “hello” by using + :command:`asprintf()`: .. code-block:: console @@ -570,21 +569,19 @@ install the header file that matches your |CL| version. exit(EXIT_FAILURE); } - - - The functions ``asprintf()`` and ``vasprintf()`` are analogs of - ``sprintf(3)`` and ``vsprintf(3)``, except that they allocate a string - large enough to hold the output including the terminating null byte ('\0'), - and return a pointer to it via the first argument. This pointer should be - passed to ``free(3)`` to release the allocated storage when it is no longer - needed. + The functions :command:`asprintf()` and :command:`vasprintf()` are analogs of + :command:`sprintf(3)` and :command:`vsprintf(3)`, except that they allocate a + string large enough to hold the output including the terminating null byte + ('\0'), and return a pointer to it via the first argument. This pointer + should be passed to :command:`free(3)` to release the allocated storage when + it is no longer needed. #. Create the new telemetry record: - The function ``tm_create_record()`` initializes a telemetry record and + The function :command:`tm_create_record()` initializes a telemetry record and sets the severity and classification of that record, as well as the payload version number. The memory needed to store the telemetry record is allocated - and should be freed with ``tm_free_record()`` when no longer needed. + and should be freed with :command:`tm_free_record()` when no longer needed. .. code-block:: console @@ -596,7 +593,7 @@ install the header file that matches your |CL| version. #. Set the payload field of a telemetrics record: - The function ``tm_set_payload()`` attaches the provided telemetry record + The function :command:`tm_set_payload()` attaches the provided telemetry record data to the telemetry record. The current maximum payload size is 8192b. .. code-block:: console @@ -608,17 +605,17 @@ install the header file that matches your |CL| version. } free(payload); - The ``free()`` function frees the memory space pointed to by ptr, which - must have been returned by a previous call to ``malloc()``, ``calloc()``, - or ``realloc()``. Otherwise, or if ``free(ptr)`` has already been called - before, undefined behavior occurs. If ptr is NULL, no operation is - performed. + The :command:`free()` function frees the memory space pointed to by `ptr`, which + must have been returned by a previous call to :command:`malloc()`, + :command:`calloc()`, or :command:`realloc()`. Otherwise, or if + :command:`free(ptr)` has already been called before, undefined behavior + occurs. If `ptr` is NULL, no operation is performed. #. Send a record to the telemetrics daemon: - The function ``tm_send_record()`` delivers the record to the local - ``telemprobd(1)`` service. Since the telemetry record was allocated by - the program it should be freed with ``tm_free_record()`` when it is no + The function :command:`tm_send_record()` delivers the record to the local + :command:`telemprobd(1)` service. Since the telemetry record was allocated by + the program it should be freed with :command:`tm_free_record()` when it is no longer needed. .. code-block:: console @@ -640,7 +637,7 @@ install the header file that matches your |CL| version. #. A full sample application with compiling flags: - Create a new file test.c and add the following code: + Create a new file :file:`test.c` and add the following code: .. code-block:: console @@ -724,7 +721,7 @@ Reference The telemetry API ================= -Installing the ``telemetrics`` bundle includes the libtelemetry C library, +Installing the :command:`telemetrics` bundle includes the libtelemetry C library, which exposes an API used by the telemprobd and telempostd daemons. You can use these in your applications as well. The API documentation is found in the :file:`telemetry.h` file in `Telemetrics client`_ repository. @@ -744,54 +741,63 @@ Configuration options The client uses the following configuration options from the config file: -* **server**: This specifies the web server to which telempostd sends the - telemetry records. -* **socket_path**: This specifies the path of the unix domain socket on which - the telemprobd listens for connections from the probes. -* **spool_dir**: This configuration option is related to spooling. If the - daemon is not able to send the telemetry records to the backend server due - to reasons such as the network availability, then it stores the records in - a spool directory. This option specifies the path of the spool directory. - This directory should be owned by the same user as the daemon. -* **record_expiry**: This is the time, in minutes, after which the records in - the spool directory are deleted by the daemon. -* **spool_process_time**: This specifies the time interval, in seconds, that - the daemon waits for before checking the spool directory for records. The - daemon picks up the records in the order of modification date and tries to - send the record to the server. It sends a maximum of 10 records at a time. - If it was able to send a record successfully, it deletes the record from the - spool. If the daemon finds a record older than the "record_expiry" time, then - it deletes that record. The daemon looks at a maximum of 20 records in a - single spool run loop. -* **rate_limit_enabled**: This determines whether rate-limiting is enabled - or disabled. When enabled, there is a threshold on both records sent within - a window of time, and record bytes sent within a window a time. -* **record_burst_limit**: This is the maximum amount of records allowed to be - passed by the daemon within the record_window_length of time. If set to -1, - the rate-limiting for record bursts is disabled. -* **record_window_length**: The time, in minutes (0-59), that establishes the - window length for the record_burst_limit. For example, if - record_burst_window=1000 and record_window_length=15, then no more than - 1000 records can be passed within any given fifteen-minute window. -* **byte_burst_limit**: This is the maximum amount of bytes that can be - passed by the daemon within the byte_window_length of time. If set to -1, - the rate-limiting for byte bursts is disabled. -* **byte_window_length**: This is the time, in minutes (0-59), that establishes - the window length for the byte_burst_limit. -* **rate_limit_strategy**: This is the strategy chosen once the rate-limiting - threshold has been reached. Currently the options are 'drop' or 'spool', - with spool being the default. If spool is chosen, records will be spooled - and sent at a later time. -* **record_retention_enabled**: When this key is enabled (true) the daemon - saves a copy of the payload on disk from all valid records. To avoid the - excessive use of disk space only the latest 100 records are kept. The default - value for this configuration key is false. -* **record_server_delivery_enabled**: This key controls the delivery of - records to server; when enabled (default value), the record will be posted to - the address in the configuration file. If this configuration key is disabled - (false), records will not be spooled or posted to backend. This configuration - key can be used in combination with record_retention_enabled to keep copies - of telemetry records locally only. +server + This specifies the web server to which telempostd sends the telemetry records. +socket_path + This specifies the path of the unix domain socket on which the telemprobd + listens for connections from the probes. +spool_dir + This configuration option is related to spooling. If the daemon is not able + to send the telemetry records to the backend server due to reasons such as + the network availability, then it stores the records in a spool directory. + This option specifies the path of the spool directory. This directory should + be owned by the same user as the daemon. +record_expiry + This is the time, in minutes, after which the records in the spool directory + are deleted by the daemon. +spool_process_time + This specifies the time interval, in seconds, that the daemon waits for + before checking the spool directory for records. The daemon picks up the + records in the order of modification date and tries to send the record to the + server. It sends a maximum of 10 records at a time. If it was able to send a + record successfully, it deletes the record from the spool. If the daemon + finds a record older than the "record_expiry" time, then it deletes that + record. The daemon looks at a maximum of 20 records in a single spool run loop. +rate_limit_enabled + This determines whether rate-limiting is enabled or disabled. When enabled, + there is a threshold on both records sent within a window of time, and record + bytes sent within a window a time. +record_burst_limit + This is the maximum amount of records allowed to be passed by the daemon + within the record_window_length of time. If set to -1, the rate-limiting for + record bursts is disabled. +record_window_length + The time, in minutes (0-59), that establishes the window length for the + record_burst_limit. For example, if record_burst_window=1000 and + record_window_length=15, then no more than 1000 records can be passed within + any given fifteen-minute window. +byte_burst_limit + This is the maximum amount of bytes that can be passed by the daemon within + the byte_window_length of time. If set to -1, the rate-limiting for byte + bursts is disabled. +byte_window_length + This is the time, in minutes (0-59), that establishes the window length for + the byte_burst_limit. +rate_limit_strategy + This is the strategy chosen once the rate-limiting threshold has been + reached. Currently the options are 'drop' or 'spool', with spool being the + default. If spool is chosen, records will be spooled and sent at a later time. +record_retention_enabled + When this key is enabled (true) the daemon saves a copy of the payload on + disk from all valid records. To avoid the excessive use of disk space only + the latest 100 records are kept. The default value for this configuration key + is false. +record_server_delivery_enabled + This key controls the delivery of records to server; when enabled (default + value), the record will be posted to the address in the configuration file. + If this configuration key is disabled (false), records will not be spooled or + posted to backend. This configuration key can be used in combination with + record_retention_enabled to keep copies of telemetry records locally only. .. note:: @@ -827,18 +833,18 @@ start/stop/restart ------------------ The commands to start, stop and restart the telemetry services manage all -required services and probes on the system. There is no need to separately -start/stop/restart the two client daemons **telemprobd** and **telempostd**. -The **restart** command option will call **telemctl stop** followed -by **telemctl start** . +required services and probes on the system. There is no need to separately +start/stop/restart the two client daemons telemprobd and telempostd. +The :command:`restart` command option will call :command:`telemctl stop` +followed by :command:`telemctl start` . is-active --------- -The `is-active` option reports whether the two client daemons are active. This -is useful to verify that the **opt-in** and **opt-out** options have taken -effect, or to ensure that telemetry is functioning on the system. Note that -both daemons are verified. +The :command:`is-active` option reports whether the two client daemons are +active. This is useful to verify that the :command:`opt-in` and +:command:`opt-out` options have taken effect, or to ensure that telemetry is +functioning on the system. Note that both daemons are verified. .. code-block:: bash @@ -850,7 +856,6 @@ both daemons are verified. telempostd : active - .. _Telemetrics client: https://github.com/clearlinux/telemetrics-client/ .. _latest version: https://github.com/clearlinux/telemetrics-client/tree/master/src .. _heartbeat probe: https://github.com/clearlinux/telemetrics-client/tree/master/src/probes/hello.c diff --git a/source/reference/reference.rst b/source/reference/reference.rst index c639603d..95339ad8 100644 --- a/source/reference/reference.rst +++ b/source/reference/reference.rst @@ -27,4 +27,5 @@ Clear Linux concepts :glob: ../concepts/* - + ../tooling/stateless + ../tooling/security \ No newline at end of file diff --git a/source/concepts/figures/stateless-1.png b/source/tooling/figures/stateless-1.png similarity index 100% rename from source/concepts/figures/stateless-1.png rename to source/tooling/figures/stateless-1.png diff --git a/source/concepts/figures/stateless-2.png b/source/tooling/figures/stateless-2.png similarity index 100% rename from source/concepts/figures/stateless-2.png rename to source/tooling/figures/stateless-2.png diff --git a/source/concepts/security.rst b/source/tooling/security.rst similarity index 57% rename from source/concepts/security.rst rename to source/tooling/security.rst index 418b75f4..c78fb6d3 100644 --- a/source/concepts/security.rst +++ b/source/tooling/security.rst @@ -1,45 +1,36 @@ .. _security: OS Security -************************* +########### |CL-ATTR| aims to make systemic and layered security-conscious decisions that are both performant and practical. This security philosophy is rooted within the project's codebase and operating culture. - .. contents:: :local: :depth: 1 +Security in updates +******************* +The |CL| team believes in the benefits of software security through open +sourcing, incremental updates, and rapidly resolving known security advisories. -Security in Updates -=================== - -The |CL| team believes in the benefits of -software security through open sourcing, incremental updates, and -rapidly resolving known security advisories. - - - -The latest Linux* codebase --------------------------- +The latest Linux\* codebase +=========================== |CL| uses the newest version of the Linux kernel which allows the operating system to leverage the latest features from the upstream Linux kernel, including security fixes. - - - -Automated Effective Updating ----------------------------- +Automated effective updating +============================ |CL| is incrementally updated multiple times per day. -This `rolling release model`_ allows |CL| to consume the latest security -fixes of software packages as soon as they become available. -There is no waiting for major or minor releases on |CL|. +This `rolling release`_ model allows |CL| to consume the latest security fixes +of software packages as soon as they become available. There is no waiting for +major or minor releases on |CL|. An update is not effective if it is just simply downloaded onto a system. It needs to be obtained *AND* ensured that the new patched copy is being @@ -47,47 +38,34 @@ used; not an older copy loaded into memory. |CL| will let you know when a service needs to be rebooted or do it for your automatically after a software update, if desired. +In |CL| updates are delivered automatically, efficiently, and effectively. For +more information about software updates in |CL|, refer to the :ref:`swupd-guide` +guide. -In |CL| updates are delivered automatically, efficiently, -and effectively. For more information see -`documentation about Software Updates`_ in |CL|. - - - - - -Automated CVE Scanning and Remediation --------------------------------------- +Automated CVE scanning and remediation +====================================== The sheer number of software packages and security vulnerabilities is growing exponentially. Repositories of Common Vulnerabilities and Exposures (CVEs) and their fixes, if known, are published by :abbr:`NIST` in a National Vulnerability Database \ |NVD|\ and at \ |MITRE|\ . - |CL| employs a proactive and measured approach to addressing known and fixable :abbr:`CVEs (Common Vulnerabilities and Exposures)`. -Packages are automatically scanned against -:abbr:`CVEs (Common Vulnerabilities and Exposures)` daily, and security +Packages are automatically scanned against CVEs daily, and security patches are deployed as soon as they are available. -These combined practices minimize the amount of -time |CL| systems are exposed to unnecessary security risk. - - - - - -Security in Software -==================== +These combined practices minimize the amount of time |CL| systems are exposed to unnecessary security risk. +Security in software +********************* Minimized attack surface -------------------------- +======================== -|CL| removes legacy, unneeded, or redundant standards and -components as much as possible to enable the use of best known security -standards. Below are some examples: +|CL| removes legacy, unneeded, or redundant standards and components as much as +possible to enable the use of best known security standards. Below are some +examples: * `RC4`, `SSLv3`, `3DES`, and `SHA-1` ciphers which have had known vulnerabilities, have been explicitly disabled within many |CL| packages to @@ -96,12 +74,10 @@ standards. Below are some examples: * Services and subsystems which expose sensitive system information have been removed such as the `finger` and `tcpwrappers`. -* `SFTP` has been disabled by default due to security - considerations. - +* `SFTP` has been disabled by default due to security considerations. Verified trust --------------- +============== |CL| encourages the use of secure practices such as encryption and digital signature verification throughout the system and discourages blind @@ -109,29 +85,23 @@ trust. Below are some examples: * All update operations from swupd are transparently encrypted and checked against the |CL| maintainers' public key for authenticity. - More information can be found in this blog post: - `blog post about swupd security`_ + More information about swupd security can be found in the + `Security for software update in Clear Linux* OS`_ blog post. * Before being built, packages available from |CL| verify checksums and signatures provided by third party project codebases and maintainers. * |CL| features a unified certificate store, `clrtrust`_ which comes ready to work with well-known Certificate Authorities out of the box. - `clrtrust`_ also offers an easy to use command line interface for managing + clrtrust also offers an easy to use command line interface for managing system-wide chains of trust, instead of ignoring foreign certificates. - - - - - Compiled with secure options ----------------------------- - -While |CL| packages are optimized for performance on -Intel® architecture, security conscious kernel and compiler options are -sensibly taken advantage of. Below are some examples: +============================ +While |CL| packages are optimized for performance on Intel® architecture, +security conscious kernel and compiler options are sensibly taken advantage of. +Below are some examples: * Kernels shipped with |CL| are signed and disallow the usage of custom kernel modules to maintain verifiable system integrity. @@ -139,23 +109,19 @@ sensibly taken advantage of. Below are some examples: * `Address space layout randomization (ASLR)`_ and `Kernel address space layout randomization (KASLR)`_ are kernel features which defend against certain memory based attacks. - More information can be found in a `blog post about PIE executables`_ . + More information about PIE executables can be found in the + `Recent GNU* C library improvements`_ blog post. +Security in system design +************************* +Simple, yet effective, techniques are used throughout the |CL| system design to +defend against common attack vectors and enable good security hygiene. Below are +some examples: - - - -Security in System Design -========================= - -Simple, yet effective, techniques are used throughout the -|CL| system design to defend against common attack vectors and enable -good security hygiene. Below are some examples: - - -* Full disk encryption using `Linux Unified Key Setup`_ (LUKS) is available - during installation. +* Full disk encryption using :abbr:`LUKS (Linux Unified Key Setup)` is available + during installation. Refer to `cryptsetup`_ for additional information about + LUKS. * |CL| uses the PAM cracklib module to harden user login and password security resulting in: @@ -172,22 +138,13 @@ good security hygiene. Below are some examples: * `Tallow`_, a lightweight service which monitors and blocks suspicious SSH login patterns, is installed with the :command:`openssh-server` bundle. - - - - - -.. _`documentation about Software Updates`: https://clearlinux.org/documentation/clear-linux/concepts/swupd-about -.. _`cve-check-tool`: https://github.com/clearlinux/cve-check-tool -.. _`blog post about swupd security`: https://clearlinux.org/blogs/security-software-update-clear-linux-os-intel-architecture -.. _`rolling release model`: https://en.wikipedia.org/wiki/Rolling_release +.. _`Security for software update in Clear Linux* OS`: https://clearlinux.org/blogs/security-software-update-clear-linux-os-intel-architecture +.. _`Recent GNU* C library improvements`: https://clearlinux.org/blogs/recent-gnu-c-library-improvements +.. _`rolling release`: https://en.wikipedia.org/wiki/Rolling_release .. _`clrtrust`: https://github.com/clearlinux/clrtrust .. _`Address space layout randomization (ASLR)`: https://en.wikipedia.org/wiki/Address_space_layout_randomization .. _`Kernel address space layout randomization (KASLR)`: https://lwn.net/Articles/569635/ -.. _`dm-verity`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/device-mapper/verity.txt -.. _`SELinux`: https://github.com/SELinuxProject -.. _`Linux Unified Key Setup`: https://gitlab.com/cryptsetup/cryptsetup/ -.. _`blog post about PIE executables`: https://clearlinux.org/blogs/recent-gnu-c-library-improvements +.. _`cryptsetup`: https://gitlab.com/cryptsetup/cryptsetup/ .. _`Tallow`: https://github.com/clearlinux/tallow .. |NVD| raw:: html diff --git a/source/concepts/stateless.rst b/source/tooling/stateless.rst similarity index 85% rename from source/concepts/stateless.rst rename to source/tooling/stateless.rst index 3252d22a..6e75ef5b 100644 --- a/source/concepts/stateless.rst +++ b/source/tooling/stateless.rst @@ -3,24 +3,23 @@ Stateless ######### -In most operating systems, files can become intermingled with user and system -data and configurations. +In most operating systems, user data, system data, and configuration files +can become intermingled. .. figure:: figures/stateless-1.png - :scale: 45% + :scale: 45% :align: center :alt: Stateless: User and system files mixed Figure 1: Without stateless, user and system files become mixed on the filesystem over time. -|CL-ATTR| has a stateless design philosophy of which the goal is to provide an +|CL-ATTR| has a stateless design philosophy with the goal to provide an :abbr:`OS (operating system)` that functions without excessive user configuration or customization. Stateless in this context does *not* mean ephemeral or non-persistent. .. contents:: :local: - :depth: 2 - + :depth: 1 File-level separation ********************* @@ -29,7 +28,7 @@ To accomplish a stateless design the Linux Filesystem Hierarchy is separated between user-owned areas and |CL|-owned areas. .. figure:: figures/stateless-2.png - :scale: 45% + :scale: 45% :align: center :alt: Stateless: User and system files separation @@ -48,10 +47,10 @@ Files under the :file:`/etc/`, :file:`/home`, and :file:`/var` directories are owned and managed by the user. A freshly installed |CL| system will only have a minimal set of files in the :file:`/etc/` directory and software installed by |CL| does not write to :file:`/etc`. This operating assumption allows |CL| -users to clearly identify the configuration that makes their system unique. +users to clearly identify the configuration that makes their system unique. -Software Configuration +Software configuration ********************** With stateless separation, default software configurations are read in order @@ -62,12 +61,12 @@ Default configurations ====================== Software in |CL| provides default configuration values so that it is -immediately functional, whenever it is appropriate to do so. +immediately functional, whenever it is appropriate to do so. |CL| distributed software packages may be directly modified to include default configuration values or default configuration files may be provided by |CL| under :file:`/usr/share/defaults`. These files can be referenced as templates -for customization. +for customization. For example, the default configuration that Apache uses when installed can be found at :file:`/usr/share/defaults/httpd/httpd.conf` directory. @@ -81,39 +80,37 @@ modified by the user under :file:`/etc/`. If the configuration file does not already exist, it can be created in the appropriate location. User defined configuration files should contain the minimal set of desired -changes and rely on default configuration for the rest. +changes and rely on default configuration for the rest. For example, a customized Apache configuration can be used instead by: #. Create the destination directory for the configuration: - .. code :: bash + .. code-block:: bash sudo mkdir /etc/httpd #. Copy the default configuration as a reference template: - .. code :: bash + .. code-block:: bash sudo cp /usr/share/defaults/httpd/httpd.conf /etc/httpd/ #. Make any desired modifications to the configurations: - .. code :: bash + .. code-block:: bash sudoedit /etc/httpd/httpd.conf #. Reload the service or reboot the system to pickup any changes: - .. code :: bash + .. code-block:: bash systemctl daemon-reload httpd && systemctl restart httpd - This pattern can be used to modify the configurations of other programs too. The `stateless man page`_ has application-specific examples. - System reset ************ @@ -124,22 +121,19 @@ easily restored by simply deleting everything under :file:`/etc/` and Running the commands below effectively performs a system reset as if it was just installed: -.. code:: +.. code-block:: bash sudo rm -rf /etc sudo rm -rf /var -In other Linux distributions, this can be a catastrophic action that renders a -system unable to boot. +In other Linux distributions, this can be a catastrophic action that renders +a system unable to boot. Additional information ********************** * `stateless man page`_ -* `Where is /etc/fstab in Clear Linux? `_ - - .. _`stateless man page`: https://github.com/clearlinux/clr-man-pages/blob/master/stateless.7.rst diff --git a/source/tutorials/tutorials.rst b/source/tutorials/tutorials.rst index 0d5300e9..b7d67ebc 100644 --- a/source/tutorials/tutorials.rst +++ b/source/tutorials/tutorials.rst @@ -22,10 +22,7 @@ Explore our tutorials to discover what you can do with |CL|! kata kata_migration kubernetes/kubernetes* - greengrass - dlrs/dlrs yubikey-u2f nvidia - dars redis tutorial-proxy