clearlinux/clear-linux-documentation
2
0
Fork 0
mirror of https://github.com/clearlinux/clear-linux-documentation.git synced 2026-08-22 15:15:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Initial commit for maintenance guides clean up (preparation for translation) (#648)

Browse Source 
Signed-off-by: Kristal Dale <kristal.dale@intel.com>

Initial commit of cleanup for translations (maintenance guides)

Signed-off-by: Kristal Dale <kristal.dale@intel.com>

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 <kristal.dale@intel.com>

Update per requested changes on PR.

Signed-off-by: Kristal Dale <kristal.dale@intel.com>

Edits per requested changes on PR from @mvincerx

Signed-off-by: Kristal Dale <kristal.dale@intel.com>
This commit is contained in:
Kristal Dale
2019-07-19 18:15:45 -07:00
committed by michael vincerra
parent 5ab6383d6d
commit b9e5806856
15 changed files with 344 additions and 280 deletions
Download Patch File Download Diff File Expand all files Collapse all files
source/clear-linux/guides/maintenance/architect-lifecycle.rst
+20 -25
View File
@@ -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 <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
source/clear-linux/guides/maintenance/assign-static-ip.rst
+27 -27
View File
@@ -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 <nm-static-ip>` should be used.
network configuration is being managed by NetworkManager, then use the
instructions for :ref:`using NetworkManager <nm-static-ip>`.
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 <networkd-static-ip>` should be used.
configuration is being managed by `systemd-networkd`, then use the
instructions for :ref:`using systemd-networkd <networkd-static-ip>`.
.. _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.
<https://www.freedesktop.org/software/systemd/man/systemd.network.html>`_
for more configuration options.
#. Restart the systemd-networkd service:
#. Restart the `systemd-networkd` service:
.. code-block:: bash
source/clear-linux/guides/maintenance/bulk-provision.rst
+38 -31
View File
@@ -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/<MAC address>``
* ``http://192.168.1.1:60000/icis/get_role/<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/<MAC address>
* http://192.168.1.1:60000/icis/get_role/<role>
* http://192.168.1.1:60000/ipxe/ipxe_boot_script.txt
#. Power on the PXE client and watch it boot and install |CL|.
source/clear-linux/guides/maintenance/cpu-performance.rst
+33 -22
View File
@@ -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
<c-states-section>` and :ref:`P-states <P-states-section>`
@@ -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
source/clear-linux/guides/maintenance/developer-workstation.rst
+32 -30
View File
@@ -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 <swupd-guide>`. Visit our :ref:`swupd-about` page to understand
how |CL| simplifies software versioning compared to other Linux\*
distributions.
Before continuing, review the :ref:`swupd <swupd-guide>` 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* <enable-user-space>`. 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* <enable-user-space>`. 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 <swupd-guide>`, 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 <swupd-guide-example-install-bundle>`
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 <bundles-about>`
* :ref:`Software update <swupd-about>`
* :ref:`Mixer <mixer-about>`
* :ref:`Autospec <autospec-about>`
* :ref:`Software update <swupd-guide>`
* :ref:`Mixer <mixer>`
* :ref:`Autospec <autospec>`
Other resources for developers
-----------------------------------
source/clear-linux/guides/maintenance/enable-user-space.rst
+13 -13
View File
@@ -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 `<userid>`.
enable the :command:`sudo` command for your new <userid>.
To be able to execute all applications with root privileges, add the
`<userid>` to the `wheel group`_.
<userid> to the `wheel group`_.
#. Add `<userid>` to the `wheel` group:
#. Add <userid> to the wheel group:
.. code-block:: bash
usermod -G wheel -a <userid>
#. Log out of root and into the new `<userid>`.
#. Log out of root and into the new <userid>.
To log off as root, enter :command:`exit`.
#. Enter the new `<userid>` and the password created earlier.
#. Enter the new <userid> and the password created earlier.
You will now be in the home directory of `<userid>`.
You will now be in the home directory of <userid>.
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
source/clear-linux/guides/maintenance/fix-broken-install.rst
+23 -12
View File
@@ -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<swupd-guide>`
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<swupd-guide>` 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 <bare-metal-install-desktop>`
* 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
source/clear-linux/guides/maintenance/hostname.rst
+13 -6
View File
@@ -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.
source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst
+30 -25
View File
@@ -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/
source/clear-linux/guides/maintenance/kernel-development.rst
+27 -19
View File
@@ -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/<TAG_NAME>`.
point. An older version can pulled by switching to different git tag by using
:command:`git checkout tag/<TAG_NAME>`.
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
source/clear-linux/guides/maintenance/kernel-modules-dkms.rst
+14 -10
View File
@@ -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 <swupd-guide>`.
@@ -254,8 +259,7 @@ The instructions below show a generic example:
sudo dkms add -m <MODULE-NAME>
#. 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
source/clear-linux/guides/maintenance/kernel-modules.rst
+13 -11
View File
@@ -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 <https://github.com/clearlinux/distribution>`_ 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
source/clear-linux/guides/maintenance/restart.rst
+26 -24
View File
@@ -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:
source/clear-linux/guides/maintenance/time.rst
+5 -4
View File
@@ -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
source/clear-linux/guides/maintenance/validate-signatures.rst
+30 -21
View File
@@ -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.