diff --git a/source/clear-linux/clear-linux.rst b/source/clear-linux/clear-linux.rst index bc5cd177..74496d0d 100644 --- a/source/clear-linux/clear-linux.rst +++ b/source/clear-linux/clear-linux.rst @@ -3,33 +3,33 @@ |CL-PRJ| ############################################# -Welcome to the |CLOSIA| documentation pages, the source for |CL| documentation. +Welcome to the |CL-ATTR| documentation pages, the source for |CL| documentation. Our documentation is divided into the following sections: * :ref:`get-started` - If you are new to |CL|, get started fast with tutorials for installing |CL| on - bare metal, in a virtual environment, or as a live image on a USB stick. + If you are new to |CL|, get started fast with tutorials for installing |CL| on + bare metal, in a virtual environment, or as a live image on a USB stick. -* :ref:`concepts` - - Wondering what makes |CL| different? Learn about |CL| features and what +* :ref:`concepts` + + Wondering what makes |CL| different? Learn about |CL| features and what differentiates |CL| from other Linux distros. -* :ref:`guides` +* :ref:`guides` - Guides show how to complete common tasks that help you leverage |CL| native - features effectively. From basic system configuration to advanced management + Guides show how to complete common tasks that help you leverage |CL| native + features effectively. From basic system configuration to advanced management of a cloud installation, there is a guide for you. -* :ref:`tutorials` +* :ref:`tutorials` - |CL| tutorials provide step-by-step instructions on how |CL| features can - be used and extended, frequently with third-party tools. + |CL| tutorials provide step-by-step instructions on how |CL| features can + be used and extended, frequently with third-party tools. -* :ref:`reference` - - Find the detailed information you need to enable your configuration or task +* :ref:`reference` + + Find the detailed information you need to enable your configuration or task in our |CL| reference section. .. toctree:: diff --git a/source/clear-linux/concepts/figures/mixer-about-1.png b/source/clear-linux/concepts/figures/mixer-about-1.png new file mode 100644 index 00000000..8120a068 Binary files /dev/null and b/source/clear-linux/concepts/figures/mixer-about-1.png differ diff --git a/source/clear-linux/concepts/figures/mixer-about-2.png b/source/clear-linux/concepts/figures/mixer-about-2.png new file mode 100644 index 00000000..83f03375 Binary files /dev/null and b/source/clear-linux/concepts/figures/mixer-about-2.png differ diff --git a/source/clear-linux/concepts/mixer-about.rst b/source/clear-linux/concepts/mixer-about.rst index 7515a995..485ea846 100644 --- a/source/clear-linux/concepts/mixer-about.rst +++ b/source/clear-linux/concepts/mixer-about.rst @@ -1,14 +1,82 @@ .. _mixer-about: Mixer -####### +##### -Mixing refers to composing a custom, versioned image of |CLOSIA| for a specific use case. While upstream |CL| provides options to install bundles for various capabilities, some developers and OSVs may wish to either augment the operating system with functionality from their own packages or modify the structure of current bundles. Mixing offers a method to add capabilities while retaining the ability to stay up to date with an upstream version of |CL|. +|CL-ATTR| is a powerful, modular, and customizable OS. Upstream |CL| offers +many images to support different environments and use-cases. There are +hundreds of bundles that will meet most, if not all, of your OS and software +needs. -Mixing is a multi-step process that starts with installing the mixer bundle using swupd. You will also need a working knowledge of :abbr:`RPMs (RPM Package Manager files)` and how |CL| bundles work. For a detailed guide on how to create a |CL| mix, visit :ref:`mixer`. +However, if you need additional customization or content, |CL| provides the +mixer tool. Depending on your needs, the mixer tool allows you to: -Related Concepts -================ +1. :ref:`create-mix` to create a distinct derivative of the |CL| that + contains your custom software. +2. :ref:`create-mixin` to add custom bundles but also keep updating the OS + from upstream. -* :ref:`swupd-about` +.. _create-mix: + +Create a mix +============ + +When creating a mix, you can + +* Use any existing upstream bundles with no modification. +* Redefine what goes into existing bundles. +* Create completely new, custom bundles with your own custom packages. + +With mixer you are not required to incorporate every upstream release into +your mix. You decide which upstream versions to update your derivative to, as +illustrated in Figure 1. + +.. figure:: figures/mixer-about-1.png + :scale: 75% + :alt: Creating a custom mix. + + Figure 1: With a custom mix, you add your custom bundle and decide which + upstream versions to update your mix to, on your own release cycle. + +Creating your own mix forks away from the |CL| upstream and requires that you +act as your own OSV. There is a greater level of responsibility, requiring +more infrastructure and processes to adopt. However, with this approach, you +have a higher degree of control and customization of your custom |CL|. + + +.. _create-mixin: + +Create a mixin +============== + +The second option is to use the :command:`mixin` tool, a light wrapper for +mixer, to create custom bundles and sideload them into your upstream version +of |CL|. A mixin is useful when you need to add custom or 3rd +party content but want to keep on the upstream update cycle, as shown in +Figure 2. You can also create new bundles using upstream packages. + +.. figure:: figures/mixer-about-2.png + :scale: 75% + :alt: Creating a custom mix. + + Figure 2: With a mixin you can add custom bundles, but stay on upstream. + +Mixin is primarily intended for end users. It is easier to adopt as it does +not require breaking from upstream or acting as an OSV. With mixin + +* You are responsible for maintaining and testing your custom bundle(s). +* You retain access to all upstream bundles and updates. +* You can easily revert your system back to the upstream version. + +Related topics +============== + +|CL| provides flexibility in how you customize your OS. Learn more about +mixer and related topics to decide which customization approach is best for +you. + +* :ref:`mixer` +* :ref:`mixin` * :ref:`bundles-about` +* :ref:`swupd-about` +* :ref:`deploy-at-scale` diff --git a/source/clear-linux/concepts/security.rst b/source/clear-linux/concepts/security.rst index 27ec5235..ee744db8 100644 --- a/source/clear-linux/concepts/security.rst +++ b/source/clear-linux/concepts/security.rst @@ -97,7 +97,7 @@ standards. Below are some examples: have been removed such as the `finger` and `tcpwrappers`. * `SFTP` has been disabled by default due to security - considerations. See the `openssh-server reference page`_ for more details. + considerations. Verified trust @@ -182,7 +182,6 @@ good security hygiene. Below are some examples: .. _`documentation about Software Updates`: https://clearlinux.org/documentation/clear-linux/concepts/swupd-about .. _`cve-check-tool`: https://github.com/clearlinux/cve-check-tool -.. _`openssh-server reference page`: https://clearlinux.org/documentation/clear-linux/reference/bundles/openssh-server .. _`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 .. _`clrtrust`: https://github.com/clearlinux/clrtrust diff --git a/source/clear-linux/concepts/swupd-about.rst b/source/clear-linux/concepts/swupd-about.rst index f132c229..ef1d9ee0 100644 --- a/source/clear-linux/concepts/swupd-about.rst +++ b/source/clear-linux/concepts/swupd-about.rst @@ -3,35 +3,35 @@ Software update ############### -|CLOSIA| does software updates differently than traditional Linux-based -operating systems. Where traditional distributions rely on packages for -software deployment, |CL| uses the concept of a "bundle" for -deployment. Traditional Linux packages provide a particular utility or -library; |CL| bundles provide all necessary packages to enable a +|CL-ATTR| does software updates differently than traditional Linux-based +operating systems. Where traditional distributions rely on packages for +software deployment, |CL| uses the concept of a "bundle" for +deployment. Traditional Linux packages provide a particular utility or +library; |CL| bundles provide all necessary packages to enable a specific function. -With |CL|, updating equates to an entirely new OS version with a -specific set of bundles, as compared to a package-based distribution in -which packages may be updated individually. |CL| updates are +With |CL|, updating equates to an entirely new OS version with a +specific set of bundles, as compared to a package-based distribution in +which packages may be updated individually. |CL| updates are efficient, updating only changed files instead of entire packages. -System administrators can customize or add bundles to the OS, while still -taking advantage of a controlled update stream. This enables system +System administrators can customize or add bundles to the OS, while still +taking advantage of a controlled update stream. This enables system administrators to focus on the pieces that make their deployment unique. Bundles ======= -While we use packages to manage compiling source code into installable -binaries, we do not deploy software through packages. Instead, we use bundles -to deploy software, where each bundle encapsulates a particular functionality --- functionality that is enabled by composing all the required upstream -open-source projects and packages into one logical unit: a bundle. This +While we use packages to manage compiling source code into installable +binaries, we do not deploy software through packages. Instead, we use bundles +to deploy software, where each bundle encapsulates a particular functionality +-- functionality that is enabled by composing all the required upstream +open-source projects and packages into one logical unit: a bundle. This simplifies installing features on |CL|. -For additional resources regarding available bundles, useful bundle commands, -and compatible |CL| kernels, visit our :ref:`bundles-about` +For additional resources regarding available bundles, useful bundle commands, +and compatible |CL| kernels, visit our :ref:`bundles-about` page. @@ -65,8 +65,8 @@ describe the versions of all the software on the OS. Each build is composed of a specific set of bundles made from a particular version of packages. This matters on a daily basis to system administrators, who need to determine which of their systems do not have the latest security -fixes, or which combinations of software have been tested. Every release -of the same number is guaranteed to contain the same versions of software, +fixes, or which combinations of software have been tested. Every release +of the same number is guaranteed to contain the same versions of software, so there's no ambiguity between two systems running the same version of |CL|. @@ -76,20 +76,20 @@ Updating Another notable difference between package-based distributions and |CL| is how updates are managed. On a package-based OS, system administrators update each individual package or piece of software to a newer (or older!) version. With -|CL|, an update translates to an entirely new OS version, containing one -or many updates. It is not possible to update a piece of the system while +|CL|, an update translates to an entirely new OS version, containing one +or many updates. It is not possible to update a piece of the system while remaining on the same version of |CL|. How is this useful? Although it seems, at first, like a huge restriction or limitation, this method has many non-obvious benefits. Imagine a cloud environment composed of numerous machines. Here, a homogeneous set of software makes sense -- from the system administrator's level down to the -user level. Homogeneous systems allow users to focus on their contributions -and/or code, rather than configuring environments or worrying about -synchronizing versions and updates. At the system admin level, it ensures +user level. Homogeneous systems allow users to focus on their contributions +and/or code, rather than configuring environments or worrying about +synchronizing versions and updates. At the system admin level, it ensures security is tighter and makes it far easier to monitor and update patches. -|CL| promotes regular updating of the OS and will automatically check +|CL| promotes regular updating of the OS and will automatically check for updates and apply them by default. To learn how to run an update of your system, visit our :ref:`swupd-guide` page. @@ -98,9 +98,9 @@ To learn how to run an update of your system, visit our :ref:`swupd-guide` page. Update speed ============ -Software updates with |CL| are also efficient. Bundles simply describe -a set of files, and the update technology updates *only* files that actually -changed by using binary-delta technology for efficiency [1]_. Operating systems +Software updates with |CL| are also efficient. Bundles simply describe +a set of files, and the update technology updates *only* files that actually +changed by using binary-delta technology for efficiency [1]_. Operating systems that use packages as the unit of deployment require full package updates (thus hogging resources), even when one small file in that package has changed. @@ -128,5 +128,5 @@ a controlled update stream. To learn more about mixing, visit our :ref:`mixer-about` page. -.. [1] The software update technology for |CLOSIA| was first presented at the +.. [1] The software update technology for |CL-ATTR| was first presented at the Linux Plumbers conference in 2012. diff --git a/source/clear-linux/get-started/bare-metal-install-beta/bare-metal-install-beta.rst b/source/clear-linux/get-started/bare-metal-install-beta/bare-metal-install-beta.rst new file mode 100644 index 00000000..07cce2a5 --- /dev/null +++ b/source/clear-linux/get-started/bare-metal-install-beta/bare-metal-install-beta.rst @@ -0,0 +1,808 @@ +.. _bare-metal-install-beta: + +Install |CL-ATTR| from the live desktop beta image +################################################## + +The live desktop beta image allows you to boot |CL-ATTR| into a GNOME +desktop without modifying the host system. Using the live image, you can +explore the possibilities of developing with |CL|. You can also launch the +new installer and install |CL| on your target system. + +.. contents:: :local: + :depth: 1 + +System requirements +******************* + +Assure that your target system supports the installation: + +* :ref:`system-requirements` +* :ref:`compatibility-check` + +Preliminary steps +***************** + +#. `Navigate to the image directory`_. + +#. Download the file :file:`clear--live-desktop-beta.img.xz` + + .. note:: + + ```` is the latest |CL| auto-numbered release. + +#. Follow your OS instructions to create a bootable USB drive. + + * :ref:`bootable-usb-linux-all` + * :ref:`bootable-usb-mac-all` + * :ref:`bootable-usb-windows-all` + +.. _install-from-live-image: + +Install from live image +*********************** + +After you've downloaded and burned the live desktop image on a +USB drive, follow these steps. + +#. Insert the USB drive into an available USB slot. + +#. Power on the system. + +#. Open the system BIOS setup menu by pressing the F2 key. + + .. note:: + + Your BIOS setup menu entry point may vary. + +#. In the setup menu, enable the UEFI boot and set the USB drive as the + first option in the device boot order. + +#. Save these settings and exit. + +#. Reboot the target system. + +Launch the installer +==================== + +#. After the |CL| live desktop image boots, select the :guilabel:`Activities` menu in the upper left. + +#. Select the icon, :guilabel:`Install Clear Linux OS`, shown in Figure 1. + + .. figure:: figures/bare-metal-install-beta-1.png + :scale: 50 % + :alt: Install Clear Linux OS icon + + Figure 1: Install Clear Linux OS icon + +#. Upon selecting the icon, the installer is launched, as shown in Figure 2. + + .. figure:: figures/bare-metal-install-beta-2.png + :scale: 50 % + :alt: Clear Linux OS Installer + + Figure 2: Clear Linux OS Installer + +.. _minimum-installation-requirements: + +Minimum installation requirements +********************************* + +To fulfill minimum installation requirements, complete the +:guilabel:`Required options`. :guilabel:`Advanced options` are optional. Additional user help is described below. + +.. note:: + + * The :kbd:`Install` button is only highlighted **after** you complete the + :ref:`required-options-installation`, and after you enter all required + values in submenus of :ref:`required-options-installation` and + :ref:`advanced-options-installation`. + + * You must choose whether or not to participate in :ref:`telemetrics` + before you can finish installation. + + * You may wish to :ref:`test-network-settings` before you + :ref:`configure-network-interfaces`. Assure that a ``Success`` message is received before installation. + +Main Menu +********* + +In the |CL| Installer Main Menu, two tabs appear: +:guilabel:`[R] Required options` and :guilabel:`[A] Advanced options`. +Navigate between tabs using the arrow keys or these shortcut keys: + +* :kbd:`Shift+A` for :guilabel:`[A] Advanced options` +* :kbd:`Shift+R` for :guilabel:`[R] Required options` + +To meet the minimum requirements, enter your choices in the +:guilabel:`Required options`. After confirmation, your selections appear +below menu options in the Main Menu, beside the :guilabel:`>>` chevron. + +Navigation +********** + +* Select :kbd:`Tab` or :kbd:`Up/Down` arrows to highlight your choice. + +* Select :kbd:`Enter` or :kbd:`Spacebar` to confirm your choice. + +* Select :kbd:`Cancel` or :kbd:`Esc` to cancel your choice. + + The |CL| Installer Main Menu appears as shown in Figure 3. + + .. figure:: figures/bare-metal-install-beta-3.png + :scale: 100 % + :alt: Clear Linux OS Installer Main Menu + + Figure 3: :guilabel:`Clear Linux OS Installer Main Menu` + +.. _required-options-installation: + +Required options +**************** + +Choose Timezone +=============== + +#. From the Main Menu, select :guilabel:`Choose Timezone`. + +#. Select :kbd:`Enter` to continue. + +#. In :guilabel:`Select System Timezone`, navigate to + the desired timezone. + +#. Use :kbd:`Tab` to navigate to :guilabel:`Confirm`. + +#. Select :kbd:`Enter` to :kbd:`Confirm`. + + .. note:: + + Select :guilabel:`Cancel` to restore the previously defined value and + return to the Main Menu. + + .. figure:: figures/bare-metal-install-beta-4.png + :scale: 100 % + :alt: Select System Timezone + + Figure 4: :guilabel:`Select System Timezone` + +Choose Language +=============== + +#. From the Main Menu, select :guilabel:`Choose Language`. + +#. Select :kbd:`Enter`. + +#. In :guilabel:`Select System Language`, navigate to your desired language. + +#. Select :kbd:`Tab` to highlight :kbd:`Confirm`. + +#. Select :kbd:`Enter` to :kbd:`Confirm`. + + .. note:: + + Select :guilabel:`Cancel` to restore the previously defined value and return to the Main Menu. + + .. figure:: figures/bare-metal-install-beta-5.png + :scale: 100 % + :alt: Select System Language + + Figure 5: :guilabel:`Select System Language` + + +Configure the Keyboard +====================== + +#. From the Main Menu, select :guilabel:`Configure the Keyboard`. + +#. Select :kbd:`Enter`. + +#. In :guilabel:`Select Keyboard`, navigate to the desired option. + +#. In :guilabel:`Test keyboard`, type text to assure that the keys map to + your keyboard. + +#. Select :kbd:`Tab` to highlight :guilabel:`Confirm`. + +#. Select :kbd:`Enter` to :kbd:`Confirm`. + + .. note:: + + Select :guilabel:`Cancel` to restore the previously defined value and return to the Main Menu. + + .. figure:: figures/bare-metal-install-beta-6.png + :scale: 100 % + :alt: Select Keyboard menu + + Figure 6: :guilabel:`Select Keyboard menu` + +Configure Media +=============== + +#. From the Main Menu, select :guilabel:`Configure Media`. + + .. note:: + + Available media appear by default. + +#. Navigate to the desired media until highlighted. + + .. figure:: figures/bare-metal-install-beta-7.png + :scale: 100 % + :alt: Configure Media menu + + Figure 7: :guilabel:`Configure Media menu` + + .. note:: + + Use additional options as necessary during partitioning: + + * Select :guilabel:`Revert` to cancel changes and revert to the + original configuration. + * Select :guilabel:`Rescan` to show media connected to the host + machine. + +#. Select :kbd:`Enter` or :kbd:`Spacebar` to select it. + + Two options for partitioning appear. + +#. Select :guilabel:`Auto Partition` to accept the default configuration, or + :guilabel:`Add Partition` to add partitions manually. See instructions + below. + +#. Select :kbd:`Enter` to :kbd:`Confirm`. + +#. Choose one partitioning option and continue below: + + * :ref:`auto-partition` + * :ref:`add-partition` + +.. _auto-partition: + +Auto Partition +============== + +Auto partition will configure the media to meet the minimum requirements. + +#. Select :guilabel:`Auto Partition` as shown in Figure 8. + +#. Select :kbd:`Enter` or :kbd:`Spacebar` to highlight + :guilabel:`Auto partition`. + +#. Select :kbd:`Enter` to :kbd:`Confirm`. + + This action returns you to the Main Menu. + + .. figure:: figures/bare-metal-install-beta-8.png + :scale: 100 % + :alt: Auto Partition + + Figure 8: :guilabel:`Auto Partition` + +#. You may skip to the :ref:`telemetry-tui` section below. + +.. _add-partition: + +Add Partition +============= + +Minimum requirements +==================== + +To add partitions manually, assign partitions per the minimum +requirements shown in Table 1: + +.. list-table:: **Table 1. Disk Partition Setup** + :widths: 33, 33, 33 + :header-rows: 1 + + * - FileSystem + - Mount Point + - Minimum size + * - ``VFAT`` + - /boot + - 150M + * - ``swap`` + - + - 256MB + * - ``root`` + - / + - *Size depends upon use case/desired bundles.* + +#. In the Configure Media menu, select :guilabel:`Add Partition`. + + .. note:: To change an existing partition, navigate to the partition, + and select :guilabel:`Enter`. + +boot partition +-------------- + +#. In the :guilabel:`File System` menu, select :kbd:`Up/Down` arrows to + select the file system type. See Figure 9. + +#. In :guilabel:`Mount Point`, enter the ``/boot`` partition. + +#. In :guilabel:`Size`, enter an appropriate size (e.g., 150M) per Table 1. + +#. Navigate to :guilabel:`Confirm` until highlighted. + +#. Select :guilabel:`Enter` to confirm. + + .. figure:: figures/bare-metal-install-beta-9.png + :scale: 100 % + :alt: boot partition + + Figure 9: :guilabel:`boot partition` + +swap partition +-------------- + +#. In the :guilabel:`File System` menu, select :kbd:`Up/Down` arrows to + select the file system type. See Figure 10. + +#. In :guilabel:`Mount Point`, the field remains blank. + + .. note:: + + The Mount Point field is disabled. + +#. In :guilabel:`Size`, enter an appropriate size (e.g., 256MB) per Table 1. + +#. Navigate to :guilabel:`Add`. + +#. Select :guilabel:`Enter` to continue. + + .. figure:: figures/bare-metal-install-beta-10.png + :scale: 100 % + :alt: swap partition + + Figure 10: :guilabel:`swap partition` + +root partition +-------------- + +#. In the :guilabel:`File System` menu, select :kbd:`Up/Down` arrows to + select the file system type. See Figure 11. + +#. In :guilabel:`Mount Point`, enter ``/root``. + +#. In :guilabel:`Size`, enter an appropriate size per Table 1. + + .. note:: + + The remaining available space shows by default. + +#. Navigate to :guilabel:`Add` until highlighted. + +#. Select :guilabel:`Enter` to continue. + + You are returned to the :guilabel:`Configure media` menu. + +#. Select :guilabel:`Confirm` to complete the media selection. + + .. figure:: figures/bare-metal-install-beta-11.png + :scale: 100 % + :alt: root partition + + Figure 11: :guilabel:`root partition` + + You are returned to the :guilabel:`Configure media` menu. Your partitions should appear similar to those shown in Figure 12. + + .. figure:: figures/bare-metal-install-beta-12.png + :scale: 100 % + :alt: Partitions + + Figure 12: :guilabel:`Partitions` + +#. Navigate to :guilabel:`Confirm` until highlighted. + +#. Select :guilabel:`Enter` to complete adding partitions. + +.. _telemetry-tui: + +Telemetry +========= + +To fulfill the :guilabel:`Required options`, choose whether or not to +participate in `telemetry`_. :ref:`telemetrics` is a |CL| feature that +reports failures and crashes to the |CL| development team for improvements. +For more detailed information, visit our :ref:`telemetry-about` page. + +#. In the Main Menu, navigate to :guilabel:`Telemetry` and select + :kbd:`Enter`. + +#. Select :kbd:`Tab` to highlight your choice. + +#. Select :kbd:`Enter` to confirm. + + .. figure:: figures/bare-metal-install-beta-13.png + :scale: 100 % + :alt: Enable Telemetry + + Figure 13: :guilabel:`Enable Telemetry` + +Skip to finish installation +=========================== + +After selecting values for all :guilabel:`Required options`, you may skip +directly to :ref:`finish-cl-installation` + +In the Main Menu, select the :guilabel:`Advanced options` if you wish to +configure network interfaces or proxy settings, add bundles, add/manage +users, and more. Continue to the next section. + +.. _advanced-options-installation: + +Advanced Options +**************** + +.. _configure-network-interfaces: + +Configure Network Interfaces +============================ + +By default, |CL| is configured to automatically detect the host network +interface using DHCP. However, if you want to use a static IP address or if +you do not have a DHCP server on your network, follow these instructions to +manually configure the network interface. Otherwise, default network +interface settings are automatically applied. + +.. note:: + + If DHCP is available, no user selection may be required. + +#. Navigate to :guilabel:`Configure Network Interfaces` and + select :kbd:`Enter`. + +#. Navigate to the network :guilabel:`interface` you wish to change. + +#. When the desired :guilabel:`interface` is highlighted, select + :guilabel:`Enter` to edit. + + .. note:: Multiple network interfaces may appear. + + .. figure:: figures/bare-metal-install-beta-14.png + :scale: 100 % + :alt: Configure Network Interfaces + + Figure 14: :guilabel:`Configure Network Interfaces` + +#. Notice :guilabel:`Automatic / dhcp` is selected by default (at bottom). + + Optional: Navigate to the checkbox :guilabel:`Automatic / dhcp` and select + :kbd:`Spacebar` to deselect. + + .. figure:: figures/bare-metal-install-beta-15.png + :scale: 100 % + :alt: Network interface configuration + + Figure 15: :guilabel:`Network interface configuration` + +#. Navigate to the appropriate fields and assign the desired + network configuration. + +#. To save settings, navigate to :guilabel:`Confirm` and select + :kbd:`Enter`. + + .. note:: + + To revert to previous settings, navigate to the :guilabel:`Cancel` + and select :kbd:`Enter`. + +#. Upon confirming network configuration, the :guilabel:`Testing Networking` + dialogue appears. Assure the result shows success. If a failure occurs, + your changes will not be saved. + +#. Upon confirmation, you are returned to :guilabel:`Network interface` + settings. + +#. Navigate to and select :guilabel:`Main Menu`. + +Optional: :ref:`Skip to finish installation `. + +Proxy +===== + +|CL| automatically attempts to detect proxy settings, as described in +`Autoproxy`_. If you need to manually assign proxy settings, follow this +instruction. + +#. From the Advanced options menu, navigate to :guilabel:`Proxy`, and + select :kbd:`Enter`. + +#. Navigate to the field :guilabel:`HTTPS Proxy`. + + .. figure:: figures/bare-metal-install-beta-16.png + :scale: 100 % + :alt: Configure the network proxy + + Figure 16: :guilabel:`Configure the network proxy` + +#. Enter the desired proxy address and port using conventional syntax, + such as: \http://address:port. + +#. Navigate to :guilabel:`Confirm` and select :kbd:`Enter`. + +#. To revert to previous settings, navigate to :guilabel:`Cancel` + and select :guilabel:`Cancel`. + +Optional: :ref:`Skip to finish installation `. + +.. _test-network-settings: + +Test Network Settings +===================== + +To manually assure network connectivity before installing |CL|, +select :guilabel:`Test Network Settings` and select :guilabel:`Enter`. + +A progress bar appears as shown in Figure 17. + +.. figure:: figures/bare-metal-install-beta-17.png + :scale: 100 % + :alt: Testing Networking dialogue + + Figure 17: :guilabel:`Testing Networking dialogue` + +.. note:: + + Any changes made to network settings are automatically tested + during configuration. + +Optional: :ref:`Skip to finish installation `. + +Bundle Selection +================ + +#. On the Advanced menu, select :guilabel:`Bundle Selection` + +#. Navigate to the desired bundle using :kbd:`Tab` or :kbd:`Up/Down` arrows. + +#. Select :kbd:`Spacebar` to select the checkbox for each desired bundle. + + .. figure:: figures/bare-metal-install-beta-18.png + :scale: 100 % + :alt: Bundle Selection + + Figure 18: :guilabel:`Bundle Selection` + +..TODO:Add new screenshot that shows more bundles. + +#. Select :kbd:`Confirm` or :kbd:`Cancel`. + + You are returned to the :guilabel:`Advanced options` menu. + +Optional: :ref:`Skip to finish installation `. + +User Manager +============ + +Add New User +------------ + +#. In Advanced Options, select :guilabel:`User Manager`. + +#. Select :guilabel:`Add New User` as shown in Figure 19. + + .. figure:: figures/bare-metal-install-beta-19.png + :scale: 100 % + :alt: Add New User, User Name + + Figure 19: :guilabel:`Add New User` + +#. Optional: Enter a :guilabel:`User Name`. + + .. note: + + The User Name must be alphanumeric and can include spaces, commas, or hyphens. Maximum length is 64 characters. + + .. figure:: figures/bare-metal-install-beta-20.png + :scale: 100 % + :alt: User Name + + Figure 20: :guilabel:`User Name` + +#. Enter a :guilabel:`Login`. + + .. note:: + + The User Login must be alphanumeric and can include hyphens and underscores. Maximum length is 31 characters. + +#. Enter a :guilabel:`Password`. + + .. note: + + Minimum length is 8 characters. Maximum length is 255 characters. + +#. In :guilabel:`Retype`, enter the same password. + +#. Optional: Navigate to the :guilabel:`Administrative` checkbox and select + :kbd:`Spacebar` to assign administrative rights to the user. + + .. note:: + + Selecting this option enables sudo privileges for the user. + + .. figure:: figures/bare-metal-install-beta-21.png + :scale: 100 % + :alt: Administrative rights + + Figure 21: :guilabel:`Administrative rights` + +#. Select :kbd:`Confirm`. + + .. note:: + + If desired, select :guilabel:`Reset` to reset the form. + +#. In :guilabel:`User Manager`, navigate to :guilabel:`Confirm`. + +#. With :guilabel:`Confirm` highlighted, select :kbd:`Enter`. + +Modify / Delete User +-------------------- + +#. In User Manager, select :guilabel:`Tab` to highlight the user, as shown + in Figure 22. + +#. Select :kbd:`Enter` to modify the user. + + .. figure:: figures/bare-metal-install-beta-22.png + :scale: 100 % + :alt: Modify User + + Figure 22: :guilabel:`Modify User` + +#. Modify user details as desired. + + Optional: To delete the user, navigate to the :guilabel:`Delete` + button and select :kbd:`Enter` + +#. Navigate to :kbd:`Confirm` until highlighted. + + .. note:: + + Optional: Select :guilabel:`Reset` to rest the form. + +#. Select :guilabel:`Confirm` to save the changes you made. + +You are returned to the User Manager menu. + +Optional: :ref:`Skip to finish installation `. + +Kernel Command Line +=================== + +For advanced users, |CL| provides the ability to add or remove kernel +arguments. If you want to append a new argument, enter the argument here. +This argument will be used every time you install or update a +new kernel. + +#. In Advanced Options, select :guilabel:`Tab` to highlight + :guilabel:`Kernel Command Line`. + +#. Select :kbd:`Enter`. + +#. To add or remove arguments, choose one of the following options. + + .. figure:: figures/bare-metal-install-beta-23.png + :scale: 100 % + :alt: kernel command line + + Figure 23: :guilabel:`kernel command line` + +#. To add arguments, enter the argument in :guilabel:`Add Extra Arguments`. + +#. To remove an existing argument, enter the argument in + :guilabel:`Remove Arguments`. + +#. Select :kbd:`Confirm`. + +Optional: :ref:`Skip to finish installation `. + +Kernel Selection +================ + +#. Select a kernel option. By default, the latest kernel release is + selected. + + .. note:: + + To choose a different kernel, such as Long Term Support (LTS), shown in Figure 24, navigate to it using :guilabel:`Tab`. + + .. figure:: figures/bare-metal-install-beta-24.png + :scale: 100 % + :alt: Kernel selection + + Figure 24: :guilabel:`Kernel selection` + +#. Select :kbd:`Spacebar` to select the desired option. + +#. Select :kbd:`Confirm`. + +Optional: :ref:`Skip to finish installation `. + +Swupd Mirror +============ + +If you have your own custom mirror of |CL|, you can add its URL. + +#. In Advanced Options, select :guilabel:`Swupd Mirror`. + +#. To add a local swupd mirror, enter a valid URL in :guilabel:`Mirror URL:` + +#. Select :kbd:`Confirm`. + + .. figure:: figures/bare-metal-install-beta-25.png + :scale: 100 % + :alt: Swupd Mirror + + Figure 25: :guilabel:`Swupd Mirror` + +Optional: :ref:`Skip to finish installation `. + +Assign Hostname +=============== + +#. In Advanced Options, select :guilabel:`Assign Hostname`. + +#. In :guilabel:`Hostname`, enter the hostname only (excluding the domain). + + .. note:: + + Hostname does not allow empty spaces. Hostname must start with an + alphanumeric character but may also contain hyphens. Maximum length of + 63 characters. + + .. figure:: figures/bare-metal-install-beta-26.png + :scale: 100 % + :alt: Assign Hostname + + Figure 26: :guilabel:`Assign Hostname` + + +#. Navigate to :kbd:`Confirm` until highlighted. + +#. Select :kbd:`Confirm`. + +Optional: :ref:`Skip to finish installation `. + +Automatic OS Updates +==================== + +In the rare case that you need to disable automatic software updates, +follow the onscreen instructions. + +#. In Advanced Options, select :guilabel:`Automatic OS Updates`. + +#. Select the desired option. + + .. figure:: figures/bare-metal-install-beta-27.png + :scale: 100 % + :alt: Automatic OS Updates + + Figure 27: :guilabel:`Automatic OS Updates` + +You are returned to the :guilabel:`Main Menu`. + +.. _finish-cl-installation: + +Finish installation +******************* + +#. When you are satisfied with your installation configuration, navigate to + :guilabel:`Install` and select :kbd:`Enter`. + + .. note:: + + Whenever installation is finished, a ``reboot`` button appears. + +#. Select ``reboot``. + +#. When the system reboots, remove any installation media present. + +**Congratulations!** + +You have successfully installed |CL| on bare metal using the new installer. + +.. _Navigate to the image directory: https://download.clearlinux.org/image/ +.. _Autoproxy: https://clearlinux.org/features/autoproxy +.. _telemetry: https://clearlinux.org/features/telemetry diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-1.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-1.png new file mode 100644 index 00000000..e3c8ff31 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-1.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-10.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-10.png new file mode 100644 index 00000000..66fbdfd9 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-10.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-11.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-11.png new file mode 100644 index 00000000..75fb4a89 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-11.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-12.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-12.png new file mode 100644 index 00000000..96471d91 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-12.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-13.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-13.png new file mode 100644 index 00000000..3850e6b6 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-13.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-14.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-14.png new file mode 100644 index 00000000..52444039 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-14.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-15.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-15.png new file mode 100644 index 00000000..d67b1cef Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-15.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-16.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-16.png new file mode 100644 index 00000000..682427ad Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-16.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-17.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-17.png new file mode 100644 index 00000000..853d1c9f Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-17.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-18.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-18.png new file mode 100644 index 00000000..f5b3c725 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-18.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-19.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-19.png new file mode 100644 index 00000000..d12f6e17 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-19.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-2.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-2.png new file mode 100644 index 00000000..d3d4cbb6 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-2.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-20.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-20.png new file mode 100644 index 00000000..0ed795ed Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-20.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-21.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-21.png new file mode 100644 index 00000000..63540471 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-21.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-22.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-22.png new file mode 100644 index 00000000..1a1e69ab Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-22.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-23.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-23.png new file mode 100644 index 00000000..75efb1a4 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-23.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-24.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-24.png new file mode 100644 index 00000000..ab197a44 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-24.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-25.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-25.png new file mode 100644 index 00000000..0694faf3 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-25.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-26.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-26.png new file mode 100644 index 00000000..21ec0031 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-26.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-27.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-27.png new file mode 100644 index 00000000..c76ee8f1 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-27.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-3.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-3.png new file mode 100644 index 00000000..4cdc59d7 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-3.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-4.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-4.png new file mode 100644 index 00000000..62950c98 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-4.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-5.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-5.png new file mode 100644 index 00000000..f06d6aed Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-5.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-6.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-6.png new file mode 100644 index 00000000..e01f71a0 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-6.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-7.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-7.png new file mode 100644 index 00000000..dfc59890 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-7.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-8.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-8.png new file mode 100644 index 00000000..cc5b10b9 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-8.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-9.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-9.png new file mode 100644 index 00000000..5134a989 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-9.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/bare-metal-install.rst b/source/clear-linux/get-started/bare-metal-install/bare-metal-install.rst index ca00f24d..560e56e3 100644 --- a/source/clear-linux/get-started/bare-metal-install/bare-metal-install.rst +++ b/source/clear-linux/get-started/bare-metal-install/bare-metal-install.rst @@ -6,9 +6,9 @@ Install |CL-ATTR| on bare metal (automatic) These instructions guide you through the installation of |CL-ATTR| on bare metal using a bootable USB drive. -Before you begin, check that your system meets the requirements to install |CL|: +Before you begin, check that your system meets the requirements to install |CL|: -* :ref:`system-requirements` +* :ref:`system-requirements` * :ref:`compatibility-check` @@ -19,7 +19,7 @@ Get the latest |CL| installer image from the `image`_ directory. Look for the :file:`clear-[version number]-installer.img.xz` file. You can also use this command: .. code-block:: bash - + curl -O https://download.clearlinux.org/image/$(curl https://download.clearlinux.org/image/latest-images | grep "installer") Once you have downloaded the image, verify and decompress the file. @@ -58,7 +58,7 @@ Follow these steps to install |CL| on the target system: #. Reboot the target system. #. The |CL| boot menu will start as shown in figure 1. - Select :guilabel:`Clear Linux OS for Intel Architecture` and press the + Select :guilabel:`Clear Linux OS` and press the :kbd:`Enter` key or wait five seconds to automatically select it. .. figure:: figures/bare-metal-install-1.png @@ -225,7 +225,7 @@ process. Otherwise, you can follow the |CL| automatic installation steps. :guilabel:`< Automatic >` menu item shown in figure 7 and press the :kbd:`Enter` key. - The :guilabel:`Choose target device for installation` screen shown in figure 8 appears. + The :guilabel:`Choose target device for installation` screen shown in figure 8 appears. #. Move the cursor to the desired target and press the :kbd:`Enter` key. @@ -255,7 +255,7 @@ process. Otherwise, you can follow the |CL| automatic installation steps. through the automated installation process. Once all steps have completed, you will see the :guilabel:`Successful - installation` status message and the :guilabel:`< Ok >` button is highlighted as shown in figure 10. + installation` status message and the :guilabel:`< Ok >` button is highlighted as shown in figure 10. #. Press the :kbd:`Enter` key to continue. @@ -266,10 +266,10 @@ process. Otherwise, you can follow the |CL| automatic installation steps. Figure 10: :guilabel:`Installation complete` Figure 11 shows the final installer screen, showing that the - installation completed successfully and the system will reboot. + installation completed successfully and the system will reboot. -#. Press the :kbd:`Enter` key and remove the USB media while the system - restarts. +#. Press the :kbd:`Enter` key and remove the USB media while the system + restarts. .. figure:: figures/bare-metal-install-11.png :scale: 50 % @@ -306,8 +306,8 @@ Next steps ********** The automatic installation of |CL| is designed to install with minimal -software overhead. Some housekeeping and package installations could be -needed before you can take full advantage of the |CL| operating system. +software overhead. Some housekeeping and package installations could be +needed before you can take full advantage of the |CL| operating system. See the :ref:`enable-user-space` guide for additional information and instructions. diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-1.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-1.png index 957bf79a..f38b5413 100644 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-1.png and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-1.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-12.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-12.png index 76c5fe87..34e676a1 100644 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-12.png and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-12.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-2.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-2.png index b82f34fd..94be46fe 100644 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-2.png and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-2.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-6.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-6.png index 9a7024c7..2d879976 100644 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-6.png and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-6.png differ diff --git a/source/clear-linux/get-started/bootable-usb/bootable-usb-beta-all.rst b/source/clear-linux/get-started/bootable-usb/bootable-usb-beta-all.rst new file mode 100644 index 00000000..6f26d650 --- /dev/null +++ b/source/clear-linux/get-started/bootable-usb/bootable-usb-beta-all.rst @@ -0,0 +1,203 @@ +.. _bootable-usb-beta-all: + +Create a bootable USB on your OS +################################ + +Follow these instructions to create a bootable |CL-ATTR| USB drive based on +your OS. + +* :ref:`bootable-usb-linux-all` +* :ref:`bootable-usb-mac-all` +* :ref:`bootable-usb-windows-all` + +Return to :ref:`install-from-live-image` + +Requirements: +************* + +* Use a **16GB** or larger USB drive. + +.. _bootable-usb-linux-all: + +Create a bootable USB drive on Linux +************************************ + +.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst + :Start-after: verify-linux: + + +Burn the |CL| image onto a USB drive +==================================== + +.. caution:: + + |CAUTION-BACKUP-USB| + +#. Open a terminal emulator and get root privilege. + + .. code-block:: bash + + sudo -s + +#. Go to the directory with the decompressed image. +#. Plug in the USB drive. +#. Identify the USB drive using the :command:`lsblk` command. This shows all + drives attached to the system, including the primary hard disk. In the + example output below, there are 4 drives + (`/dev/sda`, `/dev/sdb`, `/dev/sdc`, and `/dev/sdd`) attached, where + `/dev/sda` is primary drive in this case. The remaining are 3 USB drives. + The output also shows the mounted partitions (under the `MOUNTPOINT` + column) for each drive. + + .. code-block:: bash + + lsblk + + Example output: + + .. code-block:: console + + NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT + sdd 8:48 1 15G 0 disk + ├─sdd2 8:50 1 5G 0 part /run/media/user1/960c184f-3bb7-42b7-bcaf-0c1282 + ├─sdd3 8:51 1 8G 0 part /run/media/user1/704f3382-b26d-4f34-af1b-cb9aab + └─sdd1 8:49 1 2G 0 part + sdb 8:16 1 14.8G 0 disk + └─sdb1 8:17 1 14.8G 0 part /run/media/user1/PATRIOT_USB + sdc 8:32 1 7.3G 0 disk + └─sdc1 8:33 1 7.3G 0 part /run/media/user1/LINUX MINT + sda 8:0 0 335.4G 0 disk + ├─sda4 8:4 0 28G 0 part + ├─sda2 8:2 0 3.7G 0 part [SWAP] + ├─sda7 8:7 0 6G 0 part /home + ├─sda5 8:5 0 1G 0 part /boot + ├─sda3 8:3 0 954M 0 part /boot/efi + ├─sda1 8:1 0 28G 0 part + ├─sda8 8:8 0 30G 0 part / + └─sda6 8:6 0 7.9G 0 part [SWAP] + +#. Before an image can be burned onto a USB drive, it should be un-mounted. + Some Linux* distros may automatically mount a USB drive when it is plugged + in. To unmount, use the :command:`umount` command followed by the device + identifier/partition. For example: From the above :command:`lsblk` output, + `/dev/sdd` has 2 mounted partitions. To unmount them, enter: + + .. code-block:: bash + + umount /dev/sdd2 + umount /dev/sdd3 + +#. Burn the image onto the USB drive. The command-line example below burns an + uncompressed image onto `/dev/sdd`: + + .. code-block:: bash + + dd if=./clear-[version number]-[image type] of=/dev/sdd bs=4M status=progress + +.. _bootable-usb-mac-all: + +Create a bootable USB drive on macOS* +************************************* + +.. include:: ../../guides/maintenance/download-verify-decompress-mac.rst + :start-after: verify-mac: + + +Burn the |CL| image onto a USB drive +==================================== + +.. caution:: + + |CAUTION-BACKUP-USB| + +#. Launch the Terminal app. +#. Go to the directory with the decompressed image. +#. Plug in a USB drive and get its identifier by entering the command + :command:`diskutil list`. See Figure 1. + + .. code-block:: console + + diskutil list + + .. figure:: figures/bootable-usb-mac-1.png + :scale: 100 % + :alt: Get USB drive identifier + + Figure 1: macOS* - Get USB drive identifier + +#. Unmount the USB drive identified in the previous step. The command-line + example below umounts `/dev/disk2`: + + .. code-block:: console + + diskutil umountDisk /dev/disk2 + +#. Burn the image onto the drive using the :command:`dd` command. The + command-line example below burns an uncompressed image onto `/dev/disk2`: + + .. code-block:: console + + sudo dd if=./clear-[version number]-[image type] of=/dev/rdisk2 bs=4m + + + Adding an ‘r’ in front of the disk identifier should help speed up the + imaging process. + + You can press :kbd:`-T` to check imaging progress. + +#. Eject the USB drive. + + .. code-block:: console + + diskutil eject /dev/disk2 + +.. _bootable-usb-windows-all: + +Create a bootable USB drive on Windows\* +**************************************** + +.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst + :Start-after: verify-windows: + +Burn the |CL| image onto a USB drive +==================================== + +.. caution:: + + |CAUTION-BACKUP-USB| + +#. Download the `Rufus`_ utility to burn the image onto a USB drive. + +#. Plug in the USB drive and open Rufus. + +#. Click the :guilabel:`SELECT` button. See Figure 1. + + .. figure:: figures/bootable-usb-windows-1.png + :scale: 80 % + :alt: Rufus utility - Click the SELECT button + + Figure 1: Rufus utility - Click the SELECT button + +#. Find and select the previously extracted |CL| image file. + Then, click the :guilabel:`Open` button. See Figure 2. + + .. figure:: figures/bootable-usb-windows-2.png + :scale: 80 % + :alt: Rufus utility - Show and select |CL| image file + + Figure 2: Rufus utility - Show and select |CL| image file + +#. Click the :guilabel:`START` button. See Figure 3. + + .. figure:: figures/bootable-usb-windows-3.png + :scale: 80 % + :alt: Rufus utility - Click the START button + + Figure 3: Rufus utility - Click START button + +Return to install from live image +********************************* + +Return to :ref:`install-from-live-image` + +.. _Rufus: https://rufus.ie/ diff --git a/source/clear-linux/get-started/get-started.rst b/source/clear-linux/get-started/get-started.rst index 1bbe2c15..f39766c2 100644 --- a/source/clear-linux/get-started/get-started.rst +++ b/source/clear-linux/get-started/get-started.rst @@ -14,14 +14,16 @@ Pre-install * :ref:`compatibility-check` * :ref:`bootable-usb` + + Install |CL| ************ * :ref:`bare-metal-install` * :ref:`bare-metal-manual-install` * :ref:`virtual-machine-install` -* :ref:`live-image` - +* :ref:`live-image` +* :ref:`bare-metal-install-beta` .. toctree:: :maxdepth: 2 @@ -33,4 +35,7 @@ Install |CL| virtual-machine-install/virtual-machine-install live-image compatibility-check - bootable-usb/bootable-usb \ No newline at end of file + bootable-usb/bootable-usb + + bare-metal-install-beta/bare-metal-install-beta + bootable-usb/bootable-usb-beta-all diff --git a/source/clear-linux/guides/deploy-at-scale.rst b/source/clear-linux/guides/deploy-at-scale.rst index 9b819057..5b3867df 100644 --- a/source/clear-linux/guides/deploy-at-scale.rst +++ b/source/clear-linux/guides/deploy-at-scale.rst @@ -1,21 +1,21 @@ -.. _deploy-at-scale.rst: +.. _deploy-at-scale: -Deploying |CL| at Scale -####################### +Deploy at Scale +############### -Once you are comfortable with `Clear Linux concepts`_, your next step -as a system administrator is to understand how to deploy Clear Linux* -at scale in your environment. +Once you are comfortable with |CL-ATTR| :ref:`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. +field. .. note:: This is not a replacement or blueprint for designing your own IT - operating environment. - + 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 @@ -27,27 +27,27 @@ field. Pick a |CL| usage and update strategy ===================================== -Different business scenarios call for different deployment methodologies. -|CLOSIA| offers the flexibility to continue consuming the upstream |CL| +Different business scenarios call for different deployment methodologies. +|CL| offers the flexibility to continue consuming the upstream |CL| distribution or the option to fork away from the |CL| distribution and -act as your own :abbr:`OSV (Operating System Vendor)`. +act as your own :abbr:`OSV (Operating System Vendor)`. Below are overviews of both approaches and some considerations. Option #1: Use the |CL| as the upstream origin (mixin) ------------------------------------------------------ -This approach is *easier to adopt* by relying on the |CL| upstream for -packaging updates for you to deploy. +This approach is *easier to adopt* by relying on the |CL| upstream for +packaging updates for you to deploy. Custom software or packages that are not available in a preformed bundle -can be added using the `mixin process`_ to form a custom bundle. -If custom bundles are needed, you will be responsible for maintaining -the custom bundle(s) and testing between |CL| releases in your environment, -while the rest of the operating system and preformed bundles come from the +can be added using the `mixin process`_ to form a custom bundle. +If custom bundles are needed, you will be responsible for maintaining +the custom bundle(s) and testing between |CL| releases in your environment, +while the rest of the operating system and preformed bundles come from the |CL| upstream. - -#. Ensure |CL| systems are able to be inventoried, managed, and orchestrated + +#. Ensure |CL| systems are able to be inventoried, managed, and orchestrated to coordinate software updates. #. With autoupdate enabled, |CL| is updated daily, however you may wish to @@ -56,70 +56,70 @@ while the rest of the operating system and preformed bundles come from the yourself which is realistic with the operational expectations of your environment. -#. Use a web caching proxy for |CL| updates for devices connected to - a local area network (LAN), like a datacenter, to increase the speed - and resiliency of updates from the |CL| update servers. - - Your caching proxy server is just like any other web application. +#. Use a web caching proxy for |CL| updates for devices connected to + a local area network (LAN), like a datacenter, to increase the speed + and resiliency of updates from the |CL| update servers. + + Your caching proxy server is just like any other web application. |WEB-SERVER-SCALE| Option #2: 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 -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 forks away from the |CL| upstream and has you act as your own +:abbr:`OSV (Operating System Vendor)` by leveraging the `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*. -* Development systems which are generating bundles and updates should be - sufficiently performant for the task and separate from the swupd update +* Development systems which are generating bundles and updates should be + sufficiently performant for the task and separate from the swupd update webservers which are serving update content to production machines. -* swupd update webservers which are serving update content to +* swupd update webservers which are serving update content to production machines (see `mixer process`_ for more information) should be - appropriately scaled. + appropriately scaled. - Your swupd update server is just like any other web application. - |WEB-SERVER-SCALE| + Your swupd update server is just like any other web application. + |WEB-SERVER-SCALE| 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. +It only makes sense that any |CL| deployment strategy should follow suit. -Manually rebuilding your own bundles or mix for every release is not -sustainable at a large scale. A |CL| deployment pipeline should be agile -enough to validate and produce new versions with speed. Whether or not those -updates actually make their way to your production can be separate -business decision. However this *ability to frequently roll new versions* of -software to your endpoints is an important prerequisite. +Manually rebuilding your own bundles or mix for every release is not +sustainable at a large scale. A |CL| deployment pipeline should be agile +enough to validate and produce new versions with speed. Whether or not those +updates actually make their way to your production can be separate +business decision. However this *ability to frequently roll new versions* of +software to your endpoints is an important prerequisite. -You own the validation and lifecycle of the OS and should treat it like any +You own the validation and lifecycle of the OS and should treat it like any other software development lifecycle. Below are some pointers: * Thoroughly understand the custom software packages that you will need to integrate with |CL| and maintain along with their dependencies. -* Setup a path to production for building |CL| based images. At minimum this +* 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 + - 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 @@ -128,92 +128,93 @@ other software development lifecycle. Below are some pointers: Versioning Infrastructure ------------------------- -|CL| version numbers are very important as they apply to the whole +|CL| version numbers are very important as they apply to the whole infrastructure stack from OS components to libraries and -applications. +applications. -Good record keeping is important, so you should keep a detailed registry +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 +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 +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. -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 +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 depending on the resources available to you. -See the `reference of Clear Linux image types`_ - +See the available :ref:`image-types`. + Below are some common ways to install |CL| to systems at scale: Baremetal --------- -Preboot Execution Environments (PXE) or other +Preboot Execution Environments (PXE) or other out-of-band booting options are one way to distribute |CL| to physical baremetal systems on a LAN. -This option works well if your customizations are fairly small in size -and infrastructure can be stateless. +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 installing Clear Linux on bare metal systems`_ +documentation on how to :ref:`bare-metal-install`. -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. +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). -The |CL| `downloads page`_ offers example prebuilt VM images and is -readily available on popular CSPs. Also see -`documentation on installing Clear Linux in VMs`_. +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`. 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 -allowing you or your customers to dynamically orchestrate and scale +Containers with a |CL| image can be a good option to blueprint and ship +your application, including all its dependencies, as an artifact while +allowing you or your customers to dynamically orchestrate and scale applications. -|CL| is capable of running a Docker host, has a container image which can +|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`_. 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 +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 +A |CL| system and its infrastructure should be considered a commodity and be easily reproducible. Avoid focusing on backing up the operating system -itself or default values. +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 +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`. Meaningful Logging & Telemetry @@ -222,16 +223,16 @@ 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`_ +* Remote syslogging in |CL| is available through the + `systemd journal-remote service`_ -* |CL| offers a `native telemetry solution`_ which can be a powerful tool - for a large deployment to quickly crowdsource issues of interest. Take +* |CL| offers a `native telemetry solution`_ which can be a powerful tool + for a large deployment to quickly crowdsource issues of interest. Take advantage of this feature with careful consideration of the target audience and the kind of data that would be valuable, and expose events - appropriately. + appropriately. - Your telemetry server is just like any other web application. + Your telemetry server is just like any other web application. |WEB-SERVER-SCALE| Orchestration and Configuration Management @@ -240,47 +241,43 @@ Orchestration and Configuration Management In cloud environments, where systems can be ephemeral, being able to configure and maintain generic instances is valuable. -|CL| offers an efficient cloud-init style solution, `micro-config-drive`_, +|CL| offers an efficient cloud-init style solution, `micro-config-drive`_, 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 +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`_ . - -A configuration management tool is useful for maintaining consistent system -and application-level configuration. Ansible\* is offered through the + +A configuration management tool is useful for maintaining consistent system +and application-level configuration. Ansible\* is offered through the *sysadmin-hostmgmt* bundle as a configuration management and automation -tool. +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 -on |CL| should aim to be host-aware but not depend on any specific host to +An Infrastructure OS can design for good behavior, but it is ultimately up +to applications to make agile design choices. Applications deployed +on |CL| should aim to be host-aware but not depend on any specific host to run. References should be relative and dynamic when possible. -The application architecture should incorporate an appropriate tolerance for -infrastructure outages. Don't just keep stateless design as a noted feature. -Continuously test its use; Automate its use by redeploying |CL| and -application on new hosts. This naturally minimizes configuration drift, +The application architecture should incorporate an appropriate tolerance for +infrastructure outages. Don't just keep stateless design as a noted feature. +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. -.. _`Clear Linux concepts`: https://clearlinux.org/documentation/clear-linux/concepts .. _`mixin process`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/mixin .. _`mixer process`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/mixer -.. _`reference of Clear Linux image types`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/image-types -.. _`documentation on installing Clear Linux on bare metal systems`: https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install .. _`downloads page`: https://download.clearlinux.org/image/ -.. _`documentation on installing Clear Linux in VMs`: https://clearlinux.org/documentation/clear-linux/get-started/virtual-machine-install .. _`containers page`: https://clearlinux.org/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 .. _`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 +.. |WEB-SERVER-SCALE| replace:: + There are many well-known ways to achieve a scalable and resilient web server for this purpose, however implementation details are not in the scope of this document. In general, they should be close to your endpoints, highly available, and easy to scale with a load balancer when diff --git a/source/clear-linux/guides/guides.rst b/source/clear-linux/guides/guides.rst index f2c65575..aebc38e8 100644 --- a/source/clear-linux/guides/guides.rst +++ b/source/clear-linux/guides/guides.rst @@ -3,11 +3,11 @@ Guides ###### -Our Guides: +Our Guides: -* Provide a critical, fundamental understanding of |CL| features +* Provide a critical, fundamental understanding of |CL-ATTR| features * Show you how to leverage the full feature set of |CL| -* Enhance your productivity when using |CL| +* Enhance your productivity when using |CL| The following guides provide step-by-step instructions for tasks that come @@ -19,3 +19,4 @@ after completing the |CL| :ref:`installation `. maintenance/maintenance network/network deploy-at-scale + telemetrics/telemetrics diff --git a/source/clear-linux/guides/maintenance/assign-static-ip.rst b/source/clear-linux/guides/maintenance/assign-static-ip.rst new file mode 100644 index 00000000..444fbf21 --- /dev/null +++ b/source/clear-linux/guides/maintenance/assign-static-ip.rst @@ -0,0 +1,71 @@ +.. _assign-static-ip: + +Assign a static IP address to a network interface +################################################# + +Introduction +************ + +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. + +Process +******* + +#. Create this directory structure: + + .. code-block:: bash + + sudo mkdir -p /etc/systemd/network + +#. Identify the interface to be assigned the static IP address: + + .. code-block:: bash + + ip addr + + The system returns the following: + + .. code-block:: console + + 1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + + 2: wlp1s0: mtu 1500 qdisc mq state DOWN group default qlen 1000 + link/ether 4a:98:8d:e5:43:15 brd ff:ff:ff:ff:ff:ff + + 3: eno1: mtu 1500 qdisc fq state UP group default qlen 1000 + link/ether f4:4d:30:68:96:20 brd ff:ff:ff:ff:ff:ff + inet 10.0.1.2/24 brd 10.54.74.255 scope global dynamic eno1 + valid_lft 6766sec preferred_lft 6766sec + inet6 fe80::f64d:30ff:fe68:9620/64 scope link + valid_lft forever preferred_lft forever + + In this example, we will use the `eno1` interface. + +#. Create the :file:`70-static.network` file and add the following: + + .. code-block:: bash + + sudo $EDITOR /etc/systemd/network/70-static.network + + [Match] + Name=[interface name] + [Network] + Address=[IP address]/24 + DHCP=yes # to get DNS info, etc. + + Replace [interface name] and [IP address] with your specific settings. + +#. Restart the networkd service: + + .. code-block:: bash + + sudo systemctl restart systemd-networkd + +**Congratulations!** You have successfully assigned a static IP address. diff --git a/source/clear-linux/guides/maintenance/autoproxy.rst b/source/clear-linux/guides/maintenance/autoproxy.rst new file mode 100644 index 00000000..b5131ab7 --- /dev/null +++ b/source/clear-linux/guides/maintenance/autoproxy.rst @@ -0,0 +1,18 @@ +.. _autoproxy: + +Autoproxy +######### + +.. rst-class:: content-collapse + +About +===== + +.. include:: autoproxy_about.txt + +.. rst-class:: content-collapse + +Guide +===== + +.. include:: autoproxy_guide.txt \ No newline at end of file diff --git a/source/clear-linux/guides/maintenance/autoproxy_about.txt b/source/clear-linux/guides/maintenance/autoproxy_about.txt new file mode 100644 index 00000000..80dcaa4e --- /dev/null +++ b/source/clear-linux/guides/maintenance/autoproxy_about.txt @@ -0,0 +1,43 @@ +The |CL-ATTR| is the first Linux distribution to support autoproxy. The OS +can discover a Proxy Auto-Config (PAC) script and use it to automatically +resolve the proxy needed for a given connection. With Autoproxy, you can use +|CL| inside any proxy environment without having to manually +configure the proxies. + +Corporate and private networks can be very complex, needing to restrict and +control network connections for security reasons. The typical side effects +are limited or blocked connectivity and requiring manual configuration of +proxies to perform the most mundane tasks such as cloning a repo or checking +for updates. With Clear Linux, all of the work is done behind the scenes to +effortlessly use your network and have connections “just work”. + +This feature removes massive complications in network connectivity due to +proxy issues. You can automate tasks like unit testing without worrying +about the proxy not being set and you can remove unset proxies from the +equation when dealing with network unavailability across systems. + +How Autoproxy works +------------------- + +We designed autoproxy around general tools provided by nearly any Linux +distribution with a few minor additions and modifications. We leveraged the +DHCP and network information provided from systemd and created a +PAC-discovery daemon. The daemon uses the information to resolve a URL for a +PAC file. The daemon then passes the URL into PACrunner*. PACrunner +downloads the PAC file and uses the newly implemented Duktape* engine to +parse it. + +.. figure:: figures/autoproxy_0.png + :width: 400px + + Figure 1: Autoproxy Flow + +From that point on, any cURL* or network requests query PACrunner for the +correct proxy to use. We modified the cURL library to communicate with +PACrunner over DBus. However, cURL will ignore PACrunner and run normally if +no PAC file is loaded or if you set any proxies manually. Thus, your +environment settings are respected and no time is wasted trying to resolve a +proxy. + +More importantly: all these steps happen in the background, very quickly, and +with no user interaction. \ No newline at end of file diff --git a/source/clear-linux/guides/maintenance/autoproxy_guide.txt b/source/clear-linux/guides/maintenance/autoproxy_guide.txt new file mode 100644 index 00000000..3422a747 --- /dev/null +++ b/source/clear-linux/guides/maintenance/autoproxy_guide.txt @@ -0,0 +1,77 @@ +Autoproxy allows |CL| to operate seamlessly behind a proxy +because, :ref:`swupd-guide` and other |CL| tools are implemented on +top of libcurl. Tools that do not use libcurl, like git, must +be configured independently. + +If you encounter problems with autoproxy functioning, use +:command:`pacdiscovery` and :command:`FindProxyForURL` to +help troubleshoot assuming a familiarity with PAC files and WPAD. + +.. note:: + + Learn more about WPAD, PAC files, and PAC functions at `findproxyforurl`_. + +.. _findproxyforurl: http://findproxyforurl.com/ + +Running :command:`pacdiscovery` with no arguments will immediately indicate + +1. if there is a problem resolving the :command:`WPAD` host name resolution: + + .. code:: console + + $ pacdiscovery + failed getaddrinfo: No address associated with hostname + Unable to find wpad host + +2. or if the :command:`pacrunner` service is disabled (masked). + + .. code:: console + + $ pacdiscovery + PAC url: http://autoproxy.your.domain.com/wpad.dat + Failed to create proxy config: Unit pacrunner.service is masked. + +Unmask the :command:`pacrunner` service by running: + +.. code:: console + + $ systemctl unmask pacrunner.service + +:command:`FindProxyForURL` with :command:`busctl` can also indicate if the +:command:`pacrunner.service` is masked. + +.. code:: console + + $ busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com" + Unit pacrunner.service is masked. + dig wpad, dig wpad. + +:command:`FindProxyForURL` returns the URL and port of the proxy server when +an external URL and host are provided as arguments. + +.. code:: console + + $ busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com" + s "PROXY proxy.your.domain.com:" + +If a proxy server is not avialable, or if :command:`pacrunner` is running +without a PAC file, :command:`FindProxyForURL` will return "DIRECT". + +.. code:: console + + $ busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com" + s "DIRECT" + +Once :command:`pacdiscovery` is able to look up :command:`WPAD`, restart the +:command:`pacrunner` service: + +.. code:: console + + $ systemctl stop pacrunner + $ systemctl restart pacdiscovery + +.. note:: + + A "domain" or "search" entry in :file:`/etc/resolv.conf` is required for short + name lookups to resolve. The :file:`resolv.conf` man page has additional + details. \ No newline at end of file diff --git a/source/clear-linux/guides/maintenance/autospec.rst b/source/clear-linux/guides/maintenance/autospec.rst index aa25a6cf..257f8e2c 100644 --- a/source/clear-linux/guides/maintenance/autospec.rst +++ b/source/clear-linux/guides/maintenance/autospec.rst @@ -96,8 +96,7 @@ we build a new helloclear RPM. .. note:: - For a local tarball, use for the *URL*: - file:// + For a local tarball, use this type of *URL*: \file:// #. If build failures or dependency issues occur, continue below. Otherwise, skip directly to `Next steps`_. diff --git a/source/clear-linux/guides/maintenance/developer-workstation.rst b/source/clear-linux/guides/maintenance/developer-workstation.rst index d408aebf..fc0582d9 100644 --- a/source/clear-linux/guides/maintenance/developer-workstation.rst +++ b/source/clear-linux/guides/maintenance/developer-workstation.rst @@ -3,42 +3,39 @@ Developer Workstation ##################### -Overview -******** +*Developer Workstation* helps you find the :ref:`bundles-about` you need to +start your |CL-ATTR| development project. -*Developer Workstation* helps you find the :ref:`bundles-about` you need to -start your |CL| development project. - -Before continuing, we recommend that you learn how to use +Before continuing, we recommend that you learn how to use :ref:`swupd `. Visit our :ref:`swupd-about` page to understand how |CL| simplifies software versioning compared to other Linux\* -distributions. +distributions. 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 Clear Linux development, you can add the +This guide helps you understand the minimum bundles required to get started. +After installing them, you can add more bundles relevant to your use case. +To run any process required for |CL| development, you can add the large bundle :ref:`*os-clr-on-clr* `. However, given how many packages this bundle contains, you may want instead to deploy a leaner -OS with only those bundles relevant to your project. Developer Workstation -responds to this need. +OS with only those bundles relevant to your project. Developer Workstation +responds to this need. -Use Table 1, *Clear Linux 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 Table 1 as a starting point. +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 Table 1 as a starting point. -.. list-table:: **Table 1. Clear Linux Developer Profiles** +.. list-table:: **Table 1. Developer Profiles** :widths: 20, 20, 20, 20 :header-rows: 1 - * - Clear Linux Bundle - - *Internet of Things (IoT)* + * - |CL| Bundle + - *Internet of Things (IoT)* - *System Administrator* - *Client/Cloud/Web Developer* - - * - `editors` + + * - `editors` - ✓ - ✓ - ✓ @@ -52,60 +49,60 @@ While your role may not neatly fit in one of these categories, consider using Ta - ✓ - ✓ - ✓ - + * - `webserver-basic` - - + - - ✓ - - ✓ - + - ✓ + * - `application-server` - - + - - ✓ - ✓ - + * - `database-basic` - - + - - ✓ - ✓ - + * - `desktop-autostart` - ✓ - ✓ - ✓ * - `dev-utils` - - - - + - + - - ✓ `swupd` search -============== +************** We recommend trying out :ref:`swupd search `, to learn the -commands to search for and add bundles relevant to your project. +commands to search for and add bundles relevant to your project. -:ref:`swupd-search` shows you how to: +:ref:`swupd-search` shows you how to: -* Use `swupd` to search for bundles +* Use `swupd` to search for bundles * Use `swupd` to add bundles Core Concepts -============= +************* -We recommend that you understand these core concepts in |CL| *before* -developing your project. +We recommend that you understand these core concepts in |CL| *before* +developing your project. * :ref:`Bundles ` * :ref:`Software update ` * :ref:`Mixer ` -* :ref:`Autospec ` +* :ref:`Autospec ` Other resources for developers ----------------------------------- -* `Developer Tooling Framework for Clear Linux`_ -* `Clear Linux Bundles`_ +* `Developer Tooling Framework`_ for |CL| +* `Bundle definition files`_ -.. _Clear Linux Bundles: https://github.com/clearlinux/clr-bundles +.. _Bundle definition files: https://github.com/clearlinux/clr-bundles -.. _Developer Tooling Framework for Clear Linux: https://github.com/clearlinux/common +.. _Developer Tooling Framework: https://github.com/clearlinux/common diff --git a/source/clear-linux/guides/maintenance/enable-user-space.rst b/source/clear-linux/guides/maintenance/enable-user-space.rst index e48e272b..288ada71 100644 --- a/source/clear-linux/guides/maintenance/enable-user-space.rst +++ b/source/clear-linux/guides/maintenance/enable-user-space.rst @@ -4,7 +4,7 @@ Create and enable a new user space ################################## This section provides steps to complete the following basic setup tasks for -a newly installed |CLOSIA| system: +a newly installed |CL-ATTR| system: * Create a new user. * Update the OS to its most current version using `swupd`. @@ -51,7 +51,7 @@ Install the `sysadmin-basic` bundle: We provide the full list of bundles and packages installed with the `sysadmin-basic`_ bundle. Additionally, we have listed -`all Clear Linux bundles`_, active or deprecated. Click any bundle on the +`all bundles`_ for |CL|, active or deprecated. Click any bundle on the list to view the manifest of the bundle. Set up a new user and add the new user to the `wheel` group @@ -88,7 +88,7 @@ Install a GUI to test `sudo` privileges .. note:: If you are following this sequence after just setting up the - pre-configured VMware\* virtual machine from the repo, you must + pre-configured VMware\* virtual machine from the repo, you must :ref:`increase virtual disk size` or the following step will fail. @@ -136,7 +136,7 @@ system. .. _`sysadmin-basic`: https://github.com/clearlinux/clr-bundles/blob/master/bundles/sysadmin-basic -.. _`all Clear Linux bundles`: +.. _`all bundles`: https://github.com/clearlinux/clr-bundles/tree/master/bundles .. _`wheel group`: diff --git a/source/clear-linux/guides/maintenance/figures/autoproxy_0.png b/source/clear-linux/guides/maintenance/figures/autoproxy_0.png new file mode 100644 index 00000000..7a02cd81 Binary files /dev/null and b/source/clear-linux/guides/maintenance/figures/autoproxy_0.png differ diff --git a/source/clear-linux/guides/maintenance/hostname.rst b/source/clear-linux/guides/maintenance/hostname.rst index 04c7108e..ce539009 100644 --- a/source/clear-linux/guides/maintenance/hostname.rst +++ b/source/clear-linux/guides/maintenance/hostname.rst @@ -3,15 +3,15 @@ Modify hostname on |CL-ATTR| ############################ -This guide describes how to modify and view the hostname of your +This guide describes how to modify and view the hostname of your |CL-ATTR| system. -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 -but is not human-friendly. Administrators and users will often want to rename -their machines with a name that is easier to remember, type, and search -for. Renaming a machine also makes it easier to identify, by including -meaningful data in the name. The following examples show human-friendly machine +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 +but is not human-friendly. Administrators and users will often want to rename +their machines with a name that is easier to remember, type, and search +for. Renaming a machine also makes it easier to identify, by including +meaningful data in the name. The following examples show human-friendly machine names: * *regression-test* @@ -21,12 +21,12 @@ names: 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. +|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. -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. +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. Make sure to reboot after setting a new hostname. .. code-block:: bash @@ -36,14 +36,14 @@ Make sure to reboot after setting a new hostname. .. note:: - There are three types of hostname: *static*, *transient*, and *pretty*. - The most common is the static hostname. Static hostnames must be between - two and 63 characters long, must start and end with a letter or number, - and may contain letters (case-insensitive), numbers, dashes, or dots. + There are three types of hostname: *static*, *transient*, and *pretty*. + The most common is the static hostname. Static hostnames must be between + two and 63 characters long, must start and end with a letter or number, + and may contain letters (case-insensitive), numbers, dashes, or dots. - If the static hostname exists, it is used to generate the transient hostname, - which is maintained by the kernel. The transient hostname can be changed - by DHCP or mDNS at runtime. + If the static hostname exists, it is used to generate the transient hostname, + which is maintained by the kernel. The transient hostname can be changed + by DHCP or mDNS at runtime. The pretty hostname is a free-form UTF8 name used for presentation to the user. @@ -70,5 +70,5 @@ You should see output similar to: Kernel : Linux 4.18.8-632.native Architecture : x86-64 - + **Congratulations!** You successfully modified the hostname of your |CL| system. diff --git a/source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst b/source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst index a676e615..287be71b 100644 --- a/source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst +++ b/source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst @@ -1,18 +1,18 @@ .. _increase-virtual-disk-size: -Increase virtual disk size of a Clear Linux\* image -################################################### +Increase virtual disk size of a |CL-ATTR| image +############################################### -|CLOSIA| prebuilt images come in different sizes, ranging from 300 MB to 20 +|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. .. contents:: This guide will cover: -Determine the partition order and sizes of the prebuilt image +Determine the partition order and sizes of the prebuilt image ************************************************************* -There are two methods to find the order and sizes of partitions virtual disk +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 / @@ -28,7 +28,7 @@ execute the :command:`lsblk` command as shown below: sudo lsblk -An example output of the :command:`lsblk` command: +An example output of the :command:`lsblk` command: .. code-block:: console @@ -36,16 +36,16 @@ An example output of the :command:`lsblk` command: sda 8:0 0 8.5G 0 disk ├─sda1 8:1 0 512M 0 part ├─sda2 8:2 0 32M 0 part [SWAP] - └─sda3 8:3 0 8G 0 part / + └─sda3 8:3 0 8G 0 part / An example of this can also be seen in Figure 1. -Checking :file:`config.json` used to build the image +Checking :file:`config.json` used to build the image ---------------------------------------------------- -The second method to determine partition to check the :file:`config.json` +The second method to determine partition to check the :file:`config.json` file used to create prebuilt image, located in the `releases`_ repository. -For example, to find the size of the Hyper-V\* image version number 20450, +For example, to find the size of the Hyper-V\* image version number 20450, follow these steps: #. Go to the `releases`_ repository. @@ -74,17 +74,17 @@ follow these steps: Increase virtual disk size ************************** -Once you have determined the disk and partition to be increased, you are +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: -------------------------------------------- -To increase the virtual disk size for a prebuilt image, perform the steps +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 +#. Use the process defined by your hypervisor or cloud provider to increase the virtual disk size of your |CL| VM. #. Power up the VM. @@ -95,7 +95,7 @@ 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 |CL| `storage-utils` bundle to install the :command:`parted` and :command:`resize2fs` tools. .. code-block:: bash @@ -121,7 +121,7 @@ Resize the partition of the virtual disk: Fix/Ignore? - #. Enter :command:`resizepart [partition number]` where + #. 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. @@ -142,18 +142,18 @@ Resize the partition of the virtual disk: .. figure:: figures/increase-virtual-disk-size-1.png :scale: 100 % - :alt: Increase root partition size + :alt: Increase root partition size Figure 1: Increase root partition size. -Resize the filesytem +Resize the filesytem -------------------- #. Enter :command:`sudo resize2fs -p /dev/[modified partition name]` where *[modified partition name]* is the partition that was changed in `parted`. #. Run the :command:`df -h` to verify that the filesystem size has - increased. + increased. Figure 2 depicts the described steps to resize the partition of the virtual disk from 8.5GB to 20GB. @@ -164,6 +164,6 @@ Resize the filesytem Figure 2: Increase root filesystem size after partition has been expanded. Congratulations! You have resized the disk, partition, and filesystem. At -this point, the increase in disk capacity is usable. +this point, the increase in disk capacity is usable. .. _releases: https://download.clearlinux.org/releases/ \ No newline at end of file diff --git a/source/clear-linux/guides/maintenance/kernel-modules.rst b/source/clear-linux/guides/maintenance/kernel-modules.rst new file mode 100644 index 00000000..5390f554 --- /dev/null +++ b/source/clear-linux/guides/maintenance/kernel-modules.rst @@ -0,0 +1,176 @@ +.. _kernel-modules: + +Add kernel modules +################## + +Kernel modules are additional pieces of software capable of being inserted +into the Linux kernel to add functionality, such as a hardware driver. +Kernel modules may already be part of the Linux source tree (in-tree) or may +come from an external source, such as directly from a vendor (out-of-tree). + +In cases where drivers beyond those enabled by default in |CL-ATTR| are +needed it may be necessary to: + +.. contents:: :local: + :depth: 1 + :backlinks: top + +Check if the module is available through |CL| +============================================= + +Using an existing module is significantly easier to maintain and retains +signature verification of the |CL| kernel. For more information on |CL| +security practices, see the :ref:`security` page. + +|CL| comes with many upstream kernel modules available for use. If +you require a kernel module, be sure to check whether it is already available in |CL| first. + +You can search for kernel module file names, which end with the :file:`.ko` +file extension, using the :command:`swupd search` command. For example: +:command:`sudo swupd search ${module_name}.ko`. +See :ref:`swupd-search` for more information. + +Request the module be added to |CL| +=================================== + +If the kernel module you need is already open source +(e.g. in the Linux upstream) and likely to be useful to others, +consider submitting a request to add or enable in the |CL| kernel. + +Make enhancement requests to the |CL| distribution `on GitHub`_ . + +Build and load an out-of-tree module +==================================== + +In some cases you may need an out-of-tree kernel module that is not +available through |CL|. + +You can build and load out-of-tree kernel modules, however you must: + +* disable secure boot +* disable kernel module integrity checking +* build the module against new versions of the Linux kernel + +.. note:: + + Any time the kernel is upgraded on your Clear Linux system, you will + need to rebuild your out-of-tree modules. + +This approach works well for individual development or testing. +For a more scalable and customizable approach, consider using the +`mixer tool`_ to provide a custom kernel and updates. + +Build kernel module +------------------- + +#. From a |CL| system, ensure you are running the *native* kernel. + Currently only the native kernel is enabled to build and load + out-of-tree modules. + + .. code-block:: bash + + $ uname -r + 4.XX.YY-ZZZZ.native + # Ensure *.native* is in the kernel name + +#. Install the `linux-dev` bundle to obtain the kernel headers, which are + required for compiling kernel modules. + + .. code-block:: bash + + sudo swupd bundle-add linux-dev + +#. Follow instructions from the kernel module source code to compile the + kernel module. + + +Load kernel module +------------------ + +#. Disable Secure Boot in your system's UEFI settings, if you have enabled + it. The loading of new out-of-tree modules modifies the signatures Secure + Boot relies on for trust. + + +#. Disable signature checking for the kernel by modifying the kernel boot + parameters and reboot the system. + + All kernel modules from |CL| have been signed to enforce kernel security. + However, out-of-tree modules break this chain of trust so this mechanism + needs to be disabled. + + .. code-block:: bash + + sudo mkdir -p /etc/kernel/cmdline.d + echo "module.sig_unenforce" | sudo tee /etc/kernel/cmdline.d/allow-unsigned-modules.conf + +#. Update the boot manager and reboot the system to implement the changed + kernel parameters. + + .. code-block:: bash + + sudo clr-boot-manager update + sudo reboot + + .. note:: + + :command:`clr-boot-manager update` does not return any + console output if successful. + + +#. After rebooting, out-of-tree modules can be manually loaded with + :command:`insmod`. + + .. code-block:: bash + + sudo insmod ${path_to_module} + + +Optional: Use `modprobe` to specify module options and aliases +-------------------------------------------------------------- + +Use :command:`modprobe` to load a module and set options. + +Because :command:`modprobe` can add or remove more than one module, due to +modules having dependencies, a method of specifying what options are +to be used with individual modules is useful. This can be done with +configuration files under the :file:`/etc/modprobe.d` directory. + +.. code-block:: bash + + sudo mkdir /etc/modprobe.d + +All files underneath the :file:`/etc/modprobe.d` directory +that end with the :file:`.conf` extension specify module options to use when +loading. This can also be used to create convenient aliases for modules or +they can override the normal loading behavior altogether for those with +special requirements. + +You can find more info on module loading in the modprobe.d manual page: + +.. code-block:: bash + + man modprobe.d + +Optional: Configure kernel modules to load at boot +-------------------------------------------------- + +Use the :file:`/etc/modules-load.d` configuration directory to +specify kernel modules to load automatically at boot. + +.. code-block:: bash + + sudo mkdir /etc/modules-load.d + +All files underneath the :file:`/etc/modules-load.d` directory +that end with the :file:`.conf` extension contain a list of module names +of aliases (one per line) to load at boot. + +You can find more info on module loading in the modules-load.d manual page: + +.. code-block:: bash + + man modules-load.d + +.. _`on GitHub`: https://github.com/clearlinux/distribution +.. _`mixer tool`: https://clearlinux.org/features/mixer-tool \ No newline at end of file diff --git a/source/clear-linux/guides/maintenance/maintenance.rst b/source/clear-linux/guides/maintenance/maintenance.rst index 712e3844..3d89fa54 100644 --- a/source/clear-linux/guides/maintenance/maintenance.rst +++ b/source/clear-linux/guides/maintenance/maintenance.rst @@ -10,15 +10,16 @@ completed. .. toctree:: :maxdepth: 2 + autoproxy developer-workstation swupd-search enable-user-space swupd-guide bulk-provision + kernel-modules mixer mixin validate-signatures - telemetry-enable time hostname increase-virtual-disk-size @@ -26,3 +27,4 @@ completed. download-verify-decompress-mac download-verify-decompress-windows autospec + assign-static-ip diff --git a/source/clear-linux/guides/maintenance/mixin.rst b/source/clear-linux/guides/maintenance/mixin.rst index 862332b2..75e2c488 100644 --- a/source/clear-linux/guides/maintenance/mixin.rst +++ b/source/clear-linux/guides/maintenance/mixin.rst @@ -3,7 +3,7 @@ Create and add custom bundles to your upstream Clear Linux system ################################################################# -|CLOSIA| offers many curated bundles that you can install on your system to +|CL-ATTR| offers many curated bundles that you can install on your system to create your desired capabilities. If the available upstream bundles do not meet your needs, you can create and add your own custom bundles to your system using one of two methods. Note: Upstream refers to the official diff --git a/source/clear-linux/guides/maintenance/swupd-guide.rst b/source/clear-linux/guides/maintenance/swupd-guide.rst index db0ba772..ea0bab61 100644 --- a/source/clear-linux/guides/maintenance/swupd-guide.rst +++ b/source/clear-linux/guides/maintenance/swupd-guide.rst @@ -5,7 +5,7 @@ Use swupd *swupd* manages the software update capability of |CL-ATTR|. It can check for valid system updates and, if found, download and install them. It can also -perform verification of the system software. +perform verification of the system software. |CL| uses :ref:`bundles ` as the base abstraction for installing functionality on top of the core operating system. Use the `swupd` @@ -18,7 +18,7 @@ This guide assumes: * The device is able to connect to the release infrastructure http://update.clearlinux.org -.. contents:: +.. contents:: :local: :depth: 2 @@ -54,7 +54,7 @@ Current OS version and update server info: Enable or disable automatic updates =================================== -|CL| updates are automatic by default but can be set to occur only +|CL| updates are automatic by default but can be set to occur only on demand. To verify your current auto-update setting: .. code-block:: bash @@ -105,7 +105,7 @@ to, overwritten, removed, or modified (e.g., permissions). sudo swupd verify -All directories that are watched by `swupd` are verified according to +All directories that are watched by `swupd` are verified according to the manifest data and hash mismatches are flagged as follows: .. code-block:: console @@ -113,7 +113,7 @@ the manifest data and hash mismatches are flagged as follows: Verifying version 23300 Verifying files ...0% - Hash mismatch for file: /usr/bin/chardetect + Hash mismatch for file: /usr/bin/chardetect ... ... Hash mismatch for file: /usr/lib/python3.6/site-packages/urllib3/util/wait.py @@ -124,7 +124,7 @@ the manifest data and hash mismatches are flagged as follows: In this case, python packages that were installed on top of the default install were flagged as mismatched. `swupd` can be directed to ignore -or fix issues based on :ref:`command line options `. +or fix issues based on :ref:`command line options `. Fixing hash mismatches ====================== @@ -138,7 +138,7 @@ ignore files or directories matching `/usr/lib/python`: .. code-block:: bash - sudo swupd verify --fix --picky --picky-whitelist=/usr/lib/python + sudo swupd verify --fix --picky --picky-whitelist=/usr/lib/python Bundles ******* @@ -150,7 +150,7 @@ You can list all of the bundles currently installed on the system .. code-block:: bash - sudo swupd bundle-list --all + sudo swupd bundle-list --all Finding a bundle containing a binary ==================================== @@ -160,7 +160,7 @@ binary. Note that it may be present in multiple bundles: .. code-block:: bash - swupd search -b + swupd search -b Adding a bundle =============== diff --git a/source/clear-linux/guides/maintenance/swupd-search.rst b/source/clear-linux/guides/maintenance/swupd-search.rst index 835775ab..45764a65 100644 --- a/source/clear-linux/guides/maintenance/swupd-search.rst +++ b/source/clear-linux/guides/maintenance/swupd-search.rst @@ -1,54 +1,54 @@ -.. _swupd-search: +.. _swupd-search: Use swupd search to find bundles ################################ This document explains how to use `swupd search` to find and add -bundles in |CL-ATTR|. +bundles in |CL-ATTR|. Assumptions *********** -This guide assumes you: +This guide assumes you: -* Possess a basic knowledge of :ref:`swupd ` -* Understand :ref:`how swupd differs ` from - other Linux\* distributions +* Possess a basic knowledge of :ref:`swupd ` +* Understand :ref:`how swupd differs ` from + other Linux\* distributions * May :ref:`mixer` to produce a custom distribution/image -How do I search for a bundle? +How do I search for a bundle? ***************************** -Use `swupd search` to locate the bundle where the application binary exists. +Use `swupd search` to locate the bundle where the application binary exists. Example: Kata\* Containers ========================== -Containers have revolutionized the way we manage cloud infrastructure. -Traditional containers often share the same OS kernel, which raises -security concerns. Instead, with Kata Containers, each container has its own -kernel instance and runs on its own :abbr:`Virtual Machine (VM)`. Whether you're running 3 or 300 nodes on your cluster, Kata Containers provide a -lightweight, fast, and secure option for app/container management. +Containers have revolutionized the way we manage cloud infrastructure. +Traditional containers often share the same OS kernel, which raises +security concerns. Instead, with Kata Containers, each container has its own +kernel instance and runs on its own :abbr:`Virtual Machine (VM)`. Whether you're running 3 or 300 nodes on your cluster, Kata Containers provide a +lightweight, fast, and secure option for app/container management. -In |CL|, you only need to add `one bundle`_ to use `Kata Containers`_: +In |CL|, you only need to add `one bundle`_ to use `Kata Containers`_: `containers-virt`. Also, check out our tutorial: :ref:`kata`. -We need to find *kata* containers in a bundle. How do we search for it? +We need to find *kata* containers in a bundle. How do we search for it? -#. Enter :command:`swupd search`, followed by 'kata' as the search term: +#. Enter :command:`swupd search`, followed by 'kata' as the search term: .. code-block:: bash sudo swupd search kata - .. note:: + .. note:: `swupd search` downloads |CL| manifest data and searches for - matching paths. Enter only one term, or hyphenated term, per + matching paths. Enter only one term, or hyphenated term, per search. Use the command :command:`man swupd` to learn more. #. Alternatively, if you want to search binaries only, add the `-b` - flag: + flag: .. code-block:: bash @@ -56,15 +56,15 @@ We need to find *kata* containers in a bundle. How do we search for it? .. note:: - `-b` flag, or `--binary`, means: Restrict search to program binary paths. Omit this flag if you want a larger scope of search results. + `-b` flag, or `--binary`, means: Restrict search to program binary paths. Omit this flag if you want a larger scope of search results. - Only the base bundle is returned. In |CL|, *bundles* can contain - other *bundles* via `includes`. For more details, see `Bundle Definition Files`_ and its subdirectory *bundles*. + Only the base bundle is returned. In |CL|, *bundles* can contain + other *bundles* via `includes`. For more details, see `Bundle Definition Files`_ and its subdirectory *bundles*. If your search does not produce results on a specific term when using - the `-b` flag, abbreviate the search term. For example, if you search - for *kubernetes* and it does not show results, instead abbreviate the - term to *kube* to show results. + the `-b` flag, abbreviate the search term. For example, if you search + for *kubernetes* and it does not show results, instead abbreviate the + term to *kube* to show results. #. Optionally, you can review our `bundles`_ or individual `packages`_ @@ -82,7 +82,7 @@ We need to find *kata* containers in a bundle. How do we search for it? .. note:: - If the bundle is already installed, *[installed]* appears in search results. If this doesn't apppear, the bundle needs to be installed. + If the bundle is already installed, *[installed]* appears in search results. If this doesn't apppear, the bundle needs to be installed. #. Add the bundle `containers-virt`: @@ -94,11 +94,11 @@ We need to find *kata* containers in a bundle. How do we search for it? To add multiple bundles simply add a space followed by the bundle name. -#. When prompted, enter your password. +#. When prompted, enter your password. #. Upon successful installation, your console should show similar data: - - .. code-block:: console + + .. code-block:: console Downloading packs... @@ -123,11 +123,11 @@ Learn how to: * :ref:`kata_migration` -* :ref:`swupd-guide` +* :ref:`swupd-guide` * :ref:`Show all available bundles ` -* :ref:`Remove bundles` +* :ref:`Remove bundles` .. _Kata Containers: https://clearlinux.org/blogs/clear-linux-os-announces-support-kata-containers @@ -135,6 +135,6 @@ Learn how to: .. _Bundle Definition Files: https://github.com/clearlinux/clr-bundles - .. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles + .. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles - .. _packages: https://github.com/clearlinux/clr-bundles/blob/master/packages + .. _packages: https://github.com/clearlinux/clr-bundles/blob/master/packages diff --git a/source/clear-linux/guides/maintenance/time.rst b/source/clear-linux/guides/maintenance/time.rst index 4a8b75dd..25ee141b 100644 --- a/source/clear-linux/guides/maintenance/time.rst +++ b/source/clear-linux/guides/maintenance/time.rst @@ -3,7 +3,7 @@ Set the time ############ -|CLOSIA| uses the `systemd-timesyncd.service` daemon to synchronize 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 the default :abbr:`NTP (Network Time Protocol)` servers cannot be reached. diff --git a/source/clear-linux/guides/maintenance/validate-signatures.rst b/source/clear-linux/guides/maintenance/validate-signatures.rst index 1a99afc6..54bbfe4d 100644 --- a/source/clear-linux/guides/maintenance/validate-signatures.rst +++ b/source/clear-linux/guides/maintenance/validate-signatures.rst @@ -3,7 +3,7 @@ Validate signatures ################### -|CLOSIA| offers a way to validate the content of an image or an update. All +|CL-ATTR| 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. @@ -21,7 +21,7 @@ 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. #. Download the image, the signature of the SHA512 sum of the image, and the - Clear Linux certificate used for signing the SHA512 sum. + |CL| certificate used for signing the SHA512 sum. .. code-block:: console @@ -29,16 +29,16 @@ used for illustrative purposes. You may use any image of |CL| you choose. curl -O https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz # Signature of SHA512 sum of image curl -O https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig - # Clear Linux certificate + # Certificate curl -O https://download.clearlinux.org/releases/$(curl https://download.clearlinux.org/latest)/clear/ClearLinuxRoot.pem -#. Generate the SHA256 sum of the Clear Linux certificate. +#. Generate the SHA256 sum of the |CL| certificate. .. code-block:: console sha256sum ClearLinuxRoot.pem -#. Ensure the generated SHA256 sum of the Clear Linux certificate matches the +#. Ensure the generated SHA256 sum of the |CL| certificate matches the following SHA256 sum to verify the integrity of the certificate. .. code-block:: console @@ -52,12 +52,19 @@ used for illustrative purposes. You may use any image of |CL| you choose. sha512sum clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz > sha512sum.out #. Ensure the signature of the SHA512 sum of the image was created using the - Clear Linux certificate. This validates the image is trusted and it has not + |CL| certificate. This validates the image is trusted and it has not been modified. .. code-block:: console - openssl smime -verify -in clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem + openssl smime -verify -purpose any -in clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem + + .. 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 output should contain ``Verification successful``. If the output contains ``bad_signature`` anywhere, then the image is not trustworthy. @@ -101,7 +108,14 @@ these steps manually when performing a ``swupd update``. .. code-block:: console - openssl smime -verify -in Manifest.MoM.sig -inform der -content Manifest.MoM -CAfile Swupd_Root.pem + openssl smime -verify -purpose any -in Manifest.MoM.sig -inform der -content Manifest.MoM -CAfile Swupd_Root.pem + + .. 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. .. note:: diff --git a/source/clear-linux/guides/network/custom-clear-container.rst b/source/clear-linux/guides/network/custom-clear-container.rst index 5f4b1009..bcc0fcac 100644 --- a/source/clear-linux/guides/network/custom-clear-container.rst +++ b/source/clear-linux/guides/network/custom-clear-container.rst @@ -3,8 +3,8 @@ 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 +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. Prerequisites @@ -111,7 +111,7 @@ Build the base container image .. note:: * :file:`os-core` provides the minimal Linux namespace. - * :file:`os-core-update` provides the basic suite for running the |CLOSIA| + * :file:`os-core-update` provides the basic suite for running the |CL| updater. #. Optionally, you can include additional bundles with the base image. diff --git a/source/clear-linux/guides/network/dpdk.rst b/source/clear-linux/guides/network/dpdk.rst index 2f8d4127..112dfe13 100644 --- a/source/clear-linux/guides/network/dpdk.rst +++ b/source/clear-linux/guides/network/dpdk.rst @@ -25,7 +25,7 @@ drivers, sample applications, and tools for fast packet processing. Prerequisites ************* -* Two platforms using |CLOSIA| release `13330`_ or higher. +* 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: @@ -130,7 +130,7 @@ NICs to DPDK modules to run DPDK applications. Set hugepages (Platforms A and B) ********************************* -|CLOSIA| supports `hugepages` for the large memory pool allocation used for +|CL| supports `hugepages` for the large memory pool allocation used for packet buffers. #. Set the number of hugepages. @@ -264,7 +264,7 @@ machines control the NICs on the host. sudo curl -O https://download.clearlinux.org/image/start_qemu.sh -#. Download a bare-metal image of |CLOSIA| and rename it as :file:`clear.img`. +#. Download a bare-metal image of |CL| and rename it as :file:`clear.img`. #. Look for an Ethernet\* device entry that contains vendor and device ID: @@ -283,7 +283,7 @@ machines control the NICs on the host. host. -#. Unbind the NICs from the host to do pass-through with virtual machines. |CLOSIA| +#. Unbind the NICs from the host to do pass-through with virtual machines. |CL| supports this action. The commands take the format: .. code-block:: bash diff --git a/source/clear-linux/guides/network/ipxe-install.rst b/source/clear-linux/guides/network/ipxe-install.rst index 2a6585ef..ad58f584 100644 --- a/source/clear-linux/guides/network/ipxe-install.rst +++ b/source/clear-linux/guides/network/ipxe-install.rst @@ -1,9 +1,9 @@ .. _ipxe-install: -Install Clear Linux over the network with iPXE -################################################ +Install |CL-ATTR| over the network with iPXE +############################################ -This guide describes how to install Clear Linux\* using :abbr:`PXE (Pre-boot +This guide describes how to install |CL-ATTR| using :abbr:`PXE (Pre-boot Execution Environment)`. PXE is an industry standard that describes client-server interaction with diff --git a/source/clear-linux/guides/network/network-bonding.rst b/source/clear-linux/guides/network/network-bonding.rst index 1b601748..1f19f0eb 100644 --- a/source/clear-linux/guides/network/network-bonding.rst +++ b/source/clear-linux/guides/network/network-bonding.rst @@ -6,7 +6,7 @@ Combine multiple interfaces with network bonding Network bonding combines multiple network interfaces into a single logical interface to provide redundancy and bandwidth aggregation. -|CLOSIA| includes Linux bonding_ and team_ drivers. This guide describes how +|CL-ATTR| includes Linux bonding_ and team_ drivers. This guide describes how to configure systemd to use the `bonding` driver. The example demonstrates how to: diff --git a/source/clear-linux/guides/network/network.rst b/source/clear-linux/guides/network/network.rst index 5df83dcb..30846ade 100644 --- a/source/clear-linux/guides/network/network.rst +++ b/source/clear-linux/guides/network/network.rst @@ -4,7 +4,7 @@ Network guide ############# This guide provides step-by-step instructions for common tasks associated with -the configuration, administration, and use of networks in the |CLOSIA|. +the configuration, administration, and use of networks in the |CL-ATTR|. .. toctree:: :maxdepth: 1 diff --git a/source/clear-linux/guides/network/vnc.rst b/source/clear-linux/guides/network/vnc.rst index 8de6f3ef..ac0138a0 100644 --- a/source/clear-linux/guides/network/vnc.rst +++ b/source/clear-linux/guides/network/vnc.rst @@ -1,10 +1,10 @@ .. _vnc: -Remote-desktop to a Clear Linux host using VNC +Remote-desktop to a |CL-ATTR| 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 |CLOSIA| host. +that allows you to connect via remote-desktop to your |CL-ATTR| host. This guide shows you how to: @@ -15,13 +15,13 @@ This guide shows you how to: * Terminate a VNC connection to your |CL| host. * Encrypt VNC traffic through an SSH tunnel. -Install the VNC server and misc. components on your Clear Linux host -******************************************************************** +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 - it to start automatically on boot, and installs TigerVNC Viewer. +* `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. Follow these steps: @@ -35,16 +35,16 @@ Follow these steps: #. Install the |CL| bundles. .. code-block:: console - + # swupd bundle-add desktop-autostart vnc-server #. Reboot your |CL| host. -Configure a VNC-server-start method on your Clear Linux host -************************************************************ +Configure a VNC-server-start method on your host +************************************************ -There are three methods you can use to configure and start the VNC server on -your host: +There are three methods you can use to configure and start the VNC server on +your |CL| host: .. list-table:: Table 1: VNC-server-start Configuration Methods :widths: 10,20,20,20 @@ -55,14 +55,14 @@ your host: - `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 + - 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 supplying the display ID. - - The system administrator sets up a systemd service script for you with - a pre-assigned display ID. You make a VNC connection and supply + - The system administrator sets up a systemd service script for you with + a pre-assigned display ID. You make a VNC connection and supply your pre-assigned display ID. - The system adminstrator configures GDM to accept connection requests. - When you make a VNC connection to the |CL| host, you see + When you make a VNC connection to the |CL| host, you see the GDM login screen and authenticate as if you are local. * - Who configures VNC settings? - You @@ -82,10 +82,10 @@ your host: - No. Use |CL| account username and password through GDM -Although all three methods can coexist on the same |CL| host, we recommend -you pick a method that suits your needs. +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 +For simplicity, the rest of this guide refers to these methods as `Method 1`, `Method 2`, and `Method 3`. Method 1: Manually start a VNC session @@ -94,18 +94,18 @@ Method 1: Manually start a VNC session You (and each user) must perform these steps to initialize your VNC settings. #. Log in. -#. Open a terminal emulator. +#. Open a terminal emulator. #. Start VNC with the :command:`vncserver` command. Since this is your first time starting VNC, it adds default configuration files and asks you to set a VNC password. - .. code-block:: console + .. code-block:: console - $ vncserver + $ vncserver Example output: - .. code-block:: console + .. code-block:: console $ vncserver @@ -123,15 +123,15 @@ You (and each user) must perform these steps to initialize your VNC settings. Starting applications specified in /home/vnc-user-a/.vnc/xstartup 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. + Upon completion, you can find the default configuration files and the + password file hidden in the `.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 - your VNC viewer app for connection. + 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 + 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] +#. 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 @@ -140,22 +140,22 @@ You (and each user) must perform these steps to initialize your VNC settings. .. note:: - If you do not recall the active session display ID, use the - :command:`vncserver -list` command to find it. + If you do not recall the active session display ID, use the + :command:`vncserver -list` command to find it. #. Optional configurations: - * To customize settings such as screen size, security type, etc., - modify the :file:`$HOME/.vnc/config` file. - * To customize the applications to run at startup, modify the - :file:`$HOME/.vnc/xstartup` file. + * To customize settings such as screen size, security type, etc., + modify the :file:`$HOME/.vnc/config` file. + * To customize the applications to run at startup, modify the + :file:`$HOME/.vnc/xstartup` file. Method 2: Automatically start a VNC session via a systemd service script ======================================================================== To configure VNC for this method, you must have root privileges. You will -set up a systemd service file for all intended VNC users with their own -preassigned unique display ID. +set up a systemd service file for all intended VNC users with their own +preassigned unique display ID. #. Log in and get root privileges. @@ -163,7 +163,7 @@ preassigned unique display ID. $ sudo -s -#. Make sure the user accounts already exist. Use the following command to +#. Make sure the user accounts already exist. Use the following command to list all users. @@ -180,8 +180,8 @@ preassigned unique display ID. #. 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 `User` field. The example below shows user + `vnc-user-b` who is assigned the display ID `5`. .. code-block:: console @@ -203,12 +203,12 @@ preassigned unique display ID. [Install] WantedBy=multi-user.target - EOF + EOF -#. Have each user log into their account and set a VNC password with +#. Have each user log into their account and set a VNC password with the :command:`vncpasswd` command before proceeding to the next step. -#. Start the VNC service script and set it to start automatically on +#. 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 @@ -217,29 +217,29 @@ preassigned unique display ID. # systemctl start vncserver@:[X].service # systemctl enable vncserver@:[X].service -#. After starting the services, verify they are running. +#. After starting the services, verify they are running. .. code-block:: console # systemctl | grep vnc - The example below shows 2 VNC sessions that were successfully started for + 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. .. code-block:: console # systemctl | grep vnc - vncserver@:5.services loaded active running VNC Remote Desktop Service for "vnc-user-b" with display ID "5" - vncserver@:6.services loaded active running VNC Remote Desktop Service for "vnc-user-c" with display ID "6" - system-vncserver.slice loaded active active system-vncserver.slice + vncserver@:5.services loaded active running VNC Remote Desktop Service for "vnc-user-b" with display ID "5" + vncserver@:6.services loaded active running VNC Remote Desktop Service for "vnc-user-c" with display ID "6" + system-vncserver.slice loaded active active system-vncserver.slice -Method 3: Multi-user logins with authentication through GDM +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. +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. #. Log in and get root privileges. @@ -253,7 +253,7 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc # mkdir -p /etc/systemd/system -#. Create a systemd socket file :file:`xvnc.socket` and add the following: +#. Create a systemd socket file :file:`xvnc.socket` and add the following: .. code-block:: console @@ -307,7 +307,7 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc EOF -#. Start the VNC socket script and set it to start automatically on boot. +#. Start the VNC socket script and set it to start automatically on boot. .. code-block:: console @@ -315,20 +315,20 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc # systemctl start xvnc.socket # systemctl enable xvnc.socket -#. After starting the socket, verify it is running. +#. After starting the socket, verify it is running. .. code-block:: console # systemctl | grep vnc - The example below shows the xvnc.socket is running. + The example below shows the xvnc.socket is running. .. code-block:: console # systemctl | grep vnc xvnc.socket loaded active listening XVNC Server on port 5900 - system-xvnc.slice loaded active active system-xvnc.slice + system-xvnc.slice loaded active active system-xvnc.slice See the `vncserver` Man page for additional information. @@ -336,15 +336,15 @@ 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 -encrypt your VNC traffic, which is discussed later in this guide. +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. +Perform the steps below to add these apps to your client system. Install a VNC viewer app ======================== -On |CL|: +On |CL|: .. code-block:: console @@ -354,9 +354,9 @@ On Ubuntu, Mint: .. code-block:: console - # apt-get install xtightvncviewer + # apt-get install xtightvncviewer -On Fedora: +On Fedora: .. code-block:: console @@ -365,38 +365,38 @@ On Fedora: On Windows: * Install `RealVNC for Windows`_ - + On macOS: -* Install `RealVNC for macOS`_ +* Install `RealVNC for macOS`_ Install an SSH client ===================== -* On most Linux distros (Clear Linux, Ubuntu, Mint, Fedora, etc.) and macOS, +* On most Linux distros (|CL|, Ubuntu, Mint, Fedora, etc.) and macOS, SSH is built-in so you don't need to install it. * On Windows, you can install `Putty`_. -Establish a VNC connection to your Clear Linux host -*************************************************** +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 +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 Clear Linux host and launch VNC -============================================= +SSH into your host and launch VNC +================================= -#. SSH into your Clear Linux host +#. SSH into your |CL| host #. On Linux distros and macOS: @@ -409,8 +409,8 @@ SSH into your Clear Linux host and launch VNC #. Launch Putty. #. Under the :guilabel:`Category` section, select :guilabel:`Session`. See Figure 1. - #. Enter the IP address of your Clear Linux host in the - :guilabel:`Host Name (or IP address)` field. + #. Enter the IP address of your |CL| host in the + :guilabel:`Host Name (or IP address)` field. #. Set the :guilabel:`Connection type` option to :guilabel:`SSH`. #. Click the :guilabel:`Open` button. @@ -420,8 +420,8 @@ SSH into your Clear Linux 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 @@ -440,35 +440,35 @@ SSH into your Clear Linux host and launch VNC Log file is /home/vnc-user-c/.vnc/clr-linux:3.log #. Take note of the generated display ID because you will input it into - the VNC viewer app to establish the connection. The above example shows - the display ID is 3. + the VNC viewer app to establish the connection. The above example shows + the display ID is 3. .. note:: - VNC automatically picks a unique display ID unless you specify one. - To specify a display ID, enter a unique number that is not already - in use after the colon. For example: + VNC automatically picks a unique display ID unless you specify one. + To specify a display ID, enter a unique number that is not already + in use after the colon. For example: .. code-block:: console $ vncserver :8 -#. You can now end the SSH connection by logging out. This does - not terminate your active VNC session. +#. You can now end the SSH connection by logging out. This does + not terminate your active VNC session. .. _connect-to-vnc-session: Connect to your VNC session =========================== -For `Method 1` and `Method 2`, you must connect to a specific active session -or display ID using one of two options: +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 +* Use the display ID -For example, if the display ID is 3, it can be specified as `5903` or just +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. @@ -483,22 +483,22 @@ number. #. Enter your credentials. * For `Method 1` and `Method 2`, enter your VNC password. No username is - required. + required. * 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 - VNC if you are logged in locally and vice versa. + VNC if you are logged in locally and vice versa. **On Windows and macOS using `RealVNC` app:** #. Start the RealVNC viewer app. See Figure 2. -#. Enter the IP address of the Clear Linux host and the fully-qualified +#. Enter the IP address of the |CL| host and the fully-qualified VNC port number. - The following screenshot shows connecting to |CL| host + The following screenshot shows connecting to |CL| host 192.168.25.54 with a fully-qualified VNC port number 5902. .. figure:: figures/vnc/vnc-2.png @@ -512,7 +512,7 @@ number. #. Enter your credentials. * For `Method 1` and `Method 2`, enter your VNC password. No username is - required. + required. * For `Method 3`, enter your |CL| account username and password through GDM. @@ -520,8 +520,8 @@ number. 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: @@ -546,16 +546,16 @@ To increase the RealVNC viewer image quality, manually change the `ColorLevel` v Figure 4: RealVNC Viewer - change :guilabel:`ColorLevel` -Terminate a VNC connection to your Clear Linux host -*************************************************** +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: -#. SSH into your Clear Linux host. +#. SSH into your |CL| host. #. Open a terminal emulator. -#. Find the active VNC session display ID with the command +#. Find the active VNC session display ID with the command :command:`vncserver -list`. .. code-block:: console @@ -581,7 +581,7 @@ truly terminate an active VNC session, follow these steps: Encrypt VNC traffic through an SSH tunnel ***************************************** -By default, VNC traffic is not encrypted. Figure 6 shows an example warning +By default, VNC traffic is not encrypted. Figure 6 shows an example warning from RealVNC Viewer. .. figure:: figures/vnc/vnc-6.png @@ -592,13 +592,13 @@ from RealVNC Viewer. 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 +#. Configure the VNC server to only accept connection from localhost by adding the `-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) - to your |CL| host with the same port number. -#. The VNC viewer app on your client system will now connect to localhost, +#. 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) + to your |CL| host with the same port number. +#. The VNC viewer app on your client system will now connect to localhost, instead of the IP address of your |CL| host. Configure VNC to only accept connection from localhost @@ -622,11 +622,11 @@ For `Method 1`: localhost # alwaysshared -#. If an active session exists, kill it, and then restart it. +#. If an active session exists, kill it, and then restart it. For `Method 2`: -#. Edit the systemd service script :file:`vncserver@:[X].service` located in +#. Edit the systemd service script :file:`vncserver@:[X].service` located in :file:`/etc/systemd/system` and add `-localhost` to the `ExecStart` line. The example below uses vncserver@:5.service: @@ -657,12 +657,12 @@ For `Method 2`: For `Method 3`: -#. No change is needed to the :file:`xvnc@service` script. +#. No change is needed to the :file:`xvnc@service` script. After you have restarted your VNC session, you can verify that it only accepts connections from localhost by using the :command:`netstat` - command like this: - + command like this: + .. code-block:: console $ netstat -plant @@ -673,7 +673,7 @@ For `Method 3`: 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 `-localhost` option was used. .. figure:: figures/vnc/vnc-7.png :scale: 100 % @@ -681,8 +681,8 @@ 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 `-localhost` option was used. + .. figure:: figures/vnc/vnc-8.png :scale: 100 % :alt: VNC session only accepting connection from localhost @@ -698,23 +698,23 @@ Set up an SSH tunnel from your client system to your |CL| host .. code-block:: console - $ 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). - .. note:: + .. note:: * `-L` specifies that [client port number] on the localhost (on the - client side) is forwarded to [fully-qualified VNC port number] + client side) is forwarded to [fully-qualified VNC port number] (on the server side). - * Replace `[client port number]` with an available client port number - (for example: 1234). For simplicity, you can make the + * Replace `[client port number]` with an available client port number + (for example: 1234). For simplicity, you can make the `[client port number]` the same as the `[fully-qualified VNC port number]`. - * Replace `[fully-qualified VNC port number]` with 5900 (default VNC - port) plus the display ID. For example, if the display ID is 2, - the fully-qualified VNC port number is is 5902. - * `-N` tells SSH to only forward ports and not execute a remote + * Replace `[fully-qualified VNC port number]` with 5900 (default VNC + port) plus the display ID. For example, if the display ID is 2, + the fully-qualified VNC port number is is 5902. + * `-N` tells SSH to only forward ports and not execute a remote command. * `-f` tells SSH to go into the background before command execution. * `-l` specifies the username to log in as. @@ -722,28 +722,28 @@ Set up an SSH tunnel from your client system to your |CL| host **On Windows:** #. Launch Putty. -#. Specify the |CL| VNC host to connect to. - - #. Under the :guilabel:`Category` section, select :guilabel:`Session`. +#. Specify the |CL| VNC host to connect to. + + #. Under the :guilabel:`Category` section, select :guilabel:`Session`. See Figure 1. - #. Enter the IP address of your Clear Linux host in the - :guilabel:`Host Name (or IP address)` field. + #. Enter the IP address of your |CL| host in the + :guilabel:`Host Name (or IP address)` field. #. Set the :guilabel:`Connection type` option to :guilabel:`SSH`. #. Configure the SSH tunnel. See Figure 9 for an example. - #. Under the :guilabel:`Category` section, go to + #. Under the :guilabel:`Category` section, go to :guilabel:`Connection` > :guilabel:`SSH` > :guilabel:`Tunnels`. - - #. In the :guilabel:`Source port` field, enter an available client + + #. In the :guilabel:`Source port` field, enter an available client port number (for example: 1234). For simplicity, you can make the `Source port` the same as the fully-qualified VNC port number. - - #. In the :guilabel:`Destination` field, enter + + #. In the :guilabel:`Destination` field, enter `localhost:` plus the fully-qualified VNC port number. #. Click the :guilabel:`Add` button. - + .. figure:: figures/vnc/vnc-9.png :scale: 100 % :alt: Putty - configure SSH tunnel @@ -756,7 +756,7 @@ Set up an SSH tunnel from your client system to your |CL| host Connect to a VNC session through an SSH tunnel ============================================== -After you have set up an SSH tunnel, follow these instructions to connect to +After you have set up an SSH tunnel, follow these instructions to connect to your VNC session. **On Linux distros:** @@ -776,13 +776,13 @@ your VNC session. .. figure:: figures/vnc/vnc-10.png :scale: 100 % :alt: RealVNC viewer app connecting to localhost:1234 - + Figure 10: RealVNC viewer app connecting to `localhost:1234` - .. note:: + .. note:: - RealVNC will still warn that the connection is not encrypted even - though its traffic is going through the SSH tunnel. You can ignore + RealVNC will still warn that the connection is not encrypted even + though its traffic is going through the SSH tunnel. You can ignore this warning. .. _RealVNC for Windows: https://www.realvnc.com/en/connect/download/viewer/windows/ diff --git a/source/clear-linux/guides/telemetrics/telemctl.rst b/source/clear-linux/guides/telemetrics/telemctl.rst new file mode 100644 index 00000000..97db933a --- /dev/null +++ b/source/clear-linux/guides/telemetrics/telemctl.rst @@ -0,0 +1,65 @@ +.. _telemctl: + +telemctl options +################ + +The |CL-ATTR| telemetry client provides an admin tool called ``telemctl`` +that is used for managing the telemetry services and probes. The tool is +located in :file:`/usr/bin`. Running it with no argument results in the +following: + +.. code-block:: bash + + sudo telemctl + +.. code-block:: console + + /usr/bin/telemctl - Control actions for telemetry services + stop Stops all running telemetry services + start Starts all telemetry services + restart Restarts all telemetry services + is-active Checks if telemprobd and telempostd are active + opt-in Opts in to telemetry, and starts telemetry services + opt-out Opts out of telemetry, and stops telemetry services + journal Prints telemetry journal contents. Use -h argument for more + options + +telemctl commands: +****************** + +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** . + +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. + +.. code-block:: bash + + sudo telemctl is-active + +.. code-block:: console + + telemprobd : active + telempostd : active + +.. include:: ./telemetry-enable.rst + :start-after: incl-opt-in-out-telemetry: + :end-before: incl-opt-in-out-telemetry-end: + +Next steps +========== + +Learn to read records: + +* :ref:`telemetry-journal` diff --git a/source/clear-linux/guides/telemetrics/telemetrics.rst b/source/clear-linux/guides/telemetrics/telemetrics.rst new file mode 100644 index 00000000..9731471f --- /dev/null +++ b/source/clear-linux/guides/telemetrics/telemetrics.rst @@ -0,0 +1,19 @@ +.. _telemetrics: + +Telemetry +######### + +The |CL-ATTR| telemetrics solution collects data from running |CL| systems +and helps to quickly identify and fix bugs in the OS. These guides will walk +you through setup, configuration, and customization of the telemetry client. The data collected from the client system is analyzed and presented by the +telemetry backend solution. For more details, learn how to +:ref:`telemetry-backend`. + +.. toctree:: + :maxdepth: 1 + + telemetry-enable + telemetry-config + telemctl + telemetry-journal + telemetry-z-api diff --git a/source/clear-linux/guides/telemetrics/telemetry-config.rst b/source/clear-linux/guides/telemetrics/telemetry-config.rst new file mode 100644 index 00000000..d97b89bb --- /dev/null +++ b/source/clear-linux/guides/telemetrics/telemetry-config.rst @@ -0,0 +1,101 @@ +.. _telemetry-config: + +Telemetry client configuration +############################## + +The telemetry client will look for the configuration file located at +:file:`/etc/telemetrics/telemetrics.conf` and use it if it exists. If the +file does not exist, the client will use the default configuration located +at :file:`/usr/share/defaults/telemetrics/telemetrics.conf`. To modify or +customize the configuration, copy the file from +:file:`/usr/share/defaults/telemetrics` to +:file:`/etc/telemetrics` and edit it. + +Configuration Options +********************* +The client uses the following configuration options from the config file: + +* **server**: This specifies the web server to which telempostd sends the + telemetry records. +* **socket_path**: This specifies the path of the unix domain socket that + the telemprobd listens on for connections from the probes. +* **spool_dir**: This configuration option is related to spooling. If the + daemon is not able to send the telemetry records to the backend server due + to reasons such as the network availability, then it stores the records in + a spool directory. This option specifies that path of the spool directory. + This directory should be owned by the same user as the daemon. + + - mkdir -p /var/spool/telemetry + - chown -R telemetry:telemetry /var/spool/telemetry + - systemctl restart telemprobd.service + +* **record_expiry**: This is the time in minutes after which the records in + the spool directory are deleted by the daemon. +* **spool_process_time**: This specifies the time interval in seconds that + the daemon waits for before checking the spool directory for records. The + daemon picks up the records in the order of modification date and tries to + send the record to the server. It sends a maximum of 10 records at a time. + If it was able to send a record successfully, it deletes the record from + the spool. If the daemon finds a record older than the "record_expiry" + time, then it deletes that record. The daemon looks at a maximum of 20 + records in a single spool run loop. +* **rate_limit_enabled**: This determines whether rate-limiting is enabled or + disabled. When enabled, there is a threshold on both records sent within a + window of time, and record bytes sent within a window a time. +* **record_burst_limit**: This is the maximum amount of records allowed to be + passed by the daemon within the record_window_length of time. If set to + -1, the rate-limiting for record bursts is disabled. +* **record_window_length**: The time in minutes (0-59) that + establishes the window length for the record_burst_limit. EX: if + record_burst_window=1000 and record_window_length=15, then no more than + 1000 records can be passed within any given fifteen minute window. +* **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:: + + Configuration options may change as the telemetry client evolves. + Please use the comments in the file itself as the most accurate + reference for configuration. + +Setting a static machine id +=========================== + +The machine id reported by the telemetry client is rotated every 3 days for +privacy reasons. If you wish to have a static machine id for testing +purposes, you can opt in by creating a static machine id file named +"opt-in-static-machine-id" under the directory :file:`/etc/telemetrics/`. +Where "unique machine ID" is your desired static machine ID. + +.. code-block:: bash + + sudo mkdir -p /etc/telemetrics + +.. code-block:: bash + + sudo echo "unique machine ID" > /etc/telemetrics/opt-in-static-machine-id + +.. note:: + + The machine id mentioned here is not the same as the system hostname. Learn how to :ref:`hostname`: + +Next steps +========== + +* :ref:`telemctl` diff --git a/source/clear-linux/guides/maintenance/telemetry-enable.rst b/source/clear-linux/guides/telemetrics/telemetry-enable.rst similarity index 61% rename from source/clear-linux/guides/maintenance/telemetry-enable.rst rename to source/clear-linux/guides/telemetrics/telemetry-enable.rst index 7b8fc2b5..7ae19481 100644 --- a/source/clear-linux/guides/maintenance/telemetry-enable.rst +++ b/source/clear-linux/guides/telemetrics/telemetry-enable.rst @@ -1,116 +1,114 @@ -.. _telemetry-enable: - -Enable and disable telemetry in |CL-ATTR| -######################################### - -|CL-ATTR| includes a telemetry solution as part of the OS that records events -of interest and reports them back to the development team via the telemetrics -client daemons, **telempobd** and **telempostmd**. This functionality is -maintained in the **telemetrics** software bundle. - -.. note:: - The telemetry functionality adheres to `Intel privacy policies`_ - regarding the collection and use of :abbr:`PII (Personally Identifiable - Information)` and is open source. Specifically, no intentionally - identifiable information about the user or system owner is collected. - -End users may enable or disable the telemetry component of |CL| or even -redirect where the records go if they wish to collect records for themselves. - -Install the telemetry software bundle -************************************* - -During the initial installation of |CL|, you are requested to join the -stability enhancement program and allow |CL| to collect anonymous reports -to improve system stability. If you choose not to join this program, then the -telemetry software bundle is not added to your system. - -To install the telemetry bundle, enter the following command as either the -root user or with :command:`sudo` privileges: - -.. code-block:: bash - - sudo swupd bundle-add telemetrics - -This adds the telemetrics-client to your system and you will automatically -opt-in for the service. - -Enable telemetry -***************** - -To start telemetry on your system, run the following command: - -.. code-block:: bash - - sudo telemctl start - -This enables and starts the :command:`telemprobd` and :command:`telempostd` daemons and your system will -begin to send telemetry data to the server defined in the file -:file:`/etc/telemetrics/telemetrics.conf`. If this file does not exist, the -:command:`telemprobd` and :command:`telempostd` daemons will use the file -:file:`/usr/share/defaults/telemetrics/telemetrics.conf`. - -Disable telemetry -***************** - -To disable both of the telemetry daemons, run the following command: - -.. code-block:: bash - - sudo telemctl stop - -Opt-out of telemetry -******************** - -To stop sending telemetrics data from your system, opt out of the -telemetry service: - -.. code-block:: bash - - sudo telemctl opt-out - -This creates the file :file:`/etc/telemetrics/opt-out` and stops the -telemetry services. - -Opt-in to telemetry -******************* - -Conversely, to opt-in to the telemetry services, simply enter the opt-in -command and start the service: - -.. code-block:: bash - - sudo telemctl opt-in - -This removes the file :file:`/etc/telemetrics/opt-out` file, if it exists, -and starts the telemetry services. - -.. note:: - - To opt-in but not immediately start telemetry services, you will need to - run the command :command:`sudo telemctl stop` after the :command:`opt-in` - command is entered. Once you are ready to start the service, enter the - command :command:`sudo telemctl start`. - -Remove the telemetry software bundle -************************************ - -To completely remove telemetrics from your system, use the command -:command:`swupd` to remove the telemetry software bundle: - -.. code-block:: bash - - sudo swupd bundle-remove telemetrics - -Additional resources -******************** - -* `Telemetry feature description`_ -* :ref:`Telemetry architecture` -* :ref:`telemetry-backend` -* https://github.com/clearlinux/telemetrics-client - -.. _Intel privacy policies: https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html - -.. _`Telemetry feature description`: - https://clearlinux.org/features/telemetry +.. _telemetry-enable: + +Enable telemetry +################ + +Telemetry enables developers to observe and proactively address issues on +|CL-ATTR| before end users are impacted. The telemetry functionality +is maintained in the ``telemetrics`` software bundle. + +.. note:: + + The telemetry functionality adheres to `Intel privacy policies`_ + regarding the collection and use of :abbr:`PII (Personally Identifiable + Information)` and is open source. Specifically, no intentionally + identifiable information about the user or system owner is collected. + +End users may enable or disable the telemetry component of |CL| or even +redirect where the records go if they wish to collect records for themselves. + +Install the telemetry software bundle +************************************* + +During the initial installation of |CL|, you are requested to join the +stability enhancement program and allow |CL| to collect anonymous reports +to improve system stability. If you choose not to join this program, then the +telemetry software bundle is not added to your system. + +To install the telemetry bundle, enter the following command as either the +root user or with :command:`sudo` privileges: + +.. code-block:: bash + + sudo swupd bundle-add telemetrics + +This adds the telemetrics-client to your system, and you will automatically +opt-in for the service. + +Enable telemetry +================ + +To start telemetry on your system, run the following command: + +.. code-block:: bash + + sudo telemctl start + +This enables and starts the :command:`telemprobd` and :command:`telempostd` +daemons. Your system will begin to send telemetry data to the server defined +in the file :file:`/etc/telemetrics/telemetrics.conf`. If this file does not +exist, the :command:`telemprobd` and :command:`telempostd` daemons will use +the file :file:`/usr/share/defaults/telemetrics/telemetrics.conf`. + +Disable telemetry +================= + +To disable both of the telemetry daemons, run the following command: + +.. code-block:: bash + + sudo telemctl stop + +.. _incl-opt-in-out-telemetry: + +Opt-in to telemetry +=================== + +To opt-in to the telemetry services, simply enter the opt-in +command and start the service: + +.. code-block:: bash + + sudo telemctl opt-in + +This removes the file :file:`/etc/telemetrics/opt-out` file, if it exists, +and starts the telemetry services. + +.. note:: + + To opt-in but not immediately start telemetry services, you will need to + run the command :command:`sudo telemctl stop` after the :command:`opt-in` + command is entered. Once you are ready to start the service, enter the + command :command:`sudo telemctl start`. + +Opt-out of telemetry +==================== + +To stop sending telemetrics data from your system, opt out of the +telemetry service: + +.. code-block:: bash + + sudo telemctl opt-out + +This creates the file :file:`/etc/telemetrics/opt-out` and stops the +telemetry services. + +.. _incl-opt-in-out-telemetry-end: + +Remove the telemetry software bundle +==================================== + +To completely remove telemetrics from your system, use the :command:`swupd` +command to remove the telemetry software bundle: + +.. code-block:: bash + + sudo swupd bundle-remove telemetrics + +Next steps +========== + +* :ref:`telemetry-config` + +.. _Intel privacy policies: https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html diff --git a/source/clear-linux/guides/telemetrics/telemetry-journal.rst b/source/clear-linux/guides/telemetrics/telemetry-journal.rst new file mode 100644 index 00000000..c0c4be80 --- /dev/null +++ b/source/clear-linux/guides/telemetrics/telemetry-journal.rst @@ -0,0 +1,108 @@ +.. _telemetry-journal: + +telemctl journal +################ + +The telemctl ``journal`` command gives you access to features and options of +the telemetry journal to assist with system analytics and debug. The +:command:`telemctl journal` has a number of options to help filter +records. Use :command:`-h` or :command:`--help` to view usage options. + +.. code-block:: bash + + sudo telemctl journal -h + +:: + + -r, --record_id Print record with specific record_id + -e, --event_id Print records with specific event_id + -c, --classification Print records with specific classification + -b, --boot_id Print records with specific boot_id + -i, --include_record Include record content + -V, --verbose Verbose output + -h, --help Display this help message + +Journal Output +************** + +To see the listing of records in the journal, run the command: + +.. code-block:: bash + + sudo telemctl journal -V + +This will produce output like the following: + +.. list-table:: **Table 1. Journal Output** + :widths: 10 30 20 20 20 + :header-rows: 1 + + * - Classification + - Time stamp + - Record ID + - Event ID + - Boot ID + + * - org.clearlinux/heartbeat/ping + - Fri 2018-09-21 00:00:57 UTC + - 269e8e4026e6aa440c4d2ed71e38efcd + - b3a51b5e62a008ed0b56d1740be67d48 + - 853a75aa-da3b-4356-a085-079abab3ffe1 + + * - org.clearlinux/hello/world + - Fri 2018-09-21 17:53:21 UTC + - b06c8d31adf5ccc7d5d3f8959d8d3e72 + - 57c64c79a9b911d68f4dab10a00267d7 + - 853a75aa-da3b-4356-a085-079abab3ffe1 + + * - org.clearlinux/crash/clr + - Fri 2018-09-21 17:57:59 UTC + - b62cd4278672ae3331cf121bc7a8e1c6 + - b6adb5751382c48eebb7ee007fe1790a + - 853a75aa-da3b-4356-a085-079abab3ffe1 + +Each line gives information about a distinct record. The :command:`-V` or +:command:`--verbose` option adds the header to identify the Classification, +Time Stamp, Record ID, Event ID and Boot ID for each record. The journal +feature can filter records according to the Classification, Record ID, Event +ID and Boot ID by using the :command:`-c`,:command:`-r`, :command:`-e` and +:command:`-b` options accordingly. + +Payload Information +******************** + +From the previous output, you may want to get more information about the +record with the "org.clearlinux/crash/clr" classification to help debug a +crash. You can use the :command:`-c` and :command:`-i` options to see the payload of the record, like this: + +.. code-block:: bash + + sudo telemctl journal -c org.clearlinux/crash/clr -i + +.. code-block:: console + + org.clearlinux/crash/clr Tue 2018-09-25 18:43:50 UTC 07ae583edbd13829965d67e9ba97d70c 69c600470769c841649266178375d67e d32c13d1-fda0-49c6-8431-e6c5b29cbefa + Process: /usr/bin/bash + PID: 685 + Signal: 11 + + Backtrace (TID 685): + #0 kill() - [libc.so.6] + #1 bash_tilde_expand() - [/usr/bin/bash] + #2 maybe_execute_file() - [/usr/bin/bash] + #3 main() - [/usr/bin/bash] + #4 __libc_start_main() - [libc.so.6] + #5 _start() - [/usr/bin/bash] + +If you have records of multiple crashes, you can use the :command:'-r' +option to specify the record more precisely, rather than going by +classification. You can also specify a classification of record and use the +:command:'-i' option to see the payload of each record with that +classification. + +Next steps +========== + +Adding telemetry to your applications: + +* :ref:`telemetry-api` diff --git a/source/clear-linux/guides/telemetrics/telemetry-z-api.rst b/source/clear-linux/guides/telemetrics/telemetry-z-api.rst new file mode 100644 index 00000000..d8a2fd0b --- /dev/null +++ b/source/clear-linux/guides/telemetrics/telemetry-z-api.rst @@ -0,0 +1,170 @@ +.. _telemetry-api: + +Telemetry API +############# + +Installing the ``telemetrics`` bundle includes the libtelemetry C library, +which exposes an API used by the telemprobd and telempostd daemons. You +can use these in your applications as well. The API documentation is found +in the :file:`telemetry.h` file in `Telemetrics client`_ repository. + +Creating records with telem-record-gen +************************************** + +The telemetrics bundle also provides a record generator tool called +``telem-record-gen``. This tool can be used to create records from shell +scripts, etc., when writing a probe in C is not desirable. Records are sent +to the backend server, and can also be echoed to stdout. + +telem-record-gen usage +====================== + +.. code-block:: bash + + telem-record-gen [OPTIONS] - create and send a custom telemetry record + +.. code-block:: console + + Help Options: + -h, --help Show help options + + Application Options: + -V, --version Print the program version + -s, --severity Severity level (1-4) - (default 1) + -c, --class Classification level_1/level_2/level_3 (required) + -p, --payload Record body (max size = 8k) (required) + -P, --payload-file File to read payload from + -R, --record-version Version number for format of payload (default 1) + -e, --event-id Event id to use in the record + -o, --echo Echo record to stdout + -n, --no-post Do not post record just print + +The :command:`-c` and :command:`-p` options are required; defaults are +supplied for most other options. The maximum payload size is 8k +(8192 bytes). Excess is ignored, regardless of source (file/commandline/ +stdin). An empty payload is allowed, but even an empty payload must be +specified in one of the three ways shown below. + +telem-record-gen examples +========================= + +There are three ways to supply the payload to the record. + +#. On the command line, use the :command:`-p ` option: + + .. code-block:: bash + + telem-record-gen -c a/b/c -n -o -p 'payload goes here' + + .. code-block:: console + + record_format_version: 4 + classification: a/b/c + severity: 1 + machine_id: FFFFFFFF + creation_timestamp: 1539023189 + arch: x86_64 + host_type: innotek GmbH|VirtualBox|1.2 + build: 25180 + kernel_version: 4.14.71-404.lts + payload_format_version: 1 + system_name: clear-linux-os + board_name: VirtualBox|Oracle Corporation + cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz + bios_version: VirtualBox + event_id: 2236710e4fc11e4a646ce956c7802788 + + payload goes here + +#. Specify a file that contains the payload with the option + :command:'-P path/to/file'. + + .. code-block:: bash + + telem-record-gen -c a/b/c -n -o -P ./payload_file.txt + + .. code-block:: console + + record_format_version: 4 + classification: a/b/c + severity: 1 + machine_id: FFFFFFFF + creation_timestamp: 1539023621 + arch: x86_64 + host_type: innotek GmbH|VirtualBox|1.2 + build: 25180 + kernel_version: 4.14.71-404.lts + payload_format_version: 1 + system_name: clear-linux-os + board_name: VirtualBox|Oracle Corporation + cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz + bios_version: VirtualBox + event_id: d73d6040afd7693cccdfece479df9795 + + payload read from file + +#. If the :command:`-p` or :command:`-P` options are absent, the tool reads + from stdin so you can use it in a :file:`heredoc` in scripts. + + .. code-block:: bash + + telem-record-gen -c a/b/c -n -o << HEOF + payload read from stdin + HEOF + + .. code-block:: console + + record_format_version: 4 + classification: a/b/c + severity: 1 + machine_id: FFFFFFFF + creation_timestamp: 1539023621 + arch: x86_64 + host_type: innotek GmbH|VirtualBox|1.2 + build: 25180 + kernel_version: 4.14.71-404.lts + payload_format_version: 1 + system_name: clear-linux-os + board_name: VirtualBox|Oracle Corporation + cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz + bios_version: VirtualBox + event_id: 2f070e8e71679f2b1f28794e3a6c42ee + + payload read from stdin + + .. note:: + + Although only the classification and payload are specified, the tool supplies values for the remaining values. + +Telemetry records and the REST API +================================== + +If you have not configured the telemetry client to keep records locally, you +can view them using the Web UI of the server, or you can query them from the +server using the REST API provided by |CL| telemetrics. The API is +available at :file:`/api/records`, and when queried, returns a JSON +response that contains a list of records. There are several parameters for +filtering queries, similar to the filters available through the telemetryui Records view. + +* classification: The classification of the record +* severity: The severity of the record. Restricted to integer value +* machine_id: The id of the machine where this record was generated on +* build: The build on which the record was generated. Restricted to 256 + characters. +* created_in_days: causes the query to return records created after the last + given days +* created_in_sec: returns the records created after the last given seconds +* limit: The maximum number of records to be returned. + +Next Steps +========== + +* :ref:`telemetry-backend` +* `Telemetrics client`_ + +Related topics +============== + +* :ref:`telemetry-about` + +.. _Telemetrics client: https://github.com/clearlinux/telemetrics-client/ diff --git a/source/clear-linux/reference/bundle-commands.rst b/source/clear-linux/reference/bundle-commands.rst index 47c1f5d2..4b5593d2 100644 --- a/source/clear-linux/reference/bundle-commands.rst +++ b/source/clear-linux/reference/bundle-commands.rst @@ -22,7 +22,7 @@ To search for bundles and their contents, enter: .. code-block:: bash - sudo swupd search [bundle name] + sudo swupd search [bundle name] To add a bundle, enter: @@ -30,14 +30,14 @@ To add a bundle, enter: sudo swupd bundle-add [bundle name] -Additional information +Additional information ====================== For additional :command:`swupd` commands, enter: .. code-block:: bash - swupd --help + swupd --help To reference the :command:`swupd` man page, enter: diff --git a/source/clear-linux/reference/bundles/bundles.html b/source/clear-linux/reference/bundles/bundles.html index 2cfc7caa..1125802f 100644 --- a/source/clear-linux/reference/bundles/bundles.html +++ b/source/clear-linux/reference/bundles/bundles.html @@ -1,53 +1,3 @@ - - Bundles in Clear Linux OS for Intel® Architecture - - - diff --git a/source/clear-linux/reference/bundles/bundles.html.txt b/source/clear-linux/reference/bundles/bundles.html.txt new file mode 100644 index 00000000..c9b36448 --- /dev/null +++ b/source/clear-linux/reference/bundles/bundles.html.txt @@ -0,0 +1,3770 @@ + + + + + + + Bundles in Clear Linux* OS + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Updated: 11/14/18 05:24 UTC +
Name Description
amateur-radioApplications to support amateur radio operations
+ +

