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

Merge pull request #649 from intelkevinputnam/rtd-theme

Browse Source 
Merge of latest content into rtd-theme
This commit is contained in:
Kevin Putnam
2019-07-19 10:27:15 -07:00
committed by GitHub
parent 76d47aa32b 965c26870d
commit 33fb4ca67d
12 changed files with 817 additions and 679 deletions
Download Patch File Download Diff File Expand all files Collapse all files
source/concepts/restart.rst
-189
View File
@@ -1,189 +0,0 @@
.. _restart:
Restart system services after an OS update
##########################################
The software life cycle describes how software is created, developed, and
deployed, and includes how to replace or update software. A good OS
provides tools for the entire software life cycle. These tools must include
ways to remove software components properly when replaced with something
else.
Most of the work on software update code in |CL| was focused on adding new
software to the system. We recommended that users reboot their system once in
a while, but we did not provide any tools to restart services easily, until
now.
User challenges
***************
It is difficult to determine which services to restart. You can either
evaluate each system and reboot manually, or figure out which services to
restart based on documentation like the |CL| release notes. Since neither
option solves the issue completely, the |CL| team created a solution.
Over the years, several OSes approached the problem and created partial
solutions such as the following:
* Automatically restart services during an upgrade.
* Evaluate services using these steps:
* Mark updates requiring a reboot, such as kernel updates.
* Inform the user of those updates.
* Ask the user to restart the OS.
Both solutions are acceptable for many OSes. However, |CL| updates software
automatically and users do not see notices from the updater unless they
review the journal. |CL| requires a completely different solution, with the
following requirements:
* Eliminate the guesswork about what to restart and under what circumstances.
* Cannot restart everything. Many service daemons do not support an automatic
background restart.
* Fit into the |CL| architectural perspective: be small, quick, and lean.
clr-service-restart functionality
*********************************
Typical reasons to restart a service daemon include:
* A new version replaces the executable file itself.
* A new version replaces a library component used by a service daemon.
Our method restarts daemons when it is really needed, especially
in the case of security updates. The tool restarts daemons by reading
various files in the :file:`procfs` filesystem provided by the kernel.
The second part of the problem is to determine whether or not running
processes are part of a system service. The tool focuses on system services
because most system services are background tasks with no direct user
interaction. Fortunately, :command:`systemd` provides a simple way to:
* Determine which active tasks are within the system domain.
* Determine which tasks map to which service.
We combined both solutions into a low-overhead tool that shows which system
daemons require a restart, as shown below:
Figure 1: Invoke :command:`clr-service-restart`.
.. code-block:: bash
sudo clr-service-restart -a -n
.. code-block:: console
upower.service: needs a restart (a library dependency was updated)
/usr/bin/systemctl --no-ask-password try-restart upower.service
NetworkManager.service: needs a restart (a library dependency was
updated)
/usr/bin/systemctl --no-ask-password try-restart NetworkManager.service
....
:command:`clr-service-restart` implements a whitelist to identify which
daemons can be restarted. The system administrator 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. See the options section for
details.
Options for clr-service-restart
*******************************
The *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
OS software update.
.. code-block:: bash
sudo clr-service-restart allow tallow.service
The *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
record. The example below tells :command:`clr-service-restart` not to
restart the *rngd* daemon after an OS software update.
.. code-block:: bash
sudo clr-service-restart disallow rngd
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* automatically again,
because *rngd* is whitelisted for automatic service restarts by default
in |CL|.
.. code-block:: bash
sudo clr-service-restart default rngd
Monitor options for clr-service-restart
=======================================
:command:`clr-service-restart` works in the background and is invoked with
:command:`swupd` automatically. Review the journal output to verify that
services are restarted after an OS software update.
To monitor :command:`clr-service-restart`, use one or both options described
below.
.. option:: -n
This 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.
* What unit it is.
* Why it needs a restart.
* Which command is required to restart the unit.
.. option:: -a
This 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.
If you pass both options (:option:`-a` and :option:`-n`),
: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.
Telemetry
*********
:command:`clr-service-restart` may cause problems such as a short service
outage when a daemon is being restarted, or if a daemon fails to properly
restart. To minimize issues, :command:`clr-service-restart` creates a
telemetry record and sends it to the optional |CL| telemetry service if both
conditions below are met:
* If a unit fails to automatically restart after an OS update.
* If that unit resides in the system
location :file:`/usr/lib/systemd/system`.
If you do not install the |CL| telemetrics bundle, the data is discarded. If
you install the telemetrics bundle and you opt to send telemetry, then the
system unit name is sent to the |CL| telemetry service. We evaluate the
report and update the whitelist to remove services that are not safe to
restart.
Conclusion
**********
The |CL| team enjoys coming up with simple and efficient solutions to make
your work easier. We made a github project of :command:`clr-service-restart`
and we invite you to look at the code, share your thoughts, and work with us
on improving the project. You can find the project at:
https://github.com/clearlinux/clr-service-restart
source/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst
+15 -9
View File
@@ -506,23 +506,29 @@ Congratulations. You successfully installed |CL|.
Default partition schema
========================
Table 1 shows the default partition schema with the exception of root,
which varies.
Create partitions per requirements in Table 1.
.. list-table:: **Table 1. Disk Partition Setup**
:widths: 33, 33, 33
.. list-table:: **Table 1. Default partition schema**
:widths: 25, 25, 25, 25
:header-rows: 1
* - FileSystem
- Label
- Mount Point
- Minimum size
* - ``VFAT``
- Default size
* - ``VFAT(FAT32)``
- boot
- /boot
- 150M
* - ``swap``
- 150MB
* - ``linux-swap``
- swap
-
- 256MB
* - ``root``
* - ``ext[234] or XFS``
- root
- /
- *Size depends upon use case/desired bundles.*
source/guides/kernel/kernel-modules-dkms.rst
+20 -38
View File
@@ -6,7 +6,8 @@ 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`.
:abbr:`DKMS (Dynamic Kernel Module System)` or refer to
:ref:`kernel-modules`.
.. contents:: :local:
:depth: 1
@@ -24,15 +25,10 @@ come from an external source, such as directly from a vendor (out-of-tree).
the building and installation of kernel modules. DKMS allows |CL| to provide
hooks that automatically rebuild modules against new kernel versions.
.. include:: kernel-modules.rst
:start-after: kernel-modules-availability-begin:
:end-before: kernel-modules-availability-end:
Install DKMS
************
@@ -57,11 +53,10 @@ The *kernel-native-dkms* bundle also:
.. warning::
We recommend that you always review the :command:`swupd update` output
to make sure kernel modules were successfully rebuilt against the new
kernel. This is especially important for systems where a successful boot
relies on a kernel module.
We recommend that you always review the :command:`swupd update` output
to make sure kernel modules were successfully rebuilt against the new
kernel. This is especially important for systems where a successful boot
relies on a kernel module.
Install the :command:`kernel-native-dkms` or :command:`kernel-lts-dkms`
bundle:
@@ -99,17 +94,15 @@ bundle:
sudo clr-boot-manager update
reboot
.. _kernel-modules-dkms-install-end:
Build, install, and load an out-of-tree module
**********************************************
Follow the steps in this section if you are an individual user or testing, and
you need an out-of-tree kernel module that is not available through |CL|. For
a more scalable and customizable approach, we recommend using the
:ref:`mixer` tool to provide a custom kernel and updates.
Follow the steps in this section if you are an individual user or testing,
and you need an out-of-tree kernel module that is not available through
|CL|. For a more scalable and customizable approach, we recommend using
:ref:`mixer` to provide a custom kernel and updates.
Prerequisites
=============
@@ -119,10 +112,8 @@ Before you begin, you must:
* Disable Secure Boot in UEFI/BIOS. The loading of new out-of-tree modules
modifies the signatures that Secure Boot relies on for trust.
* Obtain a kernel module package in the form of source code and/or precompiled
binaries.
* Obtain a kernel module package in the form of source code or
pre-compiled binaries.
Obtain kernel module source
===========================
@@ -159,7 +150,6 @@ a :file:`dkms.conf` file, described later in this document.
cd <KERNEL-MODULE-SOURCE>/
cat README
Build kernel module with an existing dkms.conf
==============================================
@@ -171,8 +161,8 @@ The archive contains the required :file:`dkms.conf` file, and may contain
a :file:`dkms_source_tree` directory and a :file:`dkms_binaries_only`
directory.
#. Run the :command:`dkms ldtarball` command against the kernel module archive.
#. Run the :command:`dkms ldtarball` command against the kernel
module archive.
.. code-block:: bash
@@ -180,8 +170,8 @@ directory.
:command:`dkms ldtarball` places the kernel module source under
:file:`/usr/src/<MODULE-NAME>-<MODULE-VERSION>/`, builds it if necessary, and
adds the module into the DKMS tree.
:file:`/usr/src/<MODULE-NAME>-<MODULE-VERSION>/`, builds it if necessary,
and adds the module into the DKMS tree.
#. Verify the kernel module is detected by checking the output of the
@@ -198,8 +188,6 @@ directory.
dkms install -m <MODULE-NAME> -v <MODULE-VERSION>
Build kernel module without an existing dkms.conf
=================================================
@@ -224,7 +212,7 @@ Here are some additional resources that can be used for reference:
.. note::
:command:`AUTOINSTALL=yes` must be set in the dkms.conf for the module to
be automatically recompiled with |CL| updates.
be automatically recompiled with |CL| updates.
The instructions below show a generic example:
@@ -259,14 +247,14 @@ The instructions below show a generic example:
*<PACKAGE_NAME>* and *<PACKAGE_VERSION>* must match the entries in the
:file:`dkms.conf` file.
#. Add the kernel module to the DKMS tree so that it is tracked by DKMS.
.. code-block:: bash
sudo dkms add -m <MODULE-NAME>
#. Build the kernel module using DKMS. If the build encounters errors, you may
#. Build the kernel module using DKMS. If the build encounters errors,
you may
need to edit the :file:`dkms.conf` file.
.. code-block:: bash
@@ -279,15 +267,13 @@ The instructions below show a generic example:
sudo dkms install -m <MODULE-NAME> -v <MODULE-VERSION>
Load kernel module
==================
By default, DKMS installs modules "in-tree" under :file:`/lib/modules` so the
:command:`modprobe` command can be used to load them.
#. Load the installed module with the :command:`modprobe` command.
#. Load the installed module with the :command:`modprobe` command.
.. code-block:: bash
@@ -299,7 +285,6 @@ By default, DKMS installs modules "in-tree" under :file:`/lib/modules` so the
lsmod | grep <MODULE-NAME>
Examples
********
@@ -307,9 +292,6 @@ Examples
:start-after: kernel-modules-autoload-begin:
:end-before: kernel-modules-autoload-end:
Related topics
**************
source/guides/maintenance/download-verify-decompress-linux.rst
-72
View File
@@ -1,72 +0,0 @@
.. _download-verify-decompress-linux:
Download, verify, and decompress a |CL-ATTR| image on Linux
###########################################################
This guide describes the types of |CL| images available, where to download
them, how to verify the integrity of an image, and how to decompress it.
Instructions for other operating systems are available:
* :ref:`download-verify-decompress-mac`
* :ref:`download-verify-decompress-windows`
Image types
***********
.. include:: ../../reference/image-types.rst
:start-after: image-types-content:
.. _verify-linux:
Verify the integrity of the |CL| image
**************************************
Before you use a downloaded |CL| image, verify its integrity. This action
eliminates the small chance of a corrupted image due to download issues. To
support verification, each released |CL| image has a corresponding SHA512
checksum file designated with the suffix `-SHA512SUMS`.
#. Download the corresponding SHA512 checksum file of your |CL| image.
#. Start a terminal emulator.
#. Go to the directory with the downloaded image and checksum files.
#. Verify the integrity of the image and compare it to its original checksum
with the command:
.. code-block:: bash
sha512sum -c ./clear-[version number]-[image type].[compression type]-SHA512SUMS
If the checksum of the downloaded image is different than the original
checksum, a warning is displayed with a message indicating the computed
checksum does **not** match. Otherwise, the name of the image is printed on
the screen followed by `OK`.
For a more in-depth discussion of image verification including checking the
certificate see :ref:`image-content-validation`.
.. incl-decompress-image:
Decompress the |CL| image
*************************
Released |CL| images are compressed with either GNU zip (*.gz*) or XZ
(*.xz*). The compression type depends on the target platform or
environment. To decompress the image, follow these steps:
#. Start a terminal emulator.
#. Go to the directory with the downloaded image.
To decompress an XZ image, enter:
.. code-block:: bash
unxz clear-[version number]-[image type].xz
To decompress a GZ image, enter:
.. code-block:: bash
gunzip clear-[version number]-[image type].gz
.. incl-decompress-image-end:
source/guides/maintenance/download-verify-decompress-mac.rst
-58
View File
@@ -1,58 +0,0 @@
.. _download-verify-decompress-mac:
Download, verify, and decompress a |CL-ATTR| image on macOS\*
#############################################################
This guide describes the types of |CL| images available, where to download
them, how to verify the integrity of an image, and how to decompress it.
Instructions for other operating systems are available:
* :ref:`download-verify-decompress-linux`
* :ref:`download-verify-decompress-windows`
Image types
***********
.. include:: ../../reference/image-types.rst
:start-after: image-types-content:
.. _verify-mac:
Verify the integrity of the |CL| image
**************************************
Before you use a downloaded |CL| image, verify its integrity. This action
eliminates the small chance of a corrupted image due to download issues. To
support verification, each released |CL| image has a corresponding SHA512
checksum file designated with the suffix `-SHA512SUMS`.
#. Download the corresponding SHA512 checksum file of your |CL| image.
#. Start the Terminal app.
#. Go to the directory with the downloaded image and checksum files.
#. Verify the integrity of the image and compare it to its original checksum
with the command:
.. code-block:: bash
shasum -a512 clear-[version number]-[image type].[compression type] | diff clear-[version number]-[image type].[compression type]-SHA512SUMS -
If the checksum of the downloaded image is different than the original
checksum, the differences will be displayed. Otherwise, an empty output indicates
a match and your downloaded image is good.
Decompress the |CL| image
*************************
We compress all released |CL| images by default with either GNU zip
(`.gz`) or xz (`.xz`). The compression type we use depends on the target
platform or environment. To decompress the image, follow these steps:
#. Start the Terminal app.
#. Go to the directory with the downloaded image.
#. Use the :command:`gunzip` command to decompress either compression type. For example:
.. code-block:: bash
gunzip clear-[version number]-[image type].xz
gunzip clear-[version number]-[image type].gz
source/guides/maintenance/download-verify-decompress-windows.rst
-60
View File
@@ -1,60 +0,0 @@
.. _download-verify-decompress-windows:
Download, verify, and decompress a |CL-ATTR| image on Windows\*
###############################################################
This guide describes the types of |CL-ATTR| images available, where to download
them, how to verify the integrity of an image, and how to decompress it.
Instructions for other operating systems are available:
* :ref:`download-verify-decompress-linux`
* :ref:`download-verify-decompress-mac`
Image types
***********
.. include:: ../../reference/image-types.rst
:start-after: image-types-content:
.. _verify-windows:
Verify the integrity of the |CL| image
**************************************
Before you use a downloaded |CL| image, verify its integrity. This action
eliminates the small chance of a corrupted image due to download issues. To
support verification, each released |CL| image has a corresponding SHA512
checksum file designated with the suffix `-SHA512SUMS`.
#. Download the corresponding SHA512 checksum file of your |CL| image.
#. Start Command Prompt.
#. Go to the directory with the downloaded image and checksum files.
#. Get the SHA512 checksum of the image with the command:
.. code-block:: bash
CertUtil -hashfile ./clear-[version number]-[image type].[compression type] sha512
#. Manually compare the output with the original checksum value shown in
the downloaded checksum file and make sure they match.
Decompress the |CL| image
********************************
Released |CL| images are compressed with either GNU zip (*.gz*) or XZ
(*.xz*). The compression type depends on the target platform or
environment. To decompress the image, follow these steps:
#. Download and install `7-Zip`_.
#. Go to the directory with the downloaded image and right-click it.
#. From the pop-up menu, select :guilabel:`7-Zip` and select
:guilabel:`Extract Here` as shown in Figure 1.
.. figure:: figures/download-verify-decompress-windows-fig-1.png
:scale: 80 %
:alt: 7-Zip extract file
Figure 1: Windows 7-Zip extract file.
.. _7-Zip: http://www.7-zip.org/
source/guides/maintenance/download-verify-decompress.rst
+176
View File
@@ -0,0 +1,176 @@
.. _download-verify-decompress:
Download, verify, and decompress a |CL-ATTR| image
##################################################
This guide describes the available types of |CL| images, where to
download them, how to verify their integrity, and how to decompress them.
Follow the steps for your OS.
.. contents::
:local:
:depth: 1
.. include:: ../../reference/image-types.rst
:start-after: image-types-content:
:end-before: incl-image-filename-end:
.. _download-verify-decompress-linux:
Linux OS steps
**************
.. _verify-linux:
Verify the integrity of the |CL| image
======================================
Before you use a downloaded |CL| image, verify its integrity. This action
eliminates the small chance of a corrupted image due to download issues. To
support verification, each released |CL| image has a corresponding SHA512
checksum file designated with the suffix `-SHA512SUMS`.
#. Download the corresponding SHA512 checksum file of your |CL| `image`_.
#. Start a terminal emulator.
#. Go to the directory with the downloaded image and checksum files.
#. Verify the integrity of the image and compare it to its original checksum
with the command:
.. code-block:: bash
sha512sum -c ./clear-[version number]-[image type].[compression type]-SHA512SUMS
If the checksum of the downloaded image is different than the original
checksum, a warning is displayed with a message indicating the computed
checksum does **not** match. Otherwise, the name of the image is printed on
the screen followed by `OK`.
For a more in-depth discussion of image verification including checking the
certificate see :ref:`image-content-validation`.
.. incl-decompress-image:
Decompress the |CL| image
=========================
Released |CL| images are compressed with either GNU zip (*.gz*) or XZ
(*.xz*). The compression type depends on the target platform or
environment. To decompress the image, follow these steps:
#. Start a terminal emulator.
#. Go to the directory with the downloaded image.
To decompress an XZ image, enter:
.. code-block:: bash
unxz clear-[version number]-[image type].xz
To decompress a GZ image, enter:
.. code-block:: bash
gunzip clear-[version number]-[image type].gz
.. incl-decompress-image-end:
.. _download-verify-decompress-mac:
macOS\* steps
*************
.. _verify-mac:
Verify the integrity of the |CL| image
======================================
Before you use a downloaded |CL| image, verify its integrity. This action
eliminates the small chance of a corrupted image due to download issues. To
support verification, each released |CL| image has a corresponding SHA512
checksum file designated with the suffix `-SHA512SUMS`.
#. Download the corresponding SHA512 checksum file of your |CL| `image`_.
#. Open a Terminal.
#. Go to the directory with the downloaded image and checksum files.
#. Verify the integrity of the image and compare it to its original checksum
with the command:
.. code-block:: bash
shasum -a512 clear-[version number]-[image type].[compression type] | diff clear-[version number]-[image type].[compression type]-SHA512SUMS -
If the checksum of the downloaded image is different than the original
checksum, the differences will be displayed. Otherwise, an empty output indicates
a match and your downloaded image is good.
Decompress the |CL| image
=========================
We compress all released |CL| images by default with either GNU zip
(`.gz`) or xz (`.xz`). The compression type we use depends on the target
platform or environment. To decompress the image, follow these steps:
#. Open a Terminal.
#. Go to the directory with the downloaded image.
#. Use the :command:`gunzip` command to decompress either compression type. For example:
.. code-block:: bash
gunzip clear-[version number]-[image type].xz
gunzip clear-[version number]-[image type].gz
.. _download-verify-decompress-windows:
Windows\* OS steps
******************
.. _verify-windows:
Verify the integrity of the |CL| image
======================================
Before you use a downloaded |CL| image, verify its integrity. This action
eliminates the small chance of a corrupted image due to download issues. To
support verification, each released |CL| image has a corresponding SHA512
checksum file designated with the suffix `-SHA512SUMS`.
#. Download the corresponding SHA512 checksum file of your |CL| `image`_.
#. Start Command Prompt.
#. Go to the directory with the downloaded image and checksum files.
#. Get the SHA512 checksum of the image with the command:
.. code-block:: bash
CertUtil -hashfile ./clear-[version number]-[image type].[compression type] sha512
#. Manually compare the output with the original checksum value shown in
the downloaded checksum file and make sure they match.
Decompress the |CL| image
=========================
Released |CL| images are compressed with either GNU zip (*.gz*) or XZ
(*.xz*). The compression type depends on the target platform or
environment. To decompress the image, follow these steps:
#. Download and install `7-Zip`_.
#. Go to the directory with the downloaded image and right-click it.
#. From the pop-up menu, select :guilabel:`7-Zip` and select
:guilabel:`Extract Here` as shown in Figure 1.
.. figure:: figures/download-verify-decompress-windows-fig-1.png
:scale: 80 %
:alt: 7-Zip extract file
Figure 1: Windows 7-Zip extract file.
.. _7-Zip: http://www.7-zip.org/
Image types
***********
.. include:: ../../reference/image-types.rst
:start-after: incl-image-filename-end:
.. _image: https://clearlinux.org/downloads
source/guides/maintenance/restart.rst
+162
View File
@@ -0,0 +1,162 @@
.. _restart:
Restart system services after an OS update
##########################################
|CL-ATTR| includes a :command:`clr-service-restart` tool that shows which
system daemons require a restart.
.. contents::
:local:
:depth: 1
Description
***********
:command:`clr-service-restart` reads various files in the :file:`procfs`
filesystem provided by the kernel and relies on :command:`systemd` to
determine which services to restart.
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.
Basic options
*************
:command:`clr-service-restart` has three basic options: allow, disallow, and
default.
allow
=====
The *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
OS software update.
.. code-block:: bash
sudo clr-service-restart allow tallow.service
disallow
========
The *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
record. The example below tells :command:`clr-service-restart` not to
restart the *rngd* daemon after an OS software update.
.. code-block:: bash
sudo clr-service-restart disallow rngd
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*
automatically again, because *rngd* is whitelisted for automatic service
restarts by default in |CL|.
.. code-block:: bash
sudo clr-service-restart default rngd
Monitor options
***************
:command:`clr-service-restart` works in the background and is invoked with
: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,
: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.
-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,
:command:`clr-service-restart` outputs a list of messages showing:
* Which service needs a restart.
* What unit it is.
* Why it needs a restart.
* Which command is required to restart the unit.
-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.
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:
.. code-block:: bash
sudo clr-service-restart -a -n
Sample output:
.. code-block:: console
upower.service: needs a restart (a library dependency was updated)
/usr/bin/systemctl --no-ask-password try-restart upower.service
NetworkManager.service: needs a restart (a library dependency was
updated)
/usr/bin/systemctl --no-ask-password try-restart NetworkManager.service
....
Telemetry
*********
:command:`clr-service-restart` may cause problems such as a short service
outage when a daemon is being restarted, or if a daemon fails to properly
restart. To minimize issues, :command:`clr-service-restart` creates a
telemetry record and sends it to the optional |CL| telemetry service if both
conditions below are met:
* If a unit fails to automatically restart after an OS update.
* If that unit resides in the system location :file:`/usr/lib/systemd/system`.
If you do not install the |CL| telemetrics bundle, the data is discarded. If
you install the telemetrics bundle and you opt to send telemetry, then the
system unit name is sent to the |CL| telemetry service. We evaluate the
report and update the whitelist to remove services that are not safe to
restart.
Conclusion
**********
The |CL| team enjoys coming up with simple and efficient solutions to make
your work easier. We made a GitHub\* project of :command:`clr-service-restart`
and we invite you to look at the code, share your thoughts, and work with us
on improving the project. You can find the project at:
https://github.com/clearlinux/clr-service-restart
source/guides/telemetrics/telem-guide.rst
+423 -228
View File
@@ -3,16 +3,23 @@
Telemetrics
###########
Telemetrics in |CL-ATTR| is a client and server solution used to collect data from running |CL| systems to help quickly identify and fix bugs in the OS. Both client and server are customizable, and an API is available on the client side for instrumenting your code for debug and analysis.
Telemetrics in |CL-ATTR| is a client and server solution used to collect
data from running |CL| systems to help quickly identify and fix bugs in the
OS. Both client and server are customizable, and an API is available on the
client side for instrumenting your code for debug and analysis.
.. important::
Telemetry in |CL| is **opt-in**. The telemetry client is **not** active and sends **no** data until you explicitly enable it.
Telemetry in |CL| is **opt-in**. The telemetry client is **not** active
and sends **no** data until you explicitly enable it.
.. note::
The telemetry functionality adheres to `Intel privacy policies`_ regarding the collection and use of :abbr:`PII (Personally Identifiable Information)` and is open source.
Specifically, no intentionally identifiable information about the user or system owner is collected.
The telemetry functionality adheres to `Intel privacy policies`_ regarding
the collection and use of :abbr:`PII (Personally Identifiable Information)`
and is open source.
Specifically, no intentionally identifiable information about the user or
system owner is collected.
.. contents::
:local:
@@ -20,81 +27,124 @@ Telemetrics in |CL-ATTR| is a client and server solution used to collect data fr
Description
*************
***********
Telemetry, one of the key features of |CL|, enables developers to observe and proactively address issues in the OS before end users are impacted.
Telemetry, one of the key features of |CL|, enables developers to observe and
proactively address issues in the OS before end users are impacted.
Telemetrics is a combination word made from:
* Telemetry, which is sensing and reporting data.
* Analytics, which is using visualization and statistical inferencing to make sense of the reported data.
* Analytics, which is using visualization and statistical inferencing to make
sense of the reported data.
|CL| telemetry reports system-level debug/crash information using specialized probes. The probes monitor system tasks such as swupd, kernel oops, machine error checks, and the BIOS error report table for unhandled hardware failures. Telemetry enables real-time issue reporting to allow system developers to quickly focus on an issue and monitor corrective actions.
|CL| telemetry reports system-level debug/crash information using specialized
probes. The probes monitor system tasks such as swupd, kernel oops, machine
error checks, and the BIOS error report table for unhandled hardware
failures. Telemetry enables real-time issue reporting to allow system
developers to focus quickly on an issue and monitor corrective actions.
|CL| telemetry is fully customizable and can be used during software development for debugging purposes. You can use the libtelemetry library in your code to create custom telemetry records. You can also use the telem-record-gen utility in script files for light touch record creation where instrumenting code files doesn't make sense.
|CL| telemetry is fully customizable and can be used during software
development for debugging purposes. You can use the libtelemetry library in
your code to create custom telemetry records. You can also use the
telem-record-gen utility in script files for light-touch record creation
where instrumenting code files doesn't make sense.
The |CL| telemetrics solution is an **opt-in** choice on the client side. By default, the telemetry client is disabled until you choose to enable it. Enabling the client is covered in this guide.
The |CL| telemetrics solution is an **opt-in** choice on the client side.
By default, the telemetry client is disabled until you choose to enable it.
Enabling the client is covered in this guide.
Architecture
============
|CL| telemetry has two fundamental components, which are shown in figure 1:
* Client: generates and delivers records to the backend server via the network
* Client: generates and delivers records to the backend server via the network.
* Backend: receives records sent from the client and displays the cumulative content through a specialized web interface.
* Backend: receives records sent from the client and displays the cumulative
content through a specialized web interface.
.. figure:: figures/telemetry-e2e.png
:alt: Figure 1, Telemetry Architecture
Figure 1: :guilabel:`|CL| Telemetry Architecture`
The telemetry client provides the front end of the telemetrics solution and includes the following components:
The telemetry client provides the front end of the telemetrics solution and
includes the following components:
* telemprobd, a daemon that receives and prepares telemetry records from probes and spools them to disk.
* telempostd, a daemon that manages spooled telemetry records and delivers these records according to configurable settings.
* probes, that collect specific types of data from the operating system.
* libtelemetry, the API that telemetrics probes use to create records.
* telemprobd, which is a daemon that receives and prepares telemetry records
from probes and spools them to disk.
* telempostd, which is a daemon that manages spooled telemetry records and
delivers these records according to configurable settings.
* probes, which collect specific types of data from the operating system.
* libtelemetry, which is the API that telemetrics probes use to create records.
The telemetry backend provides the server-side component of the telemetrics solution and consists of:
The telemetry backend provides the server-side component of the telemetrics
solution and consists of:
* Nginx web server.
* Two Flask apps:
* Collector, an ingestion web app for records received from client probes.
* TelemetryUI, a web app that exposes different views to visualize the telemetry data.
* Collector, which is an ingestion web app for records received from client
probes.
* TelemetryUI, which is a web app that exposes different views to visualize
the telemetry data.
* PostgreSQL as the underlying database server.
.. note::
The default telemetry backend server is hosted by the Intel |CL| development team and is not viewable outside the Intel firewall. To collect your own records, you must set up your own telemetry backend server.
The default telemetry backend server is hosted by the Intel |CL| development
team and is not viewable outside the Intel firewall. To collect your own
records, you must set up your own telemetry backend server.
How To Use
How to use
**********
From a workflow perspective, the |CL| telemetrics system is straightforward. On the client side, the main decisions after installation and enabling telemetry concern what to do with the record data generated by the probes. You can send the data to the default or a custom backend server, keep the data local to the system, or both. The backend server has a more complex setup, but once it's running, it is simple to use and configure.
From a workflow perspective, the |CL| telemetrics system is straightforward.
On the client side, the main decisions after installation and enabling
telemetry involve what to do with the record data generated by the probes.
You can send the data to the default or a custom backend server, keep the data
local to the system, or both. The backend server has a more complex setup, but
once it's running, it is simple to use and configure.
This section walks through some of the possible scenarios for configuring the |CL| telemetrics system, and suggests which make sense according to your needs.
This section describes some of the possible scenarios for configuring
the |CL| telemetrics system, and suggests which ones make sense according to
your needs.
Scenarios
=========
#. Enable telemetry
Before probes can generate records, the telemetry client daemons must be enabled. You can configure the client before enabling by creating a custom :file:`telemetrics.conf` file that you place in the :file:`/etc/telemetrics` directory. If you choose to use the default settings, records will be sent to the telemetrics backend server managed by the |CL| development team at Intel.
#. Enable telemetry:
#. Save record data locally
Before probes can generate records, the telemetry client daemons must be
enabled. You can configure the client before enabling by creating a custom
:file:`telemetrics.conf` file that you place in the :file:`/etc/telemetrics`
directory. If you choose to use the default settings, records will be sent
to the telemetrics backend server managed by the |CL| development team at
Intel.
You can configure the telemetry client to save records locally. This is convenient when you want instant feedback during a development cycle, or to track system issues if you believe there is a machine specific problem. The client can be set to not send records at all, or to both keep the records locally and send to the backend server.
#. Save record data locally:
#. Set up a server to collect data
You can configure the telemetry client to save records locally. This is
convenient when you want instant feedback during a development cycle, or to
track system issues if you believe there is a machine specific problem. The
client can be set not to send records at all, or to both keep the records
locally and send to the backend server.
Whether you are managing a network of |CL| systems or you don't want to send records to the default telemetry server, you can set up a backend server to collect your records. The backend server can be installed on any Linux system and will give you the same dashboard as the default server.
#. Set up a server to collect data:
Whether you are managing a network of |CL| systems or you don't want to
send records to the default telemetry server, you can set up a backend
server to collect your records. The backend server can be installed on any
Linux system and provides the same dashboard as the default server.
#. Instrument your code with the libtelemetry API
#. Instrument your code with the libtelemetry API:
The ``telemetrics`` bundle includes the libtelemetry C library, which exposes an API used by the telemprobd and telempostd daemons. You can use these in your applications as well. The API documentation is found in the :file:`telemetry.h` file in `Telemetrics client`_ repository.
The ``telemetrics`` bundle includes the libtelemetry C library, which
exposes an API used by the telemprobd and telempostd daemons. You can use
these in your applications as well. The API documentation is found in the
:file:`telemetry.h` file in `Telemetrics client`_ repository.
Examples
@@ -104,14 +154,19 @@ Examples
:local:
:depth: 1
Enable or Disable Telemetry
Enable or disable telemetry
===========================
#. Enabling during installation
#. Enabling during installation:
During the initial installation of |CL|, you are requested to join the stability enhancement program and allow |CL| to collect anonymous reports to improve system stability. If you choose not to join this program, then the telemetry software bundle is not added to your system. Choosing to join will automatically enable telemetry on your system after installation is commplete.
During the initial installation of |CL|, you are requested to join the
stability enhancement program and allow |CL| to collect anonymous reports to
improve system stability. If you choose not to join this program, then the
telemetry software bundle is not added to your system. Choosing to join will
automatically enable telemetry on your system after installation is
complete.
#. Enabling after install
#. Enabling after install:
To start telemetry on your system, run the following command:
@@ -119,9 +174,13 @@ Enable or Disable Telemetry
sudo telemctl start
This enables and starts the :command:`telemprobd` and :command:`telempostd` daemons. Your system will begin to send telemetry data to the server defined in the file :file:`/etc/telemetrics/telemetrics.conf`. If this file does not exist, the :command:`telemprobd` and :command:`telempostd` daemons will use the file :file:`/usr/share/defaults/telemetrics/telemetrics.conf`.
This enables and starts the :command:`telemprobd` and :command:`telempostd`
daemons. Your system will begin to send telemetry data to the server defined
in the file :file:`/etc/telemetrics/telemetrics.conf`. If this file does not
exist, the :command:`telemprobd` and :command:`telempostd` daemons will use
the file :file:`/usr/share/defaults/telemetrics/telemetrics.conf`.
#. Disabling after install
#. Disabling after install:
To disable both of the telemetry daemons, run the following command:
@@ -129,78 +188,107 @@ Enable or Disable Telemetry
sudo telemctl stop
#. Opt in to telemetry
#. Opt in to telemetry:
To opt-in to the telemetry services, simply enter the opt-in command and start the service:
To opt-in to the telemetry services, simply enter the opt-in command, which
also starts the service:
.. code-block:: bash
sudo telemctl opt-in
This removes the :file:`/etc/telemetrics/opt-out` file, if it exists, and starts the telemetry services.
This removes the :file:`/etc/telemetrics/opt-out` file, if it exists, and
starts the telemetry services.
.. note::
To opt-in but not immediately start telemetry services, you will need to run the command :command:`sudo telemctl stop` after the :command:`opt-in` command is entered. Once you are ready to start the service, enter the command :command:`sudo telemctl start`.
To opt-in but not immediately start telemetry services, you must
run the command :command:`sudo telemctl stop` after the :command:`opt-in`
command is entered. Once you are ready to start the service, enter the
command :command:`sudo telemctl start`.
#. Opt out of telemetry
#. Opt out of telemetry:
To stop sending telemetrics data from your system, opt out of the telemetry service:
To stop sending telemetrics data from your system, opt out of the telemetry
service:
.. code-block:: bash
sudo telemctl opt-out
This creates the file :file:`/etc/telemetrics/opt-out` and stops the telemetry services.
This creates the file :file:`/etc/telemetrics/opt-out` and stops the
telemetry services.
Saving Data Locally
Saving data locally
===================
This example requires |CL| to be installed, and telemetry to be enabled on the system.
This example requires |CL| to be installed and telemetry to be enabled on the
system.
To change how records are managed, we will be copying the default :file:`/usr/share/defaults/telemetrics/telemetrics.conf` file to :file:`/etc/telemetrics/telemetrics.conf` and editing it. The changes in the :file:`/etc/telemetrics/telemetrics.conf` file will override the defaults in the :file:`/usr/share/defaults/telemetrics/telemetrics.conf` file. You may need ``root`` permissions to create and edit files in :file:`/etc`. For each example, and for any time you make changes to the configuration file, you will need to restart the client daemons to pick up the changes:
To change how records are managed, copy the default
:file:`/usr/share/defaults/telemetrics/telemetrics.conf` file to
:file:`/etc/telemetrics/telemetrics.conf` and edit it. The changes in the
:file:`/etc/telemetrics/telemetrics.conf` file will override the defaults in
the :file:`/usr/share/defaults/telemetrics/telemetrics.conf` file. You may need
``root`` permissions to create and edit files in :file:`/etc`. For each
example, and for any time you make changes to the configuration file, you must
restart the client daemons to pick up the changes:
.. code-block:: bash
sudo telemctl restart
The :command:`telemctl journal` command gives you access to features and options of the telemetry journal to assist with system analytics and debug. :command:`telemctl journal` has a number of options to help filter records. Use :command:`-h` or :command:`--help` to view usage options.
The :command:`telemctl journal` command gives you access to features and
options of the telemetry journal to assist with system analytics and debug.
:command:`telemctl journal` has a number of options to help filter records.
Use :command:`-h` or :command:`--help` to view usage options.
#. Keep local copy and send records to backend server
#. Keep a local copy and send records to backend server:
To keep a local copy of the telemetry record and also send it on to the backend server, we will need to change the :guilabel:`record_retention_enabled` configuration key value to :guilabel:`true`.
To keep a local copy of the telemetry record and also send it on to the
backend server, we will need to change the :guilabel:`
record_retention_enabled` configuration key value to :guilabel:`true`.
#. Keep all records -- don't send to backend server
#. Keep all records -- don't send to backend server:
To keep records on the system without sending them to a backend server, set the :guilabel:`record_server_delivery_enabled` key value to :guilabel:`false`. Note that you will also need to ensure the :guilabel:`record_retention_enabled` configuration key value is set to :guilabel:`true` or the system will not keep local copies.
To keep records on the system without sending them to a backend server, set
the :guilabel:`record_server_delivery_enabled` key value to
:guilabel:`false`. Note that you will also need to ensure the
:guilabel:`record_retention_enabled` configuration key value is set to
:guilabel:`true` or the system will not keep local copies.
#. Keep and send records to custom server
#. Keep and send records to custom server:
This assumes you have set up a custom server according to the next example.
The server is identified by the :guilabel:`server` setting, and by default records will be sent to the |CL| server :guilabel:`server=https://clr.telemetry.intel.com/v2/collector`. To change this, you can use an IP address or fully qualified domain name.
The server is identified by the :guilabel:`server` setting, and by default
records are sent to the |CL| server :guilabel:`server=https://clr.
telemetry.intel.com/v2/collector`. To change this, you can use an IP
address or fully qualified domain name.
Set up a backend server to collect telemetry records
====================================================
Set up a back-end server to collect telemetry records
=====================================================
For this example, start with a clean installation of |CL| on a new system
using the :ref:`bare-metal-install-server` getting started guide and:
#. Join the :guilabel:`Stability Enhancement Program` to install and
enable the telemetrics components.
#. Select the manual installation method with the following settings:
* Set the hostname to :guilabel:`clr-telem-server`,
* Create an administrative user named :guilabel:`clear` and add this user
to sudoers
#. Log in with your administrative user, from your :file:`$HOME` directory, run :command:`git` to clone the :guilabel:`telemetrics-backend` repository into the :file:`$HOME/telemetrics-backend` directory:
#. Log in with your administrative user, from your :file:`$HOME` directory,
run :command:`git` to clone the :guilabel:`telemetrics-backend` repository
into the :file:`$HOME/telemetrics-backend` directory:
.. code-block:: console
@@ -208,10 +296,12 @@ using the :ref:`bare-metal-install-server` getting started guide and:
.. note::
You may need to set up the :envvar:`https_proxy` environment variable if you have issues reaching github.com.
You may need to set up the :envvar:`https_proxy` environment variable if
you have issues reaching github.com.
#. Change your current working directory to :file:`telemetrics-backend/scripts`.
#. We will install the telemetrics backend with the :file:`deploy.sh` script file. We will set the following options and leave the remainder as default:
#. Before you install the telemetrics backend with the :file:`deploy.sh` script
file in the next step, here is an explanation of the options to be specified:
* *-a install* to perform an install
* *-d clr* to install to a |CL| distro
@@ -219,9 +309,11 @@ using the :ref:`bare-metal-install-server` getting started guide and:
.. caution::
The :file:`deploy.sh` shell script has minimal error checking and makes
several changes to your system. Be sure that the options you define on the cmdline are correct before proceeding.
several changes to your system. Be sure that the options you define on
the cmdline are correct before proceeding.
#. Run the shell script from the :file:`$HOME/telemetrics-backend/scripts` directory:
#. Run the shell script from the :file:`$HOME/telemetrics-backend/scripts`
directory:
.. code-block:: console
@@ -229,7 +321,8 @@ using the :ref:`bare-metal-install-server` getting started guide and:
The script will start and list all the defined options and prompt you for the :guilabel:`PostgreSQL` database password
The script starts and lists all the defined options and prompts you for
the :guilabel:`PostgreSQL` database password.
.. code-block:: console
@@ -242,14 +335,20 @@ using the :ref:`bare-metal-install-server` getting started guide and:
type: git
DB password: (default: postgres):
#. For the :guilabel:`DB password:`, press the :kbd:`Enter` key to accept the default password `postgres`.
#. For the :guilabel:`DB password:`, press the :kbd:`Enter` key to accept the
default password `postgres`.
.. note::
The :file:`deploy.sh` script uses :command:`sudo` to run commands and you may be prompted to enter your user password at any time while the script is executing. If this occurs, enter your user password to execute the :command:`sudo` command.
The :file:`deploy.sh` script uses :command:`sudo` to run commands and you
may be prompted to enter your user password at any time while the script
is executing. If this occurs, enter your user password to execute the
:command:`sudo` command.
#. Once all the server components have been installed you are prompted to enter the :guilabel:`PostgreSQL` database password to change it as illustrated below:
#. After all the server components have been installed, you are prompted to
enter the :guilabel:`PostgreSQL` database password to change it as
illustrated below:
.. code-block:: console
@@ -258,9 +357,14 @@ using the :ref:`bare-metal-install-server` getting started guide and:
Retype new password:
passwd: password updated successfully
Enter `postgres` for the current value of the password and then enter a new password, retype it to verify the new password and the :guilabel:`PostgreSQL` database password will be updated.
Enter `postgres` for the current value of the password and then enter a new
password, retype it to verify the new password and the
:guilabel:`PostgreSQL` database password will be updated.
#. Once the installation is complete you can use your web browser to view the new server by opening the browser on the system and typing in ``localhost`` in the address bar. You should see a web page similar to the one shown in figure 1:
#. After the installation is complete, you can use your web browser to view the
new server by opening the browser on the system and typing in ``localhost``
in the address bar. You should see a web page similar to the one shown in
figure 1:
.. figure:: figures/telemetry-backend-1.png
:alt: Telemetry UI
@@ -272,7 +376,10 @@ using the :ref:`bare-metal-install-server` getting started guide and:
Create records with telem-record-gen
====================================
The telemetrics bundle provides a record generator tool called ``telem-record-gen``. This tool can be used to create records from shell scripts or the command line when writing a probe in C is not desirable. Records are sent to the backend server, and can also be echoed to stdout.
The telemetrics bundle provides a record generator tool called
``telem-record-gen``. This tool can be used to create records from shell
scripts or the command line when writing a probe in C is not desirable.
Records are sent to the backend server, and can also be echoed to stdout.
There are three ways to supply the payload to the record.
@@ -302,7 +409,8 @@ There are three ways to supply the payload to the record.
payload goes here
#. Specify a file that contains the payload with the option :command:`-P path/to/file`.
#. Specify a file that contains the payload with the option
:command:`-P path/to/file`.
.. code-block:: bash
@@ -328,7 +436,8 @@ There are three ways to supply the payload to the record.
payload read from file
#. If the :command:`-p` or :command:`-P` options are absent, the tool reads from stdin so you can use it in a :file:`heredoc` in scripts.
#. If the :command:`-p` or :command:`-P` options are absent, the tool reads
from stdin so you can use it in a :file:`heredoc` in scripts.
.. code-block:: bash
@@ -387,171 +496,203 @@ Instrument your code with the libtelemetry API
Prerequisites
-------------
Confirm that the telemetrics header file is located on the system at :file:`usr/include/telemetry.h` The `latest version`_ of the file can also be found on github for reference, but installing the `telemetry` bundle will install the header file that matches your |CL| version.
#. Includes and variables
Confirm that the telemetrics header file is located on the system at
:file:`usr/include/telemetry.h` The `latest version`_ of the file can also be
found on github for reference, but installing the `telemetry` bundle will
install the header file that matches your |CL| version.
You will need to include the following headers in your code to use the API:
#. Includes and variables:
::
You must include the following headers in your code to use the API:
#define _GNU_SOURCE
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <telemetry.h>
.. code-block:: console
#define _GNU_SOURCE
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <telemetry.h>
Use the following code to create the variables we need to hold the data for the record we will be creating:
Use the following code to create the variables needed to hold the data for
the record to be created:
::
.. code-block:: console
uint32_t severity = 1;
uint32_t payload_version = 1;
char classification[30] = "org.clearlinux/hello/world";
struct telem_ref *tm_handle = NULL;
char *payload;
int ret = 0;
uint32_t severity = 1;
uint32_t payload_version = 1;
char classification[30] = "org.clearlinux/hello/world";
struct telem_ref *tm_handle = NULL;
char *payload;
int ret = 0;
Severity:
| Type: uint32_t
| Value: Severity field value. Accepted values are in the range 1-4, with 1 being the lowest severity, and 4 being the highest severity. Values provided outside of this range are clamped to 1 or 4. [low, med, high, crit]
Type: uint32_t
Value: Severity field value. Accepted values are in the range 1-4, with
1 being the lowest severity, and 4 being the highest severity. Values
provided outside of this range are clamped to 1 or 4. [low, med, high,
crit]
Payload_version:
| Type: uint32_t
| Value: Payload format version. The only supported value right now is 1, which indicates that the payload is a freely-formatted (unstructured) string. Values greater than 1 are reserved for future use.
Type: uint32_t
Value: Payload format version. The only supported value right now is 1,
which indicates that the payload is a freely-formatted (unstructured)
string. Values greater than 1 are reserved for future use.
Classification:
| Type: char array
| Value: It should have the form, DOMAIN/PROBENAME/REST: DOMAIN is the reverse domain to use as a namespace for the probe (e.g. org.clearlinux); PROBENAME is the name of the probe; and REST is an arbitrary value that the probe should use to classify the record. The maximum length for the classification string is 122 bytes. Each sub-category may be no longer than 40 bytes long. Two / delimiters are required.
Type: char array
Value: It should have the form, DOMAIN/PROBENAME/REST: DOMAIN is the
reverse domain to use as a namespace for the probe (e.g. org.clearlinux);
PROBENAME is the name of the probe; and REST is an arbitrary value that
the probe should use to classify the record. The maximum length for the
classification string is 122 bytes. Each sub-category may be no longer
than 40 bytes long. Two / delimiters are required.
Tm_handle:
| Type: Telem_ref struct pointer
| Value: Struct pointer declared by the caller, The struct is initialized if the function returns success.
Type: Telem_ref struct pointer
Value: Struct pointer declared by the caller, The struct is initialized
if the function returns success.
Payload:
| Type: char pointer
| Value: The payload to set
Type: char pointer
Value: The payload to set
#. For this example, we'll set the payload to “hello” by using ``asprintf()``
#. For this example, we'll set the payload to “hello” by using ``asprintf()``:
::
.. code-block:: console
if (asprintf(&payload, "hello\n") < 0) {
exit(EXIT_FAILURE);
}
if (asprintf(&payload, "hello\n") < 0) {
exit(EXIT_FAILURE);
}
The functions ``asprintf()`` and ``vasprintf()`` are analogs of ``sprintf(3)`` and ``vsprintf(3)``, except that they allocate a string large enough to hold the output including the terminating null byte ('\0'), and return a pointer to it via the first argument. This pointer should be passed to ``free(3)`` to release the allocated storage when it is no longer needed.
The functions ``asprintf()`` and ``vasprintf()`` are analogs of
``sprintf(3)`` and ``vsprintf(3)``, except that they allocate a string
large enough to hold the output including the terminating null byte ('\0'),
and return a pointer to it via the first argument. This pointer should be
passed to ``free(3)`` to release the allocated storage when it is no longer
needed.
#. Create the new telemetry record
#. Create the new telemetry record:
The function ``tm_create_record()`` initializes a telemetry record and sets the severity and classification of that record, as well as the payload version number. The memory needed to store the telemetry record is allocated and should be freed with ``tm_free_record()`` when no longer needed.
The function ``tm_create_record()`` initializes a telemetry record and
sets the severity and classification of that record, as well as the payload
version number. The memory needed to store the telemetry record is allocated
and should be freed with ``tm_free_record()`` when no longer needed.
::
.. code-block:: console
if ((ret = tm_create_record(&tm_handle, severity, classification, payload_version)) < 0) {
printf("Failed to create record: %s\n", strerror(-ret));
ret = 1;
goto fail;
}
#. Set the payload field of a telemetrics record
The function ``tm_set_payload()`` attaches the provided telemetry record data to the telemetry record. The current maximum payload size is 8192b.
::
if ((ret = tm_set_payload(tm_handle, payload)) < 0) {
printf("Failed to set record payload: %s\n", strerror(-ret));
ret = 1;
goto fail;
}
free(payload);
The ``free()`` function frees the memory space pointed to by ptr, which must have been returned by a previous call to ``malloc()``, ``calloc()``, or ``realloc()``. Otherwise, or if ``free(ptr)`` has already been called before, undefined behavior occurs. If ptr is NULL, no operation is performed.
#. Send a record to the telemetrics daemon
The function ``tm_send_record()`` delivers the record to the local ``telemprobd(1)`` service. Since the telemetry record was allocated by the program it should be freed with ``tm_free_record()`` when it is no longer needed.
::
if ((ret = tm_send_record(tm_handle)) < 0) {
printf("Failed to send record to daemon: %s\n", strerror(-ret));
ret = 1;
goto fail;
} else {
printf("Successfully sent record to daemon.\n");
ret = 0;
}
fail:
tm_free_record(tm_handle);
tm_handle = NULL;
return ret;
#. Full sample application with compiling flags
Create a new file test.c add the following code.
::
#define _GNU_SOURCE
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <telemetry.h>
int main(int argc, char **argv)
{
uint32_t severity = 1;
uint32_t payload_version = 1;
char classification[30] = "org.clearlinux/hello/world";
struct telem_ref *tm_handle = NULL;
char *payload;
int ret = 0;
if (asprintf(&payload, "hello\n") < 0) {
exit(EXIT_FAILURE);
}
if ((ret = tm_create_record(&tm_handle, severity, classification, payload_version)) < 0) {
printf("Failed to create record: %s\n", strerror(-ret));
ret = 1;
goto fail;
}
if ((ret = tm_set_payload(tm_handle, payload)) < 0) {
printf("Failed to set record payload: %s\n", strerror(-ret));
ret = 1;
goto fail;
}
free(payload);
if ((ret = tm_send_record(tm_handle)) < 0) {
printf("Failed to send record to daemon: %s\n", strerror(-ret));
ret = 1;
goto fail;
} else {
printf("Successfully sent record to daemon.\n");
ret = 0;
}
fail:
tm_free_record(tm_handle);
tm_handle = NULL;
return ret;
if ((ret = tm_create_record(&tm_handle, severity, classification, payload_version)) < 0) {
printf("Failed to create record: %s\n", strerror(-ret));
ret = 1;
goto fail;
}
#. Set the payload field of a telemetrics record:
The function ``tm_set_payload()`` attaches the provided telemetry record
data to the telemetry record. The current maximum payload size is 8192b.
.. code-block:: console
if ((ret = tm_set_payload(tm_handle, payload)) < 0) {
printf("Failed to set record payload: %s\n", strerror(-ret));
ret = 1;
goto fail;
}
free(payload);
The ``free()`` function frees the memory space pointed to by ptr, which
must have been returned by a previous call to ``malloc()``, ``calloc()``,
or ``realloc()``. Otherwise, or if ``free(ptr)`` has already been called
before, undefined behavior occurs. If ptr is NULL, no operation is
performed.
#. Send a record to the telemetrics daemon:
The function ``tm_send_record()`` delivers the record to the local
``telemprobd(1)`` service. Since the telemetry record was allocated by
the program it should be freed with ``tm_free_record()`` when it is no
longer needed.
.. code-block:: console
if ((ret = tm_send_record(tm_handle)) < 0) {
printf("Failed to send record to daemon: %s\n", strerror(-ret));
ret = 1;
goto fail;
} else {
printf("Successfully sent record to daemon.\n");
ret = 0;
}
fail:
tm_free_record(tm_handle);
tm_handle = NULL;
return ret;
#. A full sample application with compiling flags:
Create a new file test.c and add the following code:
.. code-block:: console
#define _GNU_SOURCE
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <telemetry.h>
int main(int argc, char **argv)
{
uint32_t severity = 1;
uint32_t payload_version = 1;
char classification[30] = "org.clearlinux/hello/world";
struct telem_ref *tm_handle = NULL;
char *payload;
int ret = 0;
if (asprintf(&payload, "hello\n") < 0) {
exit(EXIT_FAILURE);
}
if ((ret = tm_create_record(&tm_handle, severity, classification, payload_version)) < 0) {
printf("Failed to create record: %s\n", strerror(-ret));
ret = 1;
goto fail;
}
if ((ret = tm_set_payload(tm_handle, payload)) < 0) {
printf("Failed to set record payload: %s\n", strerror(-ret));
ret = 1;
goto fail;
}
free(payload);
if ((ret = tm_send_record(tm_handle)) < 0) {
printf("Failed to send record to daemon: %s\n", strerror(-ret));
ret = 1;
goto fail;
} else {
printf("Successfully sent record to daemon.\n");
ret = 0;
}
fail:
tm_free_record(tm_handle);
tm_handle = NULL;
return ret;
}
Compile with the gcc compiler, using this command:
@@ -570,7 +711,8 @@ Confirm that the telemetrics header file is located on the system at :file:`usr/
.. note::
A full example of the `heartbeat probe`_ in C is documented in the source code.
A full example of the `heartbeat probe`_ in C is documented in the
source code.
Reference
*********
@@ -579,34 +721,77 @@ Reference
:local:
:depth: 1
The Telemetry API
The telemetry API
=================
Installing the ``telemetrics`` bundle includes the libtelemetry C library, which exposes an API used by the telemprobd and telempostd daemons. You can use these in your applications as well. The API documentation is found in the :file:`telemetry.h` file in `Telemetrics client`_ repository.
Installing the ``telemetrics`` bundle includes the libtelemetry C library,
which exposes an API used by the telemprobd and telempostd daemons. You can
use these in your applications as well. The API documentation is found in the
:file:`telemetry.h` file in `Telemetrics client`_ repository.
Client Configuration
Client configuration
====================
The telemetry client will look for the configuration file located at :file:`/etc/telemetrics/telemetrics.conf` and use it if it exists. If the file does not exist, the client will use the default configuration located at :file:`/usr/share/defaults telemetrics/telemetrics.conf`. To modify or customize the configuration, copy the file from :file:`/usr/share/defaults/telemetrics` to :file:`/etc/telemetrics` and edit it.
The telemetry client will look for the configuration file located at
:file:`/etc/telemetrics/telemetrics.conf` and use it if it exists. If the
file does not exist, the client will use the default configuration located
at :file:`/usr/share/defaults telemetrics/telemetrics.conf`. To modify or
customize the configuration, copy the file from
:file:`/usr/share/defaults/telemetrics` to :file:`/etc/telemetrics` and edit it.
Configuration Options
Configuration options
---------------------
The client uses the following configuration options from the config file:
* **server**: This specifies the web server to which telempostd sends the telemetry records.
* **socket_path**: This specifies the path of the unix domain socket that the telemprobd listens on for connections from the probes.
* **spool_dir**: This configuration option is related to spooling. If the daemon is not able to send the telemetry records to the backend server due to reasons such as the network availability, then it stores the records in a spool directory. This option specifies that path of the spool directory. This directory should be owned by the same user as the daemon.
* **record_expiry**: This is the time in minutes after which the records in the spool directory are deleted by the daemon.
* **spool_process_time**: This specifies the time interval in seconds that the daemon waits for before checking the spool directory for records. The daemon picks up the records in the order of modification date and tries to send the record to the server. It sends a maximum of 10 records at a time. If it was able to send a record successfully, it deletes the record from the spool. If the daemon finds a record older than the "record_expiry" time, then it deletes that record. The daemon looks at a maximum of 20 records in a single spool run loop.
* **rate_limit_enabled**: This determines whether rate-limiting is enabled or disabled. When enabled, there is a threshold on both records sent within a window of time, and record bytes sent within a window a time.
* **record_burst_limit**: This is the maximum amount of records allowed to be passed by the daemon within the record_window_length of time. If set to -1, the rate-limiting for record bursts is disabled.
* **record_window_length**: The time in minutes (0-59) that establishes the window length for the record_burst_limit. EX: if record_burst_window=1000 and record_window_length=15, then no more than 1000 records can be passed within any given fifteen minute window.
* **server**: This specifies the web server to which telempostd sends the
telemetry records.
* **socket_path**: This specifies the path of the unix domain socket on which
the telemprobd listens for connections from the probes.
* **spool_dir**: This configuration option is related to spooling. If the
daemon is not able to send the telemetry records to the backend server due
to reasons such as the network availability, then it stores the records in
a spool directory. This option specifies the path of the spool directory.
This directory should be owned by the same user as the daemon.
* **record_expiry**: This is the time, in minutes, after which the records in
the spool directory are deleted by the daemon.
* **spool_process_time**: This specifies the time interval, in seconds, that
the daemon waits for before checking the spool directory for records. The
daemon picks up the records in the order of modification date and tries to
send the record to the server. It sends a maximum of 10 records at a time.
If it was able to send a record successfully, it deletes the record from the
spool. If the daemon finds a record older than the "record_expiry" time, then
it deletes that record. The daemon looks at a maximum of 20 records in a
single spool run loop.
* **rate_limit_enabled**: This determines whether rate-limiting is enabled
or disabled. When enabled, there is a threshold on both records sent within
a window of time, and record bytes sent within a window a time.
* **record_burst_limit**: This is the maximum amount of records allowed to be
passed by the daemon within the record_window_length of time. If set to -1,
the rate-limiting for record bursts is disabled.
* **record_window_length**: The time, in minutes (0-59), that establishes the
window length for the record_burst_limit. For example, if
record_burst_window=1000 and record_window_length=15, then no more than
1000 records can be passed within any given fifteen-minute window.
* **byte_burst_limit**: This is the maximum amount of bytes that can be
passed by the daemon within the byte_window_length of time. If set to -1, the rate-limiting for byte bursts is disabled.
* **byte_window_length**: This is the time, in minutes (0-59), that establishes the window length for the byte_burst_limit.
* **rate_limit_strategy**: This is the strategy chosen once the rate-limiting threshold has been reached. Currently the options are 'drop' or 'spool', with spool being the default. If spool is chosen, records will be spooled and sent at a later time.
* **record_retention_enabled**: When this key is enabled (true) the daemon saves a copy of the payload on disk from all valid records. To avoid the excessive use of disk space only the latest 100 records are kept. The default value for this configuration key is false.
* **record_server_delivery_enabled**: This key controls the delivery of records to server; when enabled (default value), the record will be posted to the address in the configuration file. If this configuration key is disabled (false), records will not be spooled or posted to backend. This configuration key can be used in combination with record_retention_enabled to keep copies of telemetry records locally only.
passed by the daemon within the byte_window_length of time. If set to -1,
the rate-limiting for byte bursts is disabled.
* **byte_window_length**: This is the time, in minutes (0-59), that establishes
the window length for the byte_burst_limit.
* **rate_limit_strategy**: This is the strategy chosen once the rate-limiting
threshold has been reached. Currently the options are 'drop' or 'spool',
with spool being the default. If spool is chosen, records will be spooled
and sent at a later time.
* **record_retention_enabled**: When this key is enabled (true) the daemon
saves a copy of the payload on disk from all valid records. To avoid the
excessive use of disk space only the latest 100 records are kept. The default
value for this configuration key is false.
* **record_server_delivery_enabled**: This key controls the delivery of
records to server; when enabled (default value), the record will be posted to
the address in the configuration file. If this configuration key is disabled
(false), records will not be spooled or posted to backend. This configuration
key can be used in combination with record_retention_enabled to keep copies
of telemetry records locally only.
.. note::
@@ -615,9 +800,12 @@ The client uses the following configuration options from the config file:
reference for configuration.
Client Run-time Options
Client run-time options
=======================
The |CL| telemetry client provides an admin tool called :guilabel:`telemctl` for managing the telemetry services and probes. The tool is located in :file:`/usr/bin`. Running it with no argument results in the following:
The |CL| telemetry client provides an admin tool called :guilabel:`telemctl`
for managing the telemetry services and probes. The tool is located in
:file:`/usr/bin`. Running it with no argument results in the following:
.. code-block:: bash
@@ -638,12 +826,19 @@ The |CL| telemetry client provides an admin tool called :guilabel:`telemctl` for
start/stop/restart
------------------
The commands to start, stop and restart the telemetry services manage all required services and probes on the system. There is no need to separately start/stop/restart the two client daemons **telemprobd** and **telempostd**. The **restart** command option will call **telemctl stop** followed by **telemctl start** .
The commands to start, stop and restart the telemetry services manage all
required services and probes on the system. There is no need to separately
start/stop/restart the two client daemons **telemprobd** and **telempostd**.
The **restart** command option will call **telemctl stop** followed
by **telemctl start** .
is-active
---------
The `is-active` option reports whether the two client daemons are active. This is useful to verify that the **opt-in** and **opt-out** options have taken effect, or to ensure that telemetry is functioning on the system. Note that both daemons are verified.
The `is-active` option reports whether the two client daemons are active. This
is useful to verify that the **opt-in** and **opt-out** options have taken
effect, or to ensure that telemetry is functioning on the system. Note that
both daemons are verified.
.. code-block:: bash
source/tutorials/docker/docker.rst
+10 -13
View File
@@ -3,8 +3,8 @@
Run Docker\* on |CL-ATTR|
#########################
|CL-ATTR| supports multiple containerization platforms, including a Docker\*
solution. |CL| has many `unique features`_ including a minimal default
|CL-ATTR| supports multiple containerization platforms, including a Docker
solution. |CL| has many unique features including a minimal default
installation, which makes it compelling to use as a host for container
workloads, management, and orchestration.
@@ -36,7 +36,7 @@ Before you install any new packages, update |CL| with the following command:
Additionally, you should have:
* A basic understanding of Linux and Docker.
* A basic understanding of Linux\* and Docker.
* |CL| environment that has transparent network access to the Internet.
If you are behind a HTTP proxy server, in a corporate setting for example,
@@ -79,8 +79,8 @@ packages to run Docker images as containers.
Congratulations! At this point, you have a working installation of Docker
on |CL|. You are ready to start using container images on your system.
Integration with Kata Containers (optional)
********************************************
Integration with Kata Containers\* (optional)
*********************************************
`Kata Containers`_, is an open source project aiming to increase security
of containers by using a hardware-backed virtual machine container runtime
@@ -93,7 +93,7 @@ More information on installing and using the *kata-runtime* may be found at :re
.. note::
The proceeding sections of this tutorial are standard to Docker setup
The remaining sections of this tutorial are standard to Docker setup
and configuration. If you are familiar with Docker basics, you do not
need to continue reading. The following sections are provided here for
sake of completeness.
@@ -105,8 +105,8 @@ Additional Docker configuration
Perform additional Docker daemon configuration via a configuration file
typically located at :file:`/etc/docker/daemon.json`. |CL| features a
`stateless system`_ so the configuration file :file:`daemon.json` does *NOT*
exist by default.
:ref:`stateless` system so the configuration file :file:`daemon.json` does
*NOT* exist by default.
#. Create the :file:`daemon.json` by running this command:
@@ -148,10 +148,10 @@ Pulling and running an image from Docker Hub
`Docker Hub`_ is a publically available container image repository which
comes preconfigured with Docker. In the example below we will pull and run
an the official Docker image for nginx, an open source reverse proxy server.
an the official Docker image for nginx\*, an open source reverse proxy server.
#. First, pull a container image from Docker Hub using the
:command:`docker pull` command. Download the latest nginx Docker
:command:`docker pull` command. Download the latest nginx\* Docker
container image by running this command:
.. code-block:: bash
@@ -218,14 +218,11 @@ Related topics
* `Docker Hub`_
* `Kata Containers`_
.. _unique features: https://clearlinux.org/features
.. _Docker proxy instructions: https://docs.docker.com/config/daemon/systemd/#httphttps-proxy
.. _bundles: https://clearlinux.org/documentation/clear-linux/concepts/bundles-about#related-concepts
.. _stateless system: https://clearlinux.org/features/stateless
.. _Docker documentation on daemon configuration: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file
.. _Kata Containers: https://katacontainers.io/
source/tutorials/kubernetes/kubernetes.rst
+9 -9
View File
@@ -132,7 +132,8 @@ deployment and your security needs.
Configure and run Kubernetes
****************************
This section describes how to configure and run Kubernetes with CRI-O and kata-runtime.
This section describes how to configure and run Kubernetes with CRI-O and
kata-runtime.
Configure and run CRI-O + kata-runtime
======================================
@@ -150,7 +151,8 @@ Configure and run CRI-O + kata-runtime
sudo systemctl daemon-reload
sudo systemctl restart crio
#. Initialize the master control plane with the command below and follow the displayed instructions to set up `kubectl`:
#. Initialize the master control plane with the command below and follow the
displayed instructions to set up `kubectl`:
.. code-block:: bash
@@ -190,8 +192,8 @@ If you choose the `flannel` add-on, then you must add the following to the
--pod-network-cidr 10.244.0.0/16
Furthermore, if you are using CRI-O and `flannel` and you want to use Kata Containers,
edit the :file:`/etc/crio/crio.conf` file to add:
Furthermore, if you are using CRI-O and `flannel` and you want to use
Kata Containers, edit the :file:`/etc/crio/crio.conf` file to add:
.. code-block:: bash
@@ -234,7 +236,8 @@ Read the Kubernetes documentation to learn more about:
Cloud native setup automation (optional)
****************************************
Clone the `cloud-native-setup`_ repository on your system and follow the instructions. This repository includes helper scripts to automate configuration.
Clone the `cloud-native-setup`_ repository on your system and follow the
instructions. This repository includes helper scripts to automate configuration.
Package configuration customization (optional)
**********************************************
@@ -258,7 +261,7 @@ following commands:
sudo cp /usr/share/defaults/crio/crio.conf /etc/crio/
sudo $EDITOR /etc/crio/crio.conf
Learn more about `Stateless`_ in |CL| and view the |CL| `documentation`_.
Learn more about :ref:`stateless` in |CL| and view the |CL| `documentation`_.
Proxy configuration (optional)
******************************
@@ -398,9 +401,6 @@ Troubleshooting
.. _Joining your nodes: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#join-nodes
.. _Stateless: https://clearlinux.org/features/stateless
.. _documentation: https://clearlinux.org/documentation/clear-linux
.. _cloud-native-setup: https://github.com/clearlinux/cloud-native-setup
source/tutorials/wordpress/web-server-install.rst
+2 -3
View File
@@ -4,7 +4,7 @@ Set up a LAMP web server on |CL-ATTR|
#####################################
This tutorial provides instructions on how to set up a
:abbr:`LAMP (Linux, Apache, MySQL, PHP)` web server on |CL-ATTR| and how
:abbr:`LAMP (Linux, Apache\*, MySQL, PHP)` web server on |CL-ATTR| and how
to use phpMyAdmin\* to manage an associated database. Note that this
tutorial installs MariaDB\*, which is a drop-in replacement for MySQL\*.
@@ -75,7 +75,7 @@ Apache software bundle on |CL|.
Change the default configuration and data directory
***************************************************
|CL| is designed to be a `stateless`_ operating system which means that you
|CL| is designed to be a :ref:`stateless` operating system which means that you
must create an optional configuration file to override the default values.
The default location of the Apache configuration file, :file:`httpd.conf`,
is located in the :file:`/usr/share/defaults/httpd` directory. |CL| can
@@ -502,4 +502,3 @@ Next, add the WordPress components needed to host a WordPress website with :ref:
.. _Apache HTTP Server Project: https://httpd.apache.org/
.. _phpMyAdmin: https://www.phpmyadmin.net/
.. _stateless: https://clearlinux.org/features/stateless