From b9e5806856a2c0d82d92e19a408d3ebe01abc4b9 Mon Sep 17 00:00:00 2001 From: Kristal Dale Date: Fri, 19 Jul 2019 18:15:45 -0700 Subject: [PATCH] Initial commit for maintenance guides clean up (preparation for translation) (#648) Signed-off-by: Kristal Dale Initial commit of cleanup for translations (maintenance guides) Signed-off-by: Kristal Dale Clean up in preparation for translations - Standardize page formatting (use of intro sentence, TOC tree, etc) - Simplify intro sentences, remove idioms, etc - Standardize use of roles (remove use of `` and * for emphasis on special words or options) - Misc clean up (opportunistic) Signed-off-by: Kristal Dale Update per requested changes on PR. Signed-off-by: Kristal Dale Edits per requested changes on PR from @mvincerx Signed-off-by: Kristal Dale --- .../maintenance/architect-lifecycle.rst | 45 ++++++------ .../guides/maintenance/assign-static-ip.rst | 54 +++++++-------- .../guides/maintenance/bulk-provision.rst | 69 ++++++++++--------- .../guides/maintenance/cpu-performance.rst | 55 +++++++++------ .../maintenance/developer-workstation.rst | 62 +++++++++-------- .../guides/maintenance/enable-user-space.rst | 26 +++---- .../guides/maintenance/fix-broken-install.rst | 35 ++++++---- .../guides/maintenance/hostname.rst | 19 +++-- .../increase-virtual-disk-size.rst | 55 ++++++++------- .../guides/maintenance/kernel-development.rst | 46 ++++++++----- .../maintenance/kernel-modules-dkms.rst | 24 ++++--- .../guides/maintenance/kernel-modules.rst | 24 ++++--- .../guides/maintenance/restart.rst | 50 +++++++------- .../clear-linux/guides/maintenance/time.rst | 9 +-- .../maintenance/validate-signatures.rst | 51 ++++++++------ 15 files changed, 344 insertions(+), 280 deletions(-) diff --git a/source/clear-linux/guides/maintenance/architect-lifecycle.rst b/source/clear-linux/guides/maintenance/architect-lifecycle.rst index f166e542..ed328711 100644 --- a/source/clear-linux/guides/maintenance/architect-lifecycle.rst +++ b/source/clear-linux/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/clear-linux/guides/maintenance/assign-static-ip.rst b/source/clear-linux/guides/maintenance/assign-static-ip.rst index 9028fbfc..14fc8694 100644 --- a/source/clear-linux/guides/maintenance/assign-static-ip.rst +++ b/source/clear-linux/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/clear-linux/guides/maintenance/bulk-provision.rst b/source/clear-linux/guides/maintenance/bulk-provision.rst index 9d3affc2..535ea48a 100644 --- a/source/clear-linux/guides/maintenance/bulk-provision.rst +++ b/source/clear-linux/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/clear-linux/guides/maintenance/cpu-performance.rst b/source/clear-linux/guides/maintenance/cpu-performance.rst index 3a400e3c..299514e7 100644 --- a/source/clear-linux/guides/maintenance/cpu-performance.rst +++ b/source/clear-linux/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/clear-linux/guides/maintenance/developer-workstation.rst b/source/clear-linux/guides/maintenance/developer-workstation.rst index 0e6e1a32..2e487536 100644 --- a/source/clear-linux/guides/maintenance/developer-workstation.rst +++ b/source/clear-linux/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/clear-linux/guides/maintenance/enable-user-space.rst b/source/clear-linux/guides/maintenance/enable-user-space.rst index 0c1fc9e7..e51fa59e 100644 --- a/source/clear-linux/guides/maintenance/enable-user-space.rst +++ b/source/clear-linux/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/clear-linux/guides/maintenance/fix-broken-install.rst b/source/clear-linux/guides/maintenance/fix-broken-install.rst index 1ffe275d..33765b89 100644 --- a/source/clear-linux/guides/maintenance/fix-broken-install.rst +++ b/source/clear-linux/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/clear-linux/guides/maintenance/hostname.rst b/source/clear-linux/guides/maintenance/hostname.rst index ce539009..ce0c225c 100644 --- a/source/clear-linux/guides/maintenance/hostname.rst +++ b/source/clear-linux/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/clear-linux/guides/maintenance/increase-virtual-disk-size.rst b/source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst index 36344aec..e633f506 100644 --- a/source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst +++ b/source/clear-linux/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/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 7673aec8..f1ee64aa 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/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/clear-linux/guides/maintenance/kernel-modules-dkms.rst b/source/clear-linux/guides/maintenance/kernel-modules-dkms.rst index c3be4dd0..bda29de0 100644 --- a/source/clear-linux/guides/maintenance/kernel-modules-dkms.rst +++ b/source/clear-linux/guides/maintenance/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/clear-linux/guides/maintenance/kernel-modules.rst b/source/clear-linux/guides/maintenance/kernel-modules.rst index 74c4cdc3..eae7f04a 100644 --- a/source/clear-linux/guides/maintenance/kernel-modules.rst +++ b/source/clear-linux/guides/maintenance/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/clear-linux/guides/maintenance/restart.rst b/source/clear-linux/guides/maintenance/restart.rst index c39d2941..ddd4a17c 100644 --- a/source/clear-linux/guides/maintenance/restart.rst +++ b/source/clear-linux/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/clear-linux/guides/maintenance/time.rst b/source/clear-linux/guides/maintenance/time.rst index 25ee141b..caa0be16 100644 --- a/source/clear-linux/guides/maintenance/time.rst +++ b/source/clear-linux/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/clear-linux/guides/maintenance/validate-signatures.rst b/source/clear-linux/guides/maintenance/validate-signatures.rst index b506ba3a..acd88bcc 100644 --- a/source/clear-linux/guides/maintenance/validate-signatures.rst +++ b/source/clear-linux/guides/maintenance/validate-signatures.rst @@ -3,19 +3,28 @@ 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 +: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. @@ -61,21 +70,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 using 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. @@ -112,10 +121,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 using 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 +132,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.