Includes bundle(s): + +

  • desktop-gnomelibs
    • + +
  • libX11client
    • + +
  • python3-basic
    • + +

    + +
    ansible Automates software provisioning, configuration management, and application deployment.
    application-serverRun an application server via HTTP
    + +

    Includes bundle(s): + +

  • c-basic
    • + +
  • python3-basic
    • + +
  • web-server-basic
    • + +

    + +
    atomThe popular atom text editor
    + +

    Includes bundle(s): + +

  • desktop-gnomelibs
    • + +

    + +
    audit system audit tools
    axel Download accelerator
    bc basic calculator, an arbitrary-precision calculator language
    big-data-basicTools and frameworks for big data management
    + +

    Includes bundle(s): + +

  • R-basic
    • + +
  • java-basic
    • + +
  • python3-basic
    • + +

    + +
    bmap-tools Tools for creating the block map (bmap) for a file and copying files. Alternative to "dd" or "cp"
    bootloaderLoads kernel from disk and boots the system
    + +
    bootloader-extrasExtra packages to decrypt root partition
    + +
    borgbackup Deduplicating archiver with compression and authenticated encryption.
    c-basicBuild and run C/C++ language programs
    + +

    Includes bundle(s): + +

  • perl-basic
    • + +

    + +
    c-basic-legacyBuild and run 32bit C/C++ language programs
    + +
    casync Content Addressable Data Synchronizer, to distribute frequently-updated file system images over the Internet
    clamav Clam AntiVirus is an anti-virus toolkit for Unix
    cloud-apiAPI helpers for cloud access
    + +

    Includes bundle(s): + +

  • python3-basic
    • + +

    + +
    cloud-controlRun a cloud orchestration server
    + +

    Includes bundle(s): + +

  • kvm-host
    • + +
  • network-basic
    • + +
  • openssl
    • + +
  • python3-basic
    • + +
  • cloud-api
    • + +
  • storage-cluster
    • + +
  • sudo
    • + +

    + +
    cloud-native-basicContains ClearLinux native software for Cloud
    + +

    Includes bundle(s): + +

  • containers-virt
    • + +
  • ethtool
    • + +

    + +
    clr-devopsRun all Clear Linux devops workloads
    + +

    Includes bundle(s): + +

  • os-installer
    • + +
  • os-core-update
    • + +
  • mixer
    • + +
  • java-basic
    • + +
  • rust-basic
    • + +
  • koji
    • + +
  • scm-server
    • + +
  • web-server-basic
    • + +

    + +
    clr-installerImage creation and installation for Clear Linux OS
    + +

    Includes bundle(s): + +

  • curl
    • + +
  • iproute2
    • + +
  • kbd
    • + +
  • locales
    • + +
  • openssh-server
    • + +
  • telemetrics
    • + +
  • tzdata
    • + +
  • wpa_supplicant
    • + +

    + +
    cockpit Web based administration for GNU/Linux servers
    computer-vision-basicBuild computer vision applications
    + +

    Includes bundle(s): + +

  • cloud-api
    • + +
  • computer-vision-models
    • + +
  • python-extras
    • + +
  • python-data-science
    • + +
  • python2-basic
    • + +

    + +
    computer-vision-modelsDeep learning models for computer vision
    + +
    containers-basicRun container applications from Dockerhub
    + +

    Includes bundle(s): + +

  • iproute2
    • + +
  • p11-kit
    • + +

    + +
    containers-basic-devAll packages required to build the containers-basic bundle.
    + +

    Includes bundle(s): + +

  • containers-basic
    • + +
  • dev-utils
    • + +
  • os-core-dev
    • + +

    + +
    containers-virtRun container applications from Dockerhub in lightweight virtual machines
    + +

    Includes bundle(s): + +

  • containers-basic
    • + +

    + +
    containers-virt-devAll packages required to build the containers-virt bundle.
    + +

    Includes bundle(s): + +

  • containers-basic-dev
    • + +
  • containers-virt
    • + +
  • dev-utils
    • + +
  • os-core-dev
    • + +

    + +
    cpio File archiver utility
    cryptographyEncrypt, decrypt, sign and verify objects
    + +

    Includes bundle(s): + +

  • openssl
    • + +

    + +
    cryptoprocessor-managementManage the Trusted Platform Module (TPM)
    + +

    Includes bundle(s): + +

  • TPM
    • + +

    + +
    curl Transfer data to/from a URL
    darktable Photography workflow application
    database-basicRun a SQL database
    + +

    Includes bundle(s): + +

  • python3-basic
    • + +

    + +
    database-basic-devAll packages required to build the database-basic bundle.
    + +

    Includes bundle(s): + +

  • database-basic
    • + +
  • dev-utils
    • + +
  • os-core-dev
    • + +

    + +
    desktopRun the GNOME GUI desktop environment
    + +

    Includes bundle(s): + +

  • libX11client
    • + +
  • x11-server
    • + +
  • desktop-apps
    • + +
  • desktop-gnomelibs
    • + +
  • desktop-assets
    • + +
  • desktop-locales
    • + +
  • openssl
    • + +
  • sysadmin-basic
    • + +
  • which
    • + +
  • wpa_supplicant
    • + +

    + +
    desktop-appsApplications for the desktop
    + +

    Includes bundle(s): + +

  • libX11client
    • + +
  • desktop-gnomelibs
    • + +
  • python3-basic
    • + +
  • xemacs
    • + +

    + +
    desktop-apps-extrasLarger set of applications for the desktop
    + +

    Includes bundle(s): + +

  • desktop-gnomelibs
    • + +
  • desktop-kde-apps
    • + +
  • python3-basic
    • + +
  • atom
    • + +
  • darktable
    • + +
  • gimp
    • + +
  • thunderbird
    • + +
  • vlc
    • + +

    + +
    desktop-assetsImages and Icons for the desktop
    + +

    Includes bundle(s): + +

  • desktop-gnomelibs
    • + +

    + +
    desktop-autostartBundle to cause the UI to automatically start at boot
    + +

    Includes bundle(s): + +

  • desktop
    • + +

    + +
    desktop-awesomeRun a minimal desktop environment with awesome WM
    + +

    Includes bundle(s): + +

  • x11-server
    • + +

    + +
    desktop-devAll packages required to build the desktop bundle.
    + +

    Includes bundle(s): + +

  • desktop
    • + +
  • dev-utils
    • + +
  • os-core-dev
    • + +
  • sysadmin-basic-dev
    • + +

    + +
    desktop-gnomelibsHelper bundle with common libraries used by desktopy things
    + +

    Includes bundle(s): + +

  • libX11client
    • + +

    + +
    desktop-i3Run the i3 desktop environment
    + +

    Includes bundle(s): + +

  • x11-server
    • + +

    + +
    desktop-kdeApplications for the desktop from the KDE ecosystem
    + +

    Includes bundle(s): + +

  • desktop-kde-libs
    • + +
  • desktop-kde-apps
    • + +
  • qt-basic
    • + +
  • x11-tools
    • + +
  • x11-server
    • + +

    + +
    desktop-kde-appsApplications for the desktop from the KDE ecosystem
    + +

    Includes bundle(s): + +

  • desktop-kde-libs
    • + +
  • qt-basic
    • + +

    + +
    desktop-kde-libsHelper libraries from the KDE ecosystem
    + +

    Includes bundle(s): + +

  • qt-basic
    • + +

    + +
    desktop-localestranslations and documentation for desktop components
    + +
    dev-utilsAssist application development
    + +

    Includes bundle(s): + +

  • git
    • + +
  • openssl
    • + +
  • perl-basic
    • + +
  • python3-basic
    • + +

    + +
    dev-utils-devAll packages required to build the dev-utils bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • os-core-dev
    • + +
  • perl-basic-dev
    • + +

    + +
    dfu-util Device Firmware Upgrade Utilities
    dhcp-serverRun a dhcp server
    + +
    diffoscope In-depth comparison of files, archives, and directories
    diffutils Tools for file comparisons and differences
    docutils Tools for converting text to other formats (e.g. HTML, XML, LaTeX)
    domoticaHome Automation software collection
    + +

    Includes bundle(s): + +

  • cloud-api
    • + +
  • python3-basic
    • + +

    + +
    dovecot Security focused IMAP and POP3 email server
    dtc Device Tree Compiler, to describe non-discoverable hardware
    duperemove Tool for finding duplicated extents and submitting them for deduplication
    editorsRun popular terminal text editors
    + +

    Includes bundle(s): + +

  • emacs
    • + +
  • joe
    • + +
  • vim
    • + +

    + +
    editors-devAll packages required to build the editors bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • editors
    • + +
  • os-core-dev
    • + +

    + +
    educationEducational applications
    + +

    Includes bundle(s): + +

  • desktop-gnomelibs
    • + +
  • desktop-kde-libs
    • + +
  • libX11client
    • + +
  • qt-basic
    • + +
  • education-preschool
    • + +
  • education-primary
    • + +
  • education-secondary
    • + +
  • education-tertiary
    • + +

    + +
    education-preschoolEducational applications for the preschool level
    + +

    Includes bundle(s): + +

  • desktop-gnomelibs
    • + +
  • desktop-kde-libs
    • + +
  • libX11client
    • + +
  • qt-basic
    • + +

    + +
    education-primaryEducational applications for the primary school level
    + +

    Includes bundle(s): + +

  • desktop-gnomelibs
    • + +
  • desktop-kde-libs
    • + +
  • libX11client
    • + +
  • qt-basic
    • + +

    + +
    education-secondaryEducational applications for the secondary school level
    + +

    Includes bundle(s): + +

  • desktop-gnomelibs
    • + +
  • desktop-kde-libs
    • + +
  • libX11client
    • + +
  • qt-basic
    • + +

    + +
    education-tertiaryEducational applications for the tertiary school/university level
    + +

    Includes bundle(s): + +

  • desktop-gnomelibs
    • + +
  • desktop-kde-libs
    • + +
  • libX11client
    • + +
  • qt-basic
    • + +

    + +
    emacsThe popular emacs terminal text editor
    + +
    enterprise-loginEnable enterprise login systems like Active Directory
    + +
    ethtool Utility for displaying and modifying some parameters of network interface controller
    file program for recognizing the type of data contained in a computer file
    findutils basic directory searching utilities e.g. find, xargs, and locate
    fio Flexible I/O tester
    firefox Web Browser
    firmware-updateUpdate the system's firmware
    + +

    Includes bundle(s): + +

  • cryptography
    • + +
  • libX11client
    • + +

    + +
    flatpakUse flatpak packages, or build them
    + +
    fwupdate Firmware update tool
    gamesPlay games in Clear Linux
    + +

    Includes bundle(s): + +

  • libX11client
    • + +
  • p11-kit
    • + +

    + +
    games-devAll packages required to build the games bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • games
    • + +
  • os-core-dev
    • + +

    + +
    gdb GNU debugger
    gftp Text mode and GUI FTP Client
    gimp GNU Image Manipulation Program
    gitgit SCM tool
    + +

    Includes bundle(s): + +

  • openssl
    • + +
  • p11-kit
    • + +

    + +
    glmark2 OpenGL 2.0 and ES 2.0 benchmark
    go-basicBuild and run go language programs
    + +

    Includes bundle(s): + +

  • git
    • + +
  • p11-kit
    • + +

    + +
    go-basic-devAll packages required to build the go-basic bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • go-basic
    • + +
  • os-core-dev
    • + +

    + +
    goaccess Real-time web log analyzer
    gzip lossless data compression/decompression utility
    hardware-bluetoothSoftware to enable use of bluetooth hardware
    + +
    hardware-wifiFirmware and tools for basic wifi support
    + +
    haskell-basicBuild and run haskell language programs
    + +

    Includes bundle(s): + +

  • git
    • + +
  • p11-kit
    • + +
  • perl-basic
    • + +
  • c-basic
    • + +

    + +
    hpc-utilsProvide userspace management programs for various HPC related programs.
    + +

    Includes bundle(s): + +

  • perl-basic
    • + +

    + +
    htop interactive text-mode process viewer
    httpd Apache HyperText Transfer Protocol (HTTP) Server daemon
    hugo Static Web site generator
    iasimage for creating Intel Automotive Service (IAS) images, a binary file format understood by Intel© Slim Bootloader
    icdiff Improved Color Differences between similar files
    iftop display bandwidth usage on an interface
    ImageMagickImageMagick
    + +

    Includes bundle(s): + +

  • libX11client
    • + +

    + +
    inotify-tools monitor for file system events
    iproute2 utilities for controlling TCP / IP networking and traffic control
    ipvsadm used to set up, maintain or inspect the virtual server table in the Linux kernel
    irssi Internet Relay Chat (IRC) client program
    java-basicBuild and run java language programs
    + +

    Includes bundle(s): + +

  • libX11client
    • + +
  • p11-kit
    • + +
  • python3-basic
    • + +
  • which
    • + +

    + +
    java-runtimeRun java language programs
    + +

    Includes bundle(s): + +

  • libX11client
    • + +

    + +
    java9-basicBuild and run java9 language programs
    + +

    Includes bundle(s): + +

  • libX11client
    • + +
  • p11-kit
    • + +
  • python3-basic
    • + +
  • which
    • + +

    + +
    joe Text editor
    jq lightweight and flexible command-line JSON processor
    kbd library to manage the Linux keymaps
    keepalived strong & robust keepalive facility for the Linux Virtual Server project
    keepassxc KeePassXC is a password manager
    kernel-awsRun the kvm specific kernel
    + +

    Includes bundle(s): + +

  • bootloader
    • + +

    + +
    kernel-containerRun the container specific kernel
    + +
    kernel-gceRun the kvm specific kernel
    + +

    Includes bundle(s): + +

  • bootloader
    • + +

    + +
    kernel-hypervRun the hyperv specific kernel
    + +

    Includes bundle(s): + +

  • bootloader
    • + +

    + +
    kernel-hyperv-ltsRun the hyperv specific LTS kernel
    + +

    Includes bundle(s): + +

  • bootloader
    • + +

    + +
    kernel-hyperv-miniRun the hyperv mini-os specific kernel
    + +

    Includes bundle(s): + +

  • kernel-hyperv
    • + +

    + +
    kernel-install installs kernel, initrd, kernel config and system map and creates a bootloader entry for the new kernel
    kernel-iot-lts2017-preempt-rtRun the Intel "PK" kernel, an enterprise-style kernel with backports, plus PREEMPT_RT support
    + +

    Includes bundle(s): + +

  • bootloader
    • + +

    + +
    kernel-iot-lts2018Run the Intel "PK" kernel, and enterprise-style kernel with backports
    + +

    Includes bundle(s): + +

  • bootloader
    • + +

    + +
    kernel-kvmRun the kvm specific kernel
    + +

    Includes bundle(s): + +

  • bootloader
    • + +

    + +
    kernel-ltsRun the lts native kernel
    + +

    Includes bundle(s): + +

  • bootloader
    • + +

    + +
    kernel-nativeRun the native kernel
    + +

    Includes bundle(s): + +

  • bootloader
    • + +

    + +
    kernel-oracleRun the Oracle Cloud specific kernel
    + +

    Includes bundle(s): + +

  • bootloader
    • + +

    + +
    kernel-pkRun the Intel "PK" kernel, and enterprise-style kernel with backports
    + +

    Includes bundle(s): + +

  • bootloader
    • + +

    + +
    kernel-rtRun the native kernel with preempt_rt patchset
    + +

    Includes bundle(s): + +

  • bootloader
    • + +

    + +
    keychain manage SSH and GPG keys
    kojiSets up a koji build service based on NFS mounts.
    + +

    Includes bundle(s): + +

  • package-utils
    • + +
  • python2-basic
    • + +
  • web-server-basic
    • + +

    + +
    kvm-hostRun virtual machines
    + +

    Includes bundle(s): + +

  • libX11client
    • + +

    + +
    kvm-host-devAll packages required to build the kvm-host bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • kvm-host
    • + +
  • os-core-dev
    • + +

    + +
    kvm-host-extrasRun virtual machines as deployed infrastructure
    + +

    Includes bundle(s): + +

  • kvm-host
    • + +
  • python3-basic
    • + +

    + +
    letsencrypt-clientObtain and renew valid SSL certificates through Let's Encrypt's ACME service.
    + +

    Includes bundle(s): + +

  • python3-basic
    • + +
  • cloud-api
    • + +

    + +
    lftp File transfer client for http, ftp, sftp and more
    libva-utils collection of utilities and examples to exercise VA-API (Video Acceleration API)
    libX11clientGrouping only bundle for use in X using bundles
    + +
    lightdmLightDM login manager with GTK greeter
    + +
    linux-dev programs for developing Linux
    linux-tools Tools for use in Linux
    localesbasic system translations
    + +
    logrotate manages the automatic rotation and compression of log files
    lua-basicLua programming language
    + +
    machine-learning-basicBuild machine learning applications
    + +

    Includes bundle(s): + +

  • c-basic
    • + +
  • cloud-api
    • + +
  • python-extras
    • + +
  • python-data-science
    • + +
  • computer-vision-basic
    • + +
  • machine-learning-mycroft
    • + +
  • machine-learning-tensorflow
    • + +

    + +
    machine-learning-mycroftBuild machine learning applications with mycroft
    + +

    Includes bundle(s): + +

  • python-data-science
    • + +

    + +
    machine-learning-tensorflowBuild machine learning applications using Tensorflow
    + +

    Includes bundle(s): + +

  • cloud-api
    • + +
  • python-data-science
    • + +

    + +
    machine-learning-web-uiWeb based, interactive tools for machine learning
    + +

    Includes bundle(s): + +

  • cloud-api
    • + +
  • R-extras
    • + +
  • python3-basic
    • + +
  • python-data-science
    • + +

    + +
    mail-utilsProcess, read and send email
    + +

    Includes bundle(s): + +

  • python2-basic
    • + +

    + +
    mail-utils-devAll packages required to build the mail-utils bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • mail-utils
    • + +
  • os-core-dev
    • + +

    + +
    make build automation tool
    meld visual file difference and merging tool, targeted at developers
    mercurialmercurial SCM tool
    + +

    Includes bundle(s): + +

  • python3-basic
    • + +

    + +
    mixerCreate Clear Linux releases
    + +

    Includes bundle(s): + +

  • containers-basic
    • + +
  • git
    • + +
  • openssl
    • + +
  • os-installer
    • + +
  • python3-basic
    • + +
  • sysadmin-basic
    • + +
  • zstd
    • + +

    + +
    mkosi generate disk images
    mtr Poll a remote server and see how the latency and performance changes over time
    ncdu curses disk space usage management tool
    network-basicRun network utilities and modify network settings
    + +

    Includes bundle(s): + +

  • ethtool
    • + +
  • iproute2
    • + +
  • openssl
    • + +
  • perl-basic
    • + +
  • python3-basic
    • + +
  • wpa_supplicant
    • + +

    + +
    network-basic-devAll packages required to build the network-basic bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • network-basic
    • + +
  • os-core-dev
    • + +
  • perl-basic-dev
    • + +

    + +
    network-security-monitoringVarious tools to test and improve network security
    + +

    Includes bundle(s): + +

  • network-basic
    • + +

    + +
    network-time-sensitiveVarious tools and plugins to set up TSN/TCC
    + +

    Includes bundle(s): + +

  • network-basic
    • + +

    + +
    nfs-utils Server and client tooling for network file systems (NFS)
    nginx HTTP server, reverse proxy, IMAP/POP3 proxy server
    nodejs-basicRun javascript server side
    + +
    octave high-level programming language, primarily intended for numerical computations
    openqaOpenQA infrastructure
    + +

    Includes bundle(s): + +

  • kvm-host
    • + +
  • perl-basic
    • + +
  • postgresql
    • + +
  • web-server-basic
    • + +

    + +
    openssh-serverRun an ssh server
    + +
    openssl Toolkit for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols
    openstack-commonGrouping bundle used by all openstack using bundles
    + +

    Includes bundle(s): + +

  • perl-basic
    • + +
  • python3-basic
    • + +

    + +
    os-clear-containersControl Clear Containers guest setup and workloads
    + +
    os-cloudguestRun any initialization processes required of a generic cloud guest VM
    + +

    Includes bundle(s): + +

  • ethtool
    • + +
  • openssh-server
    • + +
  • sudo
    • + +

    + +
    os-cloudguest-awsRun any initialization processes required of an AWS cloud guest VM
    + +

    Includes bundle(s): + +

  • sudo
    • + +

    + +
    os-cloudguest-azureRun any initialization process requried of an Azure cloud guest VM
    + +

    Includes bundle(s): + +

  • ethtool
    • + +
  • openssh-server
    • + +
  • openssl
    • + +
  • python3-basic
    • + +
  • sudo
    • + +

    + +
    os-cloudguest-gceRun any initialization processes required of an GCE cloud guest VM
    + +

    Includes bundle(s): + +

  • sudo
    • + +
  • which
    • + +

    + +
    os-cloudguest-oracleRun any initialization processes required of an Oracle Cloud guest
    + +

    Includes bundle(s): + +

  • openssh-server
    • + +
  • sudo
    • + +

    + +
    os-cloudguest-vmwareRun any initialization processes required for VMWare VMs
    + +
    os-clr-on-clrRun any process required for Clear Linux development
    + +

    Includes bundle(s): + +

  • c-basic
    • + +
  • dev-utils
    • + +
  • dev-utils-dev
    • + +
  • editors
    • + +
  • go-basic
    • + +
  • koji
    • + +
  • kvm-host
    • + +
  • mail-utils
    • + +
  • mail-utils-dev
    • + +
  • mixer
    • + +
  • network-basic
    • + +
  • network-basic-dev
    • + +
  • openssh-server
    • + +
  • os-core
    • + +
  • os-core-dev
    • + +
  • os-core-update-dev
    • + +
  • package-builder
    • + +
  • perl-basic
    • + +
  • python3-basic
    • + +
  • storage-utils
    • + +
  • storage-utils-dev
    • + +
  • sysadmin-basic
    • + +
  • sysadmin-basic-dev
    • + +

    + +
    os-clr-on-clr-devAll packages required to build the os-clr-on-clr bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • dev-utils-dev
    • + +
  • editors-dev
    • + +
  • go-basic-dev
    • + +
  • kvm-host-dev
    • + +
  • mail-utils-dev
    • + +
  • network-basic-dev
    • + +
  • os-clr-on-clr
    • + +
  • os-core-dev
    • + +
  • perl-basic-dev
    • + +
  • storage-utils-dev
    • + +
  • sysadmin-basic-dev
    • + +

    + +
    os-coreRun a minimal Linux userspace
    + +
    os-core-devAll packages required to build the os-core bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +

    + +
    os-core-updateProvides basic suite for running the Clear Linux for iA Updater
    + +

    Includes bundle(s): + +

  • os-core
    • + +

    + +
    os-core-update-devAll packages required to build the os-core-update bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • os-core-dev
    • + +
  • os-core-update
    • + +

    + +
    os-installerRun image creation and installation for Clear Linux
    + +

    Includes bundle(s): + +

  • iproute2
    • + +
  • python3-basic
    • + +
  • wpa_supplicant
    • + +

    + +
    os-testsuiteProvides minimal functionality for core testing functions
    + +

    Includes bundle(s): + +

  • git
    • + +
  • openssh-server
    • + +

    + +
    os-testsuite-0dayHelpers for the 0day kernel testing framework
    + +

    Includes bundle(s): + +

  • c-basic
    • + +
  • dev-utils
    • + +
  • python3-basic
    • + +
  • perl-basic
    • + +

    + +
    os-testsuite-phoronixRun the Phoronix testsuite
    + +

    Includes bundle(s): + +

  • os-testsuite-phoronix-desktop
    • + +
  • os-testsuite-phoronix-server
    • + +
  • R-basic
    • + +
  • c-basic
    • + +
  • database-basic
    • + +
  • desktop-apps-extras
    • + +
  • desktop-autostart
    • + +
  • games
    • + +
  • git
    • + +
  • go-basic
    • + +
  • java-basic
    • + +
  • machine-learning-basic
    • + +
  • octave
    • + +
  • php-basic
    • + +
  • python3-basic
    • + +
  • qt-basic-dev
    • + +

    + +
    os-testsuite-phoronix-desktopRun the Phoronix testsuite (desktop version)
    + +

    Includes bundle(s): + +

  • desktop version
    • + +
  • c-basic
    • + +
  • git
    • + +
  • desktop-autostart
    • + +
  • desktop-apps-extras
    • + +
  • php-basic
    • + +
  • games
    • + +
  • python3-basic
    • + +
  • python2-basic
    • + +
  • qt-basic-dev
    • + +

    + +
    os-testsuite-phoronix-serverRun the Phoronix testsuite (server version)
    + +

    Includes bundle(s): + +

  • server version
    • + +
  • c-basic
    • + +
  • database-basic
    • + +
  • git
    • + +
  • go-basic
    • + +
  • nodejs-basic
    • + +
  • octave
    • + +
  • php-basic
    • + +
  • python3-basic
    • + +
  • python2-basic
    • + +

    + +
    os-utils-guiProvides a graphical desktop environment
    + +

    Includes bundle(s): + +

  • cryptography
    • + +
  • openssl
    • + +
  • python3-basic
    • + +
  • wpa_supplicant
    • + +
  • xfce4-desktop
    • + +
  • xemacs
    • + +
  • darktable
    • + +
  • thunderbird
    • + +
  • x11-server
    • + +

    + +
    os-utils-gui-devAll packages required to build the os-utils-gui bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • os-core-dev
    • + +
  • os-utils-gui
    • + +

    + +
    p11-kit Load and enumerate PKCS#11 modules for cryptography
    package-builderMinimal bundle for building packages via Clearlinux common tooling
    + +

    Includes bundle(s): + +

  • curl
    • + +
  • diffutils
    • + +
  • git
    • + +
  • package-utils
    • + +
  • sudo
    • + +

    + +
    package-utilsUtilities for creating, building, and managing packages
    + +

    Includes bundle(s): + +

  • python3-basic
    • + +
  • python2-basic
    • + +

    + +
    parallel shell tool for executing jobs in parallel using one or more computers
    patch updates text files according to instructions contained in a separate file
    performance-toolsRun performance and power measurements
    + +

    Includes bundle(s): + +

  • ethtool
    • + +
  • iproute2
    • + +
  • perl-basic
    • + +
  • python3-basic
    • + +
  • tcl-basic
    • + +

    + +
    perl-basicRun perl language programs
    + +
    perl-basic-devAll packages required to build the perl-basic bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • os-core-dev
    • + +
  • perl-basic
    • + +

    + +
    perl-extrasImprove user experience with a common set of prebuilt perl libraries
    + +

    Includes bundle(s): + +

  • perl-basic
    • + +

    + +
    php-basicRun php language programs
    + +
    pmdk tools and libraries for working with non-volatile memory
    pnp-tools-basicRun performance and power measurements
    + +
    postgresql Database
    powertop diagnose issues with power consumption and power management
    productivityA set of console utilities for task management and communication
    + +

    Includes bundle(s): + +

  • mail-utils
    • + +
  • python3-basic
    • + +

    + +
    pwgen generates passwords which are designed to be easily memorized by humans, while being as secure as possible.
    pxe-serverRun a PXE server
    + +

    Includes bundle(s): + +

  • python3-basic
    • + +

    + +
    python-basicRun python language programs
    + +

    Includes bundle(s): + +

  • p11-kit
    • + +
  • python2-basic
    • + +
  • python3-basic
    • + +

    + +
    python-basic-devAll packages required to build the python-basic bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • os-core-dev
    • + +
  • python-basic
    • + +

    + +
    python-data-scienceThe python data-science stack; the best of http://pydata.org
    + +

    Includes bundle(s): + +

  • c-basic
    • + +
  • python-extras
    • + +

    + +
    python-extrasImprove user experience with a common set of prebuilt python libraries
    + +

    Includes bundle(s): + +

  • python3-basic
    • + +
  • cloud-api
    • + +

    + +
    python2-basicRun legacy python language programs
    + +

    Includes bundle(s): + +

  • p11-kit
    • + +

    + +
    python3-basicRun python language programs
    + +

    Includes bundle(s): + +

  • p11-kit
    • + +

    + +
    qt-basicRun programs that use the QT runtime
    + +
    qt-basic-devAll packages required to build the qt-basic bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • os-core-dev
    • + +
  • qt-basic
    • + +

    + +
    quasselQuassel IRC
    + +

    Includes bundle(s): + +

  • libX11client
    • + +
  • qt-basic
    • + +

    + +
    R-basicRun R language programs
    + +

    Includes bundle(s): + +

  • libX11client
    • + +
  • plotting, help navigation, etc
    • + +

    + +
    R-datasetsLarge datasets for R
    + +

    Includes bundle(s): + +

  • R-basic
    • + +

    + +
    R-extrasImprove the user experience with a common set of prebuilt R libraries
    + +

    Includes bundle(s): + +

  • R-basic
    • + +
  • R-datasets
    • + +

    + +
    redis-native key-value database
    ruby-basicRun ruby language programs
    + +

    Includes bundle(s): + +

  • p11-kit
    • + +

    + +
    runtime-libs-boostBasic C++ / Boost runtime libraries
    + +
    rust-basicBuild and run rust language programs
    + +

    Includes bundle(s): + +

  • git
    • + +
  • p11-kit
    • + +

    + +
    scm-serverRun a source code management server
    + +

    Includes bundle(s): + +

  • git
    • + +
  • python3-basic
    • + +

    + +
    service-osProvides the needed software for Service OS
    + +

    Includes bundle(s): + +

  • bootloader
    • + +
  • python3-basic
    • + +

    + +
    service-os-devAll packages required to build the service-os bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • os-core-dev
    • + +
  • service-os
    • + +

    + +
    shellsRun a shell
    + +
    software-defined-cockpitRun the automotive software defined cockpit which has graphic, media, sound and connectivity
    + +

    Includes bundle(s): + +

  • wpa_supplicant
    • + +

    + +
    software-defined-cockpit-devAll packages required to build the software-defined-cockpit bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • os-core-dev
    • + +
  • software-defined-cockpit
    • + +

    + +
    software-testingSoftware to run or create test suites
    + +

    Includes bundle(s): + +

  • perl-basic
    • + +
  • python-basic
    • + +

    + +
    storage-clusterRun a storage server
    + +

    Includes bundle(s): + +

  • python3-basic
    • + +
  • python2-basic
    • + +

    + +
    storage-utilsRun disk and filesystem management functions
    + +
    storage-utils-devAll packages required to build the storage-utils bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • os-core-dev
    • + +
  • storage-utils
    • + +

    + +
    strace System call diagnostic, instructional, and debugging tool
    stream-serverRun an audio or visual streaming server
    + +
    subversion Version Control System
    sudo allows a user to run a program as another user
    suricata network threat detection engine
    synergyKeyboard and mouse sharing across networks
    + +

    Includes bundle(s): + +

  • qt-basic
    • + +
  • postgresql
    • + +

    + +
    sysadmin-basicRun common utilities useful for managing a system
    + +

    Includes bundle(s): + +

  • iproute2
    • + +
  • p11-kit
    • + +
  • sudo
    • + +
  • which
    • + +

    + +
    sysadmin-basic-devAll packages required to build the sysadmin-basic bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • os-core-dev
    • + +
  • sysadmin-basic
    • + +

    + +
    sysadmin-hostmgmtUtilities and Services for managing large-scale clusters of networked hosts
    + +

    Includes bundle(s): + +

  • git
    • + +
  • pxe-server
    • + +
  • python3-basic
    • + +

    + +
    sysadmin-remoteEnable the host to be managed remotely by configuration management tools
    + +

    Includes bundle(s): + +

  • openssh-server
    • + +
  • python3-basic
    • + +
  • cockpit
    • + +
  • sudo
    • + +

    + +
    systemd-cryptsetupDummy bundle to avoid rolling back systemd, will be removed at next format bump
    + +
    tcl-basicRun tk/tcl language programs
    + +

    Includes bundle(s): + +

  • libX11client
    • + +

    + +
    telemetricsRun telemetrics client
    + +
    texlive major TeX-related typesetting programs, macro packages, and fonts.
    thunderbird Email client
    time-server-basicRun an NTP server
    + +
    tmux terminal multiplexer (similar to screen)
    tzdata timezone database
    unison bidirectional file synchronization tool
    unzip list, test, or extract files from a ZIP archive
    user-basicMeta bundle capturing most console user work flows
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • editors
    • + +
  • kvm-host
    • + +
  • mail-utils
    • + +
  • network-basic
    • + +
  • openssh-server
    • + +
  • os-core-update
    • + +
  • shells
    • + +
  • storage-utils
    • + +
  • sysadmin-basic
    • + +

    + +
    user-basic-devAll packages required to build the user-basic bundle.
    + +

    Includes bundle(s): + +

  • dev-utils
    • + +
  • dev-utils-dev
    • + +
  • editors-dev
    • + +
  • kvm-host-dev
    • + +
  • mail-utils-dev
    • + +
  • network-basic-dev
    • + +
  • os-core-dev
    • + +
  • os-core-update-dev
    • + +
  • storage-utils-dev
    • + +
  • sysadmin-basic-dev
    • + +
  • user-basic
    • + +

    + +
    valgrind suite of tools for debugging and profiling software code
    vimThe popular vim text editor
    + +

    Includes bundle(s): + +

  • python3-basic
    • + +
  • perl-basic
    • + +

    + +
    virt-managerVirtualization Management tool
    + +

    Includes bundle(s): + +

  • desktop-gnomelibs
    • + +
  • libX11client
    • + +

    + +
    vlc VideoLAN Client, multimedia player and framework
    vnc-serverEnable the host to be a vnc desktop server
    + +

    Includes bundle(s): + +

  • desktop
    • + +
  • openssh-server
    • + +

    + +
    web-server-basicRun a HTTP web server
    + +
    weechat Internet Relay Chat (IRC) client
    weston-extras Utilities and tools for the Wayland graphics compositor
    which locate executables in the system
    wiresharkNetwork packet capture and analysis
    + +

    Includes bundle(s): + +

  • postgresql
    • + +
  • qt-basic
    • + +

    + +
    wpa_supplicant backend component controlling the wireless connections
    x11-serverProvide a functional X11 Server (Xorg or wayland-based)
    + +

    Includes bundle(s): + +

  • Xorg or wayland-based
    • + +
  • libX11client
    • + +

    + +
    x11-toolsTools useful when running under X11
    + +

    Includes bundle(s): + +

  • libX11client
    • + +

    + +
    xemacs text editor and application development system
    xfce4-desktopRun GUI desktop environment
    + +

    Includes bundle(s): + +

  • libX11client
    • + +
  • which
    • + +

    + +
    xz data compression/decompression tool
    zsh Z Shell, an interactive shell and powerful command-line interpreter for scripting language
    zstd realtime data compression/decompression tool
    + + + \ No newline at end of file diff --git a/source/clear-linux/reference/bundles/bundles.rst b/source/clear-linux/reference/bundles/bundles.rst index 26c3acb9..257ff43f 100644 --- a/source/clear-linux/reference/bundles/bundles.rst +++ b/source/clear-linux/reference/bundles/bundles.rst @@ -3,13 +3,12 @@ Available bundles ################# -This document provides a current list of `available bundles`_ as -of ``12 September 2018``. +This document provides a current list of `available bundles`_. To learn more about how |CL-ATTR| uses bundles for software deployment, visit :ref:`bundles-about`. Bundle list =========== .. raw:: html - :file: bundles.html + :file: bundles.html.txt .. _available bundles: https://github.com/clearlinux/clr-bundles diff --git a/source/clear-linux/reference/collaboration/collaboration.rst b/source/clear-linux/reference/collaboration/collaboration.rst index 33229831..341d5c91 100644 --- a/source/clear-linux/reference/collaboration/collaboration.rst +++ b/source/clear-linux/reference/collaboration/collaboration.rst @@ -3,7 +3,7 @@ Collaboration guidelines ######################## -Thank you for your interest in collaborating with the |CLOSIA|. This guide +Thank you for your interest in collaborating with the |CL-ATTR|. This guide details the best ways to collaborate with the |CL| team. Additionally, this guide provides the guidelines our documentation follows. Thus, you can help improve our documents with your use case tutorials, diff --git a/source/clear-linux/reference/collaboration/documentation/code.rst b/source/clear-linux/reference/collaboration/documentation/code.rst index 9490e75b..870faeba 100644 --- a/source/clear-linux/reference/collaboration/documentation/code.rst +++ b/source/clear-linux/reference/collaboration/documentation/code.rst @@ -3,7 +3,7 @@ Code blocks ########### -Collaborating to the |CLOSIA| is all about code. Therefore, your +Contributing to the |CL-ATTR| is all about code. Therefore, your documentation must include as many code examples as possible. You can write code examples directly in the documentation or include them from a source file. Use these guidelines to insert code blocks to your documentation: diff --git a/source/clear-linux/reference/collaboration/documentation/contents.rst b/source/clear-linux/reference/collaboration/documentation/contents.rst index e88c4d7c..248053b4 100644 --- a/source/clear-linux/reference/collaboration/documentation/contents.rst +++ b/source/clear-linux/reference/collaboration/documentation/contents.rst @@ -4,7 +4,7 @@ Contents directive ################## -For |CL| documentation that has three or more sections, use the `contents::` +For |CL-ATTR| documentation that has three or more sections, use the `contents::` directive as shown in the example below. This directive automatically captures the headings (and subheadings if used) as specified in the value given after `:depth:`. Adding this directive to longer documents allows users to quickly navigate to the desired section. @@ -24,8 +24,8 @@ longer documents allows users to quickly navigate to the desired section. EXAMPLE: -Clear Linux Guide Example -************************* +Guide Example +************* Introduction ============ diff --git a/source/clear-linux/reference/collaboration/documentation/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst index 4f5efc2a..6780dde1 100644 --- a/source/clear-linux/reference/collaboration/documentation/cross.rst +++ b/source/clear-linux/reference/collaboration/documentation/cross.rst @@ -12,7 +12,7 @@ consistency of the documents. Internal cross-references ************************* -An internal cross-reference is a reference to a location within the |CLOSIA| +An internal cross-reference is a reference to a location within the |CL-ATTR| documentation. Use explicit markup labels and the ``:ref:`` role to create cross references to headings, figures, and code examples as needed. Every file must have a label before the title, which is identical to the file's @@ -127,7 +127,7 @@ Use this template to add a hyperlink with a separated definition: The include directive ********************* -Clear Linux documentation also uses the ``.. include::`` +|CL| documentation also uses the ``.. include::`` directive to include a portion of another reST file. Use the ``.. include::`` directive to show a select portion of a file. diff --git a/source/clear-linux/reference/collaboration/documentation/documentation.rst b/source/clear-linux/reference/collaboration/documentation/documentation.rst index c9040c58..15056a84 100644 --- a/source/clear-linux/reference/collaboration/documentation/documentation.rst +++ b/source/clear-linux/reference/collaboration/documentation/documentation.rst @@ -3,7 +3,7 @@ Documentation contribution guidelines ##################################### -The |CLOSIA| documentation contribution guidelines provide detailed information +The |CL-ATTR| documentation contribution guidelines provide detailed information about the scope and purpose of the documentation, the accepted writing style, and the markup used. diff --git a/source/clear-linux/reference/collaboration/documentation/grammar.rst b/source/clear-linux/reference/collaboration/documentation/grammar.rst index 938f0eb2..037ec965 100644 --- a/source/clear-linux/reference/collaboration/documentation/grammar.rst +++ b/source/clear-linux/reference/collaboration/documentation/grammar.rst @@ -4,7 +4,7 @@ Grammar guide ############# This guide provides valuable insight into the correct grammar for the -|CLOSIA| documentation. It covers subjects such as capitalization, verbs, +|CL-ATTR| documentation. It covers subjects such as capitalization, verbs, hyphenation, possessives, and contractions. Capitalization diff --git a/source/clear-linux/reference/collaboration/documentation/headings.rst b/source/clear-linux/reference/collaboration/documentation/headings.rst index 916299a3..6f1d584d 100644 --- a/source/clear-linux/reference/collaboration/documentation/headings.rst +++ b/source/clear-linux/reference/collaboration/documentation/headings.rst @@ -6,7 +6,7 @@ Headings Descriptive and brief headings are crucial to the quality of the documentation. Sphinx uses the headings within the :abbr:`ReST (RestructuredText)` files to generate the navigation of the HTML -output and the outlines of the PDF files. The |CLOSIA| publishes the +output and the outlines of the PDF files. The |CL-ATTR| publishes the documentation as HTML making consistent heading levels extremely important. In addition to the title of the file, only three levels of headings are diff --git a/source/clear-linux/reference/collaboration/documentation/images.rst b/source/clear-linux/reference/collaboration/documentation/images.rst index 6ce6ad66..c631f15d 100644 --- a/source/clear-linux/reference/collaboration/documentation/images.rst +++ b/source/clear-linux/reference/collaboration/documentation/images.rst @@ -8,7 +8,7 @@ sometimes is difficult to explain using words alone. Well-planned graphics reduce the amount of text required to explain information. Non-native English readers rely heavily on graphics because graphics enhance their understanding of the text. -Follow these guidelines when creating graphics for the |CLOSIA|: +Follow these guidelines when creating graphics for the |CL-ATTR|: * Save the image files in a :file:`figures` folder. The folder must be found at the same level as the file containing the text. diff --git a/source/clear-linux/reference/collaboration/documentation/inline.rst b/source/clear-linux/reference/collaboration/documentation/inline.rst index 2e516960..a4ccfe91 100644 --- a/source/clear-linux/reference/collaboration/documentation/inline.rst +++ b/source/clear-linux/reference/collaboration/documentation/inline.rst @@ -4,7 +4,7 @@ Inline Markup ************* Sphinx supports a large number of inline markup elements called roles. The -|CLOSIA| documentation encourages the use of as many roles as +|CL-ATTR| documentation encourages the use of as many roles as possible. Thus, you can use any additional roles supported by Sphinx not listed here. Please refer to the `Sphinx reStructuredText Markup`_ documentation for the full list of supported roles. diff --git a/source/clear-linux/reference/collaboration/documentation/language.rst b/source/clear-linux/reference/collaboration/documentation/language.rst index 1d7d0303..ba2abe49 100644 --- a/source/clear-linux/reference/collaboration/documentation/language.rst +++ b/source/clear-linux/reference/collaboration/documentation/language.rst @@ -4,13 +4,13 @@ Language reference guide ######################## This section describes acceptable usage of the English language in the -|CLOSIA| documentation. It includes information about words use, +|CL-ATTR| documentation. It includes information about words use, punctuation, and grammar. This guide does not replace a professional writer's review but is intended to help collaborators submit consistent contributions. To make translations easier and to make the content accessible to non-native -speakers, |CLOSIA| uses Simple English. However, we have not implemented any +speakers, |CL-ATTR| uses Simple English. However, we have not implemented any controlled language standards. .. toctree:: diff --git a/source/clear-linux/reference/collaboration/documentation/punctuation.rst b/source/clear-linux/reference/collaboration/documentation/punctuation.rst index 88b04d38..f019b1c3 100644 --- a/source/clear-linux/reference/collaboration/documentation/punctuation.rst +++ b/source/clear-linux/reference/collaboration/documentation/punctuation.rst @@ -4,7 +4,7 @@ Punctuation guide ################# This section contains all the information regarding the correct use of -punctuation for the |CLOSIA| documentation. +punctuation for the |CL-ATTR| documentation. Commas, Semicolons, and Colons ****************************** diff --git a/source/clear-linux/reference/collaboration/documentation/rest.rst b/source/clear-linux/reference/collaboration/documentation/rest.rst index aaf7016f..a64f6a78 100644 --- a/source/clear-linux/reference/collaboration/documentation/rest.rst +++ b/source/clear-linux/reference/collaboration/documentation/rest.rst @@ -8,7 +8,7 @@ RestructuredText guide Overview ******** -The |CLOSIA| uses Sphinx and RestructuredText as authoring tools for its +The |CL-ATTR| uses Sphinx and RestructuredText as authoring tools for its documentation. This section contains the preferred methods for using the :abbr:`ReST (RestructuredText)` markup on your documents. Please refer to the `Sphinx documentation`_ for the complete list of available markup and use diff --git a/source/clear-linux/reference/collaboration/documentation/simple.rst b/source/clear-linux/reference/collaboration/documentation/simple.rst index a67a7e19..b8ea9773 100644 --- a/source/clear-linux/reference/collaboration/documentation/simple.rst +++ b/source/clear-linux/reference/collaboration/documentation/simple.rst @@ -12,7 +12,7 @@ Simple English improves the clarity of procedural technical writing, makes translation easier, and improves comprehension for people whose first language is not English. -|CLOSIA| does not use controlled language, which restricts the writer's +|CL-ATTR| does not use controlled language, which restricts the writer's vocabulary to a list of approved words. However, we do strongly recommend using the language principles described below. diff --git a/source/clear-linux/reference/collaboration/documentation/structures.rst b/source/clear-linux/reference/collaboration/documentation/structures.rst index 38dee121..04cf1bc7 100644 --- a/source/clear-linux/reference/collaboration/documentation/structures.rst +++ b/source/clear-linux/reference/collaboration/documentation/structures.rst @@ -4,7 +4,7 @@ Consistent content structures guide ################################### This section guides you through the different content structures used in the -|CLOSIA| documentation. This section serves as an example of the correct use +|CL-ATTR| documentation. This section serves as an example of the correct use of markup. Refer to our :ref:`rest` to learn more about using restructuredText to author your content. diff --git a/source/clear-linux/reference/collaboration/documentation/tables.rst b/source/clear-linux/reference/collaboration/documentation/tables.rst index 29d0b2c2..814de470 100644 --- a/source/clear-linux/reference/collaboration/documentation/tables.rst +++ b/source/clear-linux/reference/collaboration/documentation/tables.rst @@ -5,7 +5,7 @@ Tables Tables must only be used for information that is either too numerous or too related for a list to be appropriate. The smallest acceptable table is 2x2 -not counting the table header. The |CLOSIA| uses special ReStructuredText +not counting the table header. The |CL-ATTR| uses special ReStructuredText markup to make including tables easier. If you plan on adding a table consider transforming it into a list before you embark on creating a table. Follow these general guidelines: diff --git a/source/clear-linux/reference/compatible-hardware.rst b/source/clear-linux/reference/compatible-hardware.rst index 98bceeef..3f8b23a3 100644 --- a/source/clear-linux/reference/compatible-hardware.rst +++ b/source/clear-linux/reference/compatible-hardware.rst @@ -4,10 +4,10 @@ Compatible Hardware ################### This document describes hardware that has been tested and confirmed as -compatible with |CLOSIA|. This list is not comprehensive and will continue to +compatible with |CL-ATTR|. This list is not comprehensive and will continue to grow. -.. list-table:: **Table 1. Clear Linux Compatible Hardware** +.. list-table:: **Table 1. Compatible Hardware** :widths: 20, 20 :header-rows: 1 diff --git a/source/clear-linux/reference/compatible-kernels.rst b/source/clear-linux/reference/compatible-kernels.rst index 72c6072e..cc76e524 100644 --- a/source/clear-linux/reference/compatible-kernels.rst +++ b/source/clear-linux/reference/compatible-kernels.rst @@ -1,9 +1,9 @@ .. _compatible-kernels: -Compatible Clear Linux\* kernels -################################ +Compatible kernels +################## -The |CLOSIA| provides the following Linux kernels with a respective bundle. +The |CL-ATTR| provides the following Linux kernels with a respective bundle. This document describes the specific use cases these `bundles`_ serve and provides links to their source code. @@ -44,10 +44,10 @@ The *kernel-kvm* bundle focuses on the Linux :abbr:`KVM (Kernel-based Virtual Machine)`. It is optimized for fast booting and performs best on Virtual Machines running on the Intel® architectures described on the :ref:`supported hardware list`. -Use this kernel when running |CL| as the guest OS on top of *qemu/kvm*. Use -this kernel with **cloud orchestrators** using *qemu/kvm* internally as -their **hypervisor**. This kernel can be used as a standalone |CL| VM, see -our :ref:`instructions on using KVM` for more information. The +Use this kernel when running |CL| as the guest OS on top of *qemu/kvm*. Use +this kernel with **cloud orchestrators** using *qemu/kvm* internally as +their **hypervisor**. This kernel can be used as a standalone |CL| VM, see +our :ref:`instructions on using KVM` for more information. The optimization patches are found in our `Linux-KVM`_ GitHub repo. Kernel Hyper-V\* @@ -58,7 +58,7 @@ Hyper-V. It is optimized for fast booting and performs best on Virtual Machines running on the Intel® architectures described on the :ref:`supported hardware list`. Use this kernel when running |CL| as the guest OS of **Cloud Instances** in -projects such as Microsoft `Azure`_\*. This kernel can be used in a +projects such as Microsoft `Azure`_\*. This kernel can be used in a standalone |CL| VM, see our :ref:`instructions on using Hyper-V` for more information. The optimization patches are found in our `Linux-HyperV`_ GitHub repo. diff --git a/source/clear-linux/reference/how-to-clear-overview.rst b/source/clear-linux/reference/how-to-clear-overview.rst index 91862a29..01179fec 100644 --- a/source/clear-linux/reference/how-to-clear-overview.rst +++ b/source/clear-linux/reference/how-to-clear-overview.rst @@ -6,7 +6,7 @@ How to Clear training overview The existing Linux\* ecosystem can be challenging to users because of long intervals between :abbr:`OS (operating system)` updates, which leads to large update downloads. Users can also be frustrated when managing complicated -component dependencies. |CLOSIA| solves these problems by: +component dependencies. |CL-ATTR| solves these problems by: * Allowing you to update frequently, even multiple times per day * Preventing you from combining incompatible components @@ -31,7 +31,7 @@ overview of these |CL| mechanisms: * Tools: `mixer-tools` software suite generates the update server content using |CL| official software update content, local bundle definitions, and local RPM files. -The training helps you create a customized OS that is based on |CLOSIA|. The +The training helps you create a customized OS that is based on |CL|. The training content is self-contained and hosted on GitHub. You need a clean |CL| installation and a functional network connection to complete the training. For convenience, the project includes the training files you need diff --git a/source/clear-linux/reference/image-types.rst b/source/clear-linux/reference/image-types.rst index e3d94205..5cb734c3 100644 --- a/source/clear-linux/reference/image-types.rst +++ b/source/clear-linux/reference/image-types.rst @@ -35,14 +35,14 @@ Table 2 lists the currently available images that are platform specific. * - Image Type - Description - * - installer.img - - Preferred image of |CL| with interactive installer. + * - installer.img + - Preferred image of |CL| with interactive installer. * - installer.iso - ISO of |CL| with interactive installer. Only for special cases where ISO image format is required (not for use with a USB key) * - live.img - - Image for live booting into memory, without requiring installaton. + - Image for live booting into memory, without requiring installaton. .. list-table:: Table 2: Types of platform-specific |CL| images :widths: 15, 85 @@ -70,7 +70,7 @@ Table 2 lists the currently available images that are platform specific. - Virtual Hard Disk for use with Microsoft Hyper-V\* hypervisor. Includes `optimized kernel`_ for Hyper-V. * - kvm.img - - Image for booting in a simple VM with start_qemu.sh. Includes + - Image for booting in a simple VM with start_qemu.sh. Includes `optimized kernel`_ for KVM. * - vmware.vmdk diff --git a/source/clear-linux/reference/reference.rst b/source/clear-linux/reference/reference.rst index 2f8286d3..a08ffda6 100644 --- a/source/clear-linux/reference/reference.rst +++ b/source/clear-linux/reference/reference.rst @@ -3,11 +3,11 @@ Reference ######### -This section provides additional information on the |CL| project and |CL| +This section provides additional information on the |CL| project and features. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 compatible-hardware bundle-commands diff --git a/source/clear-linux/reference/system-requirements.rst b/source/clear-linux/reference/system-requirements.rst index 25f2bc0d..38c2d44f 100644 --- a/source/clear-linux/reference/system-requirements.rst +++ b/source/clear-linux/reference/system-requirements.rst @@ -3,7 +3,7 @@ Recommended minimum system requirements ####################################### -|CL-ATTR| can run on very minimal hardware. For example, it can run on a +|CL-ATTR| can run on very minimal hardware. For example, it can run on a system with a single core CPU, 128MB of memory, and 600MB of disk space. Different use cases and applications will require different configurations. @@ -12,7 +12,7 @@ minimum requirements include: * Processors: - |CL-ATTR| can run on any Intel® 64bit processors which support UEFI\* + |CL-ATTR| can run on any Intel® 64bit processors which support UEFI\* and SSE\* v4.1 streaming SIMD\* instructions. The following processor families have been verified to run |CL|: diff --git a/source/clear-linux/tutorials/aws-web/aws-web.rst b/source/clear-linux/tutorials/aws-web/aws-web.rst index 25b9b1af..1cf7b688 100644 --- a/source/clear-linux/tutorials/aws-web/aws-web.rst +++ b/source/clear-linux/tutorials/aws-web/aws-web.rst @@ -1,6 +1,6 @@ .. _aws-web: -Create and launch Clear Linux from Amazon Web Services +Create and launch |CL-ATTR| from Amazon Web Services ###################################################### This tutorial walks you through creating and launching a |CL| @@ -25,14 +25,14 @@ This tutorial assumes the following statements are true: directory. * You have already set up an AWS user account and logged into the AWS console. - + .. note:: This tutorial uses a |CL| AMI t2.micro instance that is eligible for the AWS free tier. To learn more about AWS and setting up an account, visit the AWS website at http://aws.amazon.com. -Locate, select, and launch the Clear Linux OS Basic AMI -******************************************************* +Locate, select, and launch the |CL| Basic AMI +********************************************* #. Start from your main AWS services console menu in your browser and select the :guilabel:`EC2` text as shown in figure 1: @@ -57,18 +57,18 @@ Locate, select, and launch the Clear Linux OS Basic AMI This selection takes you to the :guilabel:`Step 1: Choose an Amazon Machine Image (AMI)` menu. -#. To find the :guilabel:`|CL| OS Basic` AMI in the +#. To find the :guilabel:`Clear Linux OS Basic` AMI in the :guilabel:`Step 1: Choose an Amazon Machine Image (AMI)` menu, do the following: - + #. In the lefthand navigation window, select the :guilabel:`AWS Marketplace` menu item to bring up the search bar to :guilabel:`Search AWS Marketplace Products`. - #. In the search bar, type `clear linux os` and hit the :kbd:`Enter` key to - search for and locate the :guilabel:`|CL| OS Basic` AMI. + #. In the search bar, type "clear linux os" and hit the :kbd:`Enter` key to + search for and locate the :guilabel:`Clear Linux OS Basic` AMI. - #. Select the :guilabel:`|CL| OS Basic` AMI by clicking on the + #. Select the :guilabel:`Clear Linux OS Basic` AMI by clicking on the :guilabel:`Select` button as shown in figure 3: .. figure:: figures/aws-web-3.png @@ -78,7 +78,7 @@ Locate, select, and launch the Clear Linux OS Basic AMI Figure 3: :guilabel:`Step 1: Choose AMI` #. A pop-up dialog box appears showing you more information about the - :guilabel:`|CL| OS Basic` AMI along with the pricing details for running + :guilabel:`Clear Linux OS Basic` AMI along with the pricing details for running |CL| on different platform configurations as shown in figure 4. Select the :guilabel:`Continue` button. @@ -129,13 +129,13 @@ Locate, select, and launch the Clear Linux OS Basic AMI Figure 7: :guilabel:`Select an existing key pair or create a new pair` #. Select the :guilabel:`Create a new key pair` option. - + #. For the :guilabel:`Key pair name` field, enter `AWSClearTestKey`. - + #. Select the :guilabel:`Download Key Pair` button to download the :file:`AWSClearTestKey.pem` to your browser's defined :file:`Downloads` directory. - + #. When the file finishes downloading, select the :guilabel:`Launch Instances` button to proceed to the :guilabel:`Launch Status` menu shown in figure 8. @@ -171,8 +171,8 @@ other instances available, they are also listed but not selected. #. To connect to your running instance, click the :guilabel:`Connect` button located at the top of your dashboard. AWS brings up the pop-up dialog - box shown in figure 11 describing how to connect to your running instance. - + box shown in figure 11 describing how to connect to your running instance. + .. _fig-aws-web-11: .. figure:: figures/aws-web-11.png @@ -223,10 +223,10 @@ other instances available, they are also listed but not selected. .. code-block:: console Warning: Permanently added 'ec2-34-209-39-184.us-west-2.compute.amazonaws.com,34.209.39.184' (ECDSA) to the list of known hosts. - clear@clr-96a8565d0ca54b0c80364a1e5e7b0f88 ~ $ + clear@clr-96a8565d0ca54b0c80364a1e5e7b0f88 ~ $ -Update the Clear Linux OS instance -********************************** +Update the |CL| instance +************************ Run the :command:`sudo swupd update` command to update the operating system as shown in figure 12: @@ -239,8 +239,8 @@ system as shown in figure 12: In this example we updated from version 18940 to 19100. -Stop the Clear Linux OS instance -******************************** +Stop the |CL| instance +********************** When you are finished using your AWS |CL| instance you need to stop it using the :guilabel:`Instances` dashboard to stop accruing charges. Complete the diff --git a/source/clear-linux/tutorials/azure.rst b/source/clear-linux/tutorials/azure.rst index 397b7032..3d278f13 100644 --- a/source/clear-linux/tutorials/azure.rst +++ b/source/clear-linux/tutorials/azure.rst @@ -1,9 +1,9 @@ .. _azure: -Run Clear Linux using Microsoft Azure CLI 2.0 -############################################# +Run |CL-ATTR| using Microsoft Azure CLI 2.0 +########################################### -|CLOSIA| is available for you to use in the Microsoft* Azure* marketplace and +|CL-ATTR| is available for you to use in the Microsoft* Azure* marketplace and is offered with three different images, also known as a :abbr:`SKU (Stock Keeping Unit)`. @@ -89,8 +89,8 @@ sysadmin-basic software bundle using the :command:`swupd` command: instructions in the `MS Azure Install Azure CLI tutorial`_ for your specific operating system. -Install MS Azure CLI 2.0 on Clear Linux -*************************************** +Install MS Azure CLI 2.0 on |CL| +******************************** #. To install the MS Azure CLI 2.0 on |CL|, use the :command:`curl` command as follows: @@ -335,8 +335,8 @@ of resources within MS Azure. "tags": null } -Create and log into the Clear Linux virtual machine -*************************************************** +Create and log into the |CL| virtual machine +******************************************** For this tutorial, we are using the |CL| Basic SKU for our VM. @@ -467,8 +467,8 @@ For this tutorial, we are using the |CL| Basic SKU for our VM. When you are finished using your new |CL| VM, type :command:`exit` to close the :command:`SSH` terminal and logout. -Stop and deallocate the Clear Linux VM and resources -**************************************************** +Stop and deallocate the |CL| VM and resources +********************************************* When you finish using your new |CL| instance, you must stop the VM and deallocate the resources in your resource group. If you only stop a VM, the OS @@ -516,7 +516,7 @@ Next steps To see use cases you can fulfill with your |CL| instance, visit our :ref:`tutorials ` section. -For additional information visit the Clear Linux +For additional information visit the |CL| `Azure Partner Mini Case Study`_ and the `Azure Partner Datasheet`_. To learn more about the MS Azure CLI 2.0 tool and options that are available, diff --git a/source/clear-linux/tutorials/docker/docker.rst b/source/clear-linux/tutorials/docker/docker.rst index e9643777..c61ce9f6 100644 --- a/source/clear-linux/tutorials/docker/docker.rst +++ b/source/clear-linux/tutorials/docker/docker.rst @@ -1,12 +1,12 @@ .. _docker: -Run Docker\* on Clear Linux\* -############################# +Run Docker\* on |CL-ATTR| +######################### -|CLOSIA| supports multiple containerization platforms, including a Docker\* -solution. |CL| has many `unique features`_ including a minimal default -installation, which makes it compelling to use as a host for container -workloads, management, and orchestration. +|CL-ATTR| supports multiple containerization platforms, including a Docker\* +solution. |CL| has many `unique features`_ including a minimal default +installation, which makes it compelling to use as a host for container +workloads, management, and orchestration. This tutorial covers: @@ -14,18 +14,29 @@ This tutorial covers: :depth: 1 .. note:: - - This tutorial focuses on the installaton of the Docker ecosystem. + + This tutorial focuses on the installaton of the Docker ecosystem. If you want to use |CL| as a Docker container image, refer to the - official `Clear Linux image on Docker Hub`_ - and `building a custom Clear Linux docker image`_ . + official |CL| container image + `published on Docker* Hub `_ + and our guide to :ref:`custom-clear-container`. Prerequisites ************* -* Basic understanding of Linux and Docker. +This tutorial assumes you have installed |CL| on your host system. +For detailed instructions on installing |CL| on a bare metal system, follow +the :ref:`bare metal installation instructions`. -* Successful completion: :ref:`bare-metal-install` +Before you install any new packages, update |CL| with the following command: + +.. code-block:: bash + + sudo swupd update + +Additionally, you should have: + +* A basic understanding of Linux and Docker. * |CL| environment that has transparent network access to the Internet. If you are behind a HTTP proxy server, in a corporate setting for example, @@ -35,10 +46,10 @@ Install the containers-basic bundle *********************************** Software in |CL| is offered in the form of `bundles`_ to provide a -complete function. The *containers-basic* provides all the required software -packages to run Docker images as containers. +complete function. The *containers-basic* provides all the required software +packages to run Docker images as containers. -#. First, install the *containers-basic* bundle by running this +#. First, install the *containers-basic* bundle by running this :command:`swupd` command: .. code-block:: bash @@ -51,49 +62,49 @@ packages to run Docker images as containers. sudo systemctl start docker - If you want Docker to start automatically on boot, enable the + If you want Docker to start automatically on boot, enable the systemd service by running this command: .. code-block:: bash sudo systemctl enable docker -#. Finally, verify :command:`docker` has been installed by running this +#. Finally, verify :command:`docker` has been installed by running this command and checking the version output for both *client* and *server*: .. code-block:: bash - sudo docker version + sudo docker version -Congratulations! At this point, you have a working installation of Docker +Congratulations! At this point, you have a working installation of Docker on |CL|. You are ready to start using container images on your system. Integration with Kata Containers (optional) ******************************************** `Kata Containers`_, is an open source project aiming to increase security -of containers by using a hardware-backed virtual machine container runtime -rather than software namespace containers that are provided by the standard +of containers by using a hardware-backed virtual machine container runtime +rather than software namespace containers that are provided by the standard Docker *runc* runtime. -Clear Linux provides easy integration of the *kata-runtime* with Docker. +|CL| provides easy integration of the *kata-runtime* with Docker. More information on installing and using the *kata-runtime* may be found at :ref:`kata`. -.. note:: +.. note:: The proceeding sections of this tutorial are standard to Docker setup - and configuration. If you are familiar with Docker basics, you do not - need to continue reading. The following sections are provided here for + and configuration. If you are familiar with Docker basics, you do not + need to continue reading. The following sections are provided here for sake of completeness. Additional Docker configuration ******************************* Perform additional Docker daemon configuration via a configuration file -typically located at :file:`/etc/docker/daemon.json`. |CL| features a +typically located at :file:`/etc/docker/daemon.json`. |CL| features a `stateless system`_ so the configuration file :file:`daemon.json` does *NOT* -exist by default. +exist by default. #. Create the :file:`daemon.json` by running this command: @@ -101,34 +112,35 @@ exist by default. sudo touch /etc/docker/daemon.json - .. note:: + .. note:: - Refer to the `Docker documentation on daemon configuration`_ for the + Refer to the `Docker documentation on daemon configuration`_ for the full list of available configuration options and examples. - A minimal configuration would be. - .. code-block:: json - - { - "storage-driver": "devicemapper" - } + A minimal configuration would be: -#. Once you've made any required changes, be sure to restart the + .. code-block:: json + + { + "storage-driver": "devicemapper" + } + +#. Once you've made any required changes, be sure to restart the Docker daemon through systemd manager by running this command: .. code-block:: bash sudo systemctl restart docker -Pulling and Running an image from Docker Hub +Pulling and running an image from Docker Hub ******************************************** `Docker Hub`_ is a publically available container image repository which -comes preconfigured with Docker. In the example below we will pull and run -an the official Docker image for nginx, an open source reverse proxy server. +comes preconfigured with Docker. In the example below we will pull and run +an the official Docker image for nginx, an open source reverse proxy server. -#. First, pull a container image from Docker Hub using the - :command:`docker pull` command. Download the latest nginx Docker +#. First, pull a container image from Docker Hub using the + :command:`docker pull` command. Download the latest nginx Docker container image by running this command: .. code-block:: bash @@ -143,37 +155,37 @@ an the official Docker image for nginx, an open source reverse proxy server. sudo docker run --name test-nginx -d -p 8080:80 nginx .. note:: - + Below is an explanation of switches used in the command above. For - detailed :command:`docker run` switches and syntax, refer to the + detailed :command:`docker run` switches and syntax, refer to the `Docker Documentation`_ . * The *--name* switch lets you provide a friendly name to target the container for future operations * The *-d* switch launches the container in the background - + * The *-p* switch allows the container's HTTP port (80) to be - accessible from the Clear Linux host on port 8080 + accessible from the |CL| host on port 8080 #. You can access the Welcome to Nginx! splash page running in the container - by browsing to http://127.0.0.1:8080 or by running this :command:`curl` - command from your Clear Linux machine: + by browsing to \http://127.0.0.1:8080 or by running this :command:`curl` + command from your |CL| machine: .. code-block:: bash curl 127.0.0.1:8080 -#. Finally, stop and delete the nginx container by running the +#. Finally, stop and delete the nginx container by running the :command:`docker stop` and :command:`docker rm` commands. .. code-block:: bash - sudo docker stop test-nginx + sudo docker stop test-nginx sudo docker rm test-nginx -Congratulations! At this point, you have successfully pulled a nginx -container image from `Docker Hub`_ and have run an example container. +Congratulations! At this point, you have successfully pulled a nginx +container image from `Docker Hub`_ and have run an example container. Creating a Docker swarm cluster ******************************* @@ -181,30 +193,27 @@ Creating a Docker swarm cluster Clusters of Docker hosts are referred to as *swarms*. The process in this tutorial can be repeated to install Docker on multiple -Clear Linux hosts with the intent to form a Docker swarm cluster. +|CL| hosts with the intent to form a Docker swarm cluster. -The `Docker documentation on swarm key concepts`_ and -`Docker documentation on creating a swarm`_ can be referenced +The `Docker documentation on swarm key concepts`_ and +`Docker documentation on creating a swarm`_ can be referenced for further instructions on setting up a swarm. -Also see: ---------- +Related topics +************** + * `Docker Home`_ * `Docker Documentation`_ * `Docker Hub`_ -* `Kata Containers`_ +* `Kata Containers`_ .. _unique features: https://clearlinux.org/features -.. _Clear Linux image on Docker Hub: https://hub.docker.com/_/clearlinux/ - -.. _building a custom Clear Linux docker image: https://clearlinux.org/documentation/clear-linux/guides/network/custom-clear-container - .. _Docker proxy instructions: https://docs.docker.com/config/daemon/systemd/#httphttps-proxy .. _bundles: https://clearlinux.org/documentation/clear-linux/concepts/bundles-about#related-concepts -.. _stateless system: https://clearlinux.org/features/stateless +.. _stateless system: https://clearlinux.org/features/stateless .. _Docker documentation on daemon configuration: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file diff --git a/source/clear-linux/tutorials/fmv.rst b/source/clear-linux/tutorials/fmv.rst index ea6699ed..31dcdeaf 100644 --- a/source/clear-linux/tutorials/fmv.rst +++ b/source/clear-linux/tutorials/fmv.rst @@ -18,8 +18,8 @@ In this tutorial we will use FMV on general code and on tutorial, you will be able to use this technology on your code and use the libraries to deploy architecture-based optimizations to your application code. -Install and configure a Clear Linux host on bare metal -****************************************************** +Install and configure a |CL| host on bare metal +*********************************************** First, follow our guide to :ref:`bare-metal-install`. @@ -184,7 +184,7 @@ You can see the multiple clones of the `foo` function: The cloned functions use AVX2 registers and vectorized instructions. To verify, enter the following commands: -:: +:: vpaddd (%r8,%rax,1),%ymm0,%ymm0 vmovdqu %ymm0,(%rcx,%rax,1) @@ -219,16 +219,16 @@ generates the following patches: --- fftw-3.3.6-pl2/libbench2/verify-lib.c 2017-01-27 21:08:13.000000000 +0000 +++ fftw-3.3.6-pl2/libbench2/verify-lib.c~ 2017-09-27 17:49:21.913802006 +0000 @@ -33,6 +33,7 @@ - + double dmax(double x, double y) { return (x > y) ? x : y; } - + +__attribute__((target_clones("avx2","arch=atom","default"))) static double aerror(C *a, C *b, int n) { if (n > 0) { @@ -111,6 +112,7 @@ } - + /* make array hermitian */ +__attribute__((target_clones("avx2","arch=atom","default"))) void mkhermitian(C *A, int rank, const bench_iodim *dim, int stride) @@ -236,7 +236,7 @@ generates the following patches: if (rank == 0) @@ -148,6 +150,7 @@ } - + /* C = A + B */ +__attribute__((target_clones("avx2","arch=atom","default"))) void aadd(C *c, C *a, C *b, int n) @@ -244,7 +244,7 @@ generates the following patches: int i; @@ -159,6 +162,7 @@ } - + /* C = A - B */ +__attribute__((target_clones("avx2","arch=atom","default"))) void asub(C *c, C *a, C *b, int n) @@ -252,7 +252,7 @@ generates the following patches: int i; @@ -170,6 +174,7 @@ } - + /* B = rotate left A (complex) */ +__attribute__((target_clones("avx2","arch=atom","default"))) void arol(C *b, C *a, int n, int nb, int na) @@ -267,8 +267,8 @@ bringing architecture-based optimizations to application code even easier. **Congratulations!** -You have successfully installed an FMV development environment on Clear -Linux. Furthermore, you used cutting edge compiler technology to improve the +You have successfully installed an FMV development environment on |CL|. +Furthermore, you used cutting edge compiler technology to improve the performance of your application based on Intel Architecture technology and profiling of the specific execution of your application. diff --git a/source/clear-linux/tutorials/greengrass.rst b/source/clear-linux/tutorials/greengrass.rst index 315f0804..b1c88c85 100644 --- a/source/clear-linux/tutorials/greengrass.rst +++ b/source/clear-linux/tutorials/greengrass.rst @@ -3,25 +3,25 @@ Enable AWS Greengrass* and OpenVINO™ on |CL-ATTR| ################################################# -Hardware accelerated Function-as-a-Service (FaaS) enables cloud developers -to deploy inference functionalities [1] on Intel® IoT edge devices with -accelerators (Integrated GPU, Intel® FPGA, and Intel® Movidius™). 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 +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™). 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 shows how to: +This tutorial will demonstrate how to: * Set up the Intel® edge device with |CL-ATTR| * Install the OpenVINO™ and AWS Greengrass* software stacks -* Use AWS Greengrass and lambdas to deploy the FaaS samples from the cloud +* Use AWS Greengrass and lambdas to deploy the FaaS samples from the cloud Supported Platforms ******************* -* Operating System: |CL-ATTR| latest release +* Operating System: |CL| latest release * Hardware: Intel® core platforms (Tutorial supports inference on CPU only) Description of Samples @@ -31,90 +31,35 @@ The AWS Greengrass samples are located at the `Edge-Analytics-FaaS`_. We provide the following AWS Greengrass samples: -* :file:`greengrass_classification_sample.py` - +* `greengrass_classification_sample.py`_ + This AWS Greengrass sample classifies a video stream using classification networks such as AlexNet and GoogLeNet and publishes top-10 results on AWS* IoT Cloud every second. -* :file:`greengrass_object_detection_sample_ssd.py` +* `greengrass_object_detection_sample_ssd.py`_ This AWS Greengrass sample detects objects in a video stream and classifies them using single-shot multi-box detection (SSD) networks such - as SSD Squeezenet, SSD Mobilenet, and SSD300. This sample publishes + as SSD Squeezenet, SSD Mobilenet, and SSD300. This sample publishes detection outputs such as class label, class confidence, and bounding box coordinates on AWS IoT Cloud every second. -Converting Deep Learning Models -******************************* - -Sample Models -============= - -For classification, `download the BVLC Alexnet model`_ as an example. -Any custom pre-trained classification models can be used with the -classification sample. - -For object detection, the sample models optimized for Intel® edge platforms -are present at :file:`/usr/share/openvino/models`. These models are provided -as an example; however, any custom pre-trained SSD models can be used with -the object detection sample. - -Running Model Optimizer -======================= - -Follow these instructions for `converting deep learning models to Intermediate Representation using Model Optimizer`_. For example, use the -following commands. - -For classification using BVLC Alexnet model: - -.. code-block:: bash - - python3 mo.py --framework caffe --input_model < - model_location>/bvlc_alexnet.caffemodel --input_proto < - model_location>/deploy.prototxt --data_type --output_dir < - output_dir> --input_shape [1,3,227,227] - -For object detection using SqueezeNetSSD-5Class model: - -.. code-block:: bash - - python3 mo.py --framework caffe --input_model - SqueezeNetSSD-5Class.caffemodel --input_proto - SqueezeNetSSD-5Class.prototxt - --data_type --output_dir - -In these examples: - -* ```` is :file:`/usr/share/openvino/models` - -* ```` is FP32 or FP16, depending on target device. - -* ```` is the directory where the user wants to store the - Intermediate Representation (IR). IR contains .xml format corresponding - to the network structure and .bin format corresponding to weights. This - .xml file should be passed to . - -* In the BVLC Alexnet model, the prototxt defines the input shape with - batch size 10 by default. In order to use any other batch size, the - entire input shape needs to be provided as an argument to the model - optimizer. For example, to use batch size 1, you can provide - “--input_shape [1,3,227,227]”. Installing |CL| on the edge device ********************************** -Start with a clean installation of |CL| on a new system, using the +Start with a clean installation of |CL| on a new system, using the :ref:`bare-metal-install`, found in :ref:`get-started`. Create user accounts ==================== -After |CL| is installed, create two user accounts. Create an administrative +After |CL| is installed, create two user accounts. Create an administrative user in |CL|. You will also create a user account for the Greengrass -services to use (see Greengrass user below). +services to use (see Greengrass user below). -#. Create a new user and set a password for that user. Enter the following +#. Create a new user and set a password for that user. Enter the following commands as ``root``: .. code-block:: bash @@ -122,105 +67,158 @@ services to use (see Greengrass user below). useradd passwd -#. Next, enable the :command:`sudo` command for your new ````. Add +#. Next, enable the :command:`sudo` command for your new ````. Add ```` to the ``wheel`` group: .. code-block:: bash usermod -G wheel -a -#. Create the user and group account for the Greengrass daemon: - - .. code-block:: console - - useradd ggc_user - groupadd ggc_group - -#. Create a :file:`/etc/fstab` file. +#. Create a :file:`/etc/fstab` file. .. code-block:: bash touch /etc/fstab - .. note:: - - By default |CL| does not create an :file:`/etc/fstab` file. - The Greengrass service needs to have the file created before + .. note:: + + By default |CL| does not create an :file:`/etc/fstab` file. + The Greengrass service needs to have the file created before it will run. - + Add required bundles ==================== -Use the ``swupd`` software updater utility to add the following bundles to -enable the OpenVINO software stack: +Use the ``swupd`` software updater utility to add the prerequisite bundles +for the OpenVINO software stack: .. code-block:: bash - swupd bundle-add os-clr-on-clear desktop-autostart computer-vision-basic + swupd bundle-add os-clr-on-clr desktop-autostart computer-vision-basic .. note:: - Learn more about how to :ref:`swupd-guide`. + Learn more about how to :ref:`swupd-guide`. -The ``computer-vision-basic`` bundle will install the OpenVINO software, +The ``computer-vision-basic`` bundle will install the OpenVINO software, along with the edge device models needed. +Converting Deep Learning Models +=============================== + +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. + +To complete this tutorial 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 +classification sample. + +For object detection, the sample models optimized for Intel® edge platforms +are included with the computer-vision-basic bundle installation at :file:`/usr/share/openvino/models`. +These models are provided as an example; however, you may also use a custom SSD model +with the Greengrass object detection sample. + +Running Model Optimizer +----------------------- + +Follow these instructions for `converting deep learning models to Intermediate Representation using Model Optimizer`_. To optimize either of the afformentioned sample models, run one of the following commands. + +For classification using BVLC Alexnet model: + +.. code-block:: bash + + python3 mo.py --framework caffe --input_model + /bvlc_alexnet.caffemodel --input_proto + /deploy.prototxt --data_type --output_dir + --input_shape [1,3,227,227] + +For object detection using SqueezeNetSSD-5Class model: + +.. code-block:: bash + + python3 mo.py --framework caffe --input_model + /'SqueezeNet 5-Class detection'/SqueezeNetSSD-5Class.caffemodel + --input_proto /'SqueezeNet 5-Class detection'/SqueezeNetSSD-5Class.prototxt + --data_type --output_dir + +In these examples: + +* ```` is :file:`/usr/share/openvino/models` + +* ```` is FP32 or FP16, depending on target device. + +* ```` is the directory where the user wants to store the + Intermediate Representation (IR). IR contains .xml format corresponding + to the network structure and .bin format corresponding to weights. This + .xml file should be passed to . + +* In the BVLC Alexnet model, the prototxt defines the input shape with + batch size 10 by default. In order to use any other batch size, the + entire input shape needs to be provided as an argument to the model + optimizer. For example, to use batch size 1, you can provide + “--input_shape [1,3,227,227]”. + + Configuring an AWS Greengrass group =================================== -For each Intel® edge platform, we need to create a new AWS Greengrass group -and install AWS Greengrass core software to establish the connection between +For each Intel® edge platform, we need to create a new AWS Greengrass group +and install AWS Greengrass core software to establish the connection between cloud and edge. #. To create an AWS Greengrass group, follow the `AWS Greengrass developer guide`_ - + #. To install and configure AWS Greengrass core on edge platform, follow - the instructions at `Start AWS Greengrass on the Core Device`_. + the instructions at `Start AWS Greengrass on the Core Device`_. In + step 8(b), download the x86_64 Ubuntu configuration of the AWS Greengrass + core software. .. note:: You will not need to run the ``cgroupfs-mount.sh`` script in step #6 - of Module 1 of the `AWS Greengrass developer guide`_ because this is - enabled already in |CL|. + of Module 1 of the `AWS Greengrass developer guide`_ because this is + enabled already in |CL|. + +#. Be sure to download both the security resources and the AWS Greengrass + core software. + + .. note:: + + Security certificates are linked to your AWS* account. + Creating and Packaging Lambda Functions ======================================= -#. Complete the tutorial at `Configure AWS Greengrass on AWS IoT`_ . - - .. note:: +#. Complete steps 1-4 of the tutorial at `Create and Package Lambda Function`_ . - This creates the tarball needed to create the AWS Greengrass - environment on the edge device. + .. note:: -#. Assure to download both the security resources and the AWS Greengrass - core software. + This creates the tarball needed to create the AWS Greengrass + environment on the edge device. - .. note:: - Security certificates are linked to your AWS* account. +#. In step 5, replace greengrassHelloWorld.py with the classification or object detection + Greengrass sample from `Edge-Analytics-Faas`_: -#. Replace greengrassHelloWorld.py with Greengrass samples: + * Classification: `greengrass_classification_sample.py`_ - * greengrass_classification_sample.py + * Object Detection: `greengrass_object_detection_sample_ssd.py`_ - * greengrass_object_detection_sample_ssd.py - -#. Zip these files with extracted Greengrass SDK folders from the previous - step into :file:`greengrass_sample_python_lambda.zip`. +#. Zip the selected Greengrass sample with the extracted Greengrass SDK folders from the previous + step into :file:`greengrass_sample_python_lambda.zip`. The zip should contain: - + * greengrasssdk - * greengrass sample - - For the sample, choose one of these: - - - greengrass_classification_sample.py - - - greengrass_object_detection_sample_ssd.py + * greengrass classification or object detection sample For example: @@ -229,15 +227,15 @@ Creating and Packaging Lambda Functions zip -r greengrass_lambda.zip greengrasssdk greengrass_object_detection_sample_ssd.py -#. Follow steps 6-11 to `complete creating lambdas`_. - - .. note:: +#. Return to the AWS Documentation and follow steps 6-11 to `complete creating lambdas`_. - In the AWS documentation, step 9(a), while uploading the zip file, - make sure to name the handler as below depending on the AWS Greengrass + .. note:: + + In step 9(a) of the AWS documentation, while uploading the zip file, + make sure to name the handler as below depending on the AWS Greengrass sample you are using: - * greengrass_object_detection_sample_ssd.function_handler (or) + * greengrass_object_detection_sample_ssd.function_handler (or) * greengrass_classification_sample.function_handler Deploying Lambdas @@ -246,18 +244,18 @@ Deploying Lambdas Configuring the Lambda function ------------------------------- -After creating the Greengrass group and the lambda function, start -configuring the lambda function for AWS Greengrass. +After creating the Greengrass group and the lambda function, start +configuring the lambda function for AWS Greengrass. #. Follow steps 1-8 in `Configure the Lambda Function`_ of the AWS - documentation. + documentation. #. In addition to the details mentioned in step 8, change the Memory limit to 2048MB to accommodate large input video streams. #. Add the following environment variables as key-value pairs when editing the lambda configuration and click on update: - + .. list-table:: **Table 1. Environment Variables: Lambda Configuration** :widths: 20 80 :header-rows: 1 @@ -265,13 +263,15 @@ configuring the lambda function for AWS Greengrass. * - Key - Value * - PARAM_MODEL_XML - - /, where is user specified and - contains IR.xml, the Intermediate Representation file from Intel® Model Optimizer + - /, where is user specified and + contains IR.xml, the Intermediate Representation file from Intel® Model Optimizer. + For this tutorial, should be set to '/usr/share/openvino/models' + or one of its subdirectories. * - PARAM_INPUT_SOURCE - /input.webm to be specified by user. Holds both input and output data. For webcam, set PARAM_INPUT_SOURCE to ‘/dev/video0’ * - PARAM_DEVICE - - For CPU, specify "CPU" + - "CPU" * - PARAM_CPU_EXTENSION_PATH - /usr/lib64/libcpu_extension.so * - PARAM_OUTPUT_DIRECTORY @@ -281,19 +281,19 @@ configuring the lambda function for AWS Greengrass. - User specified for classification sample. (e.g. 1 for top-1 result, 5 for top-5 results) -#. Add subscription to subscribe, or publish messages from AWS Greengrass - lambda function by following the steps 10-14 in `Configure the Lambda Function`_ +#. Add subscription to subscribe, or publish messages from AWS Greengrass + lambda function by following the steps 10-14 in `Configure the Lambda Function`_ - .. note:: - - The “Optional topic filter” field should be the topic + .. note:: + + The “Optional topic filter” field should be the topic mentioned inside the lambda function. - + For example, openvino/ssd or openvino/classification Local Resources --------------- -#. Select `this link to add local resources and access privileges`_. +#. Select `this link to add local resources and access privileges`_. Following are the local resources needed for the CPU: @@ -301,71 +301,71 @@ Local Resources :widths: 20, 20, 20, 20 :header-rows: 1 - * - Name - - Resource type - - Local path + * - Name + - Resource type + - Local path - Access - - * - ModelDir - - Volume - - to be specified by user + + * - ModelDir + - Volume + - to be specified by user - Read-Only - * - Webcam - - Device + * - Webcam + - Device - /dev/video0 - Read-Only - * - DataDir - - Volume - - to be specified by user. Holds both input and output + * - DataDir + - Volume + - to be specified by user. Holds both input and output data. - Read and Write Deploy ------ -To `deploy the lambda function to AWS Greengrass core device`_, select -“Deployments” on group page and follow the instructions. +To `deploy the lambda function to AWS Greengrass core device`_, select +“Deployments” on group page and follow the instructions. Output Consumption ------------------ -There are four options available for output consumption. These options are -used to report, stream, upload, or store inference output at an interval +There are four options available for output consumption. These options are +used to report, stream, upload, or store inference output at an interval defined by the variable ``reporting_interval`` in the AWS Greengrass samples. a. IoT Cloud Output: - This option is enabled by default in the AWS Greengrass samples using a - variable ``enable_iot_cloud_output``. We can use it to verify the lambda - running on the edge device. It enables publishing messages to IoT cloud - using the subscription topic specified in the lambda (For example, - ‘openvino/classification’ for classification and ‘openvino/ssd’ for - object detection samples). For classification, top-1 result with class - label are published to IoT cloud. For SSD object detection, detection - results such as bounding box co-ordinates of objects, class label, and - class confidence are published. + This option is enabled by default in the AWS Greengrass samples using a + variable ``enable_iot_cloud_output``. We can use it to verify the lambda + running on the edge device. It enables publishing messages to IoT cloud + using the subscription topic specified in the lambda (For example, + ‘openvino/classification’ for classification and ‘openvino/ssd’ for + object detection samples). For classification, top-1 result with class + label are published to IoT cloud. For SSD object detection, detection + results such as bounding box co-ordinates of objects, class label, and + class confidence are published. Follow the instructions here to `view the output on IoT cloud`_ - + b. Kinesis Streaming: - - This option enables inference output to be streamed from the edge device - to cloud using Kinesis [3] streams when ‘enable_kinesis_output’ is set - to True. The edge devices act as data producers and continually push - processed data to the cloud. The users need to set up and specify - Kinesis stream name, Kinesis shard, and AWS region in the AWS Greengrass + + This option enables inference output to be streamed from the edge device + to cloud using Kinesis [3] streams when ‘enable_kinesis_output’ is set + to True. The edge devices act as data producers and continually push + processed data to the cloud. The users need to set up and specify + Kinesis stream name, Kinesis shard, and AWS region in the AWS Greengrass samples. c. Cloud Storage using AWS S3 Bucket: - - When the ‘enable_s3_jpeg_output’ variable is set to True, it enables uploading and storing processed frames (in JPEG format) in an AWS S3 bucket. The users need to set up and specify the S3 bucket name in the + + When the ‘enable_s3_jpeg_output’ variable is set to True, it enables uploading and storing processed frames (in JPEG format) in an AWS S3 bucket. The users need to set up and specify the S3 bucket name in the AWS Greengrass samples to store the JPEG images. The images are named using the timestamp and uploaded to S3. d. Local Storage: - - When the ‘enable_s3_jpeg_output’ variable is set to True, it enables storing processed frames (in JPEG format) on the edge device. The - images are named using the timestamp and stored in a directory specified + + When the ‘enable_s3_jpeg_output’ variable is set to True, it enables storing processed frames (in JPEG format) on the edge device. The + images are named using the timestamp and stored in a directory specified by ‘PARAM_OUTPUT_DIRECTORY’. References @@ -377,7 +377,13 @@ References .. _Edge-Analytics-FaaS: https://github.com/intel/Edge-Analytics-FaaS/tree/master/AWS%20Greengrass -.. _download the BVLC Alexnet model: https://github.com/BVLC/caffe/tree/master/models/bvlc_alexnet +.. _bvlc_alexnet.caffemodel: http://dl.caffe.berkeleyvision.org/bvlc_alexnet.caffemodel + +.. _deploy.prototxt: https://github.com/BVLC/caffe/blob/master/models/bvlc_alexnet/deploy.prototxt + +.. _greengrass_classification_sample.py: https://github.com/intel/Edge-Analytics-FaaS/blob/master/AWS%20Greengrass/greengrass_classification_sample.py + +.. _greengrass_object_detection_sample_ssd.py: https://github.com/intel/Edge-Analytics-FaaS/blob/master/AWS%20Greengrass/greengrass_object_detection_sample_ssd.py .. _converting deep learning models to Intermediate Representation using Model Optimizer: https://software.intel.com/en-us/articles/OpenVINO-ModelOptimizer @@ -391,7 +397,7 @@ References .. _Configure the Lambda Function: https://docs.aws.amazon.com/greengrass/latest/developerguide/config-lambda.html -.. _Add local resources and access privileges: https://docs.aws.amazon.com/greengrass/latest/developerguide/access-local-resources.html +.. _Add local resources and access privileges: https://docs.aws.amazon.com/greengrass/latest/developerguide/access-local-resources.html .. _deploy the lambda function to AWS Greengrass core device: https://docs.aws.amazon.com/greengrass/latest/developerguide/configs-core.html @@ -401,6 +407,4 @@ References .. _this link to add local resources and access privileges: https://docs.aws.amazon.com/greengrass/latest/developerguide/access-local-resources.html -.. _Configure AWS Greengrass on AWS IoT: https://docs.aws.amazon.com/greengrass/latest/developerguide/gg-config.html - - +.. _Create and Package Lambda Function: https://docs.aws.amazon.com/greengrass/latest/developerguide/create-lambda.html diff --git a/source/clear-linux/tutorials/hadoop.rst b/source/clear-linux/tutorials/hadoop.rst index a489c855..63d6d110 100644 --- a/source/clear-linux/tutorials/hadoop.rst +++ b/source/clear-linux/tutorials/hadoop.rst @@ -4,7 +4,7 @@ Set up a single node cluster with Hadoop\* ########################################## This tutorial walks you through the process of installing, configuring, and -running Apache\* Hadoop on |CLOSIA|. The Apache Hadoop software library is a +running Apache\* Hadoop on |CL-ATTR|. The Apache Hadoop software library is a framework for distributed processing of large data sets across clusters of computers using simple programming models. It is designed to scale up from single servers to thousands of machines, with each machine offering local @@ -14,7 +14,7 @@ Prerequisites ************* Before following this tutorial, you should follow the -:ref:`bare-metal-install` to ensure you have installed |CLOSIA|. +:ref:`bare-metal-install` to ensure you have installed |CL|. Before you install any new packages, update |CL| with the following command: diff --git a/source/clear-linux/tutorials/kata.rst b/source/clear-linux/tutorials/kata.rst index aee38778..4dbdb3bb 100644 --- a/source/clear-linux/tutorials/kata.rst +++ b/source/clear-linux/tutorials/kata.rst @@ -4,7 +4,7 @@ Install Kata Containers\* ######################### This tutorial describes how to install, configure, and run `Kata Containers`_ -on |CLOSIA|. Kata Containers is an open source project developing a +on |CL-ATTR|. Kata Containers is an open source project developing a lightweight implementation of :abbr:`VMs (Virtual Machines)` that offer the speed of containers and the security of VMs. @@ -79,12 +79,12 @@ Run Kata Containers **Congratulations!** -You've successfully installed and set up Kata Containers on |CLOSIA|. +You've successfully installed and set up Kata Containers on |CL|. More information about Docker ***************************** -Docker on |CLOSIA| provides a :file:`docker.service` file to start the Docker +Docker on |CL| provides a :file:`docker.service` file to start the Docker daemon. The daemon will use runc or kata-runtime depending on the environment: diff --git a/source/clear-linux/tutorials/kata_migration.rst b/source/clear-linux/tutorials/kata_migration.rst index 942d799c..41440a1b 100644 --- a/source/clear-linux/tutorials/kata_migration.rst +++ b/source/clear-linux/tutorials/kata_migration.rst @@ -6,7 +6,7 @@ Migrate Clear Containers to Kata Containers\* `Clear Containers`_ and `Kata Containers`_ can co-exist in the same system. Both can be installed through the :file:`containers-virt bundle`. However, we recommend that you migrate to Kata Containers because Clear Containers is no -longer maintained_ and will soon be deprecated on |CLOSIA|. +longer maintained_ and will soon be deprecated on |CL-ATTR|. This guide describes how to migrate to Kata Containers and assumes that: @@ -68,7 +68,7 @@ Enable Kata Containers as default Run Kata Containers ******************* -Use the following command: +Use the following command: .. code-block:: bash diff --git a/source/clear-linux/tutorials/kubernetes.rst b/source/clear-linux/tutorials/kubernetes.rst index b5761750..794e92e6 100644 --- a/source/clear-linux/tutorials/kubernetes.rst +++ b/source/clear-linux/tutorials/kubernetes.rst @@ -3,7 +3,7 @@ Run Kubernetes\* on |CL-ATTR| ############################# -This tutorial describes how to install, configure, and run the +This tutorial describes how to install, configure, and run the `Kubernetes container orchestration system`_ on |CL-ATTR| using different container engines and runtimes. @@ -17,7 +17,7 @@ strong isolation for untrusted workloads or multi-tenant scenarios. Runc and Kata Containers can be allocated on a per-pod basis so you can mix and match both on the same host to suit your needs. -This tutorial describes the following combinations: +This tutorial describes the following combinations: * Kubernetes with Docker and runc * Kubernetes with CRI-O and kata-runtime @@ -26,7 +26,7 @@ Prerequisites ************* This tutorial assumes you have installed |CL| and updated to the latest -release on your host system. You can learn about the benefits of having an +release on your host system. You can learn about the benefits of having an up-to-date system for cloud orchestration on the :ref:`swupd-about` page. For detailed instructions on installing |CL| on a bare metal system, follow the :ref:`bare metal installation tutorial`. @@ -40,8 +40,8 @@ Before you install any new packages, update |CL| with the following command: Install Kubernetes and CRI runtimes *********************************** -Kubernetes and a set of supported :abbr:`CRI (Container Runtime Interface)` -runtimes are included in the `cloud-native-basic`_ bundle. To install the +Kubernetes and a set of supported :abbr:`CRI (Container Runtime Interface)` +runtimes are included in the `cloud-native-basic`_ bundle. To install the framework, enter the following command: .. code-block:: bash @@ -276,7 +276,7 @@ with the displayed token and IP information. Related topics ************** -Read the Kubernetes documentation to learn more about: +Read the Kubernetes documentation to learn more about: * `Understanding basic Kubernetes architecture`_ @@ -308,7 +308,7 @@ following commands: sudo cp /usr/share/defaults/crio/crio.conf /etc/crio/ sudo $EDITOR /etc/crio/crio.conf -Learn more about `Stateless in Clear Linux`_ and view the `Clear Linux documentation`_. +Learn more about `Stateless`_ in |CL| and view the |CL| `documentation`_. Proxy configuration (optional) ****************************** @@ -343,7 +343,7 @@ Troubleshooting Your DNS server may not be appropriately configured. Try adding an entry to the :file:`/etc/hosts` file with your host's IP and Name. - + For example: 100.200.50.20 myhost Use the commands :command:`hostname` and :command:`hostname -I` to retrieve them. @@ -408,7 +408,7 @@ Troubleshooting .. _Joining your nodes: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#join-nodes -.. _Stateless in Clear Linux: https://clearlinux.org/features/stateless +.. _Stateless: https://clearlinux.org/features/stateless -.. _Clear Linux documentation: https://clearlinux.org/documentation/clear-linux +.. _documentation: https://clearlinux.org/documentation/clear-linux diff --git a/source/clear-linux/tutorials/machine-learning/machine-learning.rst b/source/clear-linux/tutorials/machine-learning/machine-learning.rst index e16a25f0..2b9da141 100644 --- a/source/clear-linux/tutorials/machine-learning/machine-learning.rst +++ b/source/clear-linux/tutorials/machine-learning/machine-learning.rst @@ -3,18 +3,18 @@ TensorFlow\* machine learning on |CL-ATTR| ########################################## -This tutorial will demonstrate the installation and execusion of a TensorFlow\* +This tutorial will demonstrate the installation and execusion of a TensorFlow\* machine learning example on |CL-ATTR|. It uses a Jupyter\* Notebook and MNIST data for handwriting recognition.  -The initial steps will have you set up a Jupyter kernel and run a Notebook +The initial steps will have you set up a Jupyter kernel and run a Notebook on a bare-metal |CL| system. Prerequisites ************* -This tutorial assumes you have installed |CL| on your host system. For detailed -instructions on installing |CL| on a bare metal system, follow the +This tutorial assumes you have installed |CL| on your host system. For detailed +instructions on installing |CL| on a bare metal system, follow the :ref:`bare metal installation tutorial`. Before you install any new packages, update |CL| with the following command: @@ -191,7 +191,7 @@ run the example code. Figure 8: The system's accuracy for the entire data set. -For more in-depth information on the model used and the mathematics it entails, +For more in-depth information on the model used and the mathematics it entails, visit the TensorFlow tutorials `TensorFlow MNIST beginners demo`_ and `TensorFlow MNIST pros demo`_. diff --git a/source/clear-linux/tutorials/multi-boot/multi-boot-restore-bl.rst b/source/clear-linux/tutorials/multi-boot/multi-boot-restore-bl.rst index 88e307db..2b71ffd5 100644 --- a/source/clear-linux/tutorials/multi-boot/multi-boot-restore-bl.rst +++ b/source/clear-linux/tutorials/multi-boot/multi-boot-restore-bl.rst @@ -1,6 +1,6 @@ .. _multi-boot-restore-bl: -Restore the Clear Linux boot loader +Restore the |CL-ATTR| boot loader ################################### This guide is part of the :ref:`multi-boot` tutorial. If you install a new diff --git a/source/clear-linux/tutorials/multi-boot/multi-boot.rst b/source/clear-linux/tutorials/multi-boot/multi-boot.rst index 57e0af9e..778729d0 100644 --- a/source/clear-linux/tutorials/multi-boot/multi-boot.rst +++ b/source/clear-linux/tutorials/multi-boot/multi-boot.rst @@ -1,9 +1,9 @@ .. _multi-boot: -Multi-boot Clear Linux with other operating systems -################################################### +Multi-boot |CL-ATTR| with other operating systems +################################################# -|CLOSIA| uses the Systemd-Boot boot loader, which does not support multi- +|CL-ATTR| uses the Systemd-Boot boot loader, which does not support multi- booting without manual manipulation. This tutorial shows how to configure the |CL| boot loader to work with other :abbr:`OSes (operating systems)`. @@ -99,8 +99,8 @@ Detailed procedures .. _multi-boot-cl: -Install Clear Linux OS -********************** +Install |CL| +************ Navigation tips for text-based installation interfaces: diff --git a/source/clear-linux/tutorials/smb/smb.rst b/source/clear-linux/tutorials/smb/smb.rst index 2fb02220..71e9baee 100644 --- a/source/clear-linux/tutorials/smb/smb.rst +++ b/source/clear-linux/tutorials/smb/smb.rst @@ -4,7 +4,7 @@ Enable simple file sharing with a Windows\* machine using Samba\* ################################################################# This tutorial describes how to enable simple file sharing from a system -running |CLOSIA| to a Windows machine using Samba. For more advanced sharing, +running |CL-ATTR| to a Windows machine using Samba. For more advanced sharing, refer to the `Samba guide`_. Prerequisites @@ -96,8 +96,8 @@ use the hostname of the |CL| machine. For other ways to access shares using a hostname instead of an IP address, see `Chapter 7 of the Samba guide`_. -Map Clear Linux drive in Windows -******************************** +Map |CL| drive in Windows +************************* #. Open Windows Explorer and click on the left sidebar on :guilabel:`This PC` to change the options available at the top. diff --git a/source/clear-linux/tutorials/spark.rst b/source/clear-linux/tutorials/spark.rst index 5b02cb9a..d1b0957e 100644 --- a/source/clear-linux/tutorials/spark.rst +++ b/source/clear-linux/tutorials/spark.rst @@ -4,7 +4,7 @@ Set up a standalone cluster system using Apache\* Spark\* ######################################################### This tutorial describes how to install, configure, and run Apache Spark on -|CLOSIA|. Apache Spark is a fast general-purpose cluster computing system with +|CL-ATTR|. Apache Spark is a fast general-purpose cluster computing system with the following features: * Provides high-level APIs in Java\*, Scala\*, Python\*, and R\*. diff --git a/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst b/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst index 131471c3..40ce9c58 100644 --- a/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst +++ b/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst @@ -1,9 +1,9 @@ .. _telemetry-backend: -Create a telemetry backend server in Clear Linux -################################################ +Create a telemetry backend server in |CL-ATTR| +############################################## -|CLOSIA| includes a telemetry and analytics solution, also known as +|CL-ATTR| includes a telemetry and analytics solution, also known as telemetrics, as part of the OS that records events of interest and reports them back to the development team using the telemetrics daemons that are running on the |CL| client system. @@ -23,14 +23,13 @@ A telemetry backend server consists of two Flask applications: The applications run within a web stack, using the :guilabel:`nginx` web server, the :guilabel:`uWSGI` application server, and :guilabel:`PostgreSQL` as the underlying database server. For a detailed -description, visit the `Clear Linux telemetry backend server overview`_. +description, visit the |CL| `telemetrics backend`_ server overview. This tutorial walks you through creating a telemetrics backend server on your local |CL| machine. The tutorial uses the :command:`deploy.sh` bash -shell script that is maintained in a GitHub repository at -https://github.com/clearlinux/telemetrics-backend. Once the backend server is -up and running, we show you how to redirect telemetry records from the system -you set up to this new server location. +shell script that is maintained in a the `telemetrics backend`_ GitHub repository. +Once the backend server isup and running, we show you how to redirect telemetry +records from the system you set up to this new server location. .. note:: The telemetrics functionality adheres to `Intel privacy policies`_ @@ -82,7 +81,7 @@ Run the deploy.sh script to install the backend server cd telemetrics-backend/scripts ./deploy.sh -h - + Deploy snapshot of the telemetrics-backend -a Perform specified action (deploy, install, migrate, resetdb, @@ -111,8 +110,8 @@ following actions: * *uninstall* - uninstall all packages. .. note:: - - The *uninstall* option does not perform any actions if the + + The *uninstall* option does not perform any actions if the distro is set to |CL| and will only uninstall packages if the distro is Ubuntu @@ -160,7 +159,7 @@ To begin the installation with the options defined: #. For the :guilabel:`DB password:`, press the :kbd:`Enter` key to accept the default password `postgres`. - + The :command:`swupd` begins installing the required software bundles to set up the telemetrics backend server. The output will look similar to what is shown below: @@ -234,7 +233,7 @@ the requirements to install and implement the telemetrics server. Finally, the script enables the server and provides output similar to: .. code-block:: console - + Collecting uwsgitop Downloading uwsgitop-0.10.tar.gz Requirement already satisfied: simplejson in /usr/lib/python3.6/site-packages (from uwsgitop) @@ -331,7 +330,7 @@ Once all the server components have been installed you are prompted to enter the :guilabel:`PostgreSQL` database password to change it as illustrated below: .. code-block:: console - + Enter password for 'postgres' user: New password: Retype new password: @@ -344,7 +343,7 @@ database password will be updated. The script finalizes installation and finishes. .. code-block:: console - + Created symlink /etc/systemd/system/multi-user.target.wants/postgresql.service → /usr/lib/systemd/system/postgresql.service. Cloning into 'telemetrics-backend'... remote: Counting objects: 344, done. @@ -461,8 +460,8 @@ server, redirected the records from your local machine to this new server and tested it using the :command:`hprobe` command to send a ``hello`` record to it. -Additional resources -******************** +Related topics +************** * `Telemetry feature description`_ * :ref:`Telemetry architecture` @@ -470,7 +469,7 @@ Additional resources * https://github.com/clearlinux/telemetrics-client * https://github.com/clearlinux/telemetrics-backend -.. _`Clear Linux telemetry backend server overview`: +.. _`telemetrics backend`: https://github.com/clearlinux/telemetrics-backend .. _`Intel privacy policies`: diff --git a/source/clear-linux/tutorials/wordpress/web-server-install.rst b/source/clear-linux/tutorials/wordpress/web-server-install.rst index b4c5fb93..dce6ed5f 100644 --- a/source/clear-linux/tutorials/wordpress/web-server-install.rst +++ b/source/clear-linux/tutorials/wordpress/web-server-install.rst @@ -3,14 +3,15 @@ Set up a LAMP web server on |CL-ATTR| ##################################### -This tutorial provides instructions on how to set up a -:abbr:`LAMP (Linux, Apache, MySQL, PHP)` web server on |CL-ATTR| and how -to use phpMyAdmin\* to manage an associated database. Note that this +This tutorial provides instructions on how to set up a +:abbr:`LAMP (Linux, Apache, MySQL, PHP)` web server on |CL-ATTR| and how +to use phpMyAdmin\* to manage an associated database. Note that this tutorial installs MariaDB\*, which is a drop-in replacement for MySQL\*. -In order to create a web server using |CL| as the host OS, your host system -must be running |CL|. This tutorial assumes you have successfully installed -:ref:`Clear Linux on bare metal`. +In order to create a web server using |CL| as the host OS, your host system +must be running |CL|. This tutorial 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 tutorial`. This tutorial covers: @@ -20,19 +21,19 @@ This tutorial covers: Install Apache ************** -Apache is an open source HTTP web server application that can run on several -operating systems, including |CL|. Go to the `Apache HTTP Server Project`_ +Apache is an open source HTTP web server application that can run on several +operating systems, including |CL|. Go to the `Apache HTTP Server Project`_ for more information. Install the web-server-basic bundle =================================== -The **web-server-basic** bundle contains the packages needed to install the +The **web-server-basic** bundle contains the packages needed to install the Apache software bundle on |CL|. .. note:: - Before you install new packages, update the |CL| with the following + Before you install new packages, update the |CL| with the following console command: .. code-block:: bash @@ -54,9 +55,9 @@ Apache software bundle on |CL|. sudo systemctl start httpd.service #. To verify that the Apache server application is running, open a web - browser and navigate to: http://localhost. + browser and navigate to: \http://localhost. - If the service is running, a confirmation message will appear, similar to the + If the service is running, a confirmation message will appear, similar to the message shown in figure 1. .. figure:: figures/web-server-install-1.png @@ -67,19 +68,19 @@ Apache software bundle on |CL|. .. note:: - The :file:`index.html` file is located in the :file:`/var/www/html` directory - of your host system. You will copy this file into a new location after you + The :file:`index.html` file is located in the :file:`/var/www/html` directory + of your host system. You will copy this file into a new location after you modify the configuration in the next step. Change the default configuration and data directory *************************************************** -|CL| is designed to be a `stateless`_ operating system which means that you -must create an optional configuration file to override the default values. -The default location of the Apache configuration file, :file:`httpd.conf`, -is located in the :file:`/usr/share/defaults/httpd` directory. |CL| can -override this directory as part of the stateless paradigm. This default -:file:`.conf` file includes the following directives that allow for additional +|CL| is designed to be a `stateless`_ operating system which means that you +must create an optional configuration file to override the default values. +The default location of the Apache configuration file, :file:`httpd.conf`, +is located in the :file:`/usr/share/defaults/httpd` directory. |CL| can +override this directory as part of the stateless paradigm. This default +:file:`.conf` file includes the following directives that allow for additional locations of configuration definitions: .. code-block:: console @@ -90,23 +91,23 @@ locations of configuration definitions: IncludeOptional /etc/httpd/conf.d/*.conf IncludeOptional /etc/httpd/conf.modules.d/*.conf -In this section you will define your own httpd.conf file to override the +In this section you will define your own httpd.conf file to override the default values, and define a custom DocumentRoot for your web server. -#. Create the directory structure for :file:`/etc/httpd/conf.d`. +#. Create the directory structure for :file:`/etc/httpd/conf.d`. .. code-block:: bash sudo mkdir -p /etc/httpd/conf.d -#. Create and open the :file:`httpd.conf` file in your new :file:`/etc/httpd/conf.d` +#. Create and open the :file:`httpd.conf` file in your new :file:`/etc/httpd/conf.d` directory. .. code-block:: bash sudo nano /etc/httpd/conf.d/httpd.conf -#. Add the ``DocumentRoot`` variable to :file:`httpd.conf`. Copy the content +#. Add the ``DocumentRoot`` variable to :file:`httpd.conf`. Copy the content listed below into the new :file:`/etc/httpd/conf.d/httpd.conf` file. .. code-block:: console @@ -124,8 +125,8 @@ default values, and define a custom DocumentRoot for your web server. Require all granted -#. Create a new ``DocumentRoot`` directory structure and copy the - :file:`index.html` file from :file:`/var/www/html` directory to +#. Create a new ``DocumentRoot`` directory structure and copy the + :file:`index.html` file from :file:`/var/www/html` directory to :file:`/var/www/tutorial`. .. code-block:: bash @@ -134,21 +135,21 @@ default values, and define a custom DocumentRoot for your web server. cd /var/www/tutorial sudo cp /var/www/html/index.html . -#. To ensure a successful setup, edit the new :file:`index.html` file with an - obvious change. +#. To ensure a successful setup, edit the new :file:`index.html` file with an + obvious change. .. code-block:: bash sudo nano index.html - For example, we changed the default message + For example, we changed the default message - "It works!" + "It works!" - to + to "It works from its new location!" - + #. Stop and then restart ``httpd.service``. .. code-block:: bash @@ -156,11 +157,11 @@ default values, and define a custom DocumentRoot for your web server. sudo systemctl stop httpd.service sudo systemctl start httpd.service -#. Go to http://localhost to view the new screen. You should see your updated +#. Go to \http://localhost to view the new screen. You should see your updated default message from step 5. -#. Change the configuration back to the default :file:`/var/www/html` - location. To do this, edit the :file:`/etc/httpd/conf.d/httpd.conf` file +#. Change the configuration back to the default :file:`/var/www/html` + location. To do this, edit the :file:`/etc/httpd/conf.d/httpd.conf` file again and replace any instance of /var/www/tutorial with /var/www/html. .. code-block:: bash @@ -174,7 +175,7 @@ default values, and define a custom DocumentRoot for your web server. sudo systemctl stop httpd.service sudo systemctl start httpd.service -#. Go to http://localhost and verify that you can see the default screen +#. Go to \http://localhost and verify that you can see the default screen again. #. Optionally, remove the /var/www/tutorial directory you previously created. @@ -187,8 +188,8 @@ default values, and define a custom DocumentRoot for your web server. Install PHP *********** -An Apache installation allows you to display static web pages. Enabling PHP -allows you to generate and display dynamic web pages. To add this +An Apache installation allows you to display static web pages. Enabling PHP +allows you to generate and display dynamic web pages. To add this functionality to your web server, install PHP on your system. #. To get the php components, enter the following command: @@ -207,7 +208,7 @@ functionality to your web server, install PHP on your system. After restarting the Apache service, test your PHP installation. -#. Create and open a file named :file:`phpinfo.php` in the :file:`/var/www/html/` +#. Create and open a file named :file:`phpinfo.php` in the :file:`/var/www/html/` directory using a text editor. .. code-block:: bash @@ -220,7 +221,7 @@ functionality to your web server, install PHP on your system. -#. Go to http://localhost/phpinfo.php. +#. Go to \http://localhost/phpinfo.php. #. Verify that the PHP information screen appears, similar to figure 2: @@ -230,14 +231,14 @@ functionality to your web server, install PHP on your system. `Figure 2: The PHP information screen.` -If the PHP information screen is displayed, you have successfully installed -the PHP components and are now ready to add your database application to +If the PHP information screen is displayed, you have successfully installed +the PHP components and are now ready to add your database application to complete your LAMP server implementation. Install MariaDB *************** -Install MariaDB to store content. MariaDB is a drop-in replacement for MySQL +Install MariaDB to store content. MariaDB is a drop-in replacement for MySQL and is available in the database-basic |CL| bundle. #. To install the database-basic bundle, enter the following command: @@ -259,12 +260,12 @@ and is available in the database-basic |CL| bundle. sudo systemctl status mariadb - Press :kbd:`Ctrl` + :kbd:`c` or :kbd:`q` to exit. + Press :kbd:`Ctrl` + :kbd:`c` or :kbd:`q` to exit. Security hardening ================== -With the MariaDB service running, we can perform some basic security +With the MariaDB service running, we can perform some basic security hardening. #. To add a basic layer of security, enter the following command: @@ -273,9 +274,9 @@ hardening. sudo mysql_secure_installation -#. Respond to the questions that appear in the script below. - - .. note:: +#. Respond to the questions that appear in the script below. + + .. note:: Our suggested responses follow each question. @@ -283,8 +284,8 @@ hardening. Enter current password for root (enter for none): - In order to secure MariaDB, we need the current password for the root - user. For a newly installed MariaDB without a set root password, the + In order to secure MariaDB, we need the current password for the root + user. For a newly installed MariaDB without a set root password, the password is blank. Thus, press enter to continue. .. code-block:: bash @@ -295,7 +296,7 @@ hardening. .. _set-password: - Set the root password to prevent unauthorized MariaDB root user logins. + Set the root password to prevent unauthorized MariaDB root user logins. To set a root password, type 'y'. .. code-block:: bash @@ -319,8 +320,8 @@ hardening. Remove anonymous users? [Y/n] By default, a MariaDB installation includes an anonymous user that allows - anyone to log in to MariaDB without a user account. This anonymous user - is intended only for testing and for a smoother installation. To remove + anyone to log in to MariaDB without a user account. This anonymous user + is intended only for testing and for a smoother installation. To remove the anonymous user and make your database more secure, type 'y'. .. code-block:: bash @@ -328,8 +329,8 @@ hardening. ... Success! Disallow root login remotely? [Y/n] - Normally, root should only be allowed to connect from the 'localhost'. This - ensures that someone cannot guess the root password from the network. To + Normally, root should only be allowed to connect from the 'localhost'. This + ensures that someone cannot guess the root password from the network. To block any remote root login, type 'y'. .. code-block:: bash @@ -337,8 +338,8 @@ hardening. ... Success! Remove test database and access to it? [Y/n] - By default, MariaDB includes a database named 'test' which anyone can access. - This database is also intended only for testing and should be removed. To + By default, MariaDB includes a database named 'test' which anyone can access. + This database is also intended only for testing and should be removed. To remove the test database, type 'y'. .. code-block:: bash @@ -349,7 +350,7 @@ hardening. ... Success! Reload privilege tables now? [Y/n] - Reloading the privilege tables ensures all changes made so far take + Reloading the privilege tables ensures all changes made so far take effect immediately. To reload the privilege tables, type 'y'. .. code-block:: bash @@ -363,15 +364,15 @@ hardening. Thanks for using MariaDB! -The MariaDB installation is complete, and we can now install phpMyAdmin to +The MariaDB installation is complete, and we can now install phpMyAdmin to manage the databases. Install phpMyAdmin ****************** -The web-based tool phpMyAdmin is a straightforward way to manage MySQL or -MariaDB databases. Visit the `phpMyAdmin`_ website for the complete -discussion regarding phpMyAdmin, its documentation, the latest downloads, +The web-based tool phpMyAdmin is a straightforward way to manage MySQL or +MariaDB databases. Visit the `phpMyAdmin`_ website for the complete +discussion regarding phpMyAdmin, its documentation, the latest downloads, and other useful information. In this tutorial, we use the latest English version of phpMyAdmin. @@ -404,14 +405,14 @@ In this tutorial, we use the latest English version of phpMyAdmin. Use phpMyAdmin to manage a database *********************************** -You can use the phpMyAdmin web-based tool to manage your databases. Follow the +You can use the phpMyAdmin web-based tool to manage your databases. Follow the steps below for setting up a database called "WordPress". #. Verify that a successful installation of all LAMP server components by - going to http://localhost/phpMyAdmin. See figure 3. + going to \http://localhost/phpMyAdmin. See figure 3. #. Log in with your root userid and the password you set up when you ran the - :ref:`mysql_secure_installation command `. Enter your + :ref:`mysql_secure_installation command `. Enter your credentials and select :guilabel:`Go` to log in: .. figure:: figures/web-server-install-3.png @@ -457,8 +458,8 @@ steps below for setting up a database called "WordPress". `Figure 6: The Privileges tab.` -#. Click :guilabel:`Add user account` located at the bottom of the - :guilabel:`Privileges` tab. The `Add user account` page appears, as shown +#. Click :guilabel:`Add user account` located at the bottom of the + :guilabel:`Privileges` tab. The `Add user account` page appears, as shown in figure 7. .. figure:: figures/web-server-install-7.png @@ -476,7 +477,7 @@ steps below for setting up a database called "WordPress". * Re-type: wp-example -#. In the `Database for user account` section, select +#. In the `Database for user account` section, select :guilabel:`Grant all privileges on database “WordPress”.` #. At the bottom of the page, click :guilabel:`Go`. @@ -491,7 +492,7 @@ If successful, you should see the screen shown in figure 8: **Congratulations!** -You have now created a fully functional LAMP server along with a +You have now created a fully functional LAMP server along with a WordPress\*-ready database using |CL|. Next steps diff --git a/source/clear-linux/tutorials/wordpress/wordpress.rst b/source/clear-linux/tutorials/wordpress/wordpress.rst index 31060894..6eecac79 100644 --- a/source/clear-linux/tutorials/wordpress/wordpress.rst +++ b/source/clear-linux/tutorials/wordpress/wordpress.rst @@ -1,22 +1,22 @@ .. _wordpress: -WordPress\* on |CL-ATTR| +WordPress\* on |CL-ATTR| ######################## -This tutorial describes how to setup a web server to host a WordPress\* site on a -|CL-ATTR| system. The tutorial is split into two sections: +This tutorial describes how to setup a web server to host a WordPress\* site on a +|CL-ATTR| system. The tutorial is split into two sections: #. :ref:`web-server-install` #. :ref:`wp-install` -If you already have a |CL| based :abbr:`LAMP (Linux, Apache, MySQL, PHP)` web server, +If you already have a |CL| based :abbr:`LAMP (Linux, Apache, MySQL, PHP)` web server, you can skip ahead to the second section of this tutorial. .. note:: - This tutorial is for development and testing purposes only. Additional steps - are required to secure production systems. Those steps are beyond the scope + This tutorial is for development and testing purposes only. Additional steps + are required to secure production systems. Those steps are beyond the scope of this tutorial. .. toctree:: diff --git a/source/clear-linux/tutorials/wordpress/wp-install.rst b/source/clear-linux/tutorials/wordpress/wp-install.rst index aa062e3e..d87ff674 100644 --- a/source/clear-linux/tutorials/wordpress/wp-install.rst +++ b/source/clear-linux/tutorials/wordpress/wp-install.rst @@ -3,34 +3,34 @@ Set up WordPress\* on a LAMP web server ####################################### -This tutorial shows you how to install the WordPress\* components on your |CL| -:abbr:`LAMP (Linux, Apache, MySQL, PHP)` server. At the end of -:ref:`web-server-install`, you created a WordPress-ready database using -phpMyAdmin\* and MariaDB\*. Now that the LAMP server is up and running, you +This tutorial shows you how to install the WordPress\* components on your |CL| +:abbr:`LAMP (Linux, Apache, MySQL, PHP)` server. At the end of +:ref:`web-server-install`, you created a WordPress-ready database using +phpMyAdmin\* and MariaDB\*. Now that the LAMP server is up and running, you can add the WordPress components needed to host a WordPress website on your system. Before you begin **************** -This tutorial assumes you have successfully completed :ref:`bare-metal-install` +This tutorial assumes you have successfully completed :ref:`bare-metal-install` and that you have :ref:`web-server-install`. Create a WordPress server ************************* -WordPress can be installed in a variety of ways. These instructions are -written for users who have followed our instructions for installing phpMyAdmin -when they :ref:`set up a LAMP web server `. Note that -all steps in this tutorial have been tested using a NUC6i5SYH Intel® NUC. +WordPress can be installed in a variety of ways. These instructions are +written for users who have followed our instructions for installing phpMyAdmin +when they :ref:`set up a LAMP web server `. Note that +all steps in this tutorial have been tested using a NUC6i5SYH Intel® NUC. Visit the `NUC6i5SYH product page`_ for detailed information. -Numerous online articles are available to help you name your website and +Numerous online articles are available to help you name your website and acquire the necessary certificates. Those tasks are beyond the scope of this tutorial. -You can take several actions to harden your website from attacks. The security -of your website and the data it contains are complex and ever-evolving tasks. -Prioritize security if you plan to expose your website to the outside world. -This tutorial does not address security measures that you can take to harden +You can take several actions to harden your website from attacks. The security +of your website and the data it contains are complex and ever-evolving tasks. +Prioritize security if you plan to expose your website to the outside world. +This tutorial does not address security measures that you can take to harden your site but we strongly encourage you to take action. .. note:: @@ -41,10 +41,10 @@ your site but we strongly encourage you to take action. Download WordPress and manage directories ========================================= -For this tutorial, you will create a WordPress blog that can be accessed at: -http:///blog. +For this tutorial, you will create a WordPress blog that can be accessed at: +\http:///blog. -To accomplish this setup, you must add WordPress components to the :file:`/var/www/html/blog` +To accomplish this setup, you must add WordPress components to the :file:`/var/www/html/blog` directory. Follow these steps: @@ -83,11 +83,11 @@ Follow these steps: Set up WordPress with web-based GUI =================================== -Recall that you created a database and user when you installed phpMyAdmin during -:ref:`Creating a Clear Linux based web server `. Next, you must +Recall that you created a database and user when you installed phpMyAdmin when you +set up a |CL| based :ref:`web server `. Next, you must connect WordPress to the database and install WordPress. -To continue with the setup, go to: http:///blog/wp-admin/install.php. +To continue with the setup, go to: \http:///blog/wp-admin/install.php. The WordPress language option screen appears, as shown in figure 1. #. Select :guilabel:`English` and click :guilabel:`Continue`. @@ -99,7 +99,7 @@ The WordPress language option screen appears, as shown in figure 1. `Figure 1: WordPress language selection screen.` - The WordPress installation continues until the Welcome screen appears, as shown in + The WordPress installation continues until the Welcome screen appears, as shown in figure 2: .. figure:: figures/wp-install-2.png @@ -110,9 +110,9 @@ The WordPress language option screen appears, as shown in figure 1. #. Click :guilabel:`Let’s go!`. -#. Enter database connection specifics in the screen that appears, as shown in figure 3 +#. Enter database connection specifics in the screen that appears, as shown in figure 3 below. - + * Database name: WordPress * Database username: wordpressuser * Database password: wp-example (asterisks will not appear in the text box) @@ -127,7 +127,7 @@ The WordPress language option screen appears, as shown in figure 1. #. Click :guilabel:`Submit` to complete the setup. - Figure 4 shows the confirmation screen that verifies a successful setup. WordPress + Figure 4 shows the confirmation screen that verifies a successful setup. WordPress is connected to the MariaDB database. .. figure:: figures/wp-install-4.png @@ -142,7 +142,7 @@ The WordPress language option screen appears, as shown in figure 1. Complete successful login ========================= -Once the installation is complete, you can name your blog and create a WordPress username +Once the installation is complete, you can name your blog and create a WordPress username and password. See figure 5. .. figure:: figures/wp-install-5.png @@ -177,7 +177,7 @@ Figure 7 shows the WordPress dashboard after a successful login: You are ready to go! To check out your blog as it is seen by the outside world, enter: -http:///blog on your browser. Figure 8 shows the result: +\http:///blog on your browser. Figure 8 shows the result: .. figure:: figures/wp-install-8.png :alt: WordPress blog diff --git a/source/substitutions.txt b/source/substitutions.txt index 7a156671..24330b4c 100644 --- a/source/substitutions.txt +++ b/source/substitutions.txt @@ -1,12 +1,10 @@ .. |CL| replace:: Clear Linux OS -.. |CLOSIA| replace:: Clear Linux* OS - .. |CL-ATTR| replace:: Clear Linux* OS .. |CL-PRJ| replace:: Clear Linux* project .. |CC| replace:: Clear Containers -.. |CAUTION-BACKUP-USB| replace:: +.. |CAUTION-BACKUP-USB| replace:: Burning an image formats the USB drive, thus destroying all existing content. Backup your data before proceeding.