Merge branch 'master' of github.com:clearlinux/clear-linux-documentation into rtd-theme

Signed-off-by: Kevin Putnam <kevin.putnam@intel.com>
This commit is contained in:
Kevin Putnam
2019-07-22 11:53:11 -07:00
58 changed files with 1260 additions and 1006 deletions
@@ -3,18 +3,18 @@
Install |CL-ATTR| from the live desktop
#######################################
The live desktop allows you to boot |CL-ATTR| in a GNOME desktop without
modifying the host system, offering you the chance to explore developing
on |CL| or install it. In this document, we show how to install |CL| on a
target system.
This page explains how to boot the |CL-ATTR| live desktop image, from which
you can install |CL| or explore without modifying the host system.
.. contents:: :local:
.. contents::
:local:
:depth: 1
System requirements
*******************
Assure that your target system supports the installation:
Before installing |CL|, verify that the host system supports the
installation:
* :ref:`system-requirements`
* :ref:`compatibility-check`
@@ -22,7 +22,7 @@ Assure that your target system supports the installation:
Preliminary steps
*****************
#. `Visit our Downloads page`_.
#. Visit our `Downloads`_ page.
#. Download the file :file:`clear-<release number>-live-desktop.iso`,
also called the |CL| Desktop.
@@ -31,6 +31,10 @@ Preliminary steps
<release-number> is the latest |CL| auto-numbered release.
#. Verify and decompress the file per your OS.
* :ref:`download-verify-decompress`
#. Follow your OS instructions to create a bootable USB drive.
* :ref:`bootable-usb`
@@ -72,12 +76,13 @@ Software (optional)
Explore |CL| bundles and other software. Double-click the
:guilabel:`Software` icon from the Activities menu, shown in Figure 2.
Assure a network connection exists before launching `Software`.
Ensure a network connection exists before launching the Software application.
.. note::
`Software` application is *only intended for exploring* available bundles,
applications, and images. Do not attempt to install them.
While running the |CL| live desktop image, the Software application is
intended only for exploration. Do not attempt to install applications during
exploration.
Launch the |CL| installer
=========================
@@ -517,26 +522,21 @@ Create partitions per requirements in Table 1.
- Mount Point
- Default size
* - ``VFAT(FAT32)``
* - **VFAT(FAT32)**
- boot
- /boot
- 150MB
* - ``linux-swap``
* - **linux-swap**
- swap
-
- 256MB
* - ``ext[234] or XFS``
* - **ext[234] or XFS**
- root
- /
- *Size depends upon use case/desired bundles.*
Next steps
**********
:ref:`guides`
.. _Visit our downloads page: https://clearlinux.org/downloads
.. _Downloads: https://clearlinux.org/downloads
@@ -3,7 +3,8 @@
Install |CL-ATTR| on bare metal with live server
################################################
These instructions guide you through installing |CL-ATTR| on bare metal from a bootable USB drive using a live server image.
This page explains how to install |CL-ATTR| on bare metal from a bootable USB
drive using a live server image.
.. contents::
:local:
@@ -12,7 +13,8 @@ These instructions guide you through installing |CL-ATTR| on bare metal from a b
System requirements
*******************
Assure that your target system supports the installation:
Before installing |CL|, verify that the host system supports the
installation:
* :ref:`system-requirements`
* :ref:`compatibility-check`
@@ -23,12 +25,14 @@ Download the latest |CL| live server image
Get the latest |CL| installer image from the `Downloads`_ page. Look for the
:file:`clear-[version number]-live-server.iso` file.
#. Verify and decompress the file per your OS.
* :ref:`download-verify-decompress`
#. Follow your OS instructions to create a bootable USB drive.
* :ref:`bootable-usb`
#. After downloading the image, verify and decompress the file per your OS.
Install |CL| on your target system
**********************************
@@ -817,23 +821,29 @@ Finish installation
Default partition schema
========================
To add partitions manually, see `Advanced configuration`_ below, and create
partitions per requirements in Table 1.
Create partitions per requirements in Table 1.
.. list-table:: **Table 1. Disk Partition Setup**
:widths: 33, 33, 33
.. list-table:: **Table 1. Default partition schema**
:widths: 25, 25, 25, 25
:header-rows: 1
* - FileSystem
- Label
- Mount Point
- Minimum size
* - ``VFAT``
- Default size
* - ``VFAT(FAT32)``
- boot
- /boot
- 150M
* - ``swap``
- 150MB
* - ``linux-swap``
- swap
-
- 256MB
* - ``root``
* - ``ext[234] or XFS``
- root
- /
- *Size depends upon use case/desired bundles.*
@@ -856,5 +866,4 @@ entering :guilabel:`Configure Installation Media`:
- Windows\* OS: :command:`diskpart`, then :command:`list disk`
- macOS\* platform: :command:`diskutil list`
.. _Autoproxy: https://clearlinux.org/features/autoproxy
.. _Downloads: https://clearlinux.org/downloads
Binary file not shown.

Before

Width:  |  Height:  |  Size: 85 KiB

After

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 91 KiB

After

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 7.9 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 37 KiB

After

Width:  |  Height:  |  Size: 7.4 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 87 KiB

After

Width:  |  Height:  |  Size: 13 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 81 KiB

After

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 69 KiB

After

Width:  |  Height:  |  Size: 25 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 19 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 58 KiB

After

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 97 KiB

After

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 57 KiB

After

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 67 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 58 KiB

