Merge branch 'master' of github.com:clearlinux/clear-linux-documentation into rtd-theme
Signed-off-by: Kevin Putnam <kevin.putnam@intel.com>
@@ -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
|
||||
|
||||
|
Before Width: | Height: | Size: 85 KiB After Width: | Height: | Size: 24 KiB |
|
Before Width: | Height: | Size: 91 KiB After Width: | Height: | Size: 14 KiB |
|
Before Width: | Height: | Size: 46 KiB After Width: | Height: | Size: 7.9 KiB |
|
Before Width: | Height: | Size: 37 KiB After Width: | Height: | Size: 7.4 KiB |
|
Before Width: | Height: | Size: 87 KiB After Width: | Height: | Size: 13 KiB |
|
Before Width: | Height: | Size: 81 KiB After Width: | Height: | Size: 14 KiB |
|
Before Width: | Height: | Size: 69 KiB After Width: | Height: | Size: 25 KiB |
|
Before Width: | Height: | Size: 47 KiB After Width: | Height: | Size: 19 KiB |
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 31 KiB |
|
Before Width: | Height: | Size: 97 KiB After Width: | Height: | Size: 14 KiB |
|
Before Width: | Height: | Size: 57 KiB After Width: | Height: | Size: 24 KiB |
|
Before Width: | Height: | Size: 67 KiB |
|
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`_ .
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -28,12 +28,21 @@ Network
|
||||
|
||||
network/*
|
||||
|
||||
|
||||
Kernel
|
||||
======
|
||||
=======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
kernel/*
|
||||
kernel/*
|
||||
|
||||
Stacks
|
||||
=======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
stacks/*
|
||||
stacks/dlrs/*
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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|.
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||