@@ -69,13 +69,12 @@ this command:
Visit :ref:`image-types` for additional information about all available |CL| images.
.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst
.. include:: ../../guides/maintenance/download-verify-decompress.rst
:Start-after: verify-windows:
We also provide instructions for other operating systems:
* :ref:`download-verify-decompress-linux`
* :ref:`download-verify-decompress-mac`
Create and configure a new VM
*****************************
@@ -307,8 +306,3 @@ For other guides on using the VMWare Player and ESXi, see:
.. _VMware ESXi: https://www.vmware.com/products/esxi-and-esx.html
.. _VMware Workstation 14 Player: https://www.vmware.com/products/workstation-player.html
.. _VMware Workstation Player Documentation: https://docs.vmware.com/en/VMware-Workstation-Player/index.html
.. _image: https://cdn.download.clearlinux.org/image
@@ -4,7 +4,7 @@ Install |CL-ATTR| as a VMware\* Workstation Player guest OS
###########################################################
This page explains how to create a new VM and install |CL| on it with the
VMware Workstation 14 Player hypervisor.
VMware Workstation Player hypervisor.
.. contents::
:local:
@@ -13,16 +13,10 @@ VMware Workstation 14 Player hypervisor.
Overview
********
`VMware Workstation 14 Player`_ is a type 2 hypervisor. It runs on top of
another operating system such as Windows\* or Linux\*. With VMware ESXi, you can
create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)` on
your local system.
Installing |CL| into a new VM provides you flexibility when configuring the VM.
You can configure the VM's size, number of partitions, installed bundles, etc.
If you prefer to use a pre-configured |CL| VMware image instead, see our
:ref:`vmw-player-preconf` guide.
`VMware Workstation Player`_ is a type 2 hypervisor. It runs on top of
Windows\* or Linux\* operating systems. With VMware ESXi, you can
create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)`
on your local system.
VMware offers a type 1 hypervisor called `VMware ESXi`_ designed for the
cloud environment. For information on how to install |CL| as guest OS on
@@ -30,8 +24,12 @@ it, see :ref:`vmware-esxi-install-cl`.
.. note::
Screenshots in this document show VMware Workstation 14 Player for Windows.
Menus and prompts in the Linux version have minor wording differences.
The screenshots on this document show the Windows version of the
VMware Workstation 15 Player. The menus and prompts are similar to those
in other versions and for the Linux OS save some minor wording differences.
If you prefer to use a pre-configured |CL| VMware image instead,
see our :ref:`vmw-player-preconf` guide.
Install the VMware Workstation Player hypervisor
************************************************
@@ -40,10 +38,15 @@ Install the VMware Workstation Player hypervisor
:abbr:`Intel® VT-d (Intel® Virtualization Technology for Directed I/O)` in
your system's BIOS.
#. `VMware Workstation 14 Player`_ is available for Windows and Linux.
#. `VMware Workstation Player`_ is available for Windows and Linux.
Download your preferred version.
#. Install VMware Workstation 14 Player following the instructions
.. note::
By default, selecting download means you receive the latest version
of this application. Commands may differ based on the version.
#. Install VMware Workstation Player following the instructions
appropriate for your system's OS:
* On supported Linux distros:
@@ -64,21 +67,15 @@ Install the VMware Workstation Player hypervisor
For additional help, see the `VMware Workstation Player Documentation`_.
Download the latest |CL| installer ISO
**************************************
Download the latest |CL| installer
**********************************
Get the latest |CL| installer ISO image from the `image`_ repository.
Look for :file:`clear-[version number]-installer.iso.xz`.
Get the latest installer with |CL| OS Desktop from the `downloads`_ page.
Visit :ref:`image-types` for additional information about all available |CL| images.
.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst
:Start-after: verify-windows:
We also provide instructions for other operating systems:
* :ref:`download-verify-decompress-linux`
* :ref:`download-verify-decompress-mac`
We also provide instructions for downloading and verifying a Clear Linux ISO.
For more information, refer to :ref:`download-verify-decompress`.
Create and configure a new VM
*****************************
@@ -90,9 +87,9 @@ Create and configure a new VM
.. figure:: figures/vmw-player/vmw-player-01.png
:scale: 100%
:alt: VMware Workstation 14 Player - Create a new virtual machine
:alt: VMware Workstation Player - Create a new virtual machine
Figure 1: VMware Workstation 14 Player - Create a new virtual
Figure 1: VMware Workstation Player - Create a new virtual
machine
#. On the :guilabel:`Welcome to the New Virtual Machine Wizard` screen,
@@ -101,9 +98,9 @@ Create and configure a new VM
.. figure:: figures/vmw-player/vmw-player-02.png
:scale: 100%
:alt: VMware Workstation 14 Player - Select |CL| installer ISO
:alt: VMware Workstation Player - Select |CL| installer ISO
Figure 2: VMware Workstation 14 Player - Select |CL| installer ISO
Figure 2: VMware Workstation Player - Select |CL| installer ISO
#. Click the :guilabel:`Browse` button and select the decompressed |CL|
installer ISO.
@@ -116,13 +113,13 @@ Create and configure a new VM
.. figure:: figures/vmw-player/vmw-player-03.png
:scale: 100%
:alt: VMware Workstation 14 Player - Select guest operating system type
:alt: VMware Workstation Player - Select guest operating system type
Figure 3: VMware Workstation 14 Player - Select guest operating system
Figure 3: VMware Workstation Player - Select guest operating system
type
#. Set the :guilabel:`Version` setting to
:guilabel:`Other Linux 3.x or later kernel 64-bit`.
:guilabel:`Other Linux 4.x or later kernel 64-bit`.
#. Click the :guilabel:`Next` button.
@@ -131,9 +128,9 @@ Create and configure a new VM
.. figure:: figures/vmw-player/vmw-player-04.png
:scale: 100%
:alt: VMware Workstation 14 Player - Name virtual machine
:alt: VMware Workstation Player - Name virtual machine
Figure 4: VMware Workstation 14 Player - Name virtual machine
Figure 4: VMware Workstation Player - Name virtual machine
#. Click the :guilabel:`Next` button.
@@ -142,13 +139,14 @@ Create and configure a new VM
.. figure:: figures/vmw-player/vmw-player-05.png
:scale: 100%
:alt: VMware Workstation 14 Player - Set disk capacity
:alt: VMware Workstation Player - Set disk capacity
Figure 5: VMware Workstation 14 Player - Set disk capacity
Figure 5: VMware Workstation Player - Set disk capacity
.. note::
A minimal |CL| installation can exist on 600MB of drive space.
See :ref:`system-requirements` for more details.
For optimal performance with the |CL| Desktop image, we recommend 32GB
of drive space. See :ref:`system-requirements` for more details.
#. Click the :guilabel:`Next` button.
@@ -157,17 +155,17 @@ Create and configure a new VM
.. figure:: figures/vmw-player/vmw-player-06.png
:scale: 100%
:alt: VMware Workstation 14 Player - Customize hardware
:alt: VMware Workstation Player - Customize hardware
Figure 6: VMware Workstation 14 Player - Customize hardware
Figure 6: VMware Workstation Player - Customize hardware
#. Select :guilabel:`Memory` and set the size to 2GB. See Figure 7.
.. figure:: figures/vmw-player/vmw-player-07.png
:scale: 100%
:alt: VMware Workstation 14 Player - Set memory size
:alt: VMware Workstation Player - Set memory size
Figure 7: VMware Workstation 14 Player - Set memory size
Figure 7: VMware Workstation Player - Set memory size
.. note::
The |CL| installer ISO needs a minimum of 2GB of RAM.
@@ -180,9 +178,9 @@ Create and configure a new VM
.. figure:: figures/vmw-player/vmw-player-08.png
:scale: 100%
:alt: VMware Workstation 14 Player - Set virtualization engine option
:alt: VMware Workstation Player - Set virtualization engine option
Figure 8: VMware Workstation 14 Player - Set virtualization engine
Figure 8: VMware Workstation Player - Set virtualization engine
option
#. Under the :guilabel:`Virtualization engine` section,
@@ -200,9 +198,9 @@ Install |CL| into the new VM
.. figure:: figures/vmw-player/vmw-player-09.png
:scale: 100%
:alt: VMware Workstation 14 Player - Power on virtual machine
:alt: VMware Workstation Player - Power on virtual machine
Figure 9: VMware Workstation 14 Player - Power on virtual machine
Figure 9: VMware Workstation Player - Power on virtual machine
#. Follow the :ref:`install-on-target-start` guide to complete the
installation of |CL|.
@@ -221,67 +219,61 @@ Detach the |CL| installer ISO from the VM
.. figure:: figures/vmw-player/vmw-player-10.png
:scale: 100%
:alt: VMware Workstation 14 Player - Edit CD/DVD settings
:alt: VMware Workstation Player - Edit CD/DVD settings
Figure 10: VMware Workstation 14 Player - Edit CD/DVD settings
Figure 10: VMware Workstation Player - Edit CD/DVD settings
#. Go to :menuselection:`Removable Devices-->CD/DVD (IDE)-->Settings`.
#. On the :guilabel:`Device status` section, uncheck the
:guilabel:`Connected` and the :guilabel:`Connect at power on` settings.
See Figure 11.
.. figure:: figures/vmw-player/vmw-player-11.png
:scale: 100%
:alt: VMware Workstation 14 Player - Disconnect CD/DVD
Figure 11: VMware Workstation 14 Player - Disconnect CD/DVD
#. Go to :menuselection:`Removable Devices-->CD/DVD (IDE)-->Disconnect`.
#. Click the :guilabel:`OK` button.
#. To power off the VM, click the :guilabel:`Player` menu. See Figure 12.
.. figure:: figures/vmw-player/vmw-player-12.png
:scale: 100%
:alt: VMware Workstation 14 Player - Power off virtual machine
Figure 12: VMware Workstation 14 Player - Power off virtual machine
#. Go to :guilabel:`Power` and select :guilabel:`Shut Down Guest`.
Enable UEFI boot support
************************
|CL| needs UEFI support to boot. To enable UEFI, add the
following line to the end of your VM's :file:`.vmx` file:
|CL| needs UEFI support to boot. To enable UEFI:
.. code-block:: console
#. Power off the VM. click the :guilabel:`Player` menu. See Figure 11.
firmware = "efi"
.. note::
Depending on the OS, you can typically find the VMware VM files under:
* On Linux distros: :file:`/home/username/vmware`
* On Windows: :file:`C:\\Users\\username\\Documents\\Virtual Machines`
Power on the VM
***************
After configuring the settings above, power on your |CL| virtual machine.
#. On the :guilabel:`VMware Workstation Player` home screen, select your
VM. See Figure 13.
.. figure:: figures/vmw-player/vmw-player-13.png
.. figure:: figures/vmw-player/vmw-player-11.png
:scale: 100%
:alt: VMware Workstation 14 Player - Power on virtual machine
:alt: VMware Workstation Player - Power off virtual machine
Figure 13: VMware Workstation 14 Player - Power on virtual machine
Figure 11: VMware Workstation Player - Power off virtual machine
#. Go to :guilabel:`Power` and select :guilabel:`Shut Down Guest`.
#. Add the following line to the end of your VM's :file:`.vmx` file:
.. code-block:: console
firmware = "efi"
.. note::
Depending on the OS, you can typically find the VMware VM files under:
* On Linux distros: :file:`/home/username/vmware`
* On Windows: :file:`C:\\Users\\username\\Documents\\Virtual Machines`
#. After configuring the settings above, power on your |CL| virtual machine.
On the :guilabel:`VMware Workstation Player` home screen, select your
VM. See Figure 9.
#. Click :guilabel:`Play virtual machine`.
#. Install Open VM Tools. You may want to install the `open-vm-tools` in
your virtual machine. The Open Virtual Machine Tools (open-vm-tools) are
the open source implementation of VMware Tools for Linux guest operating
systems. In |CL| you can use the following to install the bundle in your VM
.. code-block:: console
sudo swupd bundle-add os-cloudguest-vmware
sudo systemctl enable --now open-vm-tools
More information is available on the `VMWare Tools Product Documentation`_ site.
Related topics
**************
@@ -293,10 +285,12 @@ For other guides on using the VMWare Player and ESXi, see:
.. _VMware ESXi: https://www.vmware.com/products/esxi-and-esx.html
.. _VMware Workstation 14 Player:
.. _VMware Workstation Player:
https://www.vmware.com/products/workstation-player.html
.. _VMware Workstation Player Documentation:
https://docs.vmware.com/en/VMware-Workstation-Player/index.html
.. _image: https://cdn.download.clearlinux.org/image
.. _downloads: https://clearlinux.org/downloads
.. _VMWare Tools Product Documentation: https://docs.vmware.com/en/VMware-Tools/10.1.0/com.vmware.vsphere.vmwaretools.doc/GUID-8B6EA5B7-453B-48AA-92E5-DB7F061341D1.html
@@ -38,14 +38,8 @@ Download the latest |CL| installer ISO
Get the latest |CL| installer ISO image from the `image`_ repository.
Look for :file:`clear-[version number]-installer.iso.xz`.
.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst
:Start-after: incl-decompress-image:
:end-before: incl-decompress-image-end:
For alternative instructions on other operating systems, see:
* :ref:`download-verify-decompress-mac`
* :ref:`download-verify-decompress-windows`
We also provide instructions for downloading and verifying a Clear Linux ISO.
For more information, refer to :ref:`download-verify-decompress`.
Upload the |CL| installer ISO to the VMware server
**************************************************
@@ -41,14 +41,8 @@ this command:
Visit :ref:`image-types` for additional information about all available |CL| images.
.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst
:Start-after: incl-decompress-image:
:end-before: incl-decompress-image-end:
For alternative instructions on other operating systems, see:
* :ref:`download-verify-decompress-mac`
* :ref:`download-verify-decompress-windows`
We also provide instructions for downloading and verifying a Clear Linux ISO.
For more information, refer to :ref:`download-verify-decompress`.
Upload the |CL| image to the VMware server
******************************************
@@ -107,10 +101,10 @@ hypervisor.
The steps in this section can also be referenced from the VMware documentation on `Cloning and converting virtual machine disks with vmkfstools`_
#. SSH into the `vSphere Management Assistant`_ appliance that is managing
the ESXi host or connect to the vSphere hosting using the `vSphere CLI`_.
the ESXi host or connect to the vSphere hosting using the `vSphere CLI`_.
.. note::
If there is no :abbr:`vMA (vSphere Management Assistant)` appliance or :abbr:`vCLI (vSphere CLI)` configured and available,
you can temporarily enable SSH directly on the ESXi host by following the
steps described in `Enable the Secure Shell (SSH) in the VMware Host Client`_ .
+93 -93
View File
@@ -3,30 +3,33 @@
Deploy at Scale
###############
Once you are comfortable with |CL-ATTR| :ref:`concepts <concepts>`, your
next step as a system administrator is to understand how to deploy |CL|
at scale in your environment.
In this document the term *endpoint* refers to a system targeted for
|CL| installation, whether that is a datacenter system or unit deployed in
field.
.. note::
This is not a replacement or blueprint for designing your own IT
operating environment.
Your |CL| deployment should complement the existing environment and
available tools. It is assumed foundational core IT dependencies of your
environment, such as your network, are healthy and scaled to suit the
deployment.
This guide describes deployment considerations and strategies when deploying
|CL-ATTR| at scale in your environment.
.. contents::
:local:
:depth: 2
:depth: 1
Pick a |CL| usage and update strategy
=====================================
Overview
********
In this guide the term *endpoint* refers to a system targeted for |CL|
installation, whether that is a datacenter system or unit deployed in field.
.. note::
This guide is not a replacement or blueprint for designing your own IT
operating environment.
Implementation details for a scale deployment are beyond the scope of this
guide.
Your |CL| deployment should complement your existing environment and
available tools. It is assumed core IT dependencies of your environment,
such as your network, are healthy and scaled to suit the deployment.
Pick a usage and update strategy
********************************
Different business scenarios call for different deployment methodologies.
|CL| offers the flexibility to continue consuming the upstream |CL|
@@ -36,27 +39,27 @@ act as your own :abbr:`OSV (Operating System Vendor)`.
Below is an overview of some considerations.
Create your own Linux distribution (mix)
----------------------------------------
========================================
This approach forks away from the |CL| upstream and has you act as your own
:abbr:`OSV (Operating System Vendor)` by leveraging the `mixer process`_ to
:abbr:`OSV (Operating System Vendor)` by leveraging the :ref:`mixer` process to
create customized images based on |CL|. This is a level of responsibility
that requires having more infrastructure and processes to adopt. In return,
this approach *offers you a high degree of control and customization*.
this approach *offers you a high degree of control and customization*. Consider:
* Development systems that generate bundles and updates should have
sufficient performance for the task and separate from the swupd update
sufficient performance for the task and be separate from the swupd update
webservers that serve update content to production machines.
* swupd update webservers that serve update content to
production machines (see `mixer process`_ for more information) should be
appropriately scaled.
* swupd update webservers that serve update content to production machines
should be appropriately scaled. Specific implementation details for a scalable,
resilient web server are beyond the scope of this document.
Your swupd update server is just like any other web application.
|WEB-SERVER-SCALE|
(See :ref:`mixer` for more information about update servers.)
Adopt an agile methodology
--------------------------
==========================
The cloud, and other scaled deployments, are all about flexibility and speed.
It only makes sense that any |CL| deployment strategy should follow suit.
@@ -76,48 +79,47 @@ other software development lifecycle. Below are some pointers:
* Setup a path to production for building |CL| based images. At minimum this
should include:
* A development clr-on-clr environment to test building packages and
bundles for |CL| systems.
* A development clr-on-clr environment to test building packages and
bundles for |CL| systems.
* A pre-production environment to deploy |CL| versions to before
production
* A pre-production environment to deploy |CL| versions to before
production
* Employ a continuous integration and continuous deployment (CI/CD)
philosophy in order to:
- Automatically pull custom packages as they are updated from their
upstream projects or vendors.
- Automatically pull custom packages as they are updated from their
upstream projects or vendors.
- Generate |CL| bundles and potentially bootable images with your
customizations, if any.
- Generate |CL| bundles and potentially bootable images with your
customizations, if any.
- Measure against metrics and indicators which are relevant to your
business (e.g. performance, power, etc) from release to release.
- Measure against metrics and indicators which are relevant to your
business (e.g. performance, power, etc) from release to release.
- Integrate with your organization's governance processes, such as change
control.
- Integrate with your organization's governance processes, such as change
control.
Versioning Infrastructure
-------------------------
Versioning infrastructure
=========================
|CL| version numbers are very important as they apply to the whole
infrastructure stack from OS components to libraries and
applications.
infrastructure stack from OS components to libraries and applications.
Good record keeping is important, so you should keep a detailed registry
and history of previously deployed versions and their contents.
Good record keeping is important, so you should keep a detailed registry and
history of previously deployed versions and their contents.
With a glance at the |CL| version numbers deployed, you should be
able to tell if your Clear systems are patched against a
particular security vulnerability or incorporate a critical new feature.
With a glance at the |CL| version numbers deployed, you should be able to
tell if your Clear systems are patched against a particular security
vulnerability or incorporate a critical new feature.
Pick an image distribution strategy
===================================
***********************************
Once you have decided on a usage and update strategy, you should understand
*how* |CL| will be deployed to your endpoints. In a large scale
deployment, interactive installers should be avoided in favor of automated
installations or prebuilt images.
*how* |CL| will be deployed to your endpoints. In a large scale deployment,
interactive installers should be avoided in favor of automated installations
or prebuilt images.
There are many well-known ways to install an operating system at scale. Each
have their own benefits, and one may lend itself easier in your environment
@@ -127,41 +129,40 @@ See the available :ref:`image-types`.
Below are some common ways to install |CL| to systems at scale:
Baremetal
---------
Bare metal
==========
Preboot Execution Environments (PXE) or other
out-of-band booting options are one way to distribute |CL|
to physical baremetal systems on a LAN.
Preboot Execution Environments (PXE) or other out-of-band booting options are
one way to distribute |CL| to physical bare metal systems on a LAN.
This option works well if your customizations are fairly small in size
and infrastructure can be stateless.
The |CL| `downloads page`_ offers a live image that can be deployed as
The |CL| `Downloads`_ page offers a live image that can be deployed as
a PXE boot server if one doesn't already exist in your environment. Also see
documentation on how to :ref:`bare-metal-install-server`.
Cloud Instances or Virtual Machines
-----------------------------------
Cloud instances or virtual machines
===================================
Image templates in the form of cloneable disks are an effective way to
distribute |CL| for virtual machine environments, whether on-premises or
hosted by a Cloud Solution Provider (CSP).
When used in concert with cloud VM migration features,
this can be a good option for allowing your applications a degree of high
availability and workload mobility; VMs can be restarted on a cluster of
hypervisor host or moved between datacenters transparently.
When used in concert with cloud VM migration features, this can be a good option
for allowing your applications a degree of high availability and workload
mobility; VMs can be restarted on a cluster of hypervisor host or moved between
datacenters transparently.
The |CL| `downloads page`_ offers example prebuilt VM images and is
readily available on popular CSPs. Also see
documentation on how to :ref:`virtual-machine-install`.
The |CL| `Downloads`_ page offers example prebuilt VM images and is readily
available on popular CSPs. Also see documentation on how to
:ref:`virtual-machine-install`.
Containers
----------
==========
Containerization platforms allow images to be pulled from a
repository and deployed repeatedly as isolated containers.
Containerization platforms allow images to be pulled from a repository and
deployed repeatedly as isolated containers.
Containers with a |CL| image can be a good option to blueprint and ship
your application, including all its dependencies, as an artifact while
@@ -170,16 +171,17 @@ applications.
|CL| is capable of running a Docker host, has a container image which can
be pulled from DockerHub, or can be built as a customized container.
For more information visit the `containers page`_.
For more information visit the `Containers`_ page.
Considerations with stateless systems
=====================================
*************************************
An important |CL| concept is statelessness and partitioning of system data
from user data. This concept can change the way you think about an at scale
deployment.
Backup strategy
---------------
===============
A |CL| system and its infrastructure should be considered a commodity and
be easily reproducible. Avoid focusing on backing up the operating system
@@ -187,16 +189,16 @@ itself or default values.
Instead, focus on backing up what's important and unique - the application
and data. In other words, only focus on backing up critical areas like
`/home`, `/etc`, and `/var`.
:file:`/home`, :file:`/etc`, and :file:`/var`.
Meaningful Logging & Telemetry
------------------------------
Meaningful logging & telemetry
==============================
Offload logging and telemetry from endpoints to external servers, so it is
persistent and can be accessed on another server when an issue occurs.
* Remote syslogging in |CL| is available through the
`systemd journal-remote service`_
`systemd-journal-remote.service`_
* |CL| offers a :ref:`telem-guide`, which can be a powerful tool
for a large deployment to quickly crowdsource issues of interest. Take
@@ -204,11 +206,12 @@ persistent and can be accessed on another server when an issue occurs.
and the kind of data that would be valuable, and expose events
appropriately.
Your telemetry server is just like any other web application.
|WEB-SERVER-SCALE|
Like any web server, the telemetry server should be appropriately scaled and
resilient. Specific implementation details for a scalable, resilient web
server are beyond the scope of this document.
Orchestration and Configuration Management
------------------------------------------
Orchestration and configuration management
==========================================
In cloud environments, where systems can be ephemeral, being able to
configure and maintain generic instances is valuable.
@@ -217,8 +220,8 @@ configure and maintain generic instances is valuable.
through the *os-cloudguest* bundles which allow you to configure many Day 1
tasks such as setting hostname, creating users, or placing
SSH keys in an automated way at boot. For more information on
automating configuration during deployment of |CL| endpoints see
the `documentation on bulk provisioning`_ .
automating configuration during deployment of |CL| endpoints see the
:ref:`bulk-provision` guide.
A configuration management tool is useful for maintaining consistent system
and application-level configuration. Ansible\* is offered through the
@@ -226,7 +229,7 @@ and application-level configuration. Ansible\* is offered through the
tool.
Cloud-native applications
-------------------------
=========================
An Infrastructure OS can design for good behavior, but it is ultimately up
to applications to make agile design choices. Applications deployed
@@ -239,13 +242,10 @@ Continuously test its use; Automate its use by redeploying |CL| and
application on new hosts. This naturally minimizes configuration drift,
challenges your monitoring systems, and business continuity plans.
.. _`mixer process`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/mixer
.. _`downloads page`: https://clearlinux.org/downloads/
.. _`containers page`: https://clearlinux.org/downloads/containers
.. _`systemd journal-remote service`: https://www.freedesktop.org/software/systemd/man/systemd-journal-remote.service.html
.. _`native telemetry solution`: https://clearlinux.org/features/telemetry
.. _`Downloads`: https://clearlinux.org/downloads/
.. _`Containers`: https://clearlinux.org/downloads/containers
.. _`systemd-journal-remote.service`: https://www.freedesktop.org/software/systemd/man/systemd-journal-remote.service.html
.. _`micro-config-drive`: https://github.com/clearlinux/micro-config-drive
.. _`documentation on bulk provisioning`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/bulk-provision
.. |WEB-SERVER-SCALE| replace::
There are many well-known ways to achieve a scalable and resilient web
+12 -3
View File
@@ -28,12 +28,21 @@ Network
network/*
Kernel
======
=======
.. toctree::
:maxdepth: 1
:glob:
kernel/*
kernel/*
Stacks
=======
.. toctree::
:maxdepth: 1
:glob:
stacks/*
stacks/dlrs/*
+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
+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
+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
@@ -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
+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
+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|.
+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
@@ -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
-----------------------------------
@@ -32,7 +32,7 @@ support verification, each released |CL| image has a corresponding SHA512
checksum file designated with the suffix `-SHA512SUMS`.
#. Download the corresponding SHA512 checksum file of your |CL| `image`_.
#. Start a terminal emulator.
#. Open a Terminal.
#. Go to the directory with the downloaded image and checksum files.
#. Verify the integrity of the image and compare it to its original checksum
with the command:
@@ -58,7 +58,7 @@ Released |CL| images are compressed with either GNU zip (*.gz*) or XZ
(*.xz*). The compression type depends on the target platform or
environment. To decompress the image, follow these steps:
#. Start a terminal emulator.
#. Open a Terminal.
#. Go to the directory with the downloaded image.
To decompress an XZ image, enter:
+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
@@ -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
+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.
@@ -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/
@@ -0,0 +1,226 @@
.. _query-upstream:
Query package info from upstream repository
###########################################
This guide describes how to query package information from the |CL| upstream
repositories. This guide is intended for developers and advanced users.
.. contents::
:local:
:depth: 1
:backlinks: top
Overview
********
In |CL-ATTR|, the :ref:`swupd<swupd-guide>` tool manages software
dependencies and installs bundles instead of packages. Although a bundle is
a collection of one or more packages, |CL| does not work with packages on
the client side. However, on the upstream/factory side, |CL| does work with
packages using a process called *mixing*.
Currently, :command:`swupd` does not report which packages are installed,
provide package version information, or return other package details. This
guide describes a method for retrieving package information from the |CL|
upstream repositories using :abbr:`DNF(Dandified Yum)` commands.
Prerequisites
*************
This guide assumes you have installed |CL| on your host system.
For detailed instructions on installing |CL| on a bare metal system, visit
the :ref:`bare metal installation guide <bare-metal-install-desktop>`.
Before you install any new packages, update |CL| with the following command:
.. code-block:: bash
sudo swupd update
Configure DNF
*************
#. Install the DNF bundle with the command:
.. code-block:: bash
sudo swupd bundle-add dnf
#. Create a :file:`dnf.conf` file with the commands:
.. code-block:: bash
sudo mkdir -p /etc/dnf
sudo curl -L https://github.com/clearlinux/common/raw/master/conf/dnf.conf --output /etc/dnf/dnf.conf
#. Edit the :file:`/etc/dnf/dnf.conf` file and set the **baseurl** variable
for binary and source RPMs as shown in lines 3 and 9 in the following
example.
.. code-block:: bash
:linenos:
:emphasize-lines: 3,9
[clear]
name=Clear
baseurl=https://cdn.download.clearlinux.org/releases/$releasever/clear/x86_64/os/
enabled=1
gpgcheck=0
[clear-source]
name=Clear sources
failovermethod=priority
baseurl=https://cdn.download.clearlinux.org/releases/$releasever/clear/source/SRPMS/
enabled=1
gpgcheck=0
#. Initialize the RPM database with the command:
.. code-block:: bash
sudo rpm --initdb
DNF command usage examples
**************************
.. contents:: :local:
:depth: 1
:backlinks: top
List all binary and source RPMs in the current release
======================================================
Command:
.. code-block:: bash
dnf repoquery --releasever=current
Sample output:
.. code-block:: console
Clear 5.1 MB/s | 13 MB 00:02
Clear sources 1.8 MB/s | 1.7 MB 00:00
AVB-AudioModules-0:4.1.0-1.src
AVB-AudioModules-0:4.1.0-1.x86_64
AVB-AudioModules-data-0:4.1.0-1.x86_64
AVB-AudioModules-dev-0:4.1.0-1.x86_64
AVB-AudioModules-lib-0:4.1.0-1.x86_64
AVB-AudioModules-license-0:4.1.0-1.x86_64
AVBStreamHandler-0:1.1.0-21.src
AVBStreamHandler-0:1.1.0-21.x86_64
AVBStreamHandler-abi-0:1.1.0-21.x86_64
AVBStreamHandler-bin-0:1.1.0-21.x86_64
AVBStreamHandler-data-0:1.1.0-21.x86_64
AVBStreamHandler-dev-0:1.1.0-21.x86_64
AVBStreamHandler-lib-0:1.1.0-21.x86_64
AVBStreamHandler-license-0:1.1.0-21.x86_64
...
<trimmed>
Show version information for a package in current release
=========================================================
This example queries version information for the zstd package.
Command:
.. code-block:: bash
dnf repoquery --releasever=current zstd
Sample output:
.. code-block:: console
Last metadata expiration check: 0:02:30 ago on Tue 16 Jul 2019 03:03:34 PM PDT.
zstd-0:1.4.0-46.src
zstd-0:1.4.0-46.x86_64
Show version information for a package in a specific release
============================================================
This example queries version information for the zstd package in release
21000.
Command:
.. code-block:: bash
dnf repoquery --releasever=21000 zstd
Sample output:
.. code-block:: console
Clear
2.7 MB/s | 3.9 MB 00:01
Clear sources
628 kB/s | 559 kB 00:00
zstd-0:1.3.3-20.src
zstd-0:1.3.3-20.x86_64
Show only version and release information for a package in a specific release
=============================================================================
This example queries version and release information for the zstd package in
release 15000.
Command:
.. code-block:: bash
dnf repoquery --releasever=15000 --qf="%{VERSION}\n%{RELEASE}" zstd
Sample output:
.. code-block:: console
Clear
3.4 MB/s | 3.9 MB 00:01
Clear sources
345 kB/s | 528 kB 00:01
1.1.4
5
Show the binary package for a specified binary file
===================================================
This example returns the binary package that contains the
:file:`/usr/bin/zip` binary file.
Command:
.. code-block:: bash
dnf repoquery --releasever=current --whatprovides /usr/bin/zip
Sample output:
.. code-block:: console
Last metadata expiration check: 0:04:47 ago on Tue 16 Jul 2019 03:03:34 PM PDT.
zip-bin-0:3.0-23.x86_64
Show the source package for a specified binary file
===================================================
This example returns the source package that contains the
:file:`/usr/bin/zip` binary file.
Command:
.. code-block:: bash
dnf repoquery --releasever=current --whatprovides /usr/bin/zip --srpm
Sample output:
.. code-block:: console
Last metadata expiration check: 0:05:50 ago on Tue 16 Jul 2019 03:03:34 PM PDT.
zip-0:3.0-23.src
+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:
+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
@@ -3,22 +3,32 @@
Validate signatures
###################
|CL-ATTR| offers a way to validate the content of an image or an update. All
This guide describes how to validate the contents of a |CL-ATTR| image.
.. contents::
:local:
:depth: 1
Overview
********
Validating the contents of an image is a manual process and is the same process
that :ref:`swupd-guide` performs internally.
|CL| offers a way to validate the content of an image or an update. All
validation of content works by creating and signing a hash. A valid signature
creates a chain of trust. A broken chain of trust, seen as an invalid
signature, means the content is not valid.
This guide covers how to validate the contents of an image, which is a manual
process and is the same process ``swupd`` performs internally to
validate an update.
.. _image-content-validation:
Image content validation
========================
************************
For the outlined steps, the installer image of the latest release of |CL| is
used for illustrative purposes. You may use any image of |CL| you choose.
In the steps below, we used the installer image of the latest release
of |CL|. You may use any image of |CL| you choose.
#. Download the image, the signature of the SHA512 sum of the image, and the
|CL| certificate used for signing the SHA512 sum.
@@ -52,7 +62,7 @@ used for illustrative purposes. You may use any image of |CL| you choose.
sha512sum clear-$(curl https://cdn.download.clearlinux.org/latest)-installer.img.xz > sha512sum.out
#. Ensure the signature of the SHA512 sum of the image was created using the
|CL| certificate. This validates the image is trusted and it has not
|CL| certificate. This confirms that the image is trusted and has not
been modified.
.. code-block:: console
@@ -61,21 +71,21 @@ used for illustrative purposes. You may use any image of |CL| you choose.
.. note::
The `-purpose any` option is required when using OpenSSL 1.1. If using
an earlier version of OpenSSL, omit this option to perform signature
validation. The `openssl version` command may be used to determine the
version of OpenSSL in use.
The :command:`-purpose any` option is required when using OpenSSL 1.1.
If you use an earlier version of OpenSSL, omit this option to perform
signature validation. The :command:`openssl version` command may be used
to determine the version of OpenSSL in use.
#. The output should contain ``Verification successful``. If the output
contains ``bad_signature`` anywhere, then the image is not trustworthy.
#. The output should contain "Verification successful". If the output
contains "bad_signature" anywhere, then the image is not trustworthy.
Update content validation
=========================
*************************
``swupd`` validates all update content automatically before applying the
update content. The process ``swupd`` follows internally is illustrated here
**swupd** validates all update content automatically before applying the
update content. The process swupd follows internally is illustrated here
with manual steps using the latest |CL| release. There is no need to perform
these steps manually when performing a ``swupd update``.
these steps manually when performing a :command:`swupd update`.
#. Download the :abbr:`MoM (top-level manifest)`, the signature of the MoM,
and the Swupd certificate used for signing the signature of the MoM.
@@ -89,22 +99,22 @@ these steps manually when performing a ``swupd update``.
# Swupd certificate
curl -O https://cdn.download.clearlinux.org/releases/$(curl https://cdn.download.clearlinux.org/latest)/clear/Swupd_Root.pem
#. Generate the SHA256 sum of the Swupd certificate.
#. Generate the SHA256 sum of the swupd certificate.
.. code-block:: console
sha256sum Swupd_Root.pem
#. Ensure the generated SHA256 sum of the Swupd certificate matches following
SHA256 sum to verify the integrity of the certificate.
#. Confirm that the generated SHA256 sum of the swupd certificate matches the
SHA256 sum shown below to verify the integrity of the certificate.
.. code-block:: console
ff06fc76ec5148040acb4fcb2bc8105cc72f1963b55de0daf3a4ed664c6fe72c Swupd_Root.pem
#. Ensure the signature of the MoM was created using the Swupd certificate.
This signature validates the update content is trustworthy and has not been
modified.
#. Confirm that the signature of the MoM was created using the Swupd
certificate. This signature validates the update content is trustworthy and
has not been modified.
.. code-block:: console
@@ -112,10 +122,10 @@ these steps manually when performing a ``swupd update``.
.. note::
The `-purpose any` option is required when using OpenSSL 1.1. If using
an earlier version of OpenSSL, omit this option to perform signature
validation. The `openssl version` command may be used to determine the
version of OpenSSL in use.
The :command:`-purpose any` option is required when using OpenSSL 1.1.
If you use an earlier version of OpenSSL, omit this option to perform
signature validation. The :command:`openssl version` command may be used
to determine the version of OpenSSL in use.
.. note::
@@ -123,7 +133,7 @@ these steps manually when performing a ``swupd update``.
MoM is signed directly because it is small in size compared to an image of
|CL|.
#. The output should contain ``Verification successful``. If the output
contains ``bad_signature`` anywhere, then the MoM cannot be trusted.
#. The output should contain "Verification successful". If the output
contains "bad_signature" anywhere, then the MoM cannot be trusted.
Because the MoM contains a list of hashes for bundle manifests, if the MoM
cannot be trusted, then the bundle content cannot be trusted.
@@ -3,9 +3,13 @@
Build a custom |CL-ATTR| based Docker container image
#######################################################
The official base |CL-ATTR| container image is published on Docker\* Hub and
is updated on a regular basis. This guide contains the steps to build a
custom container image.
This guide contains the steps to build a custom container image. The official
base |CL-ATTR| container image is published on Docker\* Hub and is updated on a
regular basis.
.. contents::
:local:
:depth: 1
Prerequisites
*************
@@ -82,24 +86,25 @@ Build the base container image
swupd bundle-add containers-basic
systemctl start docker
#. Use `os-install` to download and install the bundles.
#. Use :command:`os-install` to download and install the bundles.
.. code-block:: bash
swupd os-install --url https://cdn.download.clearlinux.org/update --statedir "$PWD"/swupd-state --no-boot-update --version 29790 -B os-core-update,editors,network-basic base
The `swupd` example uses the following flags:
The swupd example uses the following flags:
* :command:`os-install` tells `swupd` to download and install.
* :command:`os-install` tells swupd to download and install.
* :command:`-V / --version` specifies the version of the |CL| bundles.
* :command:`--url` specifies the URL of the bundles repository.
* :command:`--statedir` specifies the state directory where downloaded bundles
and any state information are stored.
* :command:`--no-boot-update` tells `swupd` to skip updating boot files because
* :command:`--no-boot-update` tells swupd to skip updating boot files because
boot files are not required for a container.
For more information on `swupd` flags, enter the :command:`swupd os-install -h` command.
For more information on swupd flags, enter the :command:`swupd os-install -h`
command.
Example output:
@@ -138,7 +143,7 @@ Build the base container image
.. note::
The `WARNING` message is expected and can be ignored.
The WARNING message is expected and can be ignored.
#. Create a tarball and compress it.
@@ -269,7 +274,7 @@ Example output:
.. note::
The `WARNING` message can be ignored because systemd does not run inside
The WARNING message can be ignored because systemd does not run inside
a container.
Remove a bundle
+23 -18
View File
@@ -3,12 +3,19 @@
Use DPDK to send packets between platforms
##########################################
This document describes how to send packets between two platforms in the
simple configuration shown in :ref:`Figure 1 <f1>`. The example uses the
:abbr:`Data Plane Development Kit (DPDK)`, which is a set of libraries,
drivers, sample applications, and tools for fast packet processing.
This guide describes how to send packets between two platforms.
.. _f1:
.. contents::
:local:
:depth: 1
Overview
********
Figure 1 shows how to send packets between two platforms in a simple
configuration. The example uses the :abbr:`Data Plane Development Kit (DPDK)`,
which is a set of libraries, drivers, sample applications, and tools for fast
packet processing.
.. figure:: ./figures/pktgen_lw3fd.png
:align: center
@@ -16,18 +23,18 @@ drivers, sample applications, and tools for fast packet processing.
Figure 1: Environment for l3fwd DPDK application
This example uses the following DPDK components:
This example uses the following DPDK components:
* pktgen: Traffic generator. See `pktgen documentation`_ for details.
* pktgen: Traffic generator. See `pktgen`_ documentation for details.
* l3fwd: Layer 3 forwarding example application. See
`l3fwd documentation`_ for details.
`l3fwd`_ documentation for details.
Prerequisites
*************
* Two platforms using |CL-ATTR| release `13330`_ or higher.
* Both images must include the :file:`kernel-native bundle`.
* Install the :file:`network-basic-dev` bundle with the command:
* Both images must include the :command:`kernel-native` bundle.
* Install the :command:`network-basic-dev` bundle with the command:
.. code-block:: bash
@@ -107,7 +114,7 @@ NICs to DPDK modules to run DPDK applications.
sudo modprobe vfio-pci
#. Check the NIC status to determine which network cards are not
busy. When another application is using them, the status shows `Active`,
busy. When another application is using them, the status shows "Active",
and those NICs cannot be bound.
.. code-block:: bash
@@ -160,9 +167,7 @@ Set up the physical environment (Platforms A and B)
***************************************************
Connect the NICs on Platform A to the NICs on Platform B using the network
cables as shown in :ref:`Figure 2<f2>`.
.. _f2:
cables as shown in figure 2.
.. figure:: ./figures/pyshical_net.png
@@ -174,7 +179,7 @@ Run l3fwd application (Platform B)
The `l3fwd` application is one of the DPDK examples available when you
install the :file:`dpdk-dev` bundle. `l3fwd` forwards packets from one
NIC to another. For details, refer to the `l3fwd documentation`_.
NIC to another. For details, refer to the `l3fwd`_ documentation.
#. Open the l3fwd example directory.
@@ -247,7 +252,7 @@ Run pktgen application (Platform A)
Pktgen> start 0-1
For more details, see the `pktgen documentation`_.
For more details, see the `pktgen`_ documentation.
Appendix A: Use pass-through for virtual machines
*************************************************
@@ -343,5 +348,5 @@ machines control the NICs on the host.
.. _dpdk.org NICs: http://dpdk.org/doc/nics
.. _pktgen tar package: http://dpdk.org/browse/apps/pktgen-dpdk/refs
.. _DPDK guide: http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html
.. _l3fwd documentation: http://dpdk.org/doc/guides/sample_app_ug/l3_forward.html
.. _pktgen documentation: http://pktgen-dpdk.readthedocs.io/en/latest/index.html
.. _l3fwd: http://dpdk.org/doc/guides/sample_app_ug/l3_forward.html
.. _pktgen: http://pktgen-dpdk.readthedocs.io/en/latest/index.html
+24 -16
View File
@@ -1,10 +1,17 @@
.. _ipxe-install:
Install |CL-ATTR| over the network with iPXE
############################################
Install over the network with iPXE
##################################
This guide describes how to install |CL-ATTR| using :abbr:`PXE (Pre-boot
Execution Environment)`.
Execution Environment)` over the network.
.. contents::
:local:
:depth: 1
Overview
********
PXE is an industry standard that describes client-server interaction with
network-boot software and uses the DHCP and TFTP protocols. This guide shows one
@@ -35,7 +42,7 @@ Prerequisites
Before booting with iPXE, make the following preparations.
Connect the PXE server and PXE clients to a switch on a private network, as
shown in Figure 2.
shown in figure 2.
.. figure:: ./figures/network-boot-setup.png
:alt: Network topology
@@ -63,7 +70,8 @@ Configuration
To set up |CL| using iPXE automatically, use the :file:`configure-ipxe.sh`
script included with :abbr:`ICIS (Ister Cloud Init Service)`. For additional
instructions on the script, refer to the guide on the `ICIS GitHub repository`_.
instructions on the script, refer to the guide on the `ister-cloud-init-svc`_
GitHub\* repository.
To set up |CL| manually, perform the steps below.
@@ -89,7 +97,7 @@ To set up |CL| manually, perform the steps below.
sudo -s
#. Add the `pxe-server` bundle to your |CL| system. The bundle contains all
#. Add the :command:`pxe-server` bundle to your |CL| system. The bundle contains all
files needed to run a PXE server.
.. code-block:: bash
@@ -130,8 +138,8 @@ To set up |CL| manually, perform the steps below.
boot
EOF
#. The `pxe-server` bundle contains a lightweight web-server known as
`nginx`. Create a configuration file for `nginx` to serve |CL| to PXE
#. The :command:`pxe-server` bundle contains a lightweight web-server known as
nginx. Create a configuration file for nginx to serve |CL| to PXE
clients with the following contents:
.. code-block:: console
@@ -152,18 +160,18 @@ To set up |CL| manually, perform the steps below.
.. note::
Create a separate `nginx` configuration file to serve network-bootable
images on a non-standard port number. This action saves existing `nginx`
Create a separate nginx configuration file to serve network-bootable
images on a non-standard port number. This action saves existing nginx
configurations.
#. Start `nginx` and enable the startup on boot option.
#. Start nginx and enable the startup on boot option.
.. code-block:: bash
sudo systemctl start nginx
sudo systemctl enable nginx
#. The `pxe-server` bundle contains a lightweight DNS server which
#. The :command:`pxe-server` bundle contains a lightweight DNS server which
conflicts with the DNS stub listener provided in `systemd-resolved`.
Disable the DNS stub listener and temporarily stop `systemd-resolved`.
@@ -221,7 +229,7 @@ To set up |CL| manually, perform the steps below.
sudo echo net.ipv4.ip_forward=1 > /etc/sysctl.d/80-nat-forwarding.conf
sudo echo 1 > /proc/sys/net/ipv4/ip_forward
#. The `pxe-server` bundle contains iPXE firmware images that allow computers
#. The :command:`pxe-server` bundle contains iPXE firmware images that allow computers
without an iPXE implementation to perform an iPXE boot. Create a TFTP
hosting directory and populate the directory with the iPXE firmware images
with the following commands:
@@ -231,7 +239,7 @@ To set up |CL| manually, perform the steps below.
sudo mkdir -p $tftp_root
sudo ln -sf /usr/share/ipxe/undionly.kpxe $tftp_root/undionly.kpxe
#. The `pxe-server` bundle contains a lightweight TFTP, DNS, and DHCP
#. The :command:`pxe-server` bundle contains a lightweight TFTP, DNS, and DHCP
server known as `dnsmasq`. Create a configuration file for `dnsmasq`
to listen on a dedicated IP address for those functions. PXE clients on
the private network will use this IP address.
@@ -252,7 +260,7 @@ To set up |CL| manually, perform the steps below.
tftp-root=$tftp_root
EOF
#. Add the options to host a DHCP server for PXE clients to the `dnsmasq`
#. Add the options to host a DHCP server for PXE clients to the :file:`dnsmasq`
configuration file.
.. code-block:: console
@@ -328,5 +336,5 @@ server that enables PXE clients to boot and install |CL| over the network.
.. _iPXE:
http://ipxe.org/
.. _ICIS GitHub repository:
.. _ister-cloud-init-svc:
https://github.com/clearlinux/ister-cloud-init-svc
+13 -15
View File
@@ -3,19 +3,21 @@
Combine multiple interfaces with network bonding
################################################
This guide describes how to configure systemd to use the :command:`bonding`
driver.
Network bonding combines multiple network interfaces into a single logical
interface to provide redundancy and bandwidth aggregation.
|CL-ATTR| includes Linux bonding_ and team_ drivers. This guide describes how
to configure systemd to use the `bonding` driver.
|CL-ATTR| includes the Linux `Bonding driver`_ and `Team driver`_ .
The example demonstrates how to:
* Bond all four ports of a quad-port NIC in `802.3ad` mode.
* Bond all four ports of a quad-port NIC in 802.3ad mode.
* Enable jumbo frames to optimize large data transfers on the local network.
Your NICs and network switch must support `802.3ad` mode and jumbo frames. The
Your NICs and network switch must support 802.3ad mode and jumbo frames. The
example explains how to configure your NICs for both features. Your switch may
require additional configuration. See your switch documentation for details.
@@ -54,13 +56,13 @@ require additional configuration. See your switch documentation for details.
MIIMonitorSec=1s
LACPTransmitRate=fast
Refer to the systemd.netdev_ manpage for :file:`30-bond1.netdev` file
Refer to the `systemd.netdev`_ manpage for :file:`30-bond1.netdev` file
syntax. This example is based on Example 9 on the manpage. Modify the
example for your configuration.
#. Configure the slave interfaces. Create a text file named
:file:`30-bond1-enp1s0.network`. Assign the slave interfaces to the virtual
`bond1` device and use the syntax shown in systemd.network_.
`bond1` device and use the syntax shown in `systemd.network`_.
.. code-block:: console
@@ -117,16 +119,12 @@ require additional configuration. See your switch documentation for details.
systemctl restart systemd-networkd
The `MTUBytes` settings do not take effect until you reboot or manually
apply the settings with a utility such as `ifconfig`.
apply the settings with a utility such as ifconfig.
.. _bonding:
https://www.kernel.org/doc/Documentation/networking/bonding.txt
.. _Bonding driver: https://www.kernel.org/doc/Documentation/networking/bonding.txt
.. _team:
https://www.kernel.org/doc/Documentation/networking/team.txt
.. _Team driver: https://www.kernel.org/doc/Documentation/networking/team.txt
.. _systemd.netdev:
https://www.freedesktop.org/software/systemd/man/systemd.netdev.html
.. _systemd.netdev: https://www.freedesktop.org/software/systemd/man/systemd.netdev.html
.. _systemd.network:
https://www.freedesktop.org/software/systemd/man/systemd.network.html
.. _systemd.network: https://www.freedesktop.org/software/systemd/man/systemd.network.html
+132 -131
View File
@@ -1,42 +1,40 @@
.. _vnc:
Remote-desktop to a |CL-ATTR| host using VNC
##############################################
Remote-desktop to a host using VNC
##################################
:abbr:`VNC (Virtual Network Computing)` is a client-server GUI-based tool
that allows you to connect via remote-desktop to your |CL-ATTR| host.
This guide describes how to use :abbr:`VNC (Virtual Network Computing)` to
connect to a remote |CL-ATTR| host.
This guide shows you how to:
VNC is a client-server GUI-based tool that allows you to connect via
remote-desktop to your |CL| host.
* Install the VNC server and misc. components on your |CL| host.
* Configure a VNC-server-start method on your |CL| host.
* Install a VNC viewer app and an SSH client on your client system.
* Establish a VNC connection to your |CL| host.
* Terminate a VNC connection to your |CL| host.
* Encrypt VNC traffic through an SSH tunnel.
.. contents::
:local:
:depth: 1
Install the VNC server and misc. components on your host
********************************************************
To configure VNC to work on your |CL| host, install these bundles:
* `desktop-autostart`: Installs :abbr:`GDM (Gnome Desktop Manager)`, sets
* :command:`desktop-autostart`: Installs :abbr:`GDM (Gnome Desktop Manager)`, sets
it to start automatically on boot, and installs TigerVNC Viewer.
* `vnc-server`: Installs the TigerVNC server.
* :command:`vnc-server`: Installs the TigerVNC server.
Follow these steps:
#. Log into your |CL| host and get root privileges.
.. code-block:: console
.. code-block:: bash
$ sudo -s
sudo -s
#. Install the |CL| bundles.
.. code-block:: console
.. code-block:: bash
# swupd bundle-add desktop-autostart vnc-server
swupd bundle-add desktop-autostart vnc-server
#. Reboot your |CL| host.
@@ -51,9 +49,9 @@ your |CL| host:
:header-rows: 1
* - Attribute
- `Method 1`: Manually start a VNC session
- `Method 2`: Automatically start a VNC session via a systemd service script
- `Method 3`: Create multi-user logins with authentication through GDM
- Method 1: Manually start a VNC session
- Method 2: Automatically start a VNC session via a systemd service script
- Method 3: Create multi-user logins with authentication through GDM
* - Description
- This is the traditional method where you SSH into the |CL| host, manually
start a VNC session to get a display ID, and connect to it by
@@ -86,7 +84,7 @@ Although all three methods can coexist on the same |CL| host, we recommend
you pick a method that suits your needs.
For simplicity, the rest of this guide refers to these methods as
`Method 1`, `Method 2`, and `Method 3`.
Method 1, Method 2, and Method 3.
Method 1: Manually start a VNC session
======================================
@@ -99,16 +97,14 @@ You (and each user) must perform these steps to initialize your VNC settings.
first time starting VNC, it adds default configuration files and asks you
to set a VNC password.
.. code-block:: console
.. code-block:: bash
$ vncserver
vncserver
Example output:
.. code-block:: console
$ vncserver
You will require a password to access your desktops.
Password:
@@ -124,19 +120,20 @@ You (and each user) must perform these steps to initialize your VNC settings.
Log file is /home/vnc-user-a/.vnc/clr-linux:2.log
Upon completion, you can find the default configuration files and the
password file hidden in the `.vnc` directory in your home directory.
password file hidden in the :file:`.vnc` directory in your home directory.
Also, a VNC session starts and shows a unique display ID, which is the
number following the hostname and the colon `:`. In the above example, the display ID is 2. In a later step, you will supply the display ID to
A VNC session starts and shows a unique display ID, which is the
number following the hostname and the colon ":". In the above example, the
display ID is 2. In a later step, you will supply the display ID to
your VNC viewer app for connection.
#. Kill the active VNC session for the time being with the
:command:`vncserver -kill :[display ID]` command. Substitute [display ID]
with your active VNC session display ID. For example:
.. code-block:: console
.. code-block:: bash
$ vncserver -kill :2
vncserver -kill :2
.. note::
@@ -159,29 +156,29 @@ preassigned unique display ID.
#. Log in and get root privileges.
.. code-block:: console
.. code-block:: bash
$ sudo -s
sudo -s
#. Make sure the user accounts already exist. Use the following command to
list all users.
.. code-block:: console
.. code-block:: bash
# cut -d: -f1 /etc/passwd
cut -d: -f1 /etc/passwd
#. Create the path :file:`/etc/systemd/system`.
.. code-block:: console
.. code-block:: bash
# mkdir -p /etc/systemd/system
mkdir -p /etc/systemd/system
#. Create a systemd service script file :file:`vncserver@:[X].service`,
where [X] is the display ID, for each user in :file:`/etc/systemd/system`
Each user must be assigned a unique display ID. Be sure the correct
username is entered in the `User` field. The example below shows user
`vnc-user-b` who is assigned the display ID `5`.
username is entered in the :guilabel:`User` field. The example below shows user
vnc-user-b who is assigned the display ID 5.
.. code-block:: console
@@ -211,20 +208,20 @@ preassigned unique display ID.
#. Start the VNC service script and set it to start automatically on
boot for each user. Replace the [X] with the display ID.
.. code-block:: console
.. code-block:: bash
# systemctl daemon-reload
# systemctl start vncserver@:[X].service
# systemctl enable vncserver@:[X].service
systemctl daemon-reload
systemctl start vncserver@:[X].service
systemctl enable vncserver@:[X].service
#. After starting the services, verify they are running.
.. code-block:: console
.. code-block:: bash
# systemctl | grep vnc
systemctl | grep vnc
The example below shows 2 VNC sessions that were successfully started for
users `vnc-user-b` with display ID 5 and `vnc-user-c` with display ID 6.
users vnc-user-b with display ID 5 and vnc-user-c with display ID 6.
.. code-block:: console
@@ -239,19 +236,21 @@ Method 3: Multi-user logins with authentication through GDM
For this method, VNC is configured as a systemd service that listens on port
5900 and GDM is configured to accept access requests from VNC. When you
make a VNC connection to your |CL| host, you are presented with the GDM login screen and you authenticate as if you are local. You must have root privileges to perform this configuration.
make a VNC connection to your |CL| host, you are presented with the GDM login
screen and you authenticate as if you are local. You must have root privileges
to perform this configuration.
#. Log in and get root privileges.
.. code-block:: console
.. code-block:: bash
$ sudo -s
sudo -s
#. Create the path :file:`/etc/systemd/system`.
.. code-block:: console
.. code-block:: bash
# mkdir -p /etc/systemd/system
mkdir -p /etc/systemd/system
#. Create a systemd socket file :file:`xvnc.socket` and add the following:
@@ -290,9 +289,9 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc
#. Create the path :file:`/etc/gdm`.
.. code-block:: console
.. code-block:: bash
# mkdir -p /etc/gdm
mkdir -p /etc/gdm
#. Create a GDM :file:`custom.conf` file and add the following:
@@ -309,17 +308,17 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc
#. Start the VNC socket script and set it to start automatically on boot.
.. code-block:: console
.. code-block:: bash
# systemctl daemon-reload
# systemctl start xvnc.socket
# systemctl enable xvnc.socket
systemctl daemon-reload
systemctl start xvnc.socket
systemctl enable xvnc.socket
#. After starting the socket, verify it is running.
.. code-block:: console
.. code-block:: bash
# systemctl | grep vnc
systemctl | grep vnc
The example below shows the xvnc.socket is running.
@@ -330,13 +329,13 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc
xvnc.socket loaded active listening XVNC Server on port 5900
system-xvnc.slice loaded active active system-xvnc.slice
See the `vncserver` Man page for additional information.
See the vncserver Man page for additional information.
Install a VNC viewer app and an SSH client on your client system
****************************************************************
You need a VNC viewer app on your client system to connect to your |CL| host.
An SSH client is only needed if you chose to use `Method 1` or you plan to
An SSH client is only needed if you chose to use Method 1 or you plan to
encrypt your VNC traffic, which is discussed later in this guide.
Perform the steps below to add these apps to your client system.
@@ -346,27 +345,27 @@ Install a VNC viewer app
On |CL|:
.. code-block:: console
.. code-block:: bash
# swupd bundle-add desktop-autostart
swupd bundle-add desktop-autostart
On Ubuntu, Mint:
On Ubuntu\*, Mint\*:
.. code-block:: console
.. code-block:: bash
# apt-get install xtightvncviewer
apt-get install xtightvncviewer
On Fedora:
On Fedora\*:
.. code-block:: console
.. code-block:: bash
# dnf install tigervnc
dnf install tigervnc
On Windows:
On Windows\*:
* Install `RealVNC for Windows`_
On macOS:
On macOS\*:
* Install `RealVNC for macOS`_
@@ -380,17 +379,17 @@ Install an SSH client
Establish a VNC connection to your host
***************************************
Depending on the VNC-server-configuration method chosen, use the appropriate VNC connection:
Depending on the VNC-server-configuration method chosen, use the appropriate VNC
connection:
If you chose `Method 1`, you must take a few extra steps by
using SSH to connect to your |CL| host and then manually launching VNC.
* If you chose Method 1, you must take a few extra steps by using SSH to connect
to your |CL| host and then manually launching VNC.
If you chose `Method 2`, get your preassigned VNC display ID from your
system administrator first and then proceed to the
:ref:`connect-to-vnc-session` section below.
* If you chose Method 2, get your preassigned VNC display ID from your system
administrator first and then proceed to the :ref:`connect-to-vnc-session`
section below.
If you chose `Method 3`, proceed to the
:ref:`connect-to-vnc-session` below.
* If you chose Method 3, proceed to the :ref:`connect-to-vnc-session` below.
SSH into your host and launch VNC
@@ -400,9 +399,9 @@ SSH into your host and launch VNC
#. On Linux distros and macOS:
.. code-block:: console
.. code-block:: bash
$ ssh [username]@[clear-linux-host-ip-address]
ssh [username]@[clear-linux-host-ip-address]
#. On Windows:
@@ -420,20 +419,17 @@ SSH into your host and launch VNC
Figure 1: Putty - configure SSH session settings
#. Log in with your |CL| username and password. Do not use your VNC
password.
#. Log in with your |CL| username and password. Do not use your VNC password.
#. Start a VNC session.
.. code-block:: console
.. code-block:: bash
$ vncserver
vncserver
Example output:
.. code-block:: console
$ vncserver
New 'clr-linux:3 (vnc-user-c)' desktop is clr-linux:3
Starting applications specified in /home/vnc-user-c/.vnc/xstartup
@@ -449,9 +445,9 @@ SSH into your host and launch VNC
To specify a display ID, enter a unique number that is not already
in use after the colon. For example:
.. code-block:: console
.. code-block:: bash
$ vncserver :8
vncserver :8
#. You can now end the SSH connection by logging out. This does
not terminate your active VNC session.
@@ -461,38 +457,38 @@ SSH into your host and launch VNC
Connect to your VNC session
===========================
For `Method 1` and `Method 2`, you must connect to a specific active session
For Method 1 and Method 2, you must connect to a specific active session
or display ID using one of two options:
* Use a fully-qualified VNC port number, which consists of the default VNC
server port (5900) plus the display ID
* Use the display ID
For example, if the display ID is 3, it can be specified as `5903` or just
as `3`. For `Method 3`, VNC does not expect a display ID. Use `5900`. For simplicity, the instructions below use the fully-qualified VNC port
number.
For example, if the display ID is 3, it can be specified as 5903 or just
as 3. For Method 3, VNC does not expect a display ID. Use 5900. For simplicity,
the instructions below use the fully-qualified VNC port number.
**On Linux distros:**
#. Open a terminal emulator and enter:
.. code-block:: console
.. code-block:: bash
$ vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port number]
vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port number]
#. Enter your credentials.
* For `Method 1` and `Method 2`, enter your VNC password. No username is
* For Method 1 and Method 2, enter your VNC password. No username is
required.
* For `Method 3`, enter your |CL| account username and password through
* For Method 3, enter your |CL| account username and password through
GDM.
.. note::
With `Method 3`, you cannot remotely log into your |CL| host through
With Method 3, you cannot remotely log into your |CL| host through
VNC if you are logged in locally and vice versa.
**On Windows and macOS using `RealVNC` app:**
**On Windows and macOS using RealVNC app:**
#. Start the RealVNC viewer app. See Figure 2.
#. Enter the IP address of the |CL| host and the fully-qualified
@@ -511,20 +507,21 @@ number.
#. Enter your credentials.
* For `Method 1` and `Method 2`, enter your VNC password. No username is
* For Method 1 and Method 2, enter your VNC password. No username is
required.
* For `Method 3`, enter your |CL| account username and password through
* For Method 3, enter your |CL| account username and password through
GDM.
.. note::
With `Method 3`, you cannot remotely log into your |CL| host through
With Method 3, you cannot remotely log into your |CL| host through
VNC if you are logged in locally and vice versa.
`Optional: Configure RealVNC Image Quality`
-------------------------------------------
Optional: Configure RealVNC Image Quality
-----------------------------------------
To increase the RealVNC viewer image quality, manually change the `ColorLevel` value. Follow these steps:
To increase the RealVNC viewer image quality, manually change the :guilabel:`ColorLevel`
value. Follow these steps:
#. Right-click a connection node and select :guilabel:`Properties...`.
See Figure 3.
@@ -549,7 +546,7 @@ To increase the RealVNC viewer image quality, manually change the `ColorLevel` v
Terminate a VNC connection to your host
***************************************
For `Method 1` and `Method 2`, once started, a VNC session remains active
For Method 1 and Method 2, once started, a VNC session remains active
on your |CL| host even if you close your VNC viewer app. If you want to
truly terminate an active VNC session, follow these steps:
@@ -558,24 +555,24 @@ truly terminate an active VNC session, follow these steps:
#. Find the active VNC session display ID with the command
:command:`vncserver -list`.
.. code-block:: console
.. code-block:: bash
$ vncserver -list
vncserver -list
#. Terminate it with the :command:`vncserver -kill` command followed by a
colon and the display ID.
.. code-block:: console
.. code-block:: bash
$ vncserver -kill :[display ID]
vncserver -kill :[display ID]
#. For `Method 3`, only the system administrator can stop and disable the
#. For Method 3, only the system administrator can stop and disable the
VNC service by using these commands:
.. code-block:: console
.. code-block:: bash
# systemctl stop xvnc.socket
# systemctl disable xnvc.socket
systemctl stop xvnc.socket
systemctl disable xnvc.socket
Encrypt VNC traffic through an SSH tunnel
@@ -590,10 +587,11 @@ from RealVNC Viewer.
Figure 6: RealVNC Viewer - Connection not encrypted warning
To add security, VNC traffic can be routed through an SSH tunnel. This is accomplished by following these steps:
To add security, VNC traffic can be routed through an SSH tunnel. This is
accomplished by following these steps:
#. Configure the VNC server to only accept connection from localhost by
adding the `-localhost` option.
adding the :command:`-localhost` option.
#. Set up an SSH tunnel between your client system and your |CL| host.
Your client system will forward traffic from the localhost (the client)
destined for a specified fully-qualified VNC port number (on the client)
@@ -604,7 +602,7 @@ To add security, VNC traffic can be routed through an SSH tunnel. This is accomp
Configure VNC to only accept connection from localhost
======================================================
For `Method 1`:
For Method 1:
#. Edit the :file:`config` file located in :file:`$HOME/.vnc` and uncomment
the `# localhost` line. It should look like this:
@@ -624,10 +622,10 @@ For `Method 1`:
#. If an active session exists, kill it, and then restart it.
For `Method 2`:
For Method 2:
#. Edit the systemd service script :file:`vncserver@:[X].service` located in
:file:`/etc/systemd/system` and add `-localhost` to the `ExecStart`
:file:`/etc/systemd/system` and add :command:`-localhost` to the `ExecStart`
line. The example below uses vncserver@:5.service:
.. code-block:: console
@@ -650,12 +648,12 @@ For `Method 2`:
#. Restart the service script:
.. code-block:: console
.. code-block:: bash
# systemctl daemon-load
# systemctl restart vncserver@:5.service
systemctl daemon-load
systemctl restart vncserver@:5.service
For `Method 3`:
For Method 3:
#. No change is needed to the :file:`xvnc@service` script.
@@ -663,17 +661,18 @@ For `Method 3`:
accepts connections from localhost by using the :command:`netstat`
command like this:
.. code-block:: console
.. code-block:: bash
$ netstat -plant
netstat -plant
.. note::
Add the |CL| `network-basic` bundle to get the :command:`netstat`
Add the |CL| :command:`network-basic` bundle to get the :command:`netstat`
command.
Figure 7 shows two VNC sessions (5901 and 5905) accepting connections from
any host as specified by the `0.0.0.0`'s. This is before the `-localhost` option was used.
any host as specified by the `0.0.0.0`'s. This is before the
:command:`-localhost` option was used.
.. figure:: figures/vnc/vnc-7.png
:scale: 100 %
@@ -681,7 +680,9 @@ any host as specified by the `0.0.0.0`'s. This is before the `-localhost` optio
Figure 7: VNC sessions (5901 and 5905) accepting connections from any host
Figure 8 shows two VNC sessions (5901 and 5905) only accepting connections from localhost as specified by `127.0.0.1`'s. This is after the `-localhost` option was used.
Figure 8 shows two VNC sessions (5901 and 5905) only accepting connections from
localhost as specified by `127.0.0.1`'s. This is after the
:command:`-localhost` option was used.
.. figure:: figures/vnc/vnc-8.png
:scale: 100 %
@@ -696,9 +697,9 @@ Set up an SSH tunnel from your client system to your |CL| host
#. Open terminal emulator and enter:
.. code-block:: console
.. code-block:: bash
$ ssh -L [client port number]:localhost:[fully-qualified VNC port number] \
ssh -L [client port number]:localhost:[fully-qualified VNC port number] \
-N -f -l [username] [clear-linux-host-ip-address]
#. Enter your |CL| account password (not your VNC password).
@@ -763,9 +764,9 @@ your VNC session.
#. Open terminal emulator and enter:
.. code-block:: console
.. code-block:: bash
$ vncviewer localhost:[client port number]
vncviewer localhost:[client port number]
**On Windows and macOS using `RealVNC`:**
@@ -3,7 +3,7 @@
Data Analytics Reference Stack
##############################
This tutorial shows you how to use the Data Analytics Reference Stack
This guide shows you how to use the Data Analytics Reference Stack
(DARS), and to optionally build your own images with the baseline Dockerfiles
provided in the `DARS repository`_. Our assumption is that |CL-ATTR| is the
host. However, any system that supports Docker\* containers can be used to
@@ -30,15 +30,16 @@ not be the latest released by |CL|.
.. note::
The Data Analytics Reference Stack is a collective work, and each piece of software within the work has its own license. Please see the `terms of use`_ for more details about licensing and usage of the Data Analytics Reference Stack.
The Data Analytics Reference Stack is a collective work, and each piece
of software within the work has its own license. Please see the `terms
of use`_ for more details about licensing and usage of the Data Analytics
Reference Stack.
Using the Docker Images
***********************
To immediately start using the latest stable DARS images, pull directly
from `Docker Hub`_. For this tutorial we'll use the `Dars with MKL`_ version of the stack.
from `Docker Hub`_. For this guide we'll use the `Dars with MKL`_ version of the stack.
Once you have downloaded the image, you can run it with
@@ -99,7 +100,6 @@ You can use any of the resulting images to launch fully functional
containers. If you need to customize the containers, you can edit the
provided :file:`Dockerfile`.
.. _DARS repository: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dars
.. _Docker Hub: https://hub.docker.com/
.. _OpenBLAS: http://www.openblas.net/
@@ -3,7 +3,7 @@
Deep Learning Reference Stack
#############################
This tutorial describes how to run benchmarking workloads for TensorFlow\*,
This guide describes how to run benchmarking workloads for TensorFlow\*,
PyTorch\*, and Kubeflow in |CL-ATTR| using the Deep Learning Reference Stack.
.. contents::
@@ -13,11 +13,12 @@ PyTorch\*, and Kubeflow in |CL-ATTR| using the Deep Learning Reference Stack.
Overview
********
We created the Deep Learning Reference Stack to help AI developers deliver the
best experience on Intel® Architecture. This stack reduces complexity common
with deep learning software components, provides flexibility for customized
solutions, and enables you to quickly prototype and deploy Deep Learning
workloads. Use this tutorial to run benchmarking workloads on your solution.
We created the Deep Learning Reference Stack to help AI developers deliver
the best experience on Intel® Architecture. This stack reduces complexity
common with deep learning software components, provides flexibility for
customized solutions, and enables you to quickly prototype and deploy Deep
Learning workloads. Use this guide to run benchmarking workloads on your
solution.
The Deep Learning Reference Stack is available in the following versions:
@@ -103,7 +104,7 @@ We validated these steps against the following software package versions:
.. note::
The Deep Learning Reference Stack was developed to provide the best user experience when executed on a |CL| host. However, as the stack runs in a container environment, you should be able to complete the following sections of this tutorial on other Linux* distributions, provided they comply with the Docker*, Kubernetes* and Go* package versions listed above. Look for your distribution documentation on how to update packages and manage Docker services.
The Deep Learning Reference Stack was developed to provide the best user experience when executed on a |CL| host. However, as the stack runs in a container environment, you should be able to complete the following sections of this guide on other Linux* distributions, provided they comply with the Docker*, Kubernetes* and Go* package versions listed above. Look for your distribution documentation on how to update packages and manage Docker services.
TensorFlow single and multi-node benchmarks
*******************************************
@@ -115,9 +116,7 @@ TensorFlow.
.. note::
Performance test results for the Deep Learning Reference Stack and for this tutorial were
obtained using `runc` as the runtime.
Performance test results for the Deep Learning Reference Stack and for this guide were obtained using `runc` as the runtime.
#. Download either the `Eigen`_ or the `Intel MKL-DNN`_ Docker image
from `Docker Hub`_.
@@ -194,12 +193,12 @@ single node.
Kubeflow multi-node benchmarks
******************************
The benchmark workload runs in a Kubernetes cluster. The tutorial uses
The benchmark workload runs in a Kubernetes cluster. The guide uses
`Kubeflow`_ for the Machine Learning workload deployment on three nodes.
.. warning::
If you choose the Intel® MKL-DNN or Intel® MKL-DNN-VNNI image, your platform must support the Intel® AVX-512 instruction set. Otherwise, an *illegal instruction* error may appear, and you won’t be able to complete this tutorial.
If you choose the Intel® MKL-DNN or Intel® MKL-DNN-VNNI image, your platform must support the Intel® AVX-512 instruction set. Otherwise, an *illegal instruction* error may appear, and you won’t be able to complete this guide.
Kubernetes setup
@@ -255,7 +254,7 @@ Images
You must add `launcher.py`_ to the Docker image to include the Deep
Learning Reference Stack and put the benchmarks repo in the correct
location. Note that this tutorial uses Kubeflow v0.4.0, and cannot guarantee results if you use a different version.
location. Note that this guide uses Kubeflow v0.4.0, and cannot guarantee results if you use a different version.
From the Docker image, run the following:
@@ -362,8 +361,8 @@ Run a TFJob
This replicates and deploys three test setups in your Kubernetes cluster.
Results of running this tutorial
================================
Results of running this guide
=============================
You must parse the logs of the Kubernetes pod to retrieve performance
data. The pods will still exist post-completion and will be in

Before

Width:  |  Height:  |  Size: 48 KiB

After

Width:  |  Height:  |  Size: 48 KiB

Before

Width:  |  Height:  |  Size: 51 KiB

After

Width:  |  Height:  |  Size: 51 KiB

Before

Width:  |  Height:  |  Size: 57 KiB

After

Width:  |  Height:  |  Size: 57 KiB

Before

Width:  |  Height:  |  Size: 67 KiB

After

Width:  |  Height:  |  Size: 67 KiB

Before

Width:  |  Height:  |  Size: 81 KiB

After

Width:  |  Height:  |  Size: 81 KiB

@@ -6,36 +6,36 @@ Enable AWS Greengrass\* and OpenVINO™ toolkit
Hardware accelerated Function-as-a-Service (FaaS) enables cloud developers to
deploy inference functionalities [1] on Intel® IoT edge devices with
accelerators (CPU, Integrated GPU, Intel® FPGA, and Intel® Movidius™
technology). These functions provide a great developer experience and seamless
migration of visual analytics from cloud to edge in a secure manner using a
containerized environment. Hardware-accelerated FaaS provides the best-in-class
performance by accessing optimized deep learning libraries on Intel® IoT
edge devices with accelerators.
technology). These functions provide a great developer experience and
seamless migration of visual analytics from cloud to edge in a secure manner
using a containerized environment. Hardware-accelerated FaaS provides the
best-in-class performance by accessing optimized deep learning libraries on
Intel® IoT edge devices with accelerators.
This tutorial demonstrates how to:
This guide demonstrates how to:
* Set up the Intel® edge device with |CL-ATTR|
* Install the OpenVINO™ toolkit and Amazon Web Services\* (AWS\*)
Greengrass\* software stacks
* Use AWS Greengrass\* and AWS Lambda\* to deploy the FaaS samples from the cloud
* Use AWS Greengrass\* and AWS Lambda\* to deploy the FaaS samples from
the cloud
Refer to the following topics:
.. contents:: :local:
:depth: 1
Supported platforms
*******************
* Operating System: |CL| latest release
* Hardware: Intel® core platforms (This tutorial supports inference on CPU only.)
* Hardware: Intel® core platforms (that support inference on CPU only)
Sample description
==================
The AWS Greengrass samples are located at `Edge-Analytics-FaaS`_. This
tutorial uses the 1.0 version of the source code.
guide uses the 1.0 version of the source code.
|CL| provides the following AWS Greengrass samples:
@@ -117,9 +117,9 @@ Locate sample models
--------------------
There are two types of provided models that can be used in conjunction with
AWS Greengrass for this tutorial: classification or object detection.
AWS Greengrass for this guide: classification or object detection.
To complete this tutorial using an image classification model,
To complete this guide using an image classification model,
download the BVLC AlexNet model files `bvlc_alexnet.caffemodel`_ and `deploy.prototxt`_
to the default model_location at :file:`/usr/share/openvino/models`.
Any custom pre-trained classification models can be used with the
@@ -203,7 +203,7 @@ cloud and edge.
Create and package Lambda function
**********************************
#. Complete steps 1-4 of the AWS Greengrass tutorial at `Create and Package a Lambda Function`_.
#. Complete steps 1-4 of the AWS Greengrass guide at `Create and Package a Lambda Function`_.
.. note::
@@ -271,7 +271,7 @@ configuring the Lambda function for AWS Greengrass.
* - PARAM_MODEL_XML
- <MODEL_DIR>/<IR.xml>, where <MODEL_DIR> is user specified and
contains IR.xml, the Intermediate Representation file from Intel® Model Optimizer.
For this tutorial, <MODEL_DIR> should be set to '/usr/share/openvino/models'
For this guide, <MODEL_DIR> should be set to '/usr/share/openvino/models'
or one of its subdirectories.
* - PARAM_INPUT_SOURCE
- <DATA_DIR>/input.webm to be specified by user. Holds both input and
@@ -292,8 +292,7 @@ configuring the Lambda function for AWS Greengrass.
.. note::
The optional topic filter field is the topic mentioned inside the Lambda
function. In this tutorial, sample topics include the following:
The optional topic filter field is the topic mentioned inside the Lambda function. In this guide, sample topics include the following:
:command:`openvino/ssd` or :command:`openvino/classification`
Add local resources
+124 -119
View File
@@ -3,10 +3,7 @@
Telemetrics
###########
Telemetrics in |CL-ATTR| is a client and server solution used to collect
data from running |CL| systems to help quickly identify and fix bugs in the
OS. Both client and server are customizable, and an API is available on the
client side for instrumenting your code for debug and analysis.
This guide describes the |CL-ATTR| telemetry solution.
.. important::
@@ -17,17 +14,22 @@ client side for instrumenting your code for debug and analysis.
The telemetry functionality adheres to `Intel privacy policies`_ regarding
the collection and use of :abbr:`PII (Personally Identifiable Information)`
and is open source.
Specifically, no intentionally identifiable information about the user or
system owner is collected.
and is open source.
No intentionally identifiable information about the user or system owner is
collected.
.. contents::
:local:
:depth: 1
Overview
********
Description
***********
Telemetrics in |CL| is a client and server solution used to collect
data from running |CL| systems to help quickly identify and fix bugs in the
OS. Both client and server are customizable, and an API is available on the
client side for instrumenting your code for debug and analysis.
Telemetry, one of the key features of |CL|, enables developers to observe and
proactively address issues in the OS before end users are impacted.
@@ -57,7 +59,7 @@ Enabling the client is covered in this guide.
Architecture
============
|CL| telemetry has two fundamental components, which are shown in figure 1:
|CL| telemetry has two fundamental components, which are shown in Figure 1:
* Client: generates and delivers records to the backend server via the network.
@@ -125,7 +127,7 @@ Scenarios
#. Save record data locally:
You can configure the telemetry client to save records locally. This is
You can configure the telemetry client to save records locally. This is
convenient when you want instant feedback during a development cycle, or to
track system issues if you believe there is a machine specific problem. The
client can be set not to send records at all, or to both keep the records
@@ -141,7 +143,7 @@ Scenarios
#. Instrument your code with the libtelemetry API:
The ``telemetrics`` bundle includes the libtelemetry C library, which
The :command:`telemetrics` bundle includes the libtelemetry C library, which
exposes an API used by the telemprobd and telempostd daemons. You can use
these in your applications as well. The API documentation is found in the
:file:`telemetry.h` file in `Telemetrics client`_ repository.
@@ -228,10 +230,10 @@ system.
To change how records are managed, copy the default
:file:`/usr/share/defaults/telemetrics/telemetrics.conf` file to
:file:`/etc/telemetrics/telemetrics.conf` and edit it. The changes in the
:file:`/etc/telemetrics/telemetrics.conf` and edit it. The changes in the
:file:`/etc/telemetrics/telemetrics.conf` file will override the defaults in
the :file:`/usr/share/defaults/telemetrics/telemetrics.conf` file. You may need
``root`` permissions to create and edit files in :file:`/etc`. For each
root permissions to create and edit files in :file:`/etc`. For each
example, and for any time you make changes to the configuration file, you must
restart the client daemons to pick up the changes:
@@ -249,15 +251,15 @@ Use :command:`-h` or :command:`--help` to view usage options.
#. Keep a local copy and send records to backend server:
To keep a local copy of the telemetry record and also send it on to the
backend server, we will need to change the :guilabel:`
record_retention_enabled` configuration key value to :guilabel:`true`.
backend server, we will need to change the
:guilabel:`record_retention_enabled` configuration key value to
:guilabel:`true`.
#. Keep all records -- don't send to backend server:
To keep records on the system without sending them to a backend server, set
the :guilabel:`record_server_delivery_enabled` key value to
:guilabel:`false`. Note that you will also need to ensure the
:guilabel:`false`. Note that you will also need to ensure the
:guilabel:`record_retention_enabled` configuration key value is set to
:guilabel:`true` or the system will not keep local copies.
@@ -266,9 +268,9 @@ Use :command:`-h` or :command:`--help` to view usage options.
This assumes you have set up a custom server according to the next example.
The server is identified by the :guilabel:`server` setting, and by default
records are sent to the |CL| server :guilabel:`server=https://clr.
telemetry.intel.com/v2/collector`. To change this, you can use an IP
address or fully qualified domain name.
records are sent to the |CL| server
:guilabel:`server=https://clr.telemetry.intel.com/v2/collector`. To change
this, you can use an IP address or fully qualified domain name.
Set up a back-end server to collect telemetry records
@@ -303,13 +305,13 @@ using the :ref:`bare-metal-install-server` getting started guide and:
#. Before you install the telemetrics backend with the :file:`deploy.sh` script
file in the next step, here is an explanation of the options to be specified:
* *-a install* to perform an install
* *-d clr* to install to a |CL| distro
* *-H localhost* to set the domain to localhost
* :command:`-a install` to perform an install
* :command:`-d clr` to install to a |CL| distro
* :command:`-H localhost` to set the domain to localhost
.. caution::
The :file:`deploy.sh` shell script has minimal error checking and makes
several changes to your system. Be sure that the options you define on
several changes to your system. Be sure that the options you define on
the cmdline are correct before proceeding.
#. Run the shell script from the :file:`$HOME/telemetrics-backend/scripts`
@@ -358,26 +360,24 @@ using the :ref:`bare-metal-install-server` getting started guide and:
passwd: password updated successfully
Enter `postgres` for the current value of the password and then enter a new
password, retype it to verify the new password and the
:guilabel:`PostgreSQL` database password will be updated.
password, retype it to verify the new password and the :guilabel:`PostgreSQL`
database password will be updated.
#. After the installation is complete, you can use your web browser to view the
new server by opening the browser on the system and typing in ``localhost``
in the address bar. You should see a web page similar to the one shown in
figure 1:
new server by opening the browser on the system and typing in localhost
in the address bar. You should see a web page similar to the one shown in
Figure 2 below.
.. figure:: figures/telemetry-backend-1.png
:alt: Telemetry UI
Figure 1: :guilabel:`Telemetry UI`
Figure 2: :guilabel:`Telemetry UI`
Create records with telem-record-gen
====================================
The telemetrics bundle provides a record generator tool called
``telem-record-gen``. This tool can be used to create records from shell
`telem-record-gen`. This tool can be used to create records from shell
scripts or the command line when writing a probe in C is not desirable.
Records are sent to the backend server, and can also be echoed to stdout.
@@ -470,7 +470,7 @@ Set a static machine id
The machine id reported by the telemetry client is rotated every three days
for privacy reasons. If you wish to have a static machine id for testing
purposes, you can opt in by creating a file named "opt-in-static-machine-id"
purposes, you can opt in by creating a file named `opt-in-static-machine-id`
in the directory :file:`/etc/telemetrics/`.
#. Create a directory `telemetrics`.
@@ -489,7 +489,7 @@ in the directory :file:`/etc/telemetrics/`.
.. note::
The `machine id` is different than the system hostname.
The machine ID is different than the system hostname.
Instrument your code with the libtelemetry API
==============================================
@@ -499,8 +499,8 @@ Prerequisites
Confirm that the telemetrics header file is located on the system at
:file:`usr/include/telemetry.h` The `latest version`_ of the file can also be
found on github for reference, but installing the `telemetry` bundle will
install the header file that matches your |CL| version.
found on github for reference, but installing the :command:`telemetry` bundle
will install the header file that matches your |CL| version.
#. Includes and variables:
@@ -560,9 +560,8 @@ install the header file that matches your |CL| version.
Type: char pointer
Value: The payload to set
#. For this example, we'll set the payload to “hello” by using ``asprintf()``:
#. For this example, we'll set the payload to “hello” by using
:command:`asprintf()`:
.. code-block:: console
@@ -570,21 +569,19 @@ install the header file that matches your |CL| version.
exit(EXIT_FAILURE);
}
The functions ``asprintf()`` and ``vasprintf()`` are analogs of
``sprintf(3)`` and ``vsprintf(3)``, except that they allocate a string
large enough to hold the output including the terminating null byte ('\0'),
and return a pointer to it via the first argument. This pointer should be
passed to ``free(3)`` to release the allocated storage when it is no longer
needed.
The functions :command:`asprintf()` and :command:`vasprintf()` are analogs of
:command:`sprintf(3)` and :command:`vsprintf(3)`, except that they allocate a
string large enough to hold the output including the terminating null byte
('\0'), and return a pointer to it via the first argument. This pointer
should be passed to :command:`free(3)` to release the allocated storage when
it is no longer needed.
#. Create the new telemetry record:
The function ``tm_create_record()`` initializes a telemetry record and
The function :command:`tm_create_record()` initializes a telemetry record and
sets the severity and classification of that record, as well as the payload
version number. The memory needed to store the telemetry record is allocated
and should be freed with ``tm_free_record()`` when no longer needed.
and should be freed with :command:`tm_free_record()` when no longer needed.
.. code-block:: console
@@ -596,7 +593,7 @@ install the header file that matches your |CL| version.
#. Set the payload field of a telemetrics record:
The function ``tm_set_payload()`` attaches the provided telemetry record
The function :command:`tm_set_payload()` attaches the provided telemetry record
data to the telemetry record. The current maximum payload size is 8192b.
.. code-block:: console
@@ -608,17 +605,17 @@ install the header file that matches your |CL| version.
}
free(payload);
The ``free()`` function frees the memory space pointed to by ptr, which
must have been returned by a previous call to ``malloc()``, ``calloc()``,
or ``realloc()``. Otherwise, or if ``free(ptr)`` has already been called
before, undefined behavior occurs. If ptr is NULL, no operation is
performed.
The :command:`free()` function frees the memory space pointed to by `ptr`, which
must have been returned by a previous call to :command:`malloc()`,
:command:`calloc()`, or :command:`realloc()`. Otherwise, or if
:command:`free(ptr)` has already been called before, undefined behavior
occurs. If `ptr` is NULL, no operation is performed.
#. Send a record to the telemetrics daemon:
The function ``tm_send_record()`` delivers the record to the local
``telemprobd(1)`` service. Since the telemetry record was allocated by
the program it should be freed with ``tm_free_record()`` when it is no
The function :command:`tm_send_record()` delivers the record to the local
:command:`telemprobd(1)` service. Since the telemetry record was allocated by
the program it should be freed with :command:`tm_free_record()` when it is no
longer needed.
.. code-block:: console
@@ -640,7 +637,7 @@ install the header file that matches your |CL| version.
#. A full sample application with compiling flags:
Create a new file test.c and add the following code:
Create a new file :file:`test.c` and add the following code:
.. code-block:: console
@@ -724,7 +721,7 @@ Reference
The telemetry API
=================
Installing the ``telemetrics`` bundle includes the libtelemetry C library,
Installing the :command:`telemetrics` bundle includes the libtelemetry C library,
which exposes an API used by the telemprobd and telempostd daemons. You can
use these in your applications as well. The API documentation is found in the
:file:`telemetry.h` file in `Telemetrics client`_ repository.
@@ -744,54 +741,63 @@ Configuration options
The client uses the following configuration options from the config file:
* **server**: This specifies the web server to which telempostd sends the
telemetry records.
* **socket_path**: This specifies the path of the unix domain socket on which
the telemprobd listens for connections from the probes.
* **spool_dir**: This configuration option is related to spooling. If the
daemon is not able to send the telemetry records to the backend server due
to reasons such as the network availability, then it stores the records in
a spool directory. This option specifies the path of the spool directory.
This directory should be owned by the same user as the daemon.
* **record_expiry**: This is the time, in minutes, after which the records in
the spool directory are deleted by the daemon.
* **spool_process_time**: This specifies the time interval, in seconds, that
the daemon waits for before checking the spool directory for records. The
daemon picks up the records in the order of modification date and tries to
send the record to the server. It sends a maximum of 10 records at a time.
If it was able to send a record successfully, it deletes the record from the
spool. If the daemon finds a record older than the "record_expiry" time, then
it deletes that record. The daemon looks at a maximum of 20 records in a
single spool run loop.
* **rate_limit_enabled**: This determines whether rate-limiting is enabled
or disabled. When enabled, there is a threshold on both records sent within
a window of time, and record bytes sent within a window a time.
* **record_burst_limit**: This is the maximum amount of records allowed to be
passed by the daemon within the record_window_length of time. If set to -1,
the rate-limiting for record bursts is disabled.
* **record_window_length**: The time, in minutes (0-59), that establishes the
window length for the record_burst_limit. For example, if
record_burst_window=1000 and record_window_length=15, then no more than
1000 records can be passed within any given fifteen-minute window.
* **byte_burst_limit**: This is the maximum amount of bytes that can be
passed by the daemon within the byte_window_length of time. If set to -1,
the rate-limiting for byte bursts is disabled.
* **byte_window_length**: This is the time, in minutes (0-59), that establishes
the window length for the byte_burst_limit.
* **rate_limit_strategy**: This is the strategy chosen once the rate-limiting
threshold has been reached. Currently the options are 'drop' or 'spool',
with spool being the default. If spool is chosen, records will be spooled
and sent at a later time.
* **record_retention_enabled**: When this key is enabled (true) the daemon
saves a copy of the payload on disk from all valid records. To avoid the
excessive use of disk space only the latest 100 records are kept. The default
value for this configuration key is false.
* **record_server_delivery_enabled**: This key controls the delivery of
records to server; when enabled (default value), the record will be posted to
the address in the configuration file. If this configuration key is disabled
(false), records will not be spooled or posted to backend. This configuration
key can be used in combination with record_retention_enabled to keep copies
of telemetry records locally only.
server
This specifies the web server to which telempostd sends the telemetry records.
socket_path
This specifies the path of the unix domain socket on which the telemprobd
listens for connections from the probes.
spool_dir
This configuration option is related to spooling. If the daemon is not able
to send the telemetry records to the backend server due to reasons such as
the network availability, then it stores the records in a spool directory.
This option specifies the path of the spool directory. This directory should
be owned by the same user as the daemon.
record_expiry
This is the time, in minutes, after which the records in the spool directory
are deleted by the daemon.
spool_process_time
This specifies the time interval, in seconds, that the daemon waits for
before checking the spool directory for records. The daemon picks up the
records in the order of modification date and tries to send the record to the
server. It sends a maximum of 10 records at a time. If it was able to send a
record successfully, it deletes the record from the spool. If the daemon
finds a record older than the "record_expiry" time, then it deletes that
record. The daemon looks at a maximum of 20 records in a single spool run loop.
rate_limit_enabled
This determines whether rate-limiting is enabled or disabled. When enabled,
there is a threshold on both records sent within a window of time, and record
bytes sent within a window a time.
record_burst_limit
This is the maximum amount of records allowed to be passed by the daemon
within the record_window_length of time. If set to -1, the rate-limiting for
record bursts is disabled.
record_window_length
The time, in minutes (0-59), that establishes the window length for the
record_burst_limit. For example, if record_burst_window=1000 and
record_window_length=15, then no more than 1000 records can be passed within
any given fifteen-minute window.
byte_burst_limit
This is the maximum amount of bytes that can be passed by the daemon within
the byte_window_length of time. If set to -1, the rate-limiting for byte
bursts is disabled.
byte_window_length
This is the time, in minutes (0-59), that establishes the window length for
the byte_burst_limit.
rate_limit_strategy
This is the strategy chosen once the rate-limiting threshold has been
reached. Currently the options are 'drop' or 'spool', with spool being the
default. If spool is chosen, records will be spooled and sent at a later time.
record_retention_enabled
When this key is enabled (true) the daemon saves a copy of the payload on
disk from all valid records. To avoid the excessive use of disk space only
the latest 100 records are kept. The default value for this configuration key
is false.
record_server_delivery_enabled
This key controls the delivery of records to server; when enabled (default
value), the record will be posted to the address in the configuration file.
If this configuration key is disabled (false), records will not be spooled or
posted to backend. This configuration key can be used in combination with
record_retention_enabled to keep copies of telemetry records locally only.
.. note::
@@ -827,18 +833,18 @@ start/stop/restart
------------------
The commands to start, stop and restart the telemetry services manage all
required services and probes on the system. There is no need to separately
start/stop/restart the two client daemons **telemprobd** and **telempostd**.
The **restart** command option will call **telemctl stop** followed
by **telemctl start** .
required services and probes on the system. There is no need to separately
start/stop/restart the two client daemons telemprobd and telempostd.
The :command:`restart` command option will call :command:`telemctl stop`
followed by :command:`telemctl start` .
is-active
---------
The `is-active` option reports whether the two client daemons are active. This
is useful to verify that the **opt-in** and **opt-out** options have taken
effect, or to ensure that telemetry is functioning on the system. Note that
both daemons are verified.
The :command:`is-active` option reports whether the two client daemons are
active. This is useful to verify that the :command:`opt-in` and
:command:`opt-out` options have taken effect, or to ensure that telemetry is
functioning on the system. Note that both daemons are verified.
.. code-block:: bash
@@ -850,7 +856,6 @@ both daemons are verified.
telempostd : active
.. _Telemetrics client: https://github.com/clearlinux/telemetrics-client/
.. _latest version: https://github.com/clearlinux/telemetrics-client/tree/master/src
.. _heartbeat probe: https://github.com/clearlinux/telemetrics-client/tree/master/src/probes/hello.c
+2 -1
View File
@@ -27,4 +27,5 @@ Clear Linux concepts
:glob:
../concepts/*
../tooling/stateless
../tooling/security

Before

Width:  |  Height:  |  Size: 94 KiB

After

Width:  |  Height:  |  Size: 94 KiB

Before

Width:  |  Height:  |  Size: 88 KiB

After

Width:  |  Height:  |  Size: 88 KiB

@@ -1,45 +1,36 @@
.. _security:
OS Security
*************************
###########
|CL-ATTR| aims to make systemic and layered security-conscious decisions
that are both performant and practical. This security philosophy is rooted
within the project's codebase and operating culture.
.. contents:: :local:
:depth: 1
Security in updates
*******************
The |CL| team believes in the benefits of software security through open
sourcing, incremental updates, and rapidly resolving known security advisories.
Security in Updates
===================
The |CL| team believes in the benefits of
software security through open sourcing, incremental updates, and
rapidly resolving known security advisories.
The latest Linux* codebase
--------------------------
The latest Linux\* codebase
===========================
|CL| uses the newest version of the Linux kernel which allows the operating
system to leverage the latest features from the upstream Linux kernel,
including security fixes.
Automated Effective Updating
----------------------------
Automated effective updating
============================
|CL| is incrementally updated multiple times per day.
This `rolling release model`_ allows |CL| to consume the latest security
fixes of software packages as soon as they become available.
There is no waiting for major or minor releases on |CL|.
This `rolling release`_ model allows |CL| to consume the latest security fixes
of software packages as soon as they become available. There is no waiting for
major or minor releases on |CL|.
An update is not effective if it is just simply downloaded onto a system.
It needs to be obtained *AND* ensured that the new patched copy is being
@@ -47,47 +38,34 @@ used; not an older copy loaded into memory. |CL| will let you know when a
service needs to be rebooted or do it for your automatically after
a software update, if desired.
In |CL| updates are delivered automatically, efficiently, and effectively. For
more information about software updates in |CL|, refer to the :ref:`swupd-guide`
guide.
In |CL| updates are delivered automatically, efficiently,
and effectively. For more information see
`documentation about Software Updates`_ in |CL|.
Automated CVE Scanning and Remediation
--------------------------------------
Automated CVE scanning and remediation
======================================
The sheer number of software packages and security vulnerabilities is growing
exponentially. Repositories of Common Vulnerabilities and Exposures (CVEs)
and their fixes, if known, are published by :abbr:`NIST` in a
National Vulnerability Database \ |NVD|\ and at \ |MITRE|\ .
|CL| employs a proactive and measured approach to addressing known
and fixable :abbr:`CVEs (Common Vulnerabilities and Exposures)`.
Packages are automatically scanned against
:abbr:`CVEs (Common Vulnerabilities and Exposures)` daily, and security
Packages are automatically scanned against CVEs daily, and security
patches are deployed as soon as they are available.
These combined practices minimize the amount of
time |CL| systems are exposed to unnecessary security risk.
Security in Software
====================
These combined practices minimize the amount of time |CL| systems are exposed to unnecessary security risk.
Security in software
*********************
Minimized attack surface
-------------------------
========================
|CL| removes legacy, unneeded, or redundant standards and
components as much as possible to enable the use of best known security
standards. Below are some examples:
|CL| removes legacy, unneeded, or redundant standards and components as much as
possible to enable the use of best known security standards. Below are some
examples:
* `RC4`, `SSLv3`, `3DES`, and `SHA-1` ciphers which have had known
vulnerabilities, have been explicitly disabled within many |CL| packages to
@@ -96,12 +74,10 @@ standards. Below are some examples:
* Services and subsystems which expose sensitive system information
have been removed such as the `finger` and `tcpwrappers`.
* `SFTP` has been disabled by default due to security
considerations.
* `SFTP` has been disabled by default due to security considerations.
Verified trust
--------------
==============
|CL| encourages the use of secure practices such as encryption
and digital signature verification throughout the system and discourages blind
@@ -109,29 +85,23 @@ trust. Below are some examples:
* All update operations from swupd are transparently encrypted and checked
against the |CL| maintainers' public key for authenticity.
More information can be found in this blog post:
`blog post about swupd security`_
More information about swupd security can be found in the
`Security for software update in Clear Linux* OS`_ blog post.
* Before being built, packages available from |CL| verify checksums and
signatures provided by third party project codebases and maintainers.
* |CL| features a unified certificate store, `clrtrust`_ which comes
ready to work with well-known Certificate Authorities out of the box.
`clrtrust`_ also offers an easy to use command line interface for managing
clrtrust also offers an easy to use command line interface for managing
system-wide chains of trust, instead of ignoring foreign certificates.
Compiled with secure options
----------------------------
While |CL| packages are optimized for performance on
Intel® architecture, security conscious kernel and compiler options are
sensibly taken advantage of. Below are some examples:
============================
While |CL| packages are optimized for performance on Intel® architecture,
security conscious kernel and compiler options are sensibly taken advantage of.
Below are some examples:
* Kernels shipped with |CL| are signed and disallow the usage of
custom kernel modules to maintain verifiable system integrity.
@@ -139,23 +109,19 @@ sensibly taken advantage of. Below are some examples:
* `Address space layout randomization (ASLR)`_ and
`Kernel address space layout randomization (KASLR)`_ are kernel features
which defend against certain memory based attacks.
More information can be found in a `blog post about PIE executables`_ .
More information about PIE executables can be found in the
`Recent GNU* C library improvements`_ blog post.
Security in system design
*************************
Simple, yet effective, techniques are used throughout the |CL| system design to
defend against common attack vectors and enable good security hygiene. Below are
some examples:
Security in System Design
=========================
Simple, yet effective, techniques are used throughout the
|CL| system design to defend against common attack vectors and enable
good security hygiene. Below are some examples:
* Full disk encryption using `Linux Unified Key Setup`_ (LUKS) is available
during installation.
* Full disk encryption using :abbr:`LUKS (Linux Unified Key Setup)` is available
during installation. Refer to `cryptsetup`_ for additional information about
LUKS.
* |CL| uses the PAM cracklib module to harden user login and password
security resulting in:
@@ -172,22 +138,13 @@ good security hygiene. Below are some examples:
* `Tallow`_, a lightweight service which monitors and blocks suspicious SSH
login patterns, is installed with the :command:`openssh-server` bundle.
.. _`documentation about Software Updates`: https://clearlinux.org/documentation/clear-linux/concepts/swupd-about
.. _`cve-check-tool`: https://github.com/clearlinux/cve-check-tool
.. _`blog post about swupd security`: https://clearlinux.org/blogs/security-software-update-clear-linux-os-intel-architecture
.. _`rolling release model`: https://en.wikipedia.org/wiki/Rolling_release
.. _`Security for software update in Clear Linux* OS`: https://clearlinux.org/blogs/security-software-update-clear-linux-os-intel-architecture
.. _`Recent GNU* C library improvements`: https://clearlinux.org/blogs/recent-gnu-c-library-improvements
.. _`rolling release`: https://en.wikipedia.org/wiki/Rolling_release
.. _`clrtrust`: https://github.com/clearlinux/clrtrust
.. _`Address space layout randomization (ASLR)`: https://en.wikipedia.org/wiki/Address_space_layout_randomization
.. _`Kernel address space layout randomization (KASLR)`: https://lwn.net/Articles/569635/
.. _`dm-verity`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/device-mapper/verity.txt
.. _`SELinux`: https://github.com/SELinuxProject
.. _`Linux Unified Key Setup`: https://gitlab.com/cryptsetup/cryptsetup/
.. _`blog post about PIE executables`: https://clearlinux.org/blogs/recent-gnu-c-library-improvements
.. _`cryptsetup`: https://gitlab.com/cryptsetup/cryptsetup/
.. _`Tallow`: https://github.com/clearlinux/tallow
.. |NVD| raw:: html
@@ -3,24 +3,23 @@
Stateless
#########
In most operating systems, files can become intermingled with user and system
data and configurations.
In most operating systems, user data, system data, and configuration files
can become intermingled.
.. figure:: figures/stateless-1.png
:scale: 45%
:scale: 45%
:align: center
:alt: Stateless: User and system files mixed
Figure 1: Without stateless, user and system files become mixed on the filesystem over time.
|CL-ATTR| has a stateless design philosophy of which the goal is to provide an
|CL-ATTR| has a stateless design philosophy with the goal to provide an
:abbr:`OS (operating system)` that functions without excessive user
configuration or customization. Stateless in this context does *not* mean
ephemeral or non-persistent.
.. contents:: :local:
:depth: 2
:depth: 1
File-level separation
*********************
@@ -29,7 +28,7 @@ To accomplish a stateless design the Linux Filesystem Hierarchy is separated
between user-owned areas and |CL|-owned areas.
.. figure:: figures/stateless-2.png
:scale: 45%
:scale: 45%
:align: center
:alt: Stateless: User and system files separation
@@ -48,10 +47,10 @@ Files under the :file:`/etc/`, :file:`/home`, and :file:`/var` directories are
owned and managed by the user. A freshly installed |CL| system will only have
a minimal set of files in the :file:`/etc/` directory and software installed
by |CL| does not write to :file:`/etc`. This operating assumption allows |CL|
users to clearly identify the configuration that makes their system unique.
users to clearly identify the configuration that makes their system unique.
Software Configuration
Software configuration
**********************
With stateless separation, default software configurations are read in order
@@ -62,12 +61,12 @@ Default configurations
======================
Software in |CL| provides default configuration values so that it is
immediately functional, whenever it is appropriate to do so.
immediately functional, whenever it is appropriate to do so.
|CL| distributed software packages may be directly modified to include default
configuration values or default configuration files may be provided by |CL|
under :file:`/usr/share/defaults`. These files can be referenced as templates
for customization.
for customization.
For example, the default configuration that Apache uses when installed can be
found at :file:`/usr/share/defaults/httpd/httpd.conf` directory.
@@ -81,39 +80,37 @@ modified by the user under :file:`/etc/`. If the configuration file does not
already exist, it can be created in the appropriate location.
User defined configuration files should contain the minimal set of desired
changes and rely on default configuration for the rest.
changes and rely on default configuration for the rest.
For example, a customized Apache configuration can be used instead by:
#. Create the destination directory for the configuration:
.. code :: bash
.. code-block:: bash
sudo mkdir /etc/httpd
#. Copy the default configuration as a reference template:
.. code :: bash
.. code-block:: bash
sudo cp /usr/share/defaults/httpd/httpd.conf /etc/httpd/
#. Make any desired modifications to the configurations:
.. code :: bash
.. code-block:: bash
sudoedit /etc/httpd/httpd.conf
#. Reload the service or reboot the system to pickup any changes:
.. code :: bash
.. code-block:: bash
systemctl daemon-reload httpd && systemctl restart httpd
This pattern can be used to modify the configurations of other programs too.
The `stateless man page`_ has application-specific examples.
System reset
************
@@ -124,22 +121,19 @@ easily restored by simply deleting everything under :file:`/etc/` and
Running the commands below effectively performs a system reset as if it was
just installed:
.. code::
.. code-block:: bash
sudo rm -rf /etc
sudo rm -rf /var
In other Linux distributions, this can be a catastrophic action that renders a
system unable to boot.
In other Linux distributions, this can be a catastrophic action that renders
a system unable to boot.
Additional information
**********************
* `stateless man page`_
* `Where is /etc/fstab in Clear Linux? <https://clearlinux.org/news-blogs/where-etcfstab-clear-linux>`_
.. _`stateless man page`: https://github.com/clearlinux/clr-man-pages/blob/master/stateless.7.rst
-3
View File
@@ -22,10 +22,7 @@ Explore our tutorials to discover what you can do with |CL|!
kata
kata_migration
kubernetes/kubernetes*
greengrass
dlrs/dlrs
yubikey-u2f
nvidia
dars
redis
tutorial-proxy