diff --git a/README.rst b/README.rst index 83cf1266..ab37040d 100644 --- a/README.rst +++ b/README.rst @@ -1,83 +1,74 @@ -Documentation Build Instructions +Documentation build instructions ################################ -The `website documentation`_ for Clear Linux\* OS for Intel Architecture -should be written in :abbr:`ReStructuredText (ReST)` AKA ``.rst``, which -makes it easy to build parsable, command-line readable, indexed, and -search-friendly documentation and APIs with `Sphinx`_. +.. todo add comment re not using standards here. -.. _requirements: +`Clear Linux\* OS documentation`_ is written using `reStructuredText`_ and +built using `Sphinx`_. Follow the instructions in this README to build the +documentation locally for development and testing. + +Please make yourself familiar with our `contribution guidelines`_ before +submitting a contribution. Requirements -============ +************ -To build documentation with Sphinx, ensure your system has these -prerequisites: +Make sure you have Python and Sphinx installed. We use Python 3 and +Sphinx 1.7.5 -* `GNU make`_ -* `Python`_ -* `PIP`_ -* `Sphinx`_ +The Sphinx documentation provides `instructions for installing Sphinx`_ on various +platforms. -The instructions for installing these varies according to OS. On a basic out- -of-the-box Ubuntu-like OS (which usually has Python installed by default), -check your python version you might need something like: - -.. code-block:: console - - $ sudo apt-get install python-pip - $ sudo pip install -U sphinx sphinx-autobuild - - - -.. code-block:: console - - $ python -c 'print __import__("sphinx").__version__' - 1.3.1 - -Cloning the documentation repository -==================================== - -We have confirmed Sphinx installed. The next step is to clone Gitlab -repository to our local machine. +Clone the documentation repository +********************************** +Once Sphinx is installed, clone the documentation repository to your +local machine. .. code-block:: console $ git clone https://github.com/clearlinux/clear-linux-documentation -Run make -======== +Run the build +************* -Finally are we ready to run :command:`make`. Be sure to :command:`cd` to the -:file:`source/` directory where your ``.rst`` files are, before -running :command:`make html`, or the doc format of your choice. +We build our documentation using Sphinx. In the source directory of your +local clear-linux-documentation repository, build the documentation by running +**make html**: .. code-block:: console $ make html > sphinx-build -b html -d _build/doctrees . _build/html - Running Sphinx v1.3.1 + Running Sphinx v1.7.5 making output directory... . . . build succeeded, 0 warnings. + The HTML pages are in _build/html. + Build finished. The HTML pages are in _build/html. -Open one of the .html pages in a web browser to view the rendered +Open one of the HTML pages in a web browser to view the rendered documentation. -For tips on how to contribute documentation formatted in the .rst style -needed to integrate beautifully on the clearlinux.org website, please see - `Theming Sphinx`_. +When testing changes in the documentation, make sure to remove the previous +build before building again by running **make clean**: +.. code-block:: console -.. _website documentation: https://clearlinux.org/documentation + $ make clean + > + rm -rf _build/* + +This will completely remove the previous build output. + +.. _Clear Linux\* OS documentation: https://clearlinux.org/documentation .. _Sphinx: http://sphinx-doc.org/ -.. _GNU make: https://www.gnu.org/software/make/ -.. _Python: https://www.python.org/ -.. _PIP: https://pypi.python.org/pypi/pip/ -.. _Theming Sphinx: https://github.com/otcshare/tcs-hub/blob/master/theming-sphinx.rst +.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +.. _contribution guidelines: https://clearlinux.org/documentation/clear-linux/reference/collaboration +.. _instructions for installing Sphinx: https://www.sphinx-doc.org/en/master/usage/installation.html + diff --git a/source/Makefile b/source/Makefile index 655286aa..6ef592c3 100644 --- a/source/Makefile +++ b/source/Makefile @@ -166,10 +166,8 @@ changes: @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." + -$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + python3 scripts/_python/linkcheck/parse-link-check.py $(BUILDDIR)/linkcheck doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 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..0545c003 --- /dev/null +++ b/source/clear-linux/get-started/bare-metal-install-beta/bare-metal-install-beta.rst @@ -0,0 +1,837 @@ +.. _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 +*********************** + +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 :kbd:`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 + +.. _incl-bare-metal-beta-start: + +Minimum installation requirements +********************************* + +To fulfill minimum installation requirements, complete the +`Required options`_. `Advanced options`_ are optional. + +.. note:: + + * The :kbd:`Install` button is only highlighted **after** you complete the + `Required options`_, and after you enter required values in submenus. + + * You must choose whether or not to participate in :ref:`telemetrics` + before you can finish installation. + + * You may wish to `Test Network Settings`_ before you + `Configure Network Interfaces`_. Assure that a ``Success`` message is received before installation. + +Main Menu +********* +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: Clear Linux OS Installer Main Menu + +The |CL| Installer Main Menu has two tabs: :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 +beside the :guilabel:`>>` chevron, below the menu options. + +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. + +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: 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: 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: 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: 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 method and continue below: + + * `Auto Partition`_ + * `Add 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: Auto Partition + +#. You may skip to the `Telemetry`_ section below. + +Disk encryption +=============== + +For greater security, disk encryption is supported using LUKS for all +partitions **except boot** on |CL|. To encrypt a partition, see the example +in `root partition`_ below. Encryption is optional. + +Encryption Passphrase +--------------------- + +|CL| uses a single passphrase for all encrypted partitions. Therefore, if +you turn on encryption for one partition, the same passphrase is used for +all partitions. Additional or different keys may be configured +post-installation using the ``cryptsetup`` tool. + +.. note:: + + During installation, if you encrypt the `root` partition first and the + `swap` partition second, after you select encrypt for `swap`, the + :guilabel:`Encryption Passphrase` dialogue will show the same Passphrase that was assigned to `root`. Select :guilabel:`Confirm` and + press :kbd:`Enter` to use the same Passphrase. + +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: 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: swap partition + +root partition +-------------- + +#. In the :guilabel:`File System` menu, select :kbd:`Up/Down` arrows to + select the file system type. See Figure 11. + + #. Optional: Select :guilabel:`[X] Encrypt` to encrypt the partition. + + .. figure:: figures/bare-metal-install-beta-11.png + :scale: 100% + :alt: Encrypt partition + + Figure 11: Encrypt partition + + + #. The :guilabel:`Encryption Passphrase` dialogue appears. + + .. note:: + + Minimum length is 8 characters. Maximum length is 94 characters. + + .. figure:: figures/bare-metal-install-beta-12.png + :scale: 100% + :alt: Encryption Passphrase + + Figure 12: Encryption Passphrase + + #. Enter the same passphrase in the first and second field. + + #. Navigate to :guilabel:`Confirm` and press :kbd:`Enter`. + + .. note:: + + :guilabel:`Confirm` is only highlighted if passphrases match. + +#. Optional: In :guilabel:`[Optional] Label:`, enter your desired + label for the partition. + +#. In :guilabel:`Mount Point`, enter ``/``. See Figure 11. + +#. 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. See Figure 13. + +#. You are returned to the :guilabel:`Configure media` menu. Your partitions + should be similar to those shown in Figure 13. + + .. figure:: figures/bare-metal-install-beta-13.png + :scale: 100% + :alt: Partitions + + Figure 13: Partitions + +#. Navigate to :guilabel:`Confirm` until highlighted. + +#. Select :guilabel:`Enter` to complete adding partitions. + +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-14.png + :scale: 100% + :alt: Enable Telemetry + + Figure 14: Enable Telemetry + +Skip to finish installation +=========================== + +After selecting values for all :guilabel:`Required options`, you may skip +to `Finish installation`_. + +Otherwise, continue below. In the Main Menu, select +:guilabel:`Advanced options` to configure network interfaces or proxy +settings, add bundles, add/manage users, add kernel arguments, and more. + +Advanced Options +**************** + +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-15.png + :scale: 100% + :alt: Configure Network Interfaces + + Figure 15: 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-16.png + :scale: 100% + :alt: Network interface configuration + + Figure 16: 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: 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-17.png + :scale: 100% + :alt: Configure the network proxy + + Figure 17: 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: Skip to `Finish installation`_. + +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 18. + +.. figure:: figures/bare-metal-install-beta-18.png + :scale: 100% + :alt: Testing Networking dialogue + + Figure 18: Testing Networking dialogue + +.. note:: + + Any changes made to network settings are automatically tested + during configuration. + +Optional: 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-19.png + :scale: 100% + :alt: Bundle Selection + + Figure 19: Bundle Selection + +#. Select :kbd:`Confirm` or :kbd:`Cancel`. + + You are returned to the :guilabel:`Advanced options` menu. + +Optional: 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 20. + + .. figure:: figures/bare-metal-install-beta-20.png + :scale: 100% + :alt: Add New User, User Name + + Figure 20: 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-21.png + :scale: 100% + :alt: User Name + + Figure 21: 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-22.png + :scale: 100% + :alt: Administrative rights + + Figure 22: 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 23. + +#. Select :kbd:`Enter` to modify the user. + + .. figure:: figures/bare-metal-install-beta-23.png + :scale: 100% + :alt: Modify User + + Figure 23: 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: 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-24.png + :scale: 100% + :alt: kernel command line + + Figure 24: 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: Skip to `Finish installation`_. + +Kernel Selection +================ + +#. Select a kernel option. By default, the latest kernel release is + selected. Native kernel is shown in Figure 25. + +#. To select a differnt kernel, navigate to it using :guilabel:`Tab`. + + .. figure:: figures/bare-metal-install-beta-25.png + :scale: 100% + :alt: Kernel selection + + Figure 25: Kernel selection + +#. Select :kbd:`Spacebar` to select the desired option. + +#. Select :kbd:`Confirm`. + +Optional: 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-26.png + :scale: 100% + :alt: Swupd Mirror + + Figure 26: Swupd Mirror + +Optional: 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-27.png + :scale: 100% + :alt: Assign Hostname + + Figure 27: Assign Hostname + + +#. Navigate to :kbd:`Confirm` until highlighted. + +#. Select :kbd:`Confirm`. + +Optional: 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-28.png + :scale: 100% + :alt: Automatic OS Updates + + Figure 28: Automatic OS Updates + +You are returned to the :guilabel:`Main Menu`. + +Finish installation +******************* + +#. When you are satisfied with your installation configuration, navigate to + :guilabel:`Install` and select :kbd:`Enter`. + + .. note:: + + When 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. + +Next steps +********** + +:ref:`enable-user-space` + +.. _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..888b9c2a 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..9a6b61c7 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..89ca1936 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..6ac1f059 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..3e7fbb8a 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..1eaa499e 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..d2c2a031 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..7e1d6cc9 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..4948cbe6 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..720d06dd 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..39f9a644 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..0ce16ab7 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..3a028f4e 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..f7fe354f 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..02a5cc26 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..e726b95e 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..9e1b42d5 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..14dec55a 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-28.png b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-28.png new file mode 100644 index 00000000..4e3acf29 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-beta/figures/bare-metal-install-beta-28.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..21121e06 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..dcce7ec9 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..dac8525d 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..a9b249b6 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..75d7898a 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..267278b4 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..0dca46e6 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..47cd92c1 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 @@ -1,36 +1,46 @@ .. _bare-metal-install: -Install |CL-ATTR| on bare metal (automatic) -########################################### +Install |CL-ATTR| on bare metal +############################### 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|: +.. contents:: + :local: + :depth: 1 -* :ref:`system-requirements` +System requirements +******************* + +Assure that your target system supports the installation: + +* :ref:`system-requirements` * :ref:`compatibility-check` - Download the latest |CL| installer image **************************************** -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: +Get the latest |CL| installer image from the `downloads page`_. See Figure 1. +Look for the :file:`clear-[version number]-installer.img.xz` file. + +.. figure:: figures/bare-metal-install-1.png + :scale: 50% + :alt: Visit Downloads + + Figure 1: Visit Downloads + +Optionally, you can 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. +#. Follow your OS instructions to create a bootable USB drive. -.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst - :Start-after: incl-decompress-image: - :end-before: incl-decompress-image-end: + * :ref:`bootable-usb-beta-all` -.. include:: ../bootable-usb/bootable-usb-linux.rst - :Start-after: copy-usb-linux: - :end-before: usb-next +#. After downloading the image, verify and decompress the file per your OS. .. _install-on-target: @@ -57,269 +67,21 @@ 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 - :kbd:`Enter` key or wait five seconds to automatically select it. - - .. figure:: figures/bare-metal-install-1.png - :scale: 50 % - :alt: Boot menu - - Figure 1: :guilabel:`Boot menu` - -#. This will take you into the |CL| installer menu as shown in figure 2 and explains how to - navigate through the |CL| installer setup menus. +#. This action launches the |CL| installer boot menu, shown in figure 2. .. figure:: figures/bare-metal-install-2.png - :scale: 50 % - :alt: Installer menu + :scale: 100% + :alt: Clear Linux OS Installer boot menu - Figure 2: :guilabel:`Installer menu` + Figure 2: Clear Linux OS Installer boot menu - Press the :kbd:`Enter` key. +#. With :guilabel:`Clear Linux OS` highlighted, select :kbd:`Enter`. -#. The :guilabel:`Keyboard selection` menu shown in figure 3 allows you to set - up the keyboard layout that you will be using to navigate within the |CL| - installer setup menus. +Your system will display the |CL| Installer. - .. figure:: figures/bare-metal-install-3.png - :scale: 50 % - :alt: Keyboard Selection +.. include:: ../bare-metal-install-beta/bare-metal-install-beta.rst + :start-after: incl-bare-metal-beta-start: - Figure 3: :guilabel:`Keyboard Selection` - For this guide we will select :menuselection:`Keyboard Selection --> - < * us >` for the keyboard mapping, which should already be highlighted. - Press the :kbd:`Enter` key to continue to the next menu. - -Network requirements -==================== - -The :guilabel:`Network Requirements` menu, the first step of the |CL| -installer setup process, will attempt to connect to the |CL| update server -where the installer image is located. Once the connection to the |CL| update -server is established, you will see a screen similar to the one shown in -figure 4. - -.. figure:: figures/bare-metal-install-4.png - :scale: 50 % - :alt: Network Requirements - - Figure 4: :guilabel:`Network Requirements` - -If you need to configure any :guilabel:`Proxy Settings` to gain access to the -update server, enter the appropriate address and port of your proxy server in -the :guilabel:`HTTPS proxy:` field. Select the :guilabel:`< Set proxy -configuration >` button and press :kbd:`Enter`. You will then see the -connection to the update server established. - -Optionally, set up a :guilabel:`static IP configuration` to your |CL| -installer image. Enter the required information in the :guilabel:`Interface`, -:guilabel:`IP address`, :guilabel:`Subnet mask`, :guilabel:`Gateway` and -:guilabel:`DNS` fields and then select the :guilabel:`< Set static IP -configuration >` button and press the :kbd:`Enter` key. - -The information displayed in the lower right quadrant of the screen shows the -current IP configuration for the |CL| update server where the installer image -is located. - -.. note:: - - If you are having difficulty establishing a connection to the update server - and you see the message :guilabel:`none detected, install will fail`, you - can press the :kbd:`Tab` key to highlight the :guilabel:`< Refresh >` - button and press :kbd:`Enter` to attempt to reconnect to the |CL| update - server. If this fails to establish a connection after multiple attempts, - reboot your system and return to this step. - -Once the connection to the |CL| udpate server is established, use the -:kbd:`Tab` key to advance to the :guilabel:`< Next >` button and press -:kbd:`Enter` to advance to the next |CL| installer setup menu. - -Choose |CL| installer action -============================ - -The :guilabel:`Choose Action` menu is where you can choose to install, repair, -open a shell, or exit the |CL| installer. This menu is shown in figure 5. - -.. figure:: figures/bare-metal-install-5.png - :scale: 50 % - :alt: Choose Action - - Figure 5: :guilabel:`Choose Action` - -#. Select the :menuselection:`Choose action --> Install` menu item to continue - the installation process. - - The :menuselection:`Choose action --> Repair` menu option will run the - :command:`swupd --fix` command to correct any issues found with the system - software that has already been installed on your system and correct any - issues found by overwriting the incorrect file content, adding missing - files, fixing permissions and any additional changes required to return the - file to it's original content and permissions. - - The :menuselection:`Choose action --> Shell` menu item opens a terminal - session on your system as the root user and you will be able to manage your - system from this console. When you are finished, type :command:`exit` to - return to the :guilabel:`Choose Action` menu. - - The :menuselection:`Choose action --> Exit` menu option terminates the |CL| - installation process and the system will shut down. - -#. You will be prompted to join the :guilabel:`Stability Enhancement Program` - as shown in figure 6. Press the :kbd:`Spacebar` or :kbd:`Enter` key until - the cursor appears in the :guilabel:`[ ] Yes.` button. Press tab to highlight :guilabel:`< Next >`, and select Enter to advance. - - .. figure:: figures/bare-metal-install-6.png - :scale: 50 % - :alt: Stability Enhancement Program - - Figure 6: :guilabel:`Stability Enhancement Program` - - If you choose not to enable this functionality during this step, you can - install the ``telemetrics`` software bundle at a later time. As stated in - the menu, this feature only collects anonymous information about your - system to help improve system stability and no personally identifiable - information is collected. Please visit our website to - `learn more about telemetry.`_ - -Choose |CL| installation type -***************************** - -Figure 7 shows the next step of the |CL| installer: -:guilabel:`Choose installation Type`. Chose whether to install |CL| -**automatically** or **manually**. To end the installer process and shut down -the system, select the :guilabel:`< Exit >` button. - -.. figure:: figures/bare-metal-install-7.png - :scale: 50 % - :alt: Choose installation type - - Figure 7: :guilabel:`Choose installation Type` - -If you select :guilabel:`< Automatic >` as the installation type, the |CL| -Installer will add the minimum amount of functionality required for a fully -functional |CL| system. You will not be able to modify the disk layout, add -a user or any other tasks that the manual installation process will allow. - -With the :guilabel:`< Manual(Advanced) >` option, you can do the following -additional tasks during |CL| Installer setup: - -* Modify the disk layout using the cgdisk utility. -* Add additional command-line parameters to the kernel. -* Create a hostname for your system. -* Create an administrative user. -* Add additional software bundles to enhance the functionality of your initial - |CL| installation. -* Optionally, set up a static IP address for your system. - -If you want to perform any of these additional tasks, select the -:guilabel:`< Manual(Advanced) >` menu item and follow the steps in our -:ref:`bare-metal-manual-install` to complete the |CL| manual installation -process. Otherwise, you can follow the |CL| automatic installation steps. - -|CL| automatic installation -*************************** - -#. To install the minimum components for your |CL| implementation, select the - :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. - -#. Move the cursor to the desired target and press the :kbd:`Enter` - key. - - .. figure:: figures/bare-metal-install-8.png - :scale: 50 % - :alt: Choose target device for installation - - Figure 8: :guilabel:`Choose target device for installation` - - In this example, we selected the single primary partition from our hard drive. - - With all the |CL| installer setup information gathered for the automatic - installation option, the |CL| Installer prompts you to begin the actual - installation as shown in figure 9. - - .. figure:: figures/bare-metal-install-9.png - :scale: 50 % - :alt: Begin installation - - Figure 9: :guilabel:`Begin installation` - -#. When you are satisfied with the information you have entered, select the - :guilabel:`< Yes >` button and press :kbd:`Enter` to begin installing |CL|. - - |CL| Installation begins and each step shows its status as it progresses - 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. - -#. Press the :kbd:`Enter` key to continue. - - .. figure:: figures/bare-metal-install-10.png - :scale: 50 % - :alt: Installation complete - - Figure 10: :guilabel:`Installation complete` - - Figure 11 shows the final installer screen, showing that the - installation completed successfully and the system will reboot. - -#. Press the :kbd:`Enter` key and remove the USB media while the system - restarts. - - .. figure:: figures/bare-metal-install-11.png - :scale: 50 % - :alt: Successful installation - - Figure 11: :guilabel:`Successful Installation` - -Set up your root account -======================== - -Once the |CL| installation is complete and the system boots, a full screen -console requests your login as shown in figure 12: - -.. figure:: figures/bare-metal-install-12.png - :scale: 50 % - :alt: Login screen - - Figure 12: :guilabel:`Login screen` - -#. At the initial login prompt, enter: ``root`` - -#. Once prompted, enter a new password. - -#. Re-enter the password to verify it. - -You have now set your root password and are logged in with root privileges. - -**Congratulations!** - -You have successfully installed |CL| on a bare metal system using the -automatic installation method and set the password for the ``root`` user. - -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. - -See the :ref:`enable-user-space` guide for additional information and -instructions. - - -.. _`information about stateless`: - https://clearlinux.org/features/stateless - -.. _`learn more about telemetry.`: - https://clearlinux.org/features/telemetry - -.. _`NUC6i5SYH product page`: - http://www.intel.com/content/www/us/en/nuc/nuc-kit-nuc6i5syh.html - -.. _image: https://download.clearlinux.org/image +.. _Autoproxy: https://clearlinux.org/features/autoproxy +.. _downloads page: https://clearlinux.org/downloads \ No newline at end of file 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..3b5f1d4e 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-10.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-10.png deleted file mode 100644 index b0cb9b0b..00000000 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-10.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-11.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-11.png deleted file mode 100644 index b0cc483f..00000000 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-11.png and /dev/null 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 deleted file mode 100644 index 76c5fe87..00000000 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-12.png and /dev/null 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..2e94163e 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-3.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-3.png deleted file mode 100644 index 4f6c3bb3..00000000 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-3.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-4.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-4.png deleted file mode 100644 index 1d4c4a50..00000000 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-4.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-5.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-5.png deleted file mode 100644 index 217690c2..00000000 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-5.png and /dev/null 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 deleted file mode 100644 index 9a7024c7..00000000 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-6.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-7.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-7.png deleted file mode 100644 index 9515eb20..00000000 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-7.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-8.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-8.png deleted file mode 100644 index 0a0b3e25..00000000 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-8.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-9.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-9.png deleted file mode 100644 index 35911d99..00000000 Binary files a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-9.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-1.png b/source/clear-linux/get-started/bare-metal-install/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/figures/bare-metal-install-beta-1.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-10.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-10.png new file mode 100644 index 00000000..888b9c2a Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-10.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-11.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-11.png new file mode 100644 index 00000000..9a6b61c7 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-11.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-12.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-12.png new file mode 100644 index 00000000..89ca1936 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-12.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-13.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-13.png new file mode 100644 index 00000000..6ac1f059 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-13.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-14.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-14.png new file mode 100644 index 00000000..3e7fbb8a Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-14.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-15.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-15.png new file mode 100644 index 00000000..1eaa499e Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-15.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-16.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-16.png new file mode 100644 index 00000000..d2c2a031 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-16.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-17.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-17.png new file mode 100644 index 00000000..7e1d6cc9 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-17.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-18.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-18.png new file mode 100644 index 00000000..4948cbe6 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-18.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-19.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-19.png new file mode 100644 index 00000000..720d06dd Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-19.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-2.png b/source/clear-linux/get-started/bare-metal-install/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/figures/bare-metal-install-beta-2.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-20.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-20.png new file mode 100644 index 00000000..39f9a644 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-20.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-21.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-21.png new file mode 100644 index 00000000..0ce16ab7 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-21.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-22.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-22.png new file mode 100644 index 00000000..3a028f4e Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-22.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-23.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-23.png new file mode 100644 index 00000000..f7fe354f Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-23.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-24.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-24.png new file mode 100644 index 00000000..02a5cc26 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-24.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-25.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-25.png new file mode 100644 index 00000000..e726b95e Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-25.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-26.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-26.png new file mode 100644 index 00000000..9e1b42d5 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-26.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-27.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-27.png new file mode 100644 index 00000000..14dec55a Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-27.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-28.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-28.png new file mode 100644 index 00000000..4e3acf29 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-28.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-3.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-3.png new file mode 100644 index 00000000..21121e06 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-3.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-4.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-4.png new file mode 100644 index 00000000..dcce7ec9 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-4.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-5.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-5.png new file mode 100644 index 00000000..dac8525d Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-5.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-6.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-6.png new file mode 100644 index 00000000..a9b249b6 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-6.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-7.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-7.png new file mode 100644 index 00000000..75d7898a Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-7.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-8.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-8.png new file mode 100644 index 00000000..267278b4 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-8.png differ diff --git a/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-9.png b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-9.png new file mode 100644 index 00000000..0dca46e6 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install/figures/bare-metal-install-beta-9.png differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/bare-metal-manual-install.rst b/source/clear-linux/get-started/bare-metal-manual-install/bare-metal-manual-install.rst deleted file mode 100644 index d5849e12..00000000 --- a/source/clear-linux/get-started/bare-metal-manual-install/bare-metal-manual-install.rst +++ /dev/null @@ -1,288 +0,0 @@ -.. _bare-metal-manual-install: - -Install |CL-ATTR| on bare metal (manual) -############################################# - -This section contains the steps for a |CL-ATTR| manual installation. It -picks up where the :ref:`bare-metal-install` left off. - -To perform additional tasks during the |CL| Installer setup, select the -:guilabel:`< Manual(Advanced) >` menu option (figure 1). - -* :ref:`Modify the disk layout using the cgdisk utility` -* Add additional command-line parameters to the kernel -* Create a hostname for your system -* Create an administrative user -* Add additional software bundles to enhance the functionality of your - initial |CL| installation -* Optionally set up a static IP address for your system - -Begin the manual installation process -************************************* - -#. Move the cursor to the :guilabel:`< Manual(Advanced) >` menu item - and press the :kbd:`Enter` key. - - .. figure:: figures/bare-metal-manual-install-1.png - :scale: 50 % - :alt: Choose installation Type - - Figure 1: :guilabel:`Choose installation Type` - -#. The screen :guilabel:`Choose partitioning method` will - appear (figure 2). - - .. figure:: figures/bare-metal-manual-install-2.png - :scale: 50 % - :alt: Choose partitioning method - - Figure 2: :guilabel:`Choose partitioning method` - - If your hard drive has already been partitioned for a Linux system, you - can select the :guilabel:`< Use default partition and mount scheme on - target device >` menu item and press :kbd:`Enter` to move to the next - step of the installer setup process. - - .. _cgdisk-manual-setup: - - Otherwise, to set up your hard drive partitions manually before moving to - the next step, select the :guilabel:`< Manually configure mounts and - partitions >` menu item and follow the instructions for :ref:`using CGDISK - to set up your Clear Linux hard drive`. - -.. _choose-target-device: - -Choose target device for installation -===================================== - -The :guilabel:`Choose target device for installation` menu, shown in figure -3, displays the current device and partition information. In -this example, ``/dev/sda`` is the only drive on the system with three -partitions defined and assigned. The menu cursor highlights the partition -to install |CL| onto. - -#. Select the :guilabel:`< Partition /dev/sda >` button and press the - :kbd:`Enter` key. - - .. note:: - - To return to the previous menu, press the :kbd:`Tab` key - to highlight the :guilabel:`< Previous >` button and press :kbd:`Enter` - to return to the previous menu. - - .. figure:: figures/bare-metal-manual-install-3.png - :scale: 50 % - :alt: Choose target device for installation - - Figure 3: :guilabel:`Choose target device for installation` - -#. Next, you will be presented with a warning screen (figure 4) with - :guilabel:`< No >` highlighted by default. If this is the device onto - which you wish to install |CL|, press :kbd:`Tab` to highlight - the :guilabel:`< Yes >` button. - -#. Press :kbd:`Enter` to proceed. - - .. figure:: figures/bare-metal-manual-install-4.png - :scale: 50 % - :alt: Device installation warning - - Figure 4: :guilabel:`Device installation warning` - -.. _incl-additional-manual-installer-settings: - -Additional manual installer settings -==================================== - -The next steps of the manual installer setup process allows you to: - -* Set up any additional command-line parameters to the kernel. -* Create a hostname for your system. -* Set up an administrative user. -* Install additional software bundles. -* Optionally create a static IP address for your system. - -#. The :guilabel:`Append to kernel cmdline` menu shown in figure 5 allows you - to add more options to the kernel command-line to further customize - your installation. Normally this is not required; however, if there are - specific options that need to be set in the Linux kernel, you can enter - them here. For a complete list of command-line parameters for the Linux - kernel you can visit the official documentation of the `latest kernel's - command-line parameters`_. - - Add any additional command-line parameters in the :guilabel:`Append to - cmdline:` field and then press the :kbd:`Tab` key to move to the - :guilabel:`< Next >` button and press :kbd:`Enter`. - - .. figure:: figures/bare-metal-manual-install-5.png - :scale: 50 % - :alt: Append to kernel cmdline - - Figure 5: :guilabel:`Append to kernel cmdline` - -#. The :guilabel:`Configuring Hostname` menu shown in figure 6 suggests - a hostname string prefaced with "clr". You can make your hostname anything - meaningful and unique. Once complete, press the :kbd:`Tab` key to move to - the :guilabel:`< Next >` button and press :kbd:`Enter`. - - .. figure:: figures/bare-metal-manual-install-6.png - :scale: 50 % - :alt: Configure Hostname - - Figure 6: :guilabel:`Configure Hostname` - - To learn more about hostname naming conventions and restrictions, you can - check this `wiki page about hostnames`_. - -#. The :guilabel:`User configuration` menu shown in figure 7 allows you to - create a userid with administrative privileges. If you do not want to - create a user at this time, select - :guilabel:`< No user creation (login as root) >` to skip this step and - proceed to the :guilabel:`Bundle selector` menu. - - .. figure:: figures/bare-metal-manual-install-7.png - :scale: 50 % - :alt: User configuration - - Figure 7: :guilabel:`User configuration` - - #. To create a userid, select the :guilabel:`< Create an administrative - user >` field and press :kbd:`Enter` to go to the the next screen. - #. You will be presented with the second :guilabel:`User configuration` - menu shown in figure 8. You are only required to fill in the - :guilabel:`Username`, :guilabel:`Password`, and :guilabel:`Confirm - password` fields. - #. To give a user administrative privileges, press :kbd:`Tab` until - cursor appears in the field :guilabel:`Add user to the sudoers?` and - select. This adds the user to the ``wheel`` group and allows entry of - the :command:`sudo` command. - - After entering all data, press :kbd:`Tab` until :guilabel:`< Next >` - is highlighted. Then press :kbd:`Enter`. - - .. figure:: figures/bare-metal-manual-install-8.png - :scale: 50 % - :alt: User configuration - create user - - Figure 8: :guilabel:`User configuration - create user` - -#. In the menu :guilabel:`Bundle selector` (figure 9), you can add - software bundles to your initial |CL| installation. Press the :kbd:`Tab` - key to highlight additional bundles, and then press :kbd:`Spacebar` or - :kbd:`Enter` to select each bundle. This menu will also list the - additional :guilabel:`--- required ---` software bundles that will be - installed during the |CL| installation. - - .. figure:: figures/bare-metal-manual-install-9.png - :scale: 50 % - :alt: Bundle selector - - Figure 9: :guilabel:`Bundle selector` - -For a complete description of the content of these additional bundles, go to -the :ref:`software bundle list ` and select the name for a -specific bundle to show the contents within the bundle. - -.. _incl-additional-manual-installer-settings-end: - -Target system network configuration -=================================== - -Before the actual |CL| installation begins, we must set up the -:guilabel:`Network configuration` shown in figure 10. Select -:guilabel:`< Use DHCP >` to have an IP address automatically assigned when -the system boots up. - -.. figure:: figures/bare-metal-manual-install-10.png - :scale: 50 % - :alt: Network configuration - - Figure 10: :guilabel:`Network configuration` - -You can optionally set up a static IP address for your system. Select the -:guilabel:`< Use static IP configuration >` menu item and fill in the -required fields. - -Begin installation -****************** - -The |CL| installer is now ready to use the information you provided on the -previous sections to begin the actual installation. Figure 11 shows the -installer's prompt to begin the installation. - -.. figure:: figures/bare-metal-manual-install-11.png - :scale: 50 % - :alt: Begin installation - - Figure 11: :guilabel:`Begin installation` - -When you are satisfied with the information entered, select the -:guilabel:`< Yes >` button and press :kbd:`Enter` to begin installing |CL|. - -The |CL| Installation begins and each step shows its status as it progresses -through the manual installation process as shown in figure 12. - -.. figure:: figures/bare-metal-manual-install-12.png - :scale: 50 % - :alt: Installation status - - Figure 12: :guilabel:`Installation status` - -Once all steps have completed, you will see the ``Successful installation`` -status message and the :guilabel:`< Ok >` button is highlighted as shown in -figure 13. Press the :kbd:`Enter` key to continue. - -.. figure:: figures/bare-metal-manual-install-13.png - :scale: 50 % - :alt: Installation complete - - Figure 13: :guilabel:`Installation complete` - -Congratulations! The installation completed successfully and the system will -reboot. Figure 14 shows the installer's final prompt. Press the :kbd:`Enter` -key and remove the USB media while the system restarts. - -.. figure:: figures/bare-metal-manual-install-14.png - :scale: 50 % - :alt: Successful Installation - - Figure 14: :guilabel:`Successful Installation` - -Once the system boots, the Gnome Desktop sign-in screen shown in figure 15 -appears: - -.. figure:: figures/bare-metal-manual-install-15.png - :scale: 50 % - :alt: Gnome sign-in screen - - Figure 15: :guilabel:`Gnome sign-in screen` - -Click on the :guilabel:`username` you created, enter the password, and you -will be logged into the system. The Gnome 3 desktop appears as shown in -figure 16: - -.. figure:: figures/bare-metal-manual-install-16.png - :scale: 50 % - :alt: Gnome Desktop Manager - - Figure 16: :guilabel:`Gnome Desktop Manager` - -**Congratulations!** - -You have successfully installed |CL| on a bare metal system using the -manual installation method. - -Visit our :ref:`tutorials ` section for examples on using your -|CL| system. - -.. _`information about stateless`: - https://clearLinux.org/features/stateless - -.. _`wiki page about Hostnames`: - https://en.wikipedia.org/wiki/Hostname - -.. _`learn more about telemetry.`: - https://clearLinux.org/features/telemetry - -.. _`latest kernel's command-line parameters`: - https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-1.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-1.png deleted file mode 100644 index cb023cf5..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-1.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-10.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-10.png deleted file mode 100644 index d8a3f5f3..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-10.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-11.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-11.png deleted file mode 100644 index 107febc4..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-11.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-12.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-12.png deleted file mode 100644 index 66751565..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-12.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-13.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-13.png deleted file mode 100644 index 9a14d9e1..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-13.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-14.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-14.png deleted file mode 100644 index 50fdc0ed..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-14.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-15.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-15.png deleted file mode 100644 index 7b538705..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-15.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-16.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-16.png deleted file mode 100644 index df61163b..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-16.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-2.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-2.png deleted file mode 100644 index b52d3f3b..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-2.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-3.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-3.png deleted file mode 100644 index 2c5ff918..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-3.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-4.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-4.png deleted file mode 100644 index a5897712..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-4.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-5.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-5.png deleted file mode 100644 index 54acbe3e..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-5.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-6.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-6.png deleted file mode 100644 index 0d2fe7f2..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-6.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-7.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-7.png deleted file mode 100644 index a98d99b8..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-7.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-8.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-8.png deleted file mode 100644 index 8401cf67..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-8.png and /dev/null differ diff --git a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-9.png b/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-9.png deleted file mode 100644 index 4b7fa392..00000000 Binary files a/source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-9.png and /dev/null 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..5c5d3014 --- /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:`get-started` + +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:`get-started` + +.. _Rufus: https://rufus.ie/ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/cgdisk-manual-install.rst b/source/clear-linux/get-started/cgdisk-manual-install/cgdisk-manual-install.rst deleted file mode 100644 index 5f00c804..00000000 --- a/source/clear-linux/get-started/cgdisk-manual-install/cgdisk-manual-install.rst +++ /dev/null @@ -1,313 +0,0 @@ -.. _cgdisk-manual-install: - -Create partitions for |CL-ATTR| using CGDISK -############################################ - -These instructions guide you through the initial setup of your hard drive -partitions using the :command:`cgdisk` utility . If you do not wish to continue -creating your own partitions, :ref:`return to the bare metal manual installation -`. - -Prerequisites -************* - -This guide assumes that you have followed the :ref:`bare-metal-install` -guide and intend to :ref:`install Clear Linux manually -` by choosing the :guilabel:`< Manual(Advanced) >` -menu item on the :guilabel:`Choose Installation Type` |CL| Installer setup -menu as shown in figure 1: - -.. figure:: figures/cgdisk-manual-install-1.png - :scale: 50 % - :alt: Choose installation Type - - Figure 1: :guilabel:`Choose installation Type` - -Partition using CGDISK -********************** - -We use the :command:`cgdisk` application to create a -:abbr:`GPT (GUID Partition Table)` since |CL| only supports the -:abbr:`UEFI (Unified Extensible Firmware Interface)` specification. For a -complete description of the :command:`cgdisk` utility and how to use it, -visit Rod Smith's website for a `GPT fdisk tutorial`_. - -In this guide, we intend to use an unpartitioned hard drive for the |CL| -installation. - -#. To manually partition your hard drive, select - :guilabel:`< Manually configure mounts and partitions >` in the menu - :guilabel:`Choose partitioning method`, shown in figure 2. - - .. figure:: figures/cgdisk-manual-install-2.png - :scale: 50 % - :alt: Choose partitioning method - - Figure 2: :guilabel:`Choose partitioning method` - - Next, the current device available to partition is shown. In this - example, shown in figure 3, :file:`/dev/sda` is available but - does not have any partitions defined. - -#. Select the :guilabel:`< Partition /dev/sda >` menu item and press - :kbd:`Enter` to begin the process of modifying this disk. - - .. figure:: figures/cgdisk-manual-install-3.png - :scale: 50 % - :alt: Choose a drive to partition using cgdisk tool - - Figure 3: :guilabel:`Choose a drive to partition using cgdisk tool` - - The :command:`cgdisk` application starts and displays the settings for - :file:`/dev/sda` as shown in figure 4. - - .. figure:: figures/cgdisk-manual-install-4.png - :scale: 50 % - :alt: cgdisk - - Figure 4: :guilabel:`cgdisk` - -Linux partition setup -********************* - -In order to properly set up the |CL| partitioning scheme, we create three -partitions using the :command:`cgdisk` utility in the following order: - -#. EFI boot partition -#. Linux swap partition -#. Linux root partition - -For a complete understanding of these partitions, you can review the -`Linux partitioning scheme`_ information. - -Create the EFI boot partition -============================= - -#. With the free space highlighted in the :command:`cgdisk` utility, - you can either select the :guilabel:`[ New ]` button and press :kbd:`Enter` - or press the :kbd:`N` key to define a new partition. - - The utility prompts you to enter the first sector. Press the :kbd:`Enter` - key to accept the default value shown. - - .. note:: - In this example, the first sector starts at 2048. For more information - about alignment using the cgdisk tool, see - `Rod Smith's Partitioning Advice about alignment`_. - -#. The program then prompts you for the size of the partition. To create a - 512MB partition, enter 512M and press :kbd:`Enter` as shown in figure 5: - - .. figure:: figures/cgdisk-manual-install-5.png - :scale: 50 % - :alt: cgdisk - New - - Figure 5: :guilabel:`cgdisk - New partition` - -#. To define the type of partition, the :command:`cgdisk` utility has - pre-defined partition types. Press the :kbd:`L` key to show the hex codes - you can use. Use these codes to set the correct - :abbr:`GUID (Globally unique identifier)` for *GPT partition types* as - shown in figure 6: - - .. figure:: figures/cgdisk-manual-install-6.png - :scale: 50 % - :alt: cgdisk - hex codes for partition types - - Figure 6: :guilabel:`cgdisk - hex codes for partition types` - - We need to use the following three codes for our partitions: - - * ef00 - EFI System - * 8200 - Linux swap - * 8300 - Linux filesystem - -#. To create the EFI boot partition, enter ``ef00`` as the hexcode for this - partition and press :kbd:`Enter`. - -#. To name the partition, enter ``boot`` and press :kbd:`Enter` to finish - setting up the EFI boot partition. The utility shows the first partition as - an ``EFI System`` 512MiB partition named ``boot`` as shown in figure 7: - - .. figure:: figures/cgdisk-manual-install-7.png - :scale: 50 % - :alt: cgdisk - boot partition defined - - Figure 7: :guilabel:`cgdisk - boot partition defined` - -Create the Linux swap partition -=============================== - -Next, we must create the Linux swap partition. In figure 7, notice the two -areas defined as free space. We created the first 1007.0 KiB free space area -when we started the EFI boot partition at sector 2048. For more information -about it, review `Rod Smith's Partitioning advice about alignment`_. - -#. Move your cursor to highlight the larger free space of 334.8 GiB at the - bottom of the partition list before you begin to create the Linux swap - partition as shown in figure 8: - - .. figure:: figures/cgdisk-manual-install-8.png - :scale: 50 % - :alt: cgdisk - free space selection - - Figure 8: :guilabel:`cgdisk - free space selection` - -#. To create the Linux swap partition, with the largest free space - highlighted, select the :guilabel:`[ New ]` button or press the :kbd:`N` - key and enter the following values for the Linux swap partition: - - .. code-block:: console - - First sector: press :kbd:`Enter` to select the default value - Size in sectors: 4G - Hex code or GUID: 8200 - Enter new partition name: swap - - Your :command:`cgdisk` partition list should now look like figure 9. - - .. figure:: figures/cgdisk-manual-install-9.png - :scale: 50 % - :alt: cgdisk - swap partition defined - - Figure 9: :guilabel:`cgdisk - swap partition defined` - -Create the Linux filesystem partition -===================================== - -Lastly, we must create the the Linux filesystem partition to use it as the -root mount point for you |CL| installation. - -#. Highlight the largest free space entry at the bottom of the list and select - the :guilabel:`[ New ]` button or press the :kbd:`N` key and enter the - following values to create the Linux filesystem partition: - - .. code-block:: console - - First sector: press :kbd:`Enter` to select the default value - Size in sectors: press :kbd:`Enter` to select the default value, which - is the remainder of available space on the disk - Hex code or GUID: 8300 - Enter new partition name: root - - With all the partitions now defined, you should see a list similar to what - is shown in figure 10: - - .. figure:: figures/cgdisk-manual-install-10.png - :scale: 50 % - :alt: cgdisk - defined partitions - - Figure 10: :guilabel:`cgdisk - defined partitions` - -#. If you are satisfied that the partition scheme is correct, you need to - write this GPT to the hard drive. Select the :guilabel:`[ Write ]` button - or press the :kbd:`W` key and the :command:`cgdisk` program prompts with: - - .. code-block:: console - - Are you sure you want to write the partition table to disk? (yes or no) - -#. Enter ``yes`` and press :kbd:`Enter` to write this data to the hard drive - and then select the :guilabel:`[ Quit ]` button or press :kbd:`Q` to exit - the :command:`cgdisk` utility. - -#. You see the partitions that were created as shown in figure 11. Move your - cursor to the :guilabel:`< Next >` button and press :kbd:`Enter`. - - .. figure:: figures/cgdisk-manual-install-11.png - :scale: 50 % - :alt: defined partitions - - Figure 11: :guilabel:`defined partitions` - -Set the mount points -******************** - -The :guilabel:`Set mount points` menu sets the mount points that the |CL| -installer uses for your |CL| installation, shown in figure 12. - -.. figure:: figures/cgdisk-manual-install-12.png - :scale: 50 % - :alt: Set mount points - - Figure 12: :guilabel:`Set mount points` - -In this menu you need to set the mount points for the boot and root -partitions and select to format them. - -#. Highlight the EFI System partition type menu entry and press the - :kbd:`Enter` key to edit this item. The :guilabel:`Set mount point of - sda1` menu is shown. - - #. For :guilabel:`Enter mount point:` type `/boot` and press - :kbd:`Enter`. - #. Press Tab to enter the :guilabel:`[ ] Format` field. - #. Press Enter/Spacebar to select :guilabel:`[ ] Format`, which allows - formatting of the partition. - - Figure 13 shows the information entered. Select :guilabel:`< Next >` - and press :kbd:`Enter`. - - .. figure:: figures/cgdisk-manual-install-13.png - :scale: 50 % - :alt: Set mount point of sda1 - - Figure 13: :guilabel:`Set mount point of sda1` - -#. Do the same for the Linux filesystem partition by highlighting the - :guilabel:`Linux filesystem` menu entry and entering the information shown - in figure 14 to set the :guilabel:`Enter mount point:` to :file:`/` and - enable formatting: - - .. figure:: figures/cgdisk-manual-install-14.png - :scale: 50 % - :alt: Set mount point of sda3 - - Figure 14: :guilabel:`Set mount point of sda3` - -#. Optional: Select :guilabel:`Encrypt Root Partition`, if - desired, as shown in figure 15. - - .. note:: - `Set mount points` now show as completed. - - .. figure:: figures/cgdisk-manual-install-15.png - :scale: 50 % - :alt: Encrypt root partition - - Figure 15: :guilabel:`Encrypt root partition` - -#. Type a confirmation passphrase as directed. - - .. note: - - It is recommended to record the passphrase for safekeeping. - - .. figure:: figures/cgdisk-manual-install-16.png - :scale: 50 % - :alt: Type confirmation passphrase - - Figure 16: :guilabel: `Type confirmation passphrase` - -#. Select the :guilabel:`< Next >` button and press :kbd:`Enter`. - - You have completed the process of manually partitioning your target - system. - -#. Now, :ref:`return to the bare metal manual installation - ` to complete installation of |CL|. - - Continue at the section :ref:`Additional manual installer settings - `. - -.. _`GPT fdisk tutorial`: - http://www.rodsbooks.com/gdisk/ - -.. _`Rod Smith's Partitioning Advice about alignment`: - http://www.rodsbooks.com/gdisk/advice.html#alignment - -.. _`information about swupd`: - https://clearlinux.org/features/software-update - -.. _`Linux partitioning scheme`: - https://wiki.archlinux.org/index.php/partitioning#Partition_scheme diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-1.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-1.png deleted file mode 100644 index cb023cf5..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-1.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-10.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-10.png deleted file mode 100644 index 8d977f83..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-10.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-11.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-11.png deleted file mode 100644 index 3e73dc50..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-11.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-12.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-12.png deleted file mode 100644 index 542c3101..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-12.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-13.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-13.png deleted file mode 100644 index 7393ad38..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-13.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-14.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-14.png deleted file mode 100644 index a558b8ec..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-14.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-15.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-15.png deleted file mode 100644 index 6b824a1f..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-15.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-16.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-16.png deleted file mode 100644 index 77ff7d05..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-16.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-2.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-2.png deleted file mode 100644 index 4120d770..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-2.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-3.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-3.png deleted file mode 100644 index 97303025..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-3.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-4.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-4.png deleted file mode 100644 index d81b6d95..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-4.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-5.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-5.png deleted file mode 100644 index 75163ffa..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-5.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-6.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-6.png deleted file mode 100644 index 1528b667..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-6.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-7.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-7.png deleted file mode 100644 index f9b007fc..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-7.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-8.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-8.png deleted file mode 100644 index 7c41a266..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-8.png and /dev/null differ diff --git a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-9.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-9.png deleted file mode 100644 index b5b351c3..00000000 Binary files a/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-9.png and /dev/null differ diff --git a/source/clear-linux/get-started/get-started.rst b/source/clear-linux/get-started/get-started.rst index 1bbe2c15..15ebfb9b 100644 --- a/source/clear-linux/get-started/get-started.rst +++ b/source/clear-linux/get-started/get-started.rst @@ -3,34 +3,29 @@ Get started ########### -The Get Started section will get you up and running fast with |CL-ATTR|. Use -these step-by-step instructions to guide you through the installation of |CL| +The Get Started section will get you up and running fast with |CL-ATTR|. Use +these step-by-step instructions to guide you through the installation of |CL| from bare metal to a live image. - + Pre-install *********** -* :ref:`system-requirements` -* :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:`system-requirements` .. toctree:: - :maxdepth: 2 - :hidden: + :maxdepth: 1 + + compatibility-check + bootable-usb/bootable-usb + bootable-usb/bootable-usb-beta-all + +Install |CL| +************ + +.. toctree:: + :maxdepth: 1 bare-metal-install/bare-metal-install - bare-metal-manual-install/bare-metal-manual-install - cgdisk-manual-install/cgdisk-manual-install virtual-machine-install/virtual-machine-install live-image - compatibility-check - bootable-usb/bootable-usb \ No newline at end of file + bare-metal-install-beta/bare-metal-install-beta \ No newline at end of file diff --git a/source/clear-linux/get-started/virtual-machine-install/virtual-machine-install.rst b/source/clear-linux/get-started/virtual-machine-install/virtual-machine-install.rst index 7e9ae469..34f93ac9 100644 --- a/source/clear-linux/get-started/virtual-machine-install/virtual-machine-install.rst +++ b/source/clear-linux/get-started/virtual-machine-install/virtual-machine-install.rst @@ -35,4 +35,5 @@ appropriate set of step-by-step instructions to proceed. vmw-player vmw-player-preconf hyper-v + ../../guides/maintenance/increase-virtual-disk-size.rst 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 c5470f0b..09662ae0 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-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 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..f5f76a9b --- /dev/null +++ b/source/clear-linux/guides/maintenance/kernel-modules.rst @@ -0,0 +1,177 @@ +.. _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 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..0200ba2a 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,13 +18,14 @@ This guide assumes: * The device is able to connect to the release infrastructure http://update.clearlinux.org -.. contents:: +.. contents:: :local: :depth: 2 .. _man_swupd: -For a full listing of commands and options please see the man page in |CL| +For a full listing of commands and options please see the man page found in +the `swupd` `source code`_ or on |CL| itself. .. code-block:: bash @@ -54,7 +55,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 +106,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 +114,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 +125,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 +139,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 +151,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 +161,7 @@ binary. Note that it may be present in multiple bundles: .. code-block:: bash - swupd search -b + swupd search -b Adding a bundle =============== @@ -181,3 +182,4 @@ Dependencies common to other bundles will not be removed sudo swupd bundle-remove dev-utils-dev +.. _source code: https://github.com/clearlinux/swupd-client/blob/master/docs/swupd.1.rst \ No newline at end of file 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..f16ca06b 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 @@ -122,7 +122,7 @@ To set up |CL| manually, perform the steps below. .. code-block:: console sudo cat > $ipxe_root/ipxe_boot_script.ipxe << EOF - sudo!ipxe + #!ipxe kernel linux quiet init=/usr/lib/systemd/systemd-bootchart \ initcall_debug tsc=reliable no_timer_check noreplace-smp rw \ initrd=initrd 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/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/telemetrics.rst b/source/clear-linux/guides/telemetrics/telemetrics.rst index 9731471f..0a4d1cea 100644 --- a/source/clear-linux/guides/telemetrics/telemetrics.rst +++ b/source/clear-linux/guides/telemetrics/telemetrics.rst @@ -16,4 +16,4 @@ telemetry backend solution. For more details, learn how to telemetry-config telemctl telemetry-journal - telemetry-z-api + telemetry-api diff --git a/source/clear-linux/guides/telemetrics/telemetry-z-api.rst b/source/clear-linux/guides/telemetrics/telemetry-api.rst similarity index 100% rename from source/clear-linux/guides/telemetrics/telemetry-z-api.rst rename to source/clear-linux/guides/telemetrics/telemetry-api.rst 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..9f44f5bd --- /dev/null +++ b/source/clear-linux/reference/bundles/bundles.html.txt @@ -0,0 +1,9086 @@ + + + + + + + Bundles in Clear Linux* OS + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Updated: 01/28/19 19:15 UTC +
Name Description
acl Tools to manipulate filesystem acls
acpica-unix2 Intel ACPI utilities
alsa-utils alsa management tools
amateur-radioApplications to support amateur radio operations
+ +

Includes bundle(s): +

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

+ +
ansibleThe ansible tool for host management
+ +

Includes bundle(s): +

    + +
  • ipmitool
    • + +
  • python3-basic
    • + +
+

+ +
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
aws-greengrass-iotLibraries to support building IoT applications on AWS Greengrass
+ +

Includes bundle(s): +

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

+ +
axel Download accelerator
azure-iot-sdkLibraries to support building IoT applications on Azure
+ +

Includes bundle(s): +

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

+ +
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
    • + +
+

+ +
blenderA 3D Modelling And Rendering Package
+ +

Includes bundle(s): +

    + +
  • python3-basic
    • + +
+

+ +
bmap-tools Tools for creating the block map (bmap) for a file and copying files. Alternative to "dd" or "cp"
boot-encryptedEnable booting encrypted root partition, swap, or other partitions
+ +

Includes bundle(s): +

    + +
  • bootloader-extras
    • + +
+

+ +
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
    • + +
  • nasm
    • + +
  • llvm
    • + +
  • make
    • + +
  • nasm
    • + +
+

+ +
c-basic-legacyBuild and run 32bit C/C++ language programs
+ +

Includes bundle(s): +

    + +
  • make
    • + +
  • devpkg-zlib
    • + +
+

+ +
cabextract Manipulate CAB archives
casync Content Addressable Data Synchronizer, to distribute frequently-updated file system images over the Internet
ccache cache compilations to avoid redoing the same computation and speed project build times
clamav Clam AntiVirus is an anti-virus toolkit for Unix
cloc Count lines of code for many programming languages
cloud-apiAPI helpers for cloud access
+ +

Includes bundle(s): +

    + +
  • python3-basic
    • + +
+

+ +
cloud-controlRun a cloud orchestration server
+ +

Includes bundle(s): +

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

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

Includes bundle(s): +

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

+ +
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
    • + +
  • less
    • + +
+

+ +
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
+ +

Includes bundle(s): +

    + +
  • machine-learning-tensorflow
    • + +
+

+ +
containers-basicRun container applications from Dockerhub
+ +

Includes bundle(s): +

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

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

Includes bundle(s): +

    + +
  • containers-basic
    • + +
  • dev-utils
    • + +
  • os-core-dev
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-glib
    • + +
  • devpkg-gtk3
    • + +
  • gzip
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • less
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libsecret
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-qtbase
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

+ +
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
    • + +
  • bc
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-glib
    • + +
  • devpkg-gtk3
    • + +
  • gzip
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • less
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libsecret
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • musl
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-pixman
    • + +
  • devpkg-qtbase
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

+ +
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
    • + +
+

+ +
cryptoprocessor-management-devAll packages required to build the cryptoprocessor-management bundle.
+ +

Includes bundle(s): +

    + +
  • cryptoprocessor-management
    • + +
  • dev-utils
    • + +
  • os-core-dev
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-glib
    • + +
  • gzip
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

+ +
curl Transfer data to/from a URL
cve-bin CVE scanning tool
darktable Photography workflow application
database-basicRun a SQL database
+ +

Includes bundle(s): +

    + +
  • python3-basic
    • + +
  • postgresql
    • + +
+

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

Includes bundle(s): +

    + +
  • database-basic
    • + +
  • dev-utils
    • + +
  • os-core-dev
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-glib
    • + +
  • gzip
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • nasm
    • + +
  • devpkg-openmpi
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

+ +
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
    • + +
  • fuse
    • + +
  • tzdata
    • + +
  • alsa-utils
    • + +
  • fwupdate
    • + +
+

+ +
desktop-appsApplications for the desktop
+ +

Includes bundle(s): +

    + +
  • libX11client
    • + +
  • desktop-gnomelibs
    • + +
  • python3-basic
    • + +
  • xemacs
    • + +
  • firefox
    • + +
  • libva-utils
    • + +
  • xemacs
    • + +
+

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

Includes bundle(s): +

    + +
  • desktop-gnomelibs
    • + +
  • pidgin
    • + +
  • python3-basic
    • + +
  • virt-manager
    • + +
  • atom
    • + +
  • darktable
    • + +
  • thunderbird
    • + +
  • vlc
    • + +
  • gimp
    • + +
+

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

Includes bundle(s): +

    + +
  • desktop-gnomelibs
    • + +
  • intended for all supported styles
    • + +
  • current default
    • + +
  • common
    • + +
+

+ +
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
    • + +
  • devpkg-at-spi2-atk
    • + +
  • devpkg-at-spi2-core
    • + +
  • devpkg-atk
    • + +
  • devpkg-cairo
    • + +
  • devpkg-cheese
    • + +
  • devpkg-clutter
    • + +
  • devpkg-clutter-gst
    • + +
  • devpkg-cogl
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • docutils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-evolution-data-server
    • + +
  • devpkg-evolution
    • + +
  • devpkg-expat
    • + +
  • devpkg-fontconfig
    • + +
  • fonttools
    • + +
  • devpkg-freetype
    • + +
  • devpkg-fribidi
    • + +
  • gdb
    • + +
  • devpkg-gdk-pixbuf
    • + +
  • devpkg-glib
    • + +
  • devpkg-gnome-desktop
    • + +
  • gpgme
    • + +
  • devpkg-graphite
    • + +
  • devpkg-gsettings-desktop-schemas
    • + +
  • devpkg-gst-plugins-base
    • + +
  • devpkg-gstreamer
    • + +
  • devpkg-gtk3
    • + +
  • gzip
    • + +
  • devpkg-harfbuzz
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • iproute2
    • + +
  • jq
    • + +
  • kbd
    • + +
  • less
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libdrm
    • + +
  • devpkg-libepoxy
    • + +
  • devpkg-libical
    • + +
  • devpkg-libpciaccess
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libpthread-stubs
    • + +
  • devpkg-libsecret
    • + +
  • devpkg-libsoup
    • + +
  • devpkg-libxkbcommon
    • + +
  • libxml2
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • llvm
    • + +
  • make
    • + +
  • devpkg-mesa
    • + +
  • nasm
    • + +
  • devpkg-nspr
    • + +
  • devpkg-nss
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • devpkg-orc
    • + +
  • p11-kit
    • + +
  • devpkg-pango
    • + +
  • parallel
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-pixman
    • + +
  • devpkg-qtbase
    • + +
  • devpkg-qtdeclarative
    • + +
  • scons
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • subversion
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • devpkg-wayland
    • + +
  • devpkg-wayland-protocols
    • + +
  • devpkg-webkitgtk
    • + +
  • which
    • + +
  • devpkg-xorg-server
    • + +
  • devpkg-xorgproto
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

+ +
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
    • + +
  • fuse
    • + +
  • gpgme
    • + +
  • kdiff3
    • + +
  • libxslt
    • + +
+

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

Includes bundle(s): +

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

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

Includes bundle(s): +

    + +
  • qt-basic
    • + +
+

+ +
desktop-localestranslations and documentation for desktop components
+ +

Includes bundle(s): +

    + +
  • perl-basic
    • + +
+

+ +
dev-utilsAssist application development
+ +

Includes bundle(s): +

    + +
  • git
    • + +
  • openssl
    • + +
  • perl-basic
    • + +
  • python3-basic
    • + +
  • bc
    • + +
  • cloc
    • + +
  • cpio
    • + +
  • diffutils
    • + +
  • docutils
    • + +
  • gdb
    • + +
  • icdiff
    • + +
  • inotify-tools
    • + +
  • linux-tools
    • + +
  • llvm
    • + +
  • patch
    • + +
  • strace
    • + +
  • valgrind
    • + +
+

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

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • os-core-dev
    • + +
  • perl-basic-dev
    • + +
  • bc
    • + +
  • devpkg-cairo
    • + +
  • cpio
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-glib
    • + +
  • gzip
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • less
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libpciaccess
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libpthread-stubs
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • llvm
    • + +
  • make
    • + +
  • devpkg-mesa
    • + +
  • devpkg-openmpi
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-qtbase
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • subversion
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

+ +
dev-utils-guiAssist application development (gui components)
+ +

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • libX11client
    • + +
  • tcl-basic
    • + +
  • qt-basic
    • + +
+

+ +
devpkg-at-spi2-atkAll content for pkgconfig file at-spi2-atk.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-at-spi2-core
    • + +
  • devpkg-glib
    • + +
+

+ +
devpkg-at-spi2-coreAll content for pkgconfig file at-spi2-core.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-dbus
    • + +
  • devpkg-glib
    • + +
+

+ +
devpkg-atkAll content for pkgconfig file atk.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-glib
    • + +
+

+ +
devpkg-basebasic pkgconfig infra
+ +

Includes bundle(s): +

    + +
  • c-basic
    • + +
+

+ +
devpkg-cairoAll content for pkgconfig file cairo.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-fontconfig
    • + +
  • devpkg-freetype
    • + +
  • devpkg-glib
    • + +
  • devpkg-libX11
    • + +
  • devpkg-mesa
    • + +
  • devpkg-pixman
    • + +
+

+ +
devpkg-cheeseAll content for pkgconfig file cheese.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-clutter
    • + +
  • devpkg-clutter-gst
    • + +
  • devpkg-gdk-pixbuf
    • + +
  • devpkg-glib
    • + +
  • devpkg-gstreamer
    • + +
+

+ +
devpkg-clutterAll content for pkgconfig file clutter.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-clutter-gstAll content for pkgconfig file clutter-gst.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-clutter
    • + +
  • devpkg-cogl
    • + +
  • devpkg-glib
    • + +
  • devpkg-gst-plugins-base
    • + +
  • devpkg-gstreamer
    • + +
+

+ +
devpkg-coglAll content for pkgconfig file cogl.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-dbusAll content for pkgconfig file dbus.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-elfutilsAll content for pkgconfig file elfutils.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

+ +
devpkg-evolutionAll content for pkgconfig file evolution.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-evolution-data-server
    • + +
  • devpkg-glib
    • + +
  • devpkg-gnome-desktop
    • + +
  • devpkg-gtk3
    • + +
  • devpkg-webkitgtk
    • + +
+

+ +
devpkg-evolution-data-serverAll content for pkgconfig file evolution-data-server.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-glib
    • + +
  • devpkg-gtk3
    • + +
  • devpkg-libical
    • + +
  • devpkg-libsecret
    • + +
  • devpkg-libsoup
    • + +
  • devpkg-libxml2
    • + +
  • devpkg-nspr
    • + +
  • devpkg-nss
    • + +
  • devpkg-sqlite-autoconf
    • + +
+

+ +
devpkg-expatAll content for pkgconfig file expat.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-fontconfigAll content for pkgconfig file fontconfig.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-expat
    • + +
  • devpkg-freetype
    • + +
  • devpkg-util-linux
    • + +
+

+ +
devpkg-freetypeAll content for pkgconfig file freetype.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-harfbuzz
    • + +
  • devpkg-zlib
    • + +
+

+ +
devpkg-fribidiAll content for pkgconfig file fribidi.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-fuseAll content for pkgconfig file fuse.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-gdk-pixbufAll content for pkgconfig file gdk-pixbuf.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-glib
    • + +
  • devpkg-libpng
    • + +
+

+ +
devpkg-glibAll content for pkgconfig file glib.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-pcre
    • + +
  • devpkg-util-linux
    • + +
+

+ +
devpkg-gnome-desktopAll content for pkgconfig file gnome-desktop.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-gsettings-desktop-schemas
    • + +
  • devpkg-gtk3
    • + +
+

+ +
devpkg-graphiteAll content for pkgconfig file graphite.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-gsettings-desktop-schemasAll content for pkgconfig file gsettings-desktop-schemas.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-gst-plugins-baseAll content for pkgconfig file gst-plugins-base.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-gstreamer
    • + +
  • devpkg-orc
    • + +
+

+ +
devpkg-gstreamerAll content for pkgconfig file gstreamer.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-glib
    • + +
+

+ +
devpkg-gtk3All content for pkgconfig file gtk3.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-at-spi2-atk
    • + +
  • devpkg-atk
    • + +
  • devpkg-cairo
    • + +
  • devpkg-fontconfig
    • + +
  • devpkg-gdk-pixbuf
    • + +
  • devpkg-glib
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libepoxy
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-pango
    • + +
  • devpkg-wayland
    • + +
  • devpkg-wayland-protocols
    • + +
+

+ +
devpkg-harfbuzzAll content for pkgconfig file harfbuzz.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-glib
    • + +
  • devpkg-graphite
    • + +
+

+ +
devpkg-icu4cAll content for pkgconfig file icu4c.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-libdrmAll content for pkgconfig file libdrm.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-libepoxyAll content for pkgconfig file libepoxy.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-mesa
    • + +
+

+ +
devpkg-libicalAll content for pkgconfig file libical.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-icu4c
    • + +
+

+ +
devpkg-libpciaccessAll content for pkgconfig file libpciaccess.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-libpngAll content for pkgconfig file libpng.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-zlib
    • + +
+

+ +
devpkg-libpthread-stubsAll content for pkgconfig file libpthread-stubs.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-libsecretAll content for pkgconfig file libsecret.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-glib
    • + +
+

+ +
devpkg-libsoupAll content for pkgconfig file libsoup.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-glib
    • + +
  • devpkg-libxml2
    • + +
+

+ +
devpkg-libX11All content for pkgconfig file libX11.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libpthread-stubs
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-libXauAll content for pkgconfig file libXau.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-libxcbAll content for pkgconfig file libxcb.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libXau
    • + +
  • devpkg-libXdmcp
    • + +
  • devpkg-libpthread-stubs
    • + +
+

+ +
devpkg-libXcompositeAll content for pkgconfig file libXcomposite.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libXfixes
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-libXdamageAll content for pkgconfig file libXdamage.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libXfixes
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-libXdmcpAll content for pkgconfig file libXdmcp.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-libXextAll content for pkgconfig file libXext.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libX11
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-libXfixesAll content for pkgconfig file libXfixes.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libX11
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-libXiAll content for pkgconfig file libXi.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libXext
    • + +
  • devpkg-libXfixes
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-libXineramaAll content for pkgconfig file libXinerama.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libXext
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-libxkbcommonAll content for pkgconfig file libxkbcommon.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-libxml2All content for pkgconfig file libxml2.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-libXrandrAll content for pkgconfig file libXrandr.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libXext
    • + +
  • devpkg-libXrender
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-libXrenderAll content for pkgconfig file libXrender.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libX11
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-libXxf86vmAll content for pkgconfig file libXxf86vm.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libXext
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-mesaAll content for pkgconfig file mesa.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libdrm
    • + +
+

+ +
devpkg-nsprAll content for pkgconfig file nspr.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-nssAll content for pkgconfig file nss.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-nspr
    • + +
+

+ +
devpkg-openblasAll content for pkgconfig file openblas.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-opencvAll content for pkgconfig file opencv.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-openmpiAll content for pkgconfig file openmpi.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-opensslAll content for pkgconfig file openssl.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-orcAll content for pkgconfig file orc.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-pangoAll content for pkgconfig file pango.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-cairo
    • + +
  • devpkg-fontconfig
    • + +
  • devpkg-freetype
    • + +
  • devpkg-fribidi
    • + +
  • devpkg-glib
    • + +
  • devpkg-harfbuzz
    • + +
+

+ +
devpkg-pcreAll content for pkgconfig file pcre.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-pixmanAll content for pkgconfig file pixman.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-qt3dAll content for pkgconfig file qt3d.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-qtbase
    • + +
  • devpkg-qtdeclarative
    • + +
+

+ +
devpkg-qtbaseAll content for pkgconfig file qtbase.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-qtdeclarativeAll content for pkgconfig file qtdeclarative.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-qtbase
    • + +
+

+ +
devpkg-sqlite-autoconfAll content for pkgconfig file sqlite-autoconf.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-util-linuxAll content for pkgconfig file util-linux.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-waylandAll content for pkgconfig file wayland.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-wayland-protocolsAll content for pkgconfig file wayland-protocols.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-webkitgtkAll content for pkgconfig file webkitgtk.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-glib
    • + +
  • devpkg-gtk3
    • + +
  • devpkg-libsoup
    • + +
+

+ +
devpkg-xorg-serverAll content for pkgconfig file xorg-server.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
  • devpkg-libpciaccess
    • + +
  • devpkg-mesa
    • + +
  • devpkg-pixman
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
devpkg-xorgprotoAll content for pkgconfig file xorgproto.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-xzAll content for pkgconfig file xz.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
devpkg-zlibAll content for pkgconfig file zlib.pc
+ +

Includes bundle(s): +

    + +
  • devpkg-base
    • + +
+

+ +
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
djangoDjango web framwork
+ +

Includes bundle(s): +

    + +
  • python-basic
    • + +
+

+ +
docbook-utils docbook tools
docutils Tools for converting text to other formats (e.g. HTML, XML, LaTeX)
domoticaHome Automation software collection
+ +

Includes bundle(s): +

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

+ +
dosfstools
dovecot Security focused IMAP and POP3 email server
doxygen documentation tooling
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
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-glib
    • + +
  • gzip
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

+ +
educationEducational applications
+ +

Includes bundle(s): +

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

+ +
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
    • + +
  • fwupdate
    • + +
+

+ +
flac FLAC audio format tools
flatpakUse flatpak packages, or build them
+ +

Includes bundle(s): +

    + +
  • git
    • + +
+

+ +
fonttools tools to manipulate system and user fonts
fossil Fossil is a simple, high-reliability, distributed software configuration management system
fuse fuse filesystem support
fwupdate Firmware update tool
gamesPlay games in Clear Linux
+ +

Includes bundle(s): +

    + +
  • libX11client
    • + +
  • p11-kit
    • + +
  • perl-basic
    • + +
  • diffutils
    • + +
  • theme, data, etc
    • + +
  • 32-bit
    • + +
  • native
    • + +
  • 32-bit
    • + +
  • native
    • + +
+

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

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • games
    • + +
  • os-core-dev
    • + +
  • perl-basic-dev
    • + +
  • devpkg-at-spi2-atk
    • + +
  • devpkg-at-spi2-core
    • + +
  • devpkg-atk
    • + +
  • devpkg-cairo
    • + +
  • devpkg-clutter
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-fontconfig
    • + +
  • devpkg-freetype
    • + +
  • devpkg-fribidi
    • + +
  • gdb
    • + +
  • devpkg-gdk-pixbuf
    • + +
  • devpkg-glib
    • + +
  • devpkg-graphite
    • + +
  • devpkg-gst-plugins-base
    • + +
  • devpkg-gstreamer
    • + +
  • devpkg-gtk3
    • + +
  • gzip
    • + +
  • devpkg-harfbuzz
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libdrm
    • + +
  • devpkg-libepoxy
    • + +
  • devpkg-libical
    • + +
  • devpkg-libpciaccess
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libpthread-stubs
    • + +
  • devpkg-libsecret
    • + +
  • devpkg-libsoup
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • llvm
    • + +
  • make
    • + +
  • devpkg-mesa
    • + +
  • nasm
    • + +
  • devpkg-nspr
    • + +
  • devpkg-nss
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • devpkg-orc
    • + +
  • p11-kit
    • + +
  • devpkg-pango
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-pixman
    • + +
  • devpkg-qtbase
    • + +
  • scons
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • subversion
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • devpkg-wayland
    • + +
  • devpkg-wayland-protocols
    • + +
  • devpkg-webkitgtk
    • + +
  • which
    • + +
  • devpkg-xorgproto
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

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

Includes bundle(s): +

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

+ +
glmark2 OpenGL 2.0 and ES 2.0 benchmark
global GNU GLOBAL source code tagging system
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
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-glib
    • + +
  • gzip
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

+ +
goaccess Real-time web log analyzer
gpgme GPG encryption tools
gzip lossless data compression/decompression utility
hardware-bluetoothSoftware to enable use of bluetooth hardware
+ +
hardware-wifiFirmware and tools for basic wifi support
+ +

Includes bundle(s): +

    + +
  • wpa_supplicant
    • + +
+

+ +
haskell-basicBuild and run haskell language programs
+ +

Includes bundle(s): +

    + +
  • git
    • + +
  • p11-kit
    • + +
  • perl-basic
    • + +
  • c-basic
    • + +
  • make
    • + +
  • xz
    • + +
  • devpkg-zlib
    • + +
+

+ +
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
hwloc hardware affinity tools
iasimage for creating Intel Automotive Service (IAS) images, a binary file format understood by Intel© Slim Bootloader
icdiff Improved Color Differences between similar files
icecream Distributed network compilation
iftop display bandwidth usage on an interface
ImageMagickImageMagick
+ +

Includes bundle(s): +

    + +
  • libX11client
    • + +
+

+ +
inkscape Inkscape SVG drawing program
inotify-tools monitor for file system events
intltool internationalization tool for develops
ipmitool Manage IPMI functions of a local or remote system
iproute2 utilities for controlling TCP / IP networking and traffic control
ipvsadm Virtual Server admin tool 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
    • + +
  • perl-basic
    • + +
  • 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
kdiff3 Feature-Rich Code Comparison Utility
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-native-dkmsSupport module building/loading via DKMS in native kernel
+ +

Includes bundle(s): +

    + +
  • c-basic
    • + +
  • linux-dev
    • + +
+

+ +
kernel-networktestkernel with NFS root FS support and modular network drivers
+ +
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): +

    + +
  • kernel-iot-lts2018
    • + +
+

+ +
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): +

    + +
  • git
    • + +
  • package-utils
    • + +
  • python2-basic
    • + +
  • web-server-basic
    • + +
  • nfs-utils
    • + +
  • postgresql
    • + +
+

+ +
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
    • + +
  • acpica-unix2
    • + +
  • devpkg-at-spi2-atk
    • + +
  • devpkg-at-spi2-core
    • + +
  • devpkg-atk
    • + +
  • devpkg-cairo
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • dosfstools
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-fontconfig
    • + +
  • devpkg-freetype
    • + +
  • devpkg-fribidi
    • + +
  • gdb
    • + +
  • devpkg-gdk-pixbuf
    • + +
  • devpkg-glib
    • + +
  • devpkg-graphite
    • + +
  • devpkg-gtk3
    • + +
  • gzip
    • + +
  • devpkg-harfbuzz
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libdrm
    • + +
  • devpkg-libepoxy
    • + +
  • devpkg-libpciaccess
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libpthread-stubs
    • + +
  • devpkg-libsoup
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • llvm
    • + +
  • make
    • + +
  • devpkg-mesa
    • + +
  • nasm
    • + +
  • nfs-utils
    • + +
  • devpkg-nspr
    • + +
  • devpkg-nss
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • devpkg-orc
    • + +
  • p11-kit
    • + +
  • devpkg-pango
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-pixman
    • + +
  • scons
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • subversion
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • devpkg-wayland
    • + +
  • devpkg-wayland-protocols
    • + +
  • which
    • + +
  • devpkg-xorgproto
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

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

Includes bundle(s): +

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

+ +
less the less page
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
libnl Low level firewall tools
libva-utils collection of utilities and examples to exercise VA-API (Video Acceleration API)
libX11clientGrouping only bundle for use in X using bundles
+ +
libxml2 XML processing tools
libxslt XML documentation processing tools
libzmq ZMQ tools and libs
lightdmLightDM login manager with GTK greeter
+ +
linux-dev programs for developing Linux
linux-tools Tools for use in Linux
llvm LLVM/Clang compiler toolchain
lm-sensors Read various system sensors, sometimes using scary methods
localesbasic system translations
+ +
logrotate manages the automatic rotation and compression of log files
lua-basicLua programming language
+ +
lz4 tools to compress and decompress lz4 files
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
    • + +
  • mutt
    • + +
+

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

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • mail-utils
    • + +
  • os-core-dev
    • + +
  • devpkg-cairo
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-fontconfig
    • + +
  • devpkg-freetype
    • + +
  • gdb
    • + +
  • devpkg-glib
    • + +
  • gpgme
    • + +
  • devpkg-graphite
    • + +
  • gzip
    • + +
  • devpkg-harfbuzz
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libpthread-stubs
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-qtbase
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • devpkg-xorgproto
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

+ +
make build automation tool
maker-cncCNC carving tools for Makers
+ +

Includes bundle(s): +

    + +
  • inkscape
    • + +
  • python-extras
    • + +
  • python2-basic
    • + +
+

+ +
maker-gisGIS/Mapping tools for Makers
+ +

Includes bundle(s): +

    + +
  • desktop-kde-libs
    • + +
+

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

Includes bundle(s): +

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

+ +
mixerCreate Clear Linux releases
+ +

Includes bundle(s): +

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

+ +
mkosi generate disk images
mpg123 play and decode mp3 files
mtd-utils memory (usually flash) device utilities exposing an interface between hardware drivers and upper system layers
mtr Poll a remote server and see how the latency and performance changes over time
musl musl compiler toolchain
mutt The mutt mail client
nasm assembler
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
    • + +
  • curl
    • + +
  • irssi
    • + +
  • weechat
    • + +
  • znc
    • + +
+

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

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • network-basic
    • + +
  • os-core-dev
    • + +
  • perl-basic-dev
    • + +
  • devpkg-cairo
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-glib
    • + +
  • gzip
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • iproute2
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • devpkg-nss
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

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

Includes bundle(s): +

    + +
  • libX11client
    • + +
  • network-basic
    • + +
  • qt-basic
    • + +
  • nmap
    • + +
  • suricata
    • + +
+

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

Includes bundle(s): +

    + +
  • network-basic
    • + +
  • alsa-utils
    • + +
+

+ +
nfs-utils Server and client tooling for network file systems (NFS)
nginx HTTP server, reverse proxy, IMAP/POP3 proxy server
nload network load monitor
nmap security scanner for network device discovery
nodejs-basicRun javascript server side
+ +
octave high-level programming language, primarily intended for numerical computations
openldap ldap tools
openmpi HPC tools for running on jobs on clusters
openqaOpenQA infrastructure
+ +

Includes bundle(s): +

    + +
  • kvm-host
    • + +
  • perl-extras
    • + +
  • 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): +

    + +
  • cloud-api
    • + +
  • perl-basic
    • + +
  • python3-basic
    • + +
  • keepalived
    • + +
+

+ +
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
    • + +
  • unbundle
    • + +
  • cabextract
    • + +
  • diffoscope
    • + +
  • devpkg-fribidi
    • + +
  • devpkg-gdk-pixbuf
    • + +
  • global
    • + +
  • devpkg-gtk3
    • + +
  • devpkg-libdrm
    • + +
  • devpkg-libxcb
    • + +
  • devpkg-libXdamage
    • + +
  • devpkg-libXfixes
    • + +
  • devpkg-libXxf86vm
    • + +
  • devpkg-mesa
    • + +
  • mkosi
    • + +
  • scons
    • + +
  • devpkg-xorgproto
    • + +
+

+ +
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
    • + +
  • acpica-unix2
    • + +
  • devpkg-at-spi2-atk
    • + +
  • devpkg-at-spi2-core
    • + +
  • devpkg-atk
    • + +
  • bc
    • + +
  • devpkg-cairo
    • + +
  • ccache
    • + +
  • devpkg-clutter
    • + +
  • cpio
    • + +
  • curl
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • docutils
    • + +
  • dosfstools
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • file
    • + +
  • devpkg-fontconfig
    • + +
  • devpkg-freetype
    • + +
  • devpkg-fribidi
    • + +
  • gdb
    • + +
  • devpkg-gdk-pixbuf
    • + +
  • devpkg-glib
    • + +
  • gpgme
    • + +
  • devpkg-graphite
    • + +
  • devpkg-gst-plugins-base
    • + +
  • devpkg-gstreamer
    • + +
  • devpkg-gtk3
    • + +
  • gzip
    • + +
  • devpkg-harfbuzz
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • iproute2
    • + +
  • kbd
    • + +
  • less
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libdrm
    • + +
  • devpkg-libepoxy
    • + +
  • devpkg-libical
    • + +
  • devpkg-libpciaccess
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libpthread-stubs
    • + +
  • devpkg-libsecret
    • + +
  • devpkg-libsoup
    • + +
  • devpkg-libxkbcommon
    • + +
  • libxml2
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • llvm
    • + +
  • make
    • + +
  • devpkg-mesa
    • + +
  • nasm
    • + +
  • nfs-utils
    • + +
  • devpkg-nspr
    • + +
  • devpkg-nss
    • + +
  • devpkg-openmpi
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • devpkg-orc
    • + +
  • p11-kit
    • + +
  • devpkg-pango
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-pixman
    • + +
  • plzip
    • + +
  • devpkg-qtbase
    • + +
  • devpkg-qtdeclarative
    • + +
  • scons
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • subversion
    • + +
  • texinfo
    • + +
  • texlive
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • devpkg-wayland
    • + +
  • devpkg-wayland-protocols
    • + +
  • which
    • + +
  • devpkg-xorgproto
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • yasm
    • + +
  • zip
    • + +
  • devpkg-zlib
    • + +
+

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

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • gdb
    • + +
  • devpkg-glib
    • + +
  • gzip
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

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

Includes bundle(s): +

    + +
  • os-core
    • + +
  • os-core-webproxy
    • + +
+

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

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • os-core-dev
    • + +
  • os-core-update
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • docutils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • gdb
    • + +
  • devpkg-glib
    • + +
  • gzip
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • less
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

+ +
os-core-webproxyProvides basic suite for using http proxies
+ +

Includes bundle(s): +

    + +
  • os-core
    • + +
+

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

Includes bundle(s): +

    + +
  • iproute2
    • + +
  • python3-basic
    • + +
  • wpa_supplicant
    • + +
  • curl
    • + +
  • kbd
    • + +
  • less
    • + +
+

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

Includes bundle(s): +

    + +
  • acl
    • + +
  • cpio
    • + +
  • curl
    • + +
  • diffutils
    • + +
  • file
    • + +
  • git
    • + +
  • make
    • + +
  • openssh-server
    • + +
  • perl-basic
    • + +
  • sudo
    • + +
+

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

Includes bundle(s): +

    + +
  • c-basic
    • + +
  • dev-utils
    • + +
  • python3-basic
    • + +
  • perl-basic
    • + +
  • acpica-unix2
    • + +
  • intltool
    • + +
  • llvm
    • + +
+

+ +
os-testsuite-automotiveProvides minimal functionality for automotive testing functions
+ +

Includes bundle(s): +

    + +
  • os-testsuite
    • + +
  • os-testsuite-graphics
    • + +
+

+ +
os-testsuite-graphicsProvides minimal functionality for graphics testing functions
+ +

Includes bundle(s): +

    + +
  • glmark2
    • + +
+

+ +
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
    • + +
  • devpkg-qtbase
    • + +
  • bc
    • + +
  • devpkg-cairo
    • + +
  • fio
    • + +
  • gimp
    • + +
  • devpkg-libpng
    • + +
  • openmpi
    • + +
  • devpkg-openmpi
    • + +
  • nasm
    • + +
  • devpkg-openssl
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • redis-native
    • + +
  • scons
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • unzip
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
  • hwloc
    • + +
+

+ +
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
    • + +
  • devpkg-qtbase
    • + +
  • nasm
    • + +
  • yasm
    • + +
  • bc
    • + +
  • devpkg-cairo
    • + +
  • fio
    • + +
  • gimp
    • + +
  • devpkg-libpng
    • + +
  • nasm
    • + +
  • devpkg-openssl
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • scons
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • unzip
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

+ +
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
    • + +
  • rust-basic
    • + +
  • bc
    • + +
  • fio
    • + +
  • devpkg-libpng
    • + +
  • openmpi
    • + +
  • devpkg-openmpi
    • + +
  • nasm
    • + +
  • devpkg-openssl
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • redis-native
    • + +
  • scons
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • unzip
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

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

Includes bundle(s): +

    + +
  • cryptography
    • + +
  • openssl
    • + +
  • perl-basic
    • + +
  • python3-basic
    • + +
  • wpa_supplicant
    • + +
  • xfce4-desktop
    • + +
  • xemacs
    • + +
  • darktable
    • + +
  • thunderbird
    • + +
  • x11-server
    • + +
  • alsa-utils
    • + +
  • darktable
    • + +
  • firefox
    • + +
  • thunderbird
    • + +
  • xemacs
    • + +
+

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

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • os-core-dev
    • + +
  • os-utils-gui
    • + +
  • perl-basic-dev
    • + +
  • devpkg-at-spi2-atk
    • + +
  • devpkg-at-spi2-core
    • + +
  • devpkg-atk
    • + +
  • bc
    • + +
  • devpkg-cairo
    • + +
  • devpkg-clutter
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • docutils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-fontconfig
    • + +
  • devpkg-freetype
    • + +
  • devpkg-fribidi
    • + +
  • gdb
    • + +
  • devpkg-gdk-pixbuf
    • + +
  • devpkg-glib
    • + +
  • devpkg-gnome-desktop
    • + +
  • gpgme
    • + +
  • devpkg-graphite
    • + +
  • devpkg-gsettings-desktop-schemas
    • + +
  • devpkg-gst-plugins-base
    • + +
  • devpkg-gstreamer
    • + +
  • devpkg-gtk3
    • + +
  • gzip
    • + +
  • devpkg-harfbuzz
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • jq
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libdrm
    • + +
  • devpkg-libepoxy
    • + +
  • devpkg-libpciaccess
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libpthread-stubs
    • + +
  • devpkg-libsecret
    • + +
  • devpkg-libsoup
    • + +
  • devpkg-libxkbcommon
    • + +
  • libxml2
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • llvm
    • + +
  • make
    • + +
  • devpkg-mesa
    • + +
  • nasm
    • + +
  • nfs-utils
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • devpkg-orc
    • + +
  • p11-kit
    • + +
  • devpkg-pango
    • + +
  • parallel
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-pixman
    • + +
  • devpkg-qtbase
    • + +
  • scons
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • subversion
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • devpkg-wayland
    • + +
  • devpkg-wayland-protocols
    • + +
  • which
    • + +
  • devpkg-xorg-server
    • + +
  • devpkg-xorgproto
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

+ +
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
    • + +
  • make
    • + +
  • plzip
    • + +
  • zstd
    • + +
+

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

Includes bundle(s): +

    + +
  • python3-basic
    • + +
  • perl-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
pdns PowerDNS authoritative name server (DNSSEC enabled)
pdns-recursor PowerDNS recursive caching name server
performance-toolsRun performance and power measurements
+ +

Includes bundle(s): +

    + +
  • ethtool
    • + +
  • iproute2
    • + +
  • perl-basic
    • + +
  • python3-basic
    • + +
  • tcl-basic
    • + +
  • htop
    • + +
  • linux-tools
    • + +
  • powertop
    • + +
  • strace
    • + +
  • sysstat
    • + +
+

+ +
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
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-glib
    • + +
  • gzip
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

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

Includes bundle(s): +

    + +
  • perl-basic
    • + +
+

+ +
php-basicRun php language programs
+ +
pidginMulti-protocol instant messagging client
+ +
plzip Parallel LZMA Data Compressor
pmdk Persistent Memory Development Kit 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
    • + +
  • perl-basic
    • + +
  • python3-basic
    • + +
  • irssi
    • + +
  • weechat
    • + +
+

+ +
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
    • + +
  • nginx
    • + +
+

+ +
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
    • + +
  • devpkg-cairo
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-fontconfig
    • + +
  • devpkg-freetype
    • + +
  • gdb
    • + +
  • devpkg-glib
    • + +
  • devpkg-graphite
    • + +
  • gzip
    • + +
  • devpkg-harfbuzz
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libpthread-stubs
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • devpkg-xorgproto
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

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

Includes bundle(s): +

    + +
  • c-basic
    • + +
  • cloud-api
    • + +
  • 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
+ +

Includes bundle(s): +

    + +
  • libX11client
    • + +
+

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

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • os-core-dev
    • + +
  • qt-basic
    • + +
  • devpkg-at-spi2-atk
    • + +
  • devpkg-at-spi2-core
    • + +
  • devpkg-atk
    • + +
  • devpkg-cairo
    • + +
  • devpkg-clutter
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-fontconfig
    • + +
  • devpkg-freetype
    • + +
  • devpkg-fribidi
    • + +
  • gdb
    • + +
  • devpkg-gdk-pixbuf
    • + +
  • devpkg-glib
    • + +
  • devpkg-graphite
    • + +
  • devpkg-gst-plugins-base
    • + +
  • devpkg-gstreamer
    • + +
  • devpkg-gtk3
    • + +
  • gzip
    • + +
  • devpkg-harfbuzz
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libdrm
    • + +
  • devpkg-libepoxy
    • + +
  • devpkg-libical
    • + +
  • devpkg-libpciaccess
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libpthread-stubs
    • + +
  • devpkg-libsoup
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • llvm
    • + +
  • make
    • + +
  • devpkg-mesa
    • + +
  • nasm
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • devpkg-orc
    • + +
  • p11-kit
    • + +
  • devpkg-pango
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-pixman
    • + +
  • devpkg-qt3d
    • + +
  • devpkg-qtbase
    • + +
  • devpkg-qtdeclarative
    • + +
  • scons
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • subversion
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • devpkg-wayland
    • + +
  • devpkg-wayland-protocols
    • + +
  • which
    • + +
  • devpkg-xorgproto
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

+ +
quagga zebra and related routing tools
quasselQuassel IRC
+ +

Includes bundle(s): +

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

+ +
R-basicRun R language programs
+ +

Includes bundle(s): +

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

+ +
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
    • + +
+

+ +
rebootmgr Performs scheduled or immediate system reboots after the kernel or critical OS components change.
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
    • + +
  • openssh-server
    • + +
  • perl-basic
    • + +
  • python3-basic
    • + +
  • nginx
    • + +
+

+ +
scons python build system
service-osProvides the needed software for Service OS
+ +

Includes bundle(s): +

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

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

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • os-core-dev
    • + +
  • service-os
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-glib
    • + +
  • gzip
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libpciaccess
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

+ +
shellsRun a shell
+ +

Includes bundle(s): +

    + +
  • zsh
    • + +
+

+ +
smartmontools hard disk diagnostic utilities
software-defined-cockpitRun the automotive software defined cockpit which has graphic, media, sound and connectivity
+ +

Includes bundle(s): +

    + +
  • libX11client
    • + +
  • wpa_supplicant
    • + +
  • alsa-utils
    • + +
  • v4l-utils
    • + +
+

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

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • os-core-dev
    • + +
  • software-defined-cockpit
    • + +
  • devpkg-at-spi2-atk
    • + +
  • devpkg-at-spi2-core
    • + +
  • devpkg-atk
    • + +
  • devpkg-cairo
    • + +
  • devpkg-clutter
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • docutils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-fontconfig
    • + +
  • devpkg-freetype
    • + +
  • devpkg-fribidi
    • + +
  • gdb
    • + +
  • devpkg-gdk-pixbuf
    • + +
  • devpkg-glib
    • + +
  • devpkg-graphite
    • + +
  • devpkg-gst-plugins-base
    • + +
  • devpkg-gstreamer
    • + +
  • devpkg-gtk3
    • + +
  • gzip
    • + +
  • devpkg-harfbuzz
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libdrm
    • + +
  • devpkg-libepoxy
    • + +
  • devpkg-libpciaccess
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libpthread-stubs
    • + +
  • devpkg-libsoup
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • llvm
    • + +
  • make
    • + +
  • devpkg-mesa
    • + +
  • nasm
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • devpkg-orc
    • + +
  • p11-kit
    • + +
  • devpkg-pango
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-pixman
    • + +
  • devpkg-qtbase
    • + +
  • devpkg-qtdeclarative
    • + +
  • scons
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • subversion
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • devpkg-wayland
    • + +
  • devpkg-wayland-protocols
    • + +
  • which
    • + +
  • devpkg-xorgproto
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

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

Includes bundle(s): +

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

+ +
squid HTTP caching proxy
storage-clusterRun a storage server
+ +

Includes bundle(s): +

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

+ +
storage-utilsRun disk and filesystem management functions
+ +

Includes bundle(s): +

    + +
  • smartmontools
    • + +
  • dosfstools
    • + +
  • nfs-utils
    • + +
  • pmdk
    • + +
  • smartmontools
    • + +
  • xfsprogs
    • + +
+

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

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • os-core-dev
    • + +
  • storage-utils
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • docutils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • gdb
    • + +
  • devpkg-glib
    • + +
  • gzip
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libxkbcommon
    • + +
  • libxml2
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • llvm
    • + +
  • make
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-qtbase
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

+ +
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
    • + +
  • perl-basic
    • + +
  • sudo
    • + +
  • which
    • + +
  • acpica-unix2
    • + +
  • diffutils
    • + +
  • file
    • + +
  • findutils
    • + +
  • gzip
    • + +
  • htop
    • + +
  • kbd
    • + +
  • kernel-install
    • + +
  • less
    • + +
  • parallel
    • + +
  • patch
    • + +
  • powertop
    • + +
  • strace
    • + +
  • tmux
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • xz
    • + +
  • zstd
    • + +
+

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

Includes bundle(s): +

    + +
  • dev-utils
    • + +
  • os-core-dev
    • + +
  • perl-basic-dev
    • + +
  • sysadmin-basic
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • gdb
    • + +
  • devpkg-glib
    • + +
  • gzip
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • kbd
    • + +
  • less
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libxkbcommon
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • make
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • p11-kit
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-qtbase
    • + +
  • strace
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • which
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • devpkg-zlib
    • + +
+

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

Includes bundle(s): +

    + +
  • ansible
    • + +
  • git
    • + +
  • ipmitool
    • + +
  • 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
    • + +
+

+ +
sysstat utilities for monitoring system performance and usage activity
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
+ +
texinfo unix style documentation tooling
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
unbundle Recursively resolves a package list from a bundle definition
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
    • + +
  • acpica-unix2
    • + +
  • devpkg-at-spi2-atk
    • + +
  • devpkg-at-spi2-core
    • + +
  • devpkg-atk
    • + +
  • bc
    • + +
  • devpkg-cairo
    • + +
  • cpio
    • + +
  • devpkg-dbus
    • + +
  • diffutils
    • + +
  • docbook-utils
    • + +
  • docutils
    • + +
  • dosfstools
    • + +
  • doxygen
    • + +
  • devpkg-elfutils
    • + +
  • devpkg-expat
    • + +
  • devpkg-fontconfig
    • + +
  • devpkg-freetype
    • + +
  • devpkg-fribidi
    • + +
  • gdb
    • + +
  • devpkg-gdk-pixbuf
    • + +
  • devpkg-glib
    • + +
  • gpgme
    • + +
  • devpkg-graphite
    • + +
  • devpkg-gtk3
    • + +
  • gzip
    • + +
  • devpkg-harfbuzz
    • + +
  • devpkg-icu4c
    • + +
  • intltool
    • + +
  • iproute2
    • + +
  • kbd
    • + +
  • less
    • + +
  • devpkg-libX11
    • + +
  • devpkg-libdrm
    • + +
  • devpkg-libepoxy
    • + +
  • devpkg-libpciaccess
    • + +
  • devpkg-libpng
    • + +
  • devpkg-libpthread-stubs
    • + +
  • devpkg-libsoup
    • + +
  • devpkg-libxkbcommon
    • + +
  • libxml2
    • + +
  • devpkg-libxml2
    • + +
  • libxslt
    • + +
  • llvm
    • + +
  • make
    • + +
  • devpkg-mesa
    • + +
  • nasm
    • + +
  • nfs-utils
    • + +
  • devpkg-nspr
    • + +
  • devpkg-nss
    • + +
  • devpkg-openmpi
    • + +
  • openssl
    • + +
  • devpkg-openssl
    • + +
  • devpkg-orc
    • + +
  • p11-kit
    • + +
  • devpkg-pango
    • + +
  • patch
    • + +
  • devpkg-pcre
    • + +
  • devpkg-pixman
    • + +
  • devpkg-qtbase
    • + +
  • scons
    • + +
  • devpkg-sqlite-autoconf
    • + +
  • strace
    • + +
  • subversion
    • + +
  • texinfo
    • + +
  • tzdata
    • + +
  • unzip
    • + +
  • devpkg-util-linux
    • + +
  • valgrind
    • + +
  • devpkg-wayland
    • + +
  • devpkg-wayland-protocols
    • + +
  • which
    • + +
  • devpkg-xorgproto
    • + +
  • xz
    • + +
  • devpkg-xz
    • + +
  • yasm
    • + +
  • devpkg-zlib
    • + +
+

+ +
v4l-utils video4linux tools
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
    • + +
+

+ +
virt-manager-guiEnable controlling virt-manager through a GUI
+ +

Includes bundle(s): +

    + +
  • libX11client
    • + +
  • virt-manager
    • + +
+

+ +
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
+ +

Includes bundle(s): +

    + +
  • httpd
    • + +
  • nginx
    • + +
+

+ +
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
    • + +
  • perl-basic
    • + +
  • xterm
    • + +
+

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

Includes bundle(s): +

    + +
  • libX11client
    • + +
  • which
    • + +
+

+ +
xfsprogs XFS tools
xterm The basic X.Org terminal program desktop launcher
xz data compression/decompression tool
yasm assembler
zip create ZIP archives
znc IRC network bouncer
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 d48b6de4..6fa87835 100644 --- a/source/clear-linux/reference/bundles/bundles.rst +++ b/source/clear-linux/reference/bundles/bundles.rst @@ -3,13 +3,13 @@ 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`. + +To view bundles or packages on GitHub, select the :file:`Name` in column one. 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 341d5c91..fb7b5369 100644 --- a/source/clear-linux/reference/collaboration/collaboration.rst +++ b/source/clear-linux/reference/collaboration/collaboration.rst @@ -1,17 +1,83 @@ .. _collaboration: -Collaboration guidelines +Documentation guidelines ######################## -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, -examples, or task focused guides. Read the information carefully before -submitting any work for review to ensure your contribution can be added as -quickly as possible. +See a missing topic in the documentation? Find an existing document that could +be improved? Help us out by contributing! If you haven't contributed before, +take a moment to review our `Contribution guidelines`_. + +Do you have questions about the documentation that were not answered by these +guidelines? Send your question to the `mailing list`_. + +Contribution guidelines +*********************** + +The |CL| documentation is hosted in GitHub and is written using +reStructuredText. Use our guidelines and best practices to write consistent, +readable documentation. .. toctree:: :maxdepth: 1 - documentation/documentation + Writing guide: Describes the style we use to keep our documents clear and concise. + Structure and formatting guide: Explains how we organize and format content, using reStructuredText and Sphinx. + +How to contribute +***************** + +There are multiple ways to contribute and help improve our documentation: + +* **Make a suggestion**: Have a documentation suggestion but no time to write it + yourself? Send your suggestion to the `mailing list`_. +* **Log an issue**: If you find a problem in our documentation (such as typos or + out-of-date information), log an issue in the `documentation repository`_. +* **Contribute directly via GitHub**: Whether you've found a typo, have better + instructions or examples, or have a new page to add, submit your improvement + or addition as a pull request on the `documentation repository`_. +* **Test documentation**: Step through our instructional guides and tutorials to + verify the instructions. Log or correct any out-of-date information. + +All contributions must follow our `code of conduct`_. + +Contribute via GitHub +********************* + +Our documentation is hosted in GitHub and we follow the standard `GitHub flow`_: + +#. Clone the `documentation repository`_. + +#. Create your own fork of the repository. + +#. Create a branch for your contribution. + +#. Add your commits. + +#. Open a pull request. + +#. Discuss, review, and update your contributions. + +#. Once the maintainer approves, your contribution is merged and published as + part of the documentation. + +.. _references: + +References +********** + +We use the following references to guide the grammar, style, and formatting of +our documentation: + +* `Microsoft Writing Style Guide`_ +* `Merriam-Webster Dictionary`_ +* The Chicago Manual of Style (15th edition), The University of Chicago Press +* Microsoft Press Computer Dictionary, Microsoft Press +* Read Me First!, Oracle Technical Publications + + +.. _`code of conduct`: https://clearlinux.org/community/code-of-conduct +.. _mailing list: https://lists.clearlinux.org/mailman/listinfo/dev +.. _GitHub flow: https://guides.github.com/introduction/flow/ +.. _documentation repository: https://github.com/clearlinux/clear-linux-documentation +.. _Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/ +.. _Merriam-Webster Dictionary: https://www.merriam-webster.com/ \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/documentation/basic.rst b/source/clear-linux/reference/collaboration/documentation/basic.rst deleted file mode 100644 index 021c345b..00000000 --- a/source/clear-linux/reference/collaboration/documentation/basic.rst +++ /dev/null @@ -1,130 +0,0 @@ -.. _basic: - -Basic contribution guide -######################## - -This list compiles the most common format, markup, structure, and grammar -rules for your convenience. You can find more detailed information in the -referenced sections. - -.. contents:: - :local: - :backlinks: entry - -Format -****** - -* Limit line length to 78 characters. The GitHub web interface forces this - limitation for readability. - -* Remove trailing white space from your documents. - -* Use short sentences and paragraphs. Keep sentence length under 20 words. - -* Use only lower case letters for filenames. - -* Separate multiple words in filenames using dashes. - -Markup -****** - -* Use the appropriate :abbr:`ReST (ReStructuredText)` roles for your content. - See the `ReST primer`_ for the complete list of roles. - -* Use the :abbr: role to define the first instance of an abbreviation, for - example: :abbr:\`CL (Clear Linux)\`. - -* Use hash-tags to underline the file's main title. - -* Use asterisks to underline the file's first level headings. - -* Use equal signs to underline the file's second level of headings. - -* Use dashes to underline the file's third level of headings. - -* Use labels to reference documentation sections. Do not reference - sections with URLs. See :ref:`cross` for details. - -* Don't use explicit URLs as links, for example https://clearlinux.org/. - -* Always include descriptive link text. For example: - Visit the `Clear Linux website`_. Do not use "here", "this", or similar - references for link text. - -Structure -********* - -* All files must have a main title and up to three levels of headings. - Restructure the content in multiple files as needed to comply. - -* Use descriptive headings. - -* Follow all headings with at least one paragraph of content. There should - never be two consecutive headings. - -* Separate the link and the target definition. All target definitions must be - included at the end of the file. See :ref:`cross` for details. - -* Use parallelism in headings, sentences, and lists. See our - :ref:`parallelism` for details. - -* Put conditional phrases first in cautions and warnings. For example: - "If you do X, then Y will occur." See our :ref:`notices` guide. - -* Place figures and tables immediately after related text. - -* Place code or commands immediately after the leading text in a new line, - see our :ref:`code`. - -* Reference figures, code examples, and tables by number. - For example, use "Figure 1," instead of "The figure above or below". See - :ref:`cross` and :ref:`images`. - -* Include at least one direct reference to any table or figure you add. See - :ref:`tables`. - -Grammar -******* - -* Include only one main idea in a sentence. See :ref:`simple`. - -* Limit the number of clauses you use to no more than two. See :ref:`simple`. - -* Limit the number of sentences per paragraph to about six. See :ref:`simple`. - -* Use strong verbs. See :ref:`simple`. - -* Use action verbs. See :ref:`simple`. - -* Avoid weak verbs like be, have, make, and do. See :ref:`simple`. - -* Use short direct commands and avoid niceties such as the word - "please". - -* Use the present tense wherever possible and avoid past and future - tense verbs. See :ref:`simple`. - -* Use Active voice. Write, "Someone does something"; don't write, - "Something is done by someone" or "Something is done." See :ref:`simple`. - -* Use "we" for recommendations. Write "We recommend..." as opposed to - "It is recommended...." See :ref:`simple`. - -* Use "you" rather than "the user" in your instructions. - -* Use short common English words whenever possible, see our :ref:`simple` - guide. - -* Avoid contractions. See :ref:`grammar`. - -* Use articles such as 'a', 'an', and 'the' to reduce ambiguity. - -Additional information -********************** - -Learn more about the accepted rules of grammar, punctuation, and word use in -our :ref:`language`. If you are looking for tips on how to write shorter, -clearer, and more concise content, visit our :ref:`simple` guide. - -.. _Clear Linux website: https://clearlinux.org/ -.. _ReST primer: http://docutils.sourceforge.net/docs/user/rst/quickstart.html diff --git a/source/clear-linux/reference/collaboration/documentation/code.rst b/source/clear-linux/reference/collaboration/documentation/code.rst deleted file mode 100644 index 870faeba..00000000 --- a/source/clear-linux/reference/collaboration/documentation/code.rst +++ /dev/null @@ -1,161 +0,0 @@ -.. _code: - -Code blocks -########### - -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: - -* Include code examples from a source file. Only write the code example - directly into the documentation if the example is less than 10 lines long. - -* Use the ``:linenos:`` option of the `literalinclude` directive to add line - numbers to your example. - -* Specify the programing language of your example. Not only will it - add syntax highlighting but it also allows the reader to identify code - efficiently. Use `bash` for console commands, `asm` for assembly code and - `c` for C code. - -* Treat all console commands entered by users as code examples. - -Examples -******** - -This is a code example included from a file. Note how only certain lines of -the source file are included and how the lines are renumbered. - -This source: - -.. code-block:: rst - - .. literalinclude:: ./hello.c - :language: c - :lines: 97-110 - :linenos: - -Renders as: - -.. literalinclude:: ./hello.c - :language: c - :lines: 97-110 - :linenos: - - -This example shows a series of console commands. Line numbering is not -required. Specify that these are commands using `bash` as the programing -language. - -This source: - -.. code-block:: rst - - .. code-block:: bash - - $ mkdir ${HOME}/x86-build - - $ mkdir ${HOME}/arm-build - - $ mkdir ${HOME}/cross-src - -Renders as: - -.. code-block:: bash - - $ mkdir ${HOME}/x86-build - - $ mkdir ${HOME}/arm-build - - $ mkdir ${HOME}/cross-src - -.. note:: - You will find instances which use `console` instead of `bash`. We are - currently in the process of implementing a distinction between the two. - Moving forward, `bash` will be used for commands entered by readers, and - `console` will be used for the output users obtain in the command prompt. - -Finally, this is a code example that is not part of the |CL| code base. It is -not even valid code but it can illustrate the concept. - -This source: - -.. code-block:: rest - - .. code-block:: c - - static NANO_CPU_INT_STUB_DECL (deviceStub); - - void deviceDriver (void) - - { - - . - . - . - - nanoCpuIntConnect (deviceIRQ, devicePrio, deviceIntHandler, - deviceStub); - - . - . - . - - } - -Renders as: - -.. code-block:: c - - static NANO_CPU_INT_STUB_DECL (deviceStub); - - void deviceDriver (void) - - { - - . - . - . - - nanoCpuIntConnect (deviceIRQ, devicePrio, deviceIntHandler, - deviceStub); - - . - . - . - - } - -Templates -********* - -We included templates for a basic ``.. code-block::`` directive -and for a ``.. literalinclude::`` directive. - -Use ``code-block`` for console commands, brief examples, and examples -outside the |CL| code base. - -.. code-block:: rst - - .. code-block:: language - - source - -Use ``litteralinclude`` to insert code from a source file. Keep in -mind that you can include the entire contents of the file or just -specific lines. - -.. code-block:: rst - - .. literalinclude:: ../path/to/file/file_name.c - :language: c - :lines: 5-30, 32, 70-100 - :emphasize-lines: 3 - :linenos: - -.. caution:: - The ``:emphasize-lines:`` option uses the line numbering provided - by ``:linenos:``. The emphasized line in the template will be the - third one of the example but the eighth one of the source file. - diff --git a/source/clear-linux/reference/collaboration/documentation/contents.rst b/source/clear-linux/reference/collaboration/documentation/contents.rst deleted file mode 100644 index 248053b4..00000000 --- a/source/clear-linux/reference/collaboration/documentation/contents.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _contents: - - -Contents directive -################## - -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. - -.. contents:: :local: - :depth: 2 - -.. code-block:: bash - - .. contents:: :local: - :depth: 2 - -.. note:: - - Assure that you add `:local:` as the value. For more resources on this directive, - visit the `reStruturedText Directives`_ - -EXAMPLE: - -Guide Example -************* - -Introduction -============ - -Step-by-Step -============ - -Launch -====== - - -.. _reStruturedText Directives: http://docutils.sourceforge.net/0.4/docs/ref/rst/directives.html#table-of-contents diff --git a/source/clear-linux/reference/collaboration/documentation/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst deleted file mode 100644 index 6780dde1..00000000 --- a/source/clear-linux/reference/collaboration/documentation/cross.rst +++ /dev/null @@ -1,153 +0,0 @@ -.. _cross: - -Cross-references -################ - -Sphinx provides different methods to create both internal and -external cross-references. Use only the following methods to increase the -consistency of the documents. - -.. _internal-cross: - -Internal cross-references -************************* - -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 -name, in order to be be cross-referenced within the entire documentation. - -Labels' naming conventions: - -* Ensure the label is unique throughout the documentation - -* Use only full words. - -* Use \- to link multiple words. - -* Use only as many words as necessary. - -These are some examples of proper labels: - -.. code-block:: rst - - .. _quick-start: - - .. _gerrit-access: - - .. _building-clear-linux: - -Do not use labels like these: - -.. code-block:: rst - - .. _QuickStart: - - .. _How to Gain Access to Gerrit: - - .. _building: - -As an example, this is an internal reference to the beginning of the :ref:`rest`. - -Observe that the ``:ref:`` role is replaced with the title's text. -Similarly, it will be replaced with the figure's caption. If a different -text is needed the ``:ref:`` role can still be used, for example: - -This is an internal reference to the beginning of -:ref:`this section `. - -Use the following templates to insert internal cross references properly. - -.. code-block:: rst - - .. _label-of-target: - - This is a heading - ----------------- - - This creates a link to the :ref:`label-of-target` using the text of the - heading. - - This creates a link to the :ref:`target ` using the word - 'target' instead of the heading. - -The template renders as: - -.. _label-of-target: - -This is a heading ------------------ - -This creates a link to the :ref:`label-of-target` using the text of the -heading. - -This creates a link to the :ref:`target ` using the word -'target' instead of the heading. We use the term 'target' here similar to -the way'anchor' is used in HTML. - -.. note:: - - This type of internal cross reference works across multiple files, is - independent of changes in the text of the headings, and works on all - Sphinx builders. - -External References -******************* - -External references or hyperlinks can be added easily with reST. Only -hyperlinks with a separated target definition are allowed. - -Do not use explicit hyperlinks consisting entire URLs. For example, links -like this one, https://clearlinux.org/ must be avoided. - -Hyperlinks with a separated target definition allow us to place the URL after -label. They are easier to update and independent of the text, for example: - -`Gitg`_ is a great tool to visualize a GIT tree. - -.. _Gitg: https://wiki.gnome.org/Apps/Gitg/ - -Follow these guidelines when inserting hyperlinks: - -* The labels for hyperlinks must be grammatically correct and unique within - the file. - -* Do not create labels for hyperlinks using: link, here, this, there, etc. - -* Add all target definitions at the end of the file containing the - hyperlinks. - -Use this template to add a hyperlink with a separated definition: - -.. code-block:: rst - - The state of `Oregon`_ offers a wide range of recreational activities. - -The include directive -********************* - -|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. - -.. code-block:: console - - .. include:: rest.rst - :start-after: incl-restructured-text-overview: - :end-before: incl-restructured-text-overview-end: - -In this example, note that you must: - -* Create a `target` that appears directly above a header (ease of inclusion) -* Ensure that the target is unique, as explained in :ref:`target ` -* Use a `:` at the end of the value of `start-after` and `end-before`. - -Use of the ``.. inclusion::`` for :ref:`rest` is shown below. - -.. include:: rest.rst - :start-after: incl-restructured-text-overview: - :end-before: incl-restructured-text-overview-end: - -.. _Oregon: http://traveloregon.com/ diff --git a/source/clear-linux/reference/collaboration/documentation/documentation.rst b/source/clear-linux/reference/collaboration/documentation/documentation.rst deleted file mode 100644 index 15056a84..00000000 --- a/source/clear-linux/reference/collaboration/documentation/documentation.rst +++ /dev/null @@ -1,139 +0,0 @@ -.. _documentation: - -Documentation contribution guidelines -##################################### - -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. - -The |CL| documentation is hosted in GitHub and welcomes community -contributions. This guide provides rules to write -:ref:`clear, concise`, and :ref:`consistent content`. Our -documentation is written using ReStructuredText and we provide -:ref:`examples, templates, and best practices` for that markup. - -To contribute, follow the standard `GitHub flow`_: - -#. Clone the `Clear Linux documentation repository`_. - -#. Create your own fork of the repository. - -#. Create a branch for your contribution. - -#. Add your commits. - -#. Open a pull request. - -#. Discuss, review, and update your contributions. - -#. Once the maintainer approves, your contribution is merged and published as - part of the `documentation section`_. - -The |CL| technical content is written in simple American English and our -:ref:`language` contains detailed information on that standard. - -This guide includes the following sections: - -.. toctree:: - :maxdepth: 3 - - basic - structures - rest - language - - -Scope -***** - -The |CL| documentation is divided in five sections: - -* **Get started:** Information about installing Clear Linux. -* **Concepts:** Detailed technical information about our features. -* **Guides:** Step-by-step instructions to complete common tasks and - configuration. -* **Tutorials:** Step-by-step instructions to complete the installation and - configuration of the tools needed for a specific use case. -* **Reference:** Information providing additional context or details. - -If you are unsure on which section to use for your contribution, send an -email to our `mailing list`_ at: dev@lists.clearlinux.org Include the outline -of the contribution you are planning and a brief description of its intended -purpose and scope. - -This style guide applies to the following technical content: - -* Commit messages -* Technical presentations -* All documents in ReStructuredText within and without the documentation - repository -* In-code comments -* Release notes - -We are always grateful to receive content contributions and are happy to help -via our mailing list or our IRC channel, #clearlinux. If you have found a -problem with one of our documents, please file a `bug report`_. - -Tone and audience -***************** - -The tone of the |CL| documentation should be clear, concise, confident, and -courteous. We write for our peers and want to be familiar. Use the second -person, you or we, and active voice, we configure or you run, for example. -Remain professional in your writing and carry an undertone of cordiality, -respect, and cooperation. - -Assume your audience has about the same level of technical understanding and -expertise as you did when you first started collaborating. Do not talk down -to our readers but do not assume they know everything about the subject. -Offer brief explanations or summaries of "common knowledge" if a -significant portion of readers might benefit. - -All contributions must follow our `code of conduct`_. - -Methodology -*********** - -This guide differs from other style guides and contains additional material -not found in those sources. - -To research a style question, look for the answer in this guide -first. If the question is not answered here, send your question to the -`mailing list`_ at: dev@lists.clearlinux.org. - -If the question is answered in the existing style guide or dictionary, -the solution is implemented and enforced as described. - -References -********** - -In creating and refining the policies in this document, we consulted the -following sources for guidance: - -* The Chicago Manual of Style (15th edition), The University of - Chicago Press; -* Merriam-Webster Dictionary; -* Microsoft Manual of Style for Technical Publications, Microsoft - Press; -* Microsoft Press Computer Dictionary, Microsoft Press; and -* Read Me First!, Oracle Technical Publications. - -These sources do not always concur on questions of style and usage; nor do we -always agree with these sources. In areas where there is disagreement, the -decisions are explained in the respective section. - -This guide takes precedence over all other style guides in all cases. In -cases where the guide does not address the issue at hand, please report the -issue to the `mailing list`_ using our `bug report`_. - -Use the Merriam-Webster's Collegiate Dictionary to determine correct -spelling, hyphenation, and usage. - -.. _mailing list: https://lists.clearlinux.org/mailman/listinfo/dev -.. _GitHub flow: https://guides.github.com/introduction/flow/ -.. _documentation section: https://clearlinux.org/documentation -.. _Clear Linux documentation repository: - https://github.com/clearlinux/clear-linux-documentation -.. _bug report: https://github.com/clearlinux/distribution/issues -.. _code of conduct: https://clearlinux.org/community/code-of-conduct diff --git a/source/clear-linux/reference/collaboration/documentation/figures/fibers-1.svg b/source/clear-linux/reference/collaboration/documentation/figures/fibers-1.svg deleted file mode 100644 index 288b2ca9..00000000 --- a/source/clear-linux/reference/collaboration/documentation/figures/fibers-1.svg +++ /dev/null @@ -1,165 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - Fibers - - - - diff --git a/source/clear-linux/reference/collaboration/documentation/grammar.rst b/source/clear-linux/reference/collaboration/documentation/grammar.rst deleted file mode 100644 index 037ec965..00000000 --- a/source/clear-linux/reference/collaboration/documentation/grammar.rst +++ /dev/null @@ -1,342 +0,0 @@ -.. _grammar: - -Grammar guide -############# - -This guide provides valuable insight into the correct grammar for the -|CL-ATTR| documentation. It covers subjects such as capitalization, verbs, -hyphenation, possessives, and contractions. - -Capitalization -************** - -The preferred capitalization style for all documentation is sentence -case. - -Words should only be capitalized when: - -* They are proper nouns or adjectives. -* They refer to trademarked product names. - -.. note:: - Do not capitalize a word to indicate it has a greater status than other - words. Never change the case of variable, function or file names; always - keep the original case. - -Menu capitalization -=================== - -When referring to software menu items by name, replicate the -capitalization as it appears in the software menus the user will see. -It is acceptable to refer to these items generically by using -lowercase letters if it is clear that your reference is generic and -not a specific name of a window or field on a menu, for example: - -Click :guilabel:`Edit` to display the :guilabel:`Widget Configuration` window. - -The widget configuration window has several advanced widget configuration -options. - -The second sentence could have capitalized the term "Widget -Configuration window"; but there are times when you might want to -refer to something with a generic descriptor and not its name. Observe -the use of the ReST markup ``:guilabel:`` on the first sentence. - -A few other menu capitalization rules to keep in mind: - -* Use "Select :menuselection:`File --> New`." - -* Put the option to be selected last. "Select - :menuselection:`View --> Side Bar --> Hide Side Bar`" - -* Do not include more than 3 navigation steps in a menu selection. If - more than three steps are needed divide the steps using - ``:guilabel:`` or ``:menuselection:``. For example: "Go to - :guilabel:`File` and select - :menuselection:`Print --> Print Preview --> Set Up`." - -Software version capitalization -=============================== - -Do not capitalize the word version or letter v when listing software -or hardware version numbers. The v is lowercase and closed with the -number (no period). For example: - -* Widget Pro v5.0 -* Widget Master v2.1.12 - -Hyphenated or slashed-concatenated terms -======================================== - -For hyphenated or slash-concatenated terms, capitalize only the first -letter, even if they are headings. For example: - -* Day/night Menu -* Follow-up Action Items - -Plurals and possessives -*********************** - -Because English plurals and possessives use the same /s/ and /z/ -phonemes, they can create problems for even experienced writers. This -section deals with these issues. - -Singular vs. plural possessives -=============================== - -Here are some guidelines for singular and plural possessives: - -* Use only the apostrophe to show possession for a plural that ends in - s: The boys' books. - -* Use apostrophe + s to show possession for a plural that does not end - in s: The men's books. - -* Use apostrophe + s to show possession for a singular that ends in a - silent sibilant: Illinois's capital. - -* Use apostrophe + s to show - possession for a singular that ends in a sibilant; s, x, c, z, or - others. - -The following table provides some examples with the correct and -incorrect cases and the notes that accompanies them. - -+-------------------+------------------+---------------------------+ -| Correct | Incorrect | Notes | -+===================+==================+===========================+ -| the boys' books | the boy's books | The books that belong to | -| | | several boys. | -+-------------------+------------------+---------------------------+ -| the men's books | the mens' books | The books that belong to | -| | | several men. | -| | | | -+-------------------+------------------+---------------------------+ -| Arkansas's code | Arkansas' code | The s at the end of | -| | | Arkansas is silent and | -| | | Arkansas is not a plural. | -+-------------------+------------------+---------------------------+ -| the boss's office | the boss' office | We say: "the /BOSS-iz/ | -| | | office" not "the/BOSS/ | -| | | office." | -+-------------------+------------------+---------------------------+ -| the box's lid | the boxe's lid | One could say "the box | -| | the box' lid | lid," avoiding the | -| | | possessive. | -+-------------------+------------------+---------------------------+ -| Lopez's average | Lopez' average | We say "/LO-pez-iz/ | -| | | average," not "/LO-pez/ | -| | | average." | -+-------------------+------------------+---------------------------+ -| business's sales | business' sales | If you pronounce another | -| | | syllable to show | -| | | possession, it must have | -| | | the apostrophe-s. | -+-------------------+------------------+---------------------------+ - -Apostrophe-s anomalies -====================== - -If a company name ends in s, x, c, or a sibilant sound, use the -apostrophe-s ending for -possessives: - -Traktronix's oscilloscopes - -Exception: If the company name is intended as a plural, we allow the -apostrophe-only ending: - -Tejada Instruments' calculators - -In many cases, it is actually best to avoid the possessive form -altogether for s-ending singular possessives, such as for company -names and use the company name as a nonpossessive modifier instead: - -Traktronix oscilloscopes -Tejada Instruments calculators - -We say "Intel equipment" when discussing Intel-branded products, not -"Intel's equipment", which implies that we own it, not that we produce -it. "Intel's equipment" sounds like the equipment that Intel employees -use. - -Plural modifiers -================ - -Avoid plural modifiers. For example, it should be a system -administrator, not a systems administrator. It doesn't matter how many -systems this person manages, we don't typically use the plural of a word -to modify a noun. Here is a list of exceptions: - -* operations manager -* sales department -* graphics team - - -There are always exceptions, especially when the plural form is -generally considered to be singular: sales, physics, operations. It is -best to adhere to this rule and ask if you are unsure. - -Parenthetical plurals -===================== - -Do not parenthesize optional plurals, whether added to the end of a -word, typically with the letter s, or internally. In general, think in -plurals when you write, assume that the user understands that a plural -could mean a singular as well. A typical user who has only one unit -will not be confused if you say "connect the units." On the contrary, -using parenthetical plurals often creates more confusion. - -Correct - -Men, women, children, college alumni, moose, -and even desert plants such as cacti should not -use parentheses around plurals. - -Incorrect - -A m(e)n, wom(a)n, a child(ren), college alumn(i), (moose), and -even a desert plant(s) such as a cact(i) should not use a -parenthes(e)s around a plural(s). - -Internal plural acronyms -======================== - -Some abbreviated terms can cause trouble, particularly when the -pluralized portion does not fall at the end of the phrase. These -internal-plural words should follow standard English pluralization -rules when abbreviated: The plural goes at the end of the term. - -* Alarms acknowledged and logged: AAL, AALs. -* Attorneys-general: AG, AGs. -* Regions of interest: ROI, ROIs. - -Plurals of acronyms and capitalized product names -================================================= - -Pluralize acronyms, initialisms, and capitalized product names by -adding a lowercase s; do not use an apostrophe. If the term ends in a -sibilant (s, x, z, sometimes c and others), pluralize it by adding a -lowercase es. Examples: - -Use TVs, DVDs, CDs, DVMRs not TV's, DVD's, CD's, DVMR's. -Use OSes not OSs, OS's. -Use TRAXes, iBOXes not TRAXs, TRAX's, iBOX's, iBOXs. -Use FAACes not FAAC's, assuming it is pronounced "face". -Use FAACs not FAAC's Assuming it is pronounced "fake". - -Whenever you hear the extra syllable in the plural, add the -es suffix -for the plural; if you do not hear the extra syllable, add the -s -suffix for the plural. - -Latin plurals -============= - -Pluralize Latin terms in body text as shown: - -* Use appendixes not appendices. -* Use matrixes not matrices. -* Use indexes not indices. -* Use vertexes not vertices. - -.. note:: - Some Latin plurals, such as parentheses, phenomena, alumni, and - crises, are widely used and accepted in English. - -Contractions -************ - -Avoid the use of contractions since some of them might be ambiguous and -confusing to non-native English-speaking audiences. - -Some contractions can cause confusion for non-native English-speakers -because these contractions stand for more than one construction. For -example, there's can be a contraction of there is or there has. The -same applies to where's, it's, that's, and others. - -Also, avoid contractions of the word is, especially when combined with -company or product names: Say, WidgetPro is an awesome product; not -WidgetPro's an awesome product. - -Hyphenation -*********** - -The hyphen is often used to join words together to form a compound noun. -Compound nouns often go through this progressions: - -* open compound: health care -* hyphenated compound: health-care -* closed compound: healthcare - -The English language is trending away from hyphenated compounds to -closed compounds. - -Prefix hyphenation -================== - -Do not hyphenate the prefixes listed below. Join the prefix to the -term being modified, even if this results in a double vowel or double -consonant: - -ante, counter, intra, mini, pro, super, anti, extra, meta, non, -pseudo, trans, bi, by, infra, micro, post, re, ultra, bio, inter, mid, -pre, sub, un. - -Here are some words that are often inappropriately hyphenated; do not -hyphenate these words either: - -antitheft device, multicamera, multiscreen, prepackaged, reuse, -submenu, autofocus, multifamily, multiuser, pseudoscience, semiannual, -subtotal, autoiris, multimedia, nonprofit, reengineered, semicircle, -superuser, microarchitecture, multiposition, predefined, reevaluate, -subfolder, superscript, microorganism, multiprotocol, predrilled, -reinvent, submarine. - -.. note:: - Question whether the pre- prefix is needed at all and consider - leaving it off the word entirely if the meaning is the same. - -Exceptions ----------- - -One overriding exception to the prefix rule is when the prefix is -prepended to a proper and capitalized noun: - -* Non-European -* Mid-April (but: midweek) - -Another exception is when the second word of a compound is a numeral: - -* Pre-1914 - -Some prefixes, such as self-, half-, quasi-, and ex-, when meaning -"formerly", usually need a hyphen: - -* Self-control, half-truth, quasi-corporation, ex-governor - -Suffix hyphenation -================== - -In general, do not hyphenate suffixes. Here are some examples. -The suffix -wide is usually not hyphenated: - -* Nationwide, worldwide, systemwide, campuswide, statewide, - companywide, etc. - -The suffix -wise is usually not hyphenated: - -* Otherwise, businesswise, revenuewise, clockwise, counterclockwise - - -Quotation marks -*************** - -Follow these guidelines for quotation marks: - -* Restrict use of quotation marks to terms as terms. -* Do not use quotation marks for emphasis; use *italics* for emphasis. -* Avoid using single-quote marks. -* In terms of punctuation: commas and periods typically go inside the - end-quote; semicolons, colons, question marks, and exclamation points - typically go outside quotation marks. Unless they are part of the - actual quotation. \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/documentation/headings.rst b/source/clear-linux/reference/collaboration/documentation/headings.rst deleted file mode 100644 index 6f1d584d..00000000 --- a/source/clear-linux/reference/collaboration/documentation/headings.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _headings: - -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 |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 -accepted. The following example shows all accepted levels of headings: - -.. code-block:: rst - - Title - ##### - - Level 1 sections - **************** - - Level 2 sections - ================ - - Level 3 sections - ---------------- - -Headings must be written in sentence case. Learn more about the correct -capitalization in our :ref:`grammar guide`. diff --git a/source/clear-linux/reference/collaboration/documentation/hello.c b/source/clear-linux/reference/collaboration/documentation/hello.c deleted file mode 100644 index 079db353..00000000 --- a/source/clear-linux/reference/collaboration/documentation/hello.c +++ /dev/null @@ -1,188 +0,0 @@ -/** @file - @brief Hello World Demo - - A Hello World demo for the Nanokernel and the Microkernel. - */ - -/* - * Copyright (c) 2012-2014 Wind River Systems, Inc. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/** CONFIG_MICROKERNEL - The microkernel hello world demo has two tasks that use semaphores - and sleeps to take turns printing a greeting message at a - controlled rate.*/ - -/** #else || CONFIG_NANOKERNEL - * The nanokernel hello world demo has a task and a fiber that use - * semaphores and timers to take turns printing a greeting message at - * a controlled rate. - */ - -/** - * @def SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000) - * @brief Compute equivalence in ticks. - */ -/** - * @def SLEEPTIME - * @brief Specify delay between greetings (in ms). - */ - -#if defined(CONFIG_STDOUT_CONSOLE) -#include -#define PRINT printf -#else -#include -#define PRINT printk -#endif - -#ifdef CONFIG_MICROKERNEL - -#include - -#define SLEEPTIME 500 -#define SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000) - -/** - * @brief A loop saying hello. - * - * @details - * Actions: - * -# Ouputs "Hello World!". - * -# Waits, then lets another task run. - - @param taskname The task's identification string. - @param mySem The task's semaphore. - @param otherSem The other task's semaphore. - */ -void helloLoop(const char *taskname, ksem_t mySem, ksem_t otherSem) -{ - while (1) - { - task_sem_take (mySem, TICKS_UNLIMITED); - - PRINT ("%s: Hello World!\n", taskname); /* Action 1 */ - - task_sleep (SLEEPTICKS); /* Action 2 */ - task_sem_give (otherSem); - } -} - -/** - * @brief Exchanges Hello messages with taskB. - * - * @details - * Actions: - * -# taskA gives its own semaphore, thus it says hello right away. - * -# Calls function helloLoop, thus taskA exchanges hello messages with taskB. - */ -void taskA(void) -{ - task_sem_give (TASKASEM); /* Action 1 */ - - helloLoop (__FUNCTION__, TASKASEM, TASKBSEM); /* Action 2 */ -} - -/** - * @brief Exchanges Hello messages with taskA. - * - * Actions: - * -# Calls function helloLoop, thus taskB exchanges hello messages with taskA. - */ -void taskB(void) -{ - helloLoop (__FUNCTION__, TASKBSEM, TASKASEM); /* Action 1 */ -} - -#else - -#include -#include - -#define SLEEPTIME 500 -#define SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000) - -#define STACKSIZE 2000 - -/** Declares a stack for a fiber with a size of 2000.*/ -char fiberStack[STACKSIZE]; - -/** Declares a nanokernel semaphore for a task. */ -struct nano_sem nanoSemTask; - -/** Declares a nanokernel semaphore for a fiber.*/ -struct nano_sem nanoSemFiber; - -/** - * @brief Defines the turns taken by the tasks in the fiber. - * - * Actions: - * -# Initializes semaphore. - * -# Initializes timer. - * -# Waits for task, then runs. - * -# Outputs "Hello World!". - * -# Waits, then yields to another task. - */ -void fiberEntry(void) { - struct nano_timer timer; - uint32_t data[2] = { 0, 0 }; - - nano_sem_init(&nanoSemFiber); /* Action 1 */ - - nano_timer_init(&timer, data); /* Action 2 */ - - while (1) { - - nano_fiber_sem_take(&nanoSemFiber, TICKS_UNLIMITED); /* Action 3 */ - - PRINT("%s: Hello World!\n", __FUNCTION__); /* Action 4 */ - - nano_fiber_timer_start(&timer, SLEEPTICKS); /* Action 5 */ - nano_fiber_timer_test(&timer, TICKS_UNLIMITED); - nano_fiber_sem_give(&nanoSemTask); - } -} - -/** - * @brief Implements the Hello demo. - * - * Actions: - * -# Outputs "hello". - * -# Waits, then signals fiber's semaphore. - * -# Waits on fiber to yield. - */ -void main(void) { - struct nano_timer timer; - uint32_t data[2] = { 0, 0 }; - - task_fiber_start(&fiberStack[0], STACKSIZE, (nano_fiber_entry_t) fiberEntry, - 0, 0, 7, 0); - - nano_sem_init(&nanoSemTask); - nano_timer_init(&timer, data); - - while (1) { - - PRINT("%s: Hello World!\n", __FUNCTION__); /* Action 1 */ - - nano_task_timer_start(&timer, SLEEPTICKS); /* Action 2 */ - nano_task_timer_test(&timer, TICKS_UNLIMITED); - nano_task_sem_give(&nanoSemFiber); - - nano_task_sem_take(&nanoSemTask, TICKS_UNLIMITED); /* Action 3 */ - } -} - -#endif diff --git a/source/clear-linux/reference/collaboration/documentation/images.rst b/source/clear-linux/reference/collaboration/documentation/images.rst deleted file mode 100644 index c631f15d..00000000 --- a/source/clear-linux/reference/collaboration/documentation/images.rst +++ /dev/null @@ -1,88 +0,0 @@ -.. _images: - -Images -###### - -Images or figures grab the reader's attention and convey information that -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 |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. - -* Use only lower case letters for image filenames. - -* Separate multiple words in filenames using dashes. - -* Name figures with the filename of the file they appear on and add a number - to indicate their place in the file. For example: The third figure added to - the :file:`fibers.rst` file must be named :file:`fibers-3.png`. - -* Include a caption describing the figure's content and to use as a reference. - All figures must have a caption. - -* Use cross-references. Refer to your graphics in the main text flow. - Create a label using the filename of the image. Use the `:ref:` role to place - the cross reference, see :ref:`cross` for more details. - -* Place the figure immediately after its reference in the text flow or as - close as possible. - -* Keep figures simple. They should only contain the information the - reader needs. - -* Use figures judiciously. Don't use superfluous graphics and don't - use graphics as mere decorations. They must have purpose. You don't - need to show a screenshot of every single step or window in a software - installation procedure, for example. - -* Avoid volatility. Don't incorporate information into a graphic that - might change with each release, for example: product versions or - codename abbreviations. - -* Use only approved image formats. Use either PNG or JPEG bitmap files for - screenshots and SVG files for vector graphics. If a figure is not a - photograph or screenshot, use the vector graphic file format to ensure - the figure can be changed later. - - -Examples -******** - -These examples follow the guidelines and can be used as a reference. - -The fiber context is represented in the diagram either as a box -containing different objects or a :ref:`symbol `. - -.. _fibers-1.svg: - -.. figure:: figures/fibers-1.svg - :scale: 75 % - :alt: Fibers Execution Context Symbol - - The graphic representation of the fibers execution context. - - This symbol is used to illustrate the actions performed by the - abstract fibers execution context. - -Templates -********* - -Use this template to add a figure to your documentation according to -these guidelines. - -.. code-block:: rst - - .. _file-name-#.ext: - - .. figure:: figures/file-name-#.ext - :scale: 75% - :alt: Alternative text. - - Figure 1: Brief caption detailing the contents of the image. - - Any additional explanation, description or actions depicted in the - image. It can encompass multiple lines. diff --git a/source/clear-linux/reference/collaboration/documentation/inline.rst b/source/clear-linux/reference/collaboration/documentation/inline.rst deleted file mode 100644 index a4ccfe91..00000000 --- a/source/clear-linux/reference/collaboration/documentation/inline.rst +++ /dev/null @@ -1,162 +0,0 @@ -.. _inline: - -Inline Markup -************* - -Sphinx supports a large number of inline markup elements called roles. The -|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. - -The following markup is required in every instance unless otherwise -specified. Each item provides a syntax example followed by the rendered -result. - -Abbreviations - Use the `:abbr:` abbreviation role to define an acronym or an initialism. - Add the abbreviation markup only once per file. After the abbreviation, the - acronym can be used without further definition or markup. Do not use - abbreviation markup on headings. - - :: - - :abbr:`API (Application Program Interface)` - - .. parsed-literal:: - - :abbr:`API (Application Program Interface)` - -OS Commands - Use the `:command:` role when the name of a specific command is used in a - paragraph for emphasis. Use the ``.. code-block::`` directive for fully - actionable commands in a series of steps. - - :: - - :command:`make` - - .. parsed-literal:: - - :command:`make` - -Commandline Options - In most cases, use asterisks "*" to emphasize the name of a command - option. - - :: - - Use the *-p* option to print the file. - - .. parsed-literal:: - - Use the *-p* option to print the file. - - However, if you have defined an ``.. option::`` directive, you may - use the `:option:` role. Note that the result links back to the - option definition. - - .. code-block:: rest - - .. option: -o - - Description of the -o option - - The :command:`pandoc` command can be used without :option:`-o` - - .. option:: -o - - Description of the -o option - - .. parsed-literal:: - - The :command:`pandoc` command can be used without :option:`-o` - -Files - Use the `:file:` role to emphasize a filename or directory. Do not use the - role inside a code-block but use it inside all notices that contain files - or directories. Place variable parts of the path or filename in brackets - `{}`. - - .. code-block:: rest - - :file:`collaboration.rst` - - :file:`doc/{user}/collaboration/figures` - - .. parsed-literal:: - - :file:`collaboration.rst` - - :file:`doc/{user}/collaboration/figures` - -GUI Objects - Use the `:guilabel:` role to emphasize elements of a graphic - user interface within a description. It replaces the use of quotes - when referring to windows' names, button labels, options, or single - menu elements. Always follow the marked element with the appropriate - noun. For example: - - :: - - In the :guilabel:`Tools` menu, click :guilabel:`settings`. - - .. parsed-literal:: - - In the :guilabel:`Tools` menu, click :guilabel:`settings`. - -Menu Navigation - Use the `:menuselection:` role to indicate the navigation through a menu - ending with a selection. Every `:menuselection:` element can have up to two - menu steps before the selected item. If more than two steps are required, - it can be combined with a `:guilabel:` or with another `:menuselection:` - element. For example: - - :: - - Go to :guilabel:`File` and select :menuselection:`Import --> Data Base --> MySQL`. - - Go to :menuselection:`Window --> View` and select :menuselection:`Perspective --> Other --> C++` - - .. parsed-literal:: - - Go to :guilabel:`File` and select :menuselection:`Import --> Data Base --> MySQL`. - - Go to :menuselection:`Window --> View` and select :menuselection:`Perspective --> Other --> C++` - -Makefile Variables - Use the `:makevar:` role to emphasize the name of a Makefile variable. - The role can include only the name of the variable or the variable - plus its value. - - :: - - :makevar:`PLATFORM_CONFIG` - - :makevar:`PLATFORM_CONFIG=basic_atom` - - .. parsed-literal:: - - :makevar:`PLATFORM_CONFIG` - - :makevar:`PLATFORM_CONFIG=basic_atom` - -Environment Variables - Use the `:envvar:` role to emphasize the name of environment - variables. Just as with `:makevar:`, the markup can include only the - name of the variable or the variable plus its value. - - :: - - :envvar:`ZEPHYR_BASE` - - :envvar:`QEMU_BIN_PATH=/usr/local/bin` - - .. parsed-literal:: - - :envvar:`ZEPHYR_BASE` - - :envvar:`QEMU_BIN_PATH=/usr/local/bin` - -.. _Sphinx reStructuredText Markup: - http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/documentation/language.rst b/source/clear-linux/reference/collaboration/documentation/language.rst deleted file mode 100644 index ba2abe49..00000000 --- a/source/clear-linux/reference/collaboration/documentation/language.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _language: - -Language reference guide -######################## - -This section describes acceptable usage of the English language in the -|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, |CL-ATTR| uses Simple English. However, we have not implemented any -controlled language standards. - -.. toctree:: - :maxdepth: 2 - - simple - grammar - punctuation - - - - - diff --git a/source/clear-linux/reference/collaboration/documentation/lists.rst b/source/clear-linux/reference/collaboration/documentation/lists.rst deleted file mode 100644 index 6f43ec77..00000000 --- a/source/clear-linux/reference/collaboration/documentation/lists.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. _lists: - -Lists -##### - -We use two types of lists: numbered lists and bulleted lists. Use a -numbered, or ordered, list when the order or priority of the items is -important. Use a bulleted, or unordered, list when the order of the -items is not important. - -For both kinds of list, strive to keep all items in the list parallel. -See :ref:`parallelism`. Use a sentence style, making all the list items -sentences. - -Numbered Lists -************** -Numbered (ordered) lists are most frequently used for procedures. Use -numbered lists to show sequence for the items. Here are some guidelines -for numbered lists: - -* Make sure the list is sequential in nature and not simply a - collection of items. -* Introduce a numbered list with a sentence setup text. End the setup - fragment or sentence with a colon. Example: To configure the unit, do - the following: -* Each item in the list should be parallel. -* Without exception, treat numbered list items as full sentences and - end each list entry with a period, a colon, or a comma - when the entries - are complete sentences or a mixture of fragments and sentences. In - cases where the entries are short imperative sentences introducing - commands or code, end them with colons. -* You may interrupt numbered lists with other paragraph styles, if the - interruption is some explanatory text, commands, or code. -* Second-level steps are acceptable; avoid third-level steps. -* Avoid single-step procedures; the minimum number of steps in a - procedure is two. -* Do not create numbered lists that emulate flowcharts. The reader - should be able to execute the list of steps from first to last - without branching or looping. -* Avoid over-using numbered lists, except in procedural documents such as - tutorial and step-by-step guides. -* Use the `#` symbol for all list items. Use a three-space indentation for - second-level items and for the explanatory text, commands, or code. Example: - -#. Open the door. - -#. Enter the room. - - The room you enter may be dark. If it is not equipped with a motion - sensor that triggers a light, you might want to turn on a light to - avoid tripping over furniture. - -#. Make a call. - - #. Pick up the receiver. - - #. Dial a number. - - #. Talk to the other party or leave a message. - - #. Hang up. - -#. Turn off the light. - -#. Leave the room. - -Bulleted Lists -************** -Use bulleted, or unordered, lists to reduce wordiness and paragraph -density, particularly when a sequence is not required. Here are some -guidelines for bulleted lists: - -* Introduce a bulleted list with a sentence. End the setup text with a - colon. Example: To repair the unit, you will need the following: -* Each item in the list should complete the setup sentence staying - parallel. -* Avoid interrupting bulleted lists with other paragraph styles. -* Second-level bullets are acceptable; avoid third-level bullets. - -Use sentence style bullet lists. - -Sentence style bullet lists are punctuated like sentences because all -items in the list are sentences. End all bullets with a period or a -colon if the bullet introduces a second level list. For example: - -**Incorrect** - -When setting the user code remember: - -* make the user code easy to remember. Use a number that has a meaning - for you -* change the code once a month -* do not disclose the user code to anyone else. This includes the - security company - -**Correct** - -When setting the user code, it is important to remember a few things: - -* Use a number that has a meaning for you. -* Change the code once a month. -* Do not disclose the user code to anyone else. This includes the security - company. - -Fragment style bullet lists and presentation style bullet lists are not -acceptable for either in-code documentation or stand alone -documentation. They can only be used for presentations. - -Presentation style bullets have little or no punctuation. They are -typically short phrases or even single words. They often start with a -capital and end with no punctuation, unless they are full sentences. -Use only for presentations. diff --git a/source/clear-linux/reference/collaboration/documentation/notices.rst b/source/clear-linux/reference/collaboration/documentation/notices.rst deleted file mode 100644 index e58cbb83..00000000 --- a/source/clear-linux/reference/collaboration/documentation/notices.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _notices: - -Notices: notes, cautions, warnings, and dangers -############################################### - -We use four special types of notices: notes, cautions, warnings, and -dangers. Here are some specific rules and tips with regard to these -notices: - -* Do not use a notice directly after a heading. Notices must follow a - variant of body text. -* Avoid back-to-back notices. -* To improve readability, rewrite content to eliminate multiple - notices in a single module. -* If there is no clean way to avoid using back-to-back notices, use a - different style or multiple paragraphs, for example, combine two - notes into one or separate them with body text. - -Notes -***** - -Use notes sparingly. Avoid having more than one note per subsection. If -you exceed this number consistently, consider rewriting the notes as -main body text. Example: - -.. note:: - A note is supposed to provide supplemental information, not - emphasized information. - - - -Cautions, Warnings, and Dangers -******************************* - -Tell readers what will happen if they do not heed cautions or warnings, -circuits will fry, electrical shock may kill you, etc. - -* Use "Caution" to identify hazards resulting in property damage - accidents, including data loss. Also use "Caution" to alert against - unsafe practices. -* Use "Warning" and "Danger" for property damage accidents only if - personal injury risk appropriate to these levels is also involved. - -These are examples of typical notices, the correct syntax and the -conditions for their usage: - -.. note:: - Notes are ancillary bits of information, subordinate to the main - flow. Reserve the note tag for information that does not readily - flow with the main text but which you want to set apart for one - reason or another. Notes should be relatively short. If there is - more than enough information to warrant a short paragraph, - consider rewriting the note as body text. - -.. caution:: - Cautions are low-level hazard messages that alert the user of - possible equipment, product, and software damage, including loss - of data. Cautions typically appear as a yellow triangle with a - black exclamation point. - -.. warning:: - Warnings are mid-level hazards (more serious than cautions) that - are likely to cause product damage as well as bodily injury to - humans. Warnings may appear in a black triangle with orange hazard- - specific graphics for warnings (or with the colors reversed). The - most common warning is for electrical hazards, but there are many - other hazard-specific graphics. - -.. danger:: - Dangers are high-level hazards that are likely to cause product - damage as well as bodily injury and even death to humans. Dangers - use a red triangle with white (and black) hazard-specific - graphics, the same as found on warnings. \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/documentation/parallelism.rst b/source/clear-linux/reference/collaboration/documentation/parallelism.rst deleted file mode 100644 index 611cd5e4..00000000 --- a/source/clear-linux/reference/collaboration/documentation/parallelism.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _parallelism: - -Parallelism -########### - -Parallelism refers to the practice of using similar patterns of grammar, and -sometimes length, to coordinate words, phrases, and clauses. - -Parallel construction is especially important in bulleted lists. The table -shows some unparallel structures and how they can be made parallel with a -little rewording. - -+----------------------------------+----------------------------------+ -| Parallel (do) | Unparallel (don't) | -+==================================+==================================+ -| 1. Mount the panel. | 1. Mount the panel. | -| 2. Install the battery. | 2. Battery installation. | -| 3. Wire the keypad. | 3. Wiring the keypad. | -+----------------------------------+----------------------------------+ -| The system sends a message to | The system sent a message to the | -| the call center, which calls the | call center, which calls the | -| customer and tells about the | customer and will tell about the | -| burglary. | burglary. | -+----------------------------------+----------------------------------+ -| The system tried to send alarm | The system tried to send alarm | -| messages that were precise and | messages that had precision and | -| accurate. | were accurate. | -+----------------------------------+----------------------------------+ -| You need to install the panel, | You need to install the panel, | -| wire the sensors, and test the | wire the sensors, and you | -| phone line. | must test the phone line. | -+----------------------------------+----------------------------------+ diff --git a/source/clear-linux/reference/collaboration/documentation/punctuation.rst b/source/clear-linux/reference/collaboration/documentation/punctuation.rst deleted file mode 100644 index f019b1c3..00000000 --- a/source/clear-linux/reference/collaboration/documentation/punctuation.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. _punctuation: - -Punctuation guide -################# - -This section contains all the information regarding the correct use of -punctuation for the |CL-ATTR| documentation. - -Commas, Semicolons, and Colons -****************************** -Here are the most common problems encountered with commas, semicolons, -and colons. Please refer to Merriam-Webster's Collegiate Dictionary -when in doubt. - -Serial Commas -============= - -When writing a series of items, use the serial comma before the -coordinating conjunctions *and* and *or* to avoid confusion and ambiguity. -For example: - -* Mom, Dad, and I are going to the game. -* Mom, Dad and I are going to the game. - -The first example uses the serial comma. It is clear in this sentence -that three people are going to the game. The second example does NOT -have a comma preceding the and. The reader may interpret this as -meaning the same thing as the first sentence, namely that three people -are going to the game, or that the speaker is addressing "Mom" and -telling her that only two people are going to the game. - -Commas in Numbers -================= - -Use commas to divide large numbers into sets of three digits. Use -periods for decimal points. Do not divide decimal digits into sets of -three. - -Do not use a comma to separate four-digit bit/byte numbers. - -Do not use a comma to separate four-digit page numbers. - -Do not use a comma or other punctuation to separate decimals. - - -Semicolons ";" -============== - -Here are some rules governing the use of semicolons: - -* Use semicolons in long, sentence-style bulleted phrase lists. - -* Use semicolons when two equal clauses are joined because of - similarity of construction or meaning. - -* Use semicolons in a series of items when at least one of the items - itself includes a comma. - -Examples of semicolon usage: - -Similar construction: The prewidget comes before the widget; the -postwidget comes after it. - -Comma-inclusive series: We traveled through Casper, Wyoming; Boise, -Idaho; and Eugene, Oregon. - -Colons ":" -========== - -If the text following a colon is a sentence, capitalize the -first word after the colon. If the subsequent text is not a sentence, -do not capitalize the first term unless it is a title. For example: - -* This is a capitalization example: Donuts do not cause holes. - -* These is a noncapitalization example: colons, semicolons, and commas. - -* In a title, use title case following the colon. Example: Tires: How - to Fix a Flat. - -* Use a colon at the end of a sentence or phrase that introduces - examples, a list, a path, user input, or code. - -* Don't use a colon to introduce graphics, tables, or sections. - -* Don't use a colon at the end of a task title or any heading. diff --git a/source/clear-linux/reference/collaboration/documentation/rest.rst b/source/clear-linux/reference/collaboration/documentation/rest.rst deleted file mode 100644 index a64f6a78..00000000 --- a/source/clear-linux/reference/collaboration/documentation/rest.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _rest: - -RestructuredText guide -###################### - -.. incl-restructured-text-overview: - -Overview -******** - -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 -as much markup as possible. - -.. _Sphinx documentation: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html - -Remember: **Changing incorrect markup is easier than adding markup from -scratch.** - -We provide templates, examples, and use scenarios to help you write and edit -documents easily. Use only the templates provided to ensure your content is -consistent with the rest of the documentation. - -Contributions with incorrect use of markup will not be merged until the -markup is fixed. If you have any questions regarding markup, send an email to -our mailing list at dev@lists.clearlinux.org and we will gladly help. - -To allow for easy copy and paste of the provided templates, -they are provided using either the "\`\`" parenthesis, for single line -templates, or the code-block directive, for multi-lined templates. - -Every use case is explained, examples provided and, lastly, -templates supplied. - -.. incl-restructured-text-overview-end: - -.. toctree:: - :maxdepth: 3 - - headings - inline - tables - cross - images - code - contents - diff --git a/source/clear-linux/reference/collaboration/documentation/simple.rst b/source/clear-linux/reference/collaboration/documentation/simple.rst deleted file mode 100644 index b8ea9773..00000000 --- a/source/clear-linux/reference/collaboration/documentation/simple.rst +++ /dev/null @@ -1,305 +0,0 @@ -.. _simple: - -Simple English -############## - -Simple English is a generic term for communication that emphasizes -clarity, brevity, and avoiding unnecessarily complicated or -technical terms. It encourages writers to create content that is clear -and appropriate to the audience's reading skills and knowledge. - -Simple English improves the clarity of procedural technical writing, -makes translation easier, and improves comprehension for people whose -first language is not English. - -|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. - -Short sentences and paragraphs -****************************** - -Clear writing should average 15 to 20 words per sentence. This does not -mean every sentence should be the same length. Vary your writing by -mixing short sentences with longer ones, but stick to the basic -principle of one main idea in a sentence, plus one additional point if -needed. - -Similarly, restrict your paragraph length to about six sentences. -Remember the basic structure of a paragraph: Introduction, body, and -conclusion. Both the introduction and the conclusion should be one -sentence long. The body of a paragraph should never exceed four -sentences. Here less is more. - -Simple words -************ - -Choosing simple words increases reader comprehension and reduces -ambiguity. Here are some guidelines on making good simple word choices: - -* Avoid jargon. Jargon is a type of language that is only understood - by a particular group of people, such as an industry or a club. You - can use jargon when writing for an audience who will understand, but - avoid over using it, especially on the general public. -* Be consistent. Use one term for each concept or action and use it - consistently. Don't use a different term for the same object or - action when you refer to it subsequently. -* Keep your style plain but avoid dullness. Avoid clichés, idioms, and - metaphors. Many of these devices are not easily understood across - different cultures and can lead to confusion. -* Avoid "fancy" words and phrases. The goal is to get the information - across, not to impress the reader with your vocabulary, so avoid - bureaucratic, flowery or literary style. Here are some examples of - "formal" words to avoid and preferred "informal" alternatives in - parentheses: - -* commence (start, begin) -* consequently (so) -* in excess of (more than) -* in the event of (if) -* prior to (before) -* should you wish (if you want) -* utilize (use) -* instance (example) - -Strong verbs -************ -The stronger and clearer you can make your verbs, the more directly you -communicate information to your audience. - -Keep these basic guidelines in mind as you check your verbs: - -* Use imperatives. -* Use active voice not passive voice. -* Avoid linking verbs; is, seems, becomes. -* Convert weak verbs and nominalizations to strong verbs. -* Be concise. -* Avoid "there are" and "it is" constructions. - -.. note:: - The examples in the following sections offer two versions of the same - information. The incorrect version always comes first and is formatted *in - italics*. The correct version always comes second and is formatted **in - bold**. - -Imperatives -=========== - -Commands, officially called imperatives, are the fastest and most direct -way of giving someone instructions. Imperatives are an extension of the -second-person pronoun you. The word you is implied. - -Be concise. - -Example: - -*I would appreciate it if you would send it to me.* - -**Send it to me.** - - -Present Tense vs. Future Tense -============================== - -Use simple present tense instead of future tense for most text. Future -tense is acceptable for conditional statements, for example in a -caution or a warning. - -*The system will operate at a nominal temperature of 180 degrees Fahrenheit.* - -**The system operates at a nominal temperature of 180 degrees Fahrenheit.** - -Action Verbs vs. Nominalizations -================================ - -Avoid nominalizations, which are nouns formed from verbs. For example: - -===================== ===================== -Verbs Nominalizations -===================== ===================== -complete completion -introduce introduction -provide provision -fail failure -arrange arrangement -install installation -===================== ===================== - -The problem with nominalizations is that they are often used instead of -the verbs they come from. Because they are merely the names of things, -they sound as if nothing is actually happening in the sentence. Like -passive verbs, too many of them make writing very dull and heavy-going. - -Here are some examples. - -*We had a discussion about the matter.* - -**We discussed the matter.** - -*The blizzard will cause a stoppage of the trains.* - -**The blizzard will stop the trains.** - -*IT has completed the installation of the software.* - -**IT has installed the software.** - -Infinitives vs. Participles -=========================== - -* Avoid present participial forms and gerunds, words ending in -ing, - unless they are part of a technical name. -* Use infinitives instead of participials in this type of - construction. For example: - -*There is no way of verifying this.* - -**There is no way to verify this.** - - -Active Voice vs. Passive Voice -============================== -Use active voice whenever possible to show clearly who or what is -performing an action. - -* Active voice follows standard English word order: - SUBJECT–VERB–OBJECT (optional). Modifiers come before or immediately - following the terms they modify. -* Passive voice reverses the order and weakens the verb: OBJECT–be - VERB–by SUBJECT (optional). -* Writing sentences in the passive voice, we often have to use the - verb to be and sometimes the preposition "by". - -Examples: - - -*A mistake was made.* (By whom?) - -**I made a mistake.** - -*The sheriff was shot by me.* - -**I shot the sheriff.** - -*Version 2.0 was released in June.* - -**We released version 2.0 in June.** - -.. note:: - Sometimes it is okay to use passive voice. For example, you may - use passive voice to avoid gender-specific pronouns, to avoid - blaming someone, or to address situations where the subject, who - did the action, is unknown or irrelevant. - -Noun phrases -************ -Avoid long strings of nouns. Even native English speakers might have -difficulty determining which term modifies one or another in long -strings. - -Similarly, avoid long noun phrases with multiple adjectives. Try to -limit the number of modifiers in any noun phrase to two terms maximum. - -Often the best way to split up these long noun strings is to separate -them into digestible prepositional phrases. This tends to lengthen them -but makes them much easier to understand. - -Examples of some long noun phrases and possible rewording: - -*Power management mechanism integration policies* - -**Integration policies for power management mechanisms** - -*Signal integrity test deck requirements* - -**Requirements for test desks that measure signal integrity** - -*Building radon source location method* - -**Method for locating the source of radon in buildings** - -*Employee compensation level evaluation procedures* - -**Procedures for evaluating an employee's compensation level** - -Pronouns -******** - -First Person -============ - -We recommend using we or |CL|, if you want to sound more formal, to provide -an agent, someone who does the action in a sentence, and avoid passive -constructions such as "It is recommended...." For example: - - -*5 MB is recommended.* - -**We recommend 5 MB.** - -*It is recommend that you set the value as low as possible.* - -**We recommend setting the value as low as possible.** - -*This setting has not been validated.* - -**Intel has not validated this setting.** - -Second Person -============= - -Write directly to the reader and use the second-person pronoun "you" -rather than "the user". For example: - -*If the widget is to be compressed....* - -**If you want to compress the widget...** - -*If reduced costs are wanted...* - -*If the user wants to reduce costs...* - -**If you want to reduce costs...** - - -Third Person -============ - -Third person pronouns tend to create subject-verb agreement errors -because writers often introduce a gender-neutral third person plural -they. Rewrite these sentences using a third person plural antecedent. -Avoid third person singular pronouns, especially the gender-specific -pronouns he and she, and, if necessary, rewrite these sentences using -plurals to avoid a gender-specific references in gender-indeterminate -situations. - -The preferred hierarchy of third-person pronoun usage is: - -*Wrong* - -*If a user needs to update their account...* - -Do not use the third person plural for a singular subject. - -*Avoid* - -*If a user forgets her password...* - -Do not force the feminine pronoun set (she) unless there is a specific, -approved feminine antecedent or there is some other very strong, -circumstantial reason to do so. - -Acceptable - -If a user needs to update his account... - -In traditional English usage, it is acceptable to use the masculine -pronoun set (he) when the gender is neutral or indeterminate. -This is often the rule in romance languages and other languages. - -**Preferred** - -**If users need to update their accounts...** - -Often the best solution is to use the plural form to avoid pronoun -problems. diff --git a/source/clear-linux/reference/collaboration/documentation/steps.rst b/source/clear-linux/reference/collaboration/documentation/steps.rst deleted file mode 100644 index 9301e570..00000000 --- a/source/clear-linux/reference/collaboration/documentation/steps.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _steps: - -Step-by-step instructions -######################### - -* Provide a sequence of numbered steps, see :ref:`lists`. Do not provide a - paragraph of sentences. - -* Describe one action per step. - -* If the user needs to do the same thing for several procedures, refer to - earlier steps rather than repeating them. - -* When steps and diagrams flow down a page side-by-side, put text on the left - and diagrams on the right. - -* When steps include commands or code blocks, put the commands or code blocks - after the step that includes them. - -* If directions can appear in only one place, either text or figure, put them - in the text; don't hide directions in diagrams. - -* When a series of steps is supported by one figure, refer to the figure in - the introductory text: "See Figure 15 and do the following:" - -* When a series of steps is supported by two or more figures, avoid referring - to a range of figures. Rather, refer to a specific figure in the relevant - step and show the figure immediately after the reference. **Do not write**: - "See figures 15 through 22 and do the following:" \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/documentation/structures.rst b/source/clear-linux/reference/collaboration/documentation/structures.rst deleted file mode 100644 index 04cf1bc7..00000000 --- a/source/clear-linux/reference/collaboration/documentation/structures.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _structures: - -Consistent content structures guide -################################### - -This section guides you through the different content structures used in the -|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. - -.. toctree:: - :maxdepth: 2 - - lists - steps - notices - parallelism diff --git a/source/clear-linux/reference/collaboration/documentation/tables.rst b/source/clear-linux/reference/collaboration/documentation/tables.rst deleted file mode 100644 index 814de470..00000000 --- a/source/clear-linux/reference/collaboration/documentation/tables.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. _tables: - -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 |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: - -* Use tables sparingly. - -* Stick to the 72-78 characters line length limit. - -* Indent the contents correctly. This allows the content to be read even if - it is not rendered. - -* Only create a table if the body of the table contains six or more cells, - which is a minimum table size of at least 2x3 or 3x2. - -ReST supports several types of tables. |CL| uses grid and -:abbr:`CSV-tables (Comma Separated Values tables)`. Grid tables are only -suited for very short content since they must be fully drawn. CSV-tables -support multi-lined cells, are easy to update and allow more layout -options. - -Use grid tables for small tables where the layout needs to be determined -manually. For example: - -+-----------------+------------------------+--------------+------------+ -| Name | Purpose | Known | References | -| (or brand name) | | Applications | | -+=================+========================+==============+============+ -| Super Glue | Glues things together | Small car | Quick Fix, | -| | with extra strength. | repairs. | 2010. | -+-----------------+------------------------+--------------+------------+ -| Masking Tape | Stops paint from | Painting | Master | -| | covering a surface | walls. | Painter, | -| | allowing for sharp | | 2007. | -| | edges. | | | -+-----------------+------------------------+--------------+------------+ - -Use '=' between the table heading and the rows to define the table header. Do -not add emphasis to the contents of the table header using \*\*. - - -This template can help you create grid tables: - -.. code-block:: rst - - +------------------------+------------+----------+----------+ - | Header row, column 1 | Header 2 | Header 3 | Header 4 | - | (header rows optional) | | | | - +========================+============+==========+==========+ - | body row 1, column 1 | column 2 | column 3 | column 4 | - +------------------------+------------+----------+----------+ - | body row 2 | ... | ... | | - +------------------------+------------+----------+----------+ - -CSV-tables are more flexible than grid tables. They can be updated easily and -support several layout options. For example: - -.. csv-table:: Frozen Delights! - :header: "Treat", "Quantity", "Description" - :widths: 15, 10, 30 - - "Albatross", 2.99, "On a stick!" - "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be - crunchy, now would it?" - "Gannet Ripple", 1.99, "On a stick!" - -Some of the options available with CSV-tables are table titles, an optional -header row separate from the rest of the table, and customizable column width. -See the Sphinx `CSV-tables documentation`_ to learn all the possible options -available. - -This template can help you create CSV-tables: - -.. code-block:: rst - - .. csv-table:: Table title (optional) - :header: The header, values, for each column - :widths: 15, 10, 30 - - If the values, in the, "table go beyond the line length, use quotes to - keep the content together." - Numbers like, 10, are never surrounded by quotes. - Text can, "be", in quotes but it is only needed for longer lines. - -The template renders as: - -.. csv-table:: Table title (optional) - :header: The header, values, for each column - :widths: 15, 10, 30 - - If the values, in the, "table go beyond the line length, use quotes to keep - the content together." - Numbers like, 10, are never surrounded by quotes. - Text can, "be", in quotes but it is only needed for longer lines. - - - -.. _CSV-tables documentation: - http://docutils.sourceforge.net/docs/ref/rst/directives.html#csv-table \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/structure-formatting.rst b/source/clear-linux/reference/collaboration/structure-formatting.rst new file mode 100644 index 00000000..6391dccb --- /dev/null +++ b/source/clear-linux/reference/collaboration/structure-formatting.rst @@ -0,0 +1,482 @@ +.. _structure-formatting: + +Structure and formatting +######################## + +Content should be organized to support scanning. Consistent organization, +formatting, and writing style helps readers quickly find what they need and to +understand the content more effectively. This document describes our +organization and formatting guidelines. + +Refer to :ref:`writing-guide` to learn how we keep our documents clear and +concise. + +.. contents:: :local: + :depth: 1 + +Markup +****** + +Our documentation is written in the reStructuredText markup language, using +Sphinx roles and directives. We use Sphinx to generate the final documentation. +You can read more about reStructuredText and Sphinx on their respective +websites: + +* `Sphinx documentation`_ +* `reStructuredText Primer`_ + +You can view the content directly in the .rst markup files, or generate the HTML +content by installing and building the documentation locally. To run the +documentation locally, follow the instructions found in the +`documentation repository`_ README. + +New pages +========= + +There are a few additional steps to consider when adding a new page to the +documentation. First, identify where your new page should be located within the +existing `Documentation organization`_. Second, make sure the new page is picked +up in the Sphinx build and easily linkable from other content. + +Each page must be included in a `Sphinx toctree`_ in order to be included in the +documentation content tree. Typically, pages are added to the section landing +page toctree. + +For example, the :ref:`collaboration` page toctree looks like: + +.. code-block:: rest + + .. toctree:: + :maxdepth: 1 + + writing-guide + structure-formatting + +Additionally, each page must include a uniquely named reST label directly before +the page title, to enable the `Sphinx ref role`_ for linking to a page. + +For example, this page "Structure and formating" has the label +``.. _structure-formatting``: + +.. code-block:: rest + + .. _structure-formatting: + + Structure and formatting + ######################## + +This page can then be referenced from other pages in the documentation using the +`:ref:` role: + +.. code-block:: rest + + :ref:`structure-formatting` + +Documentation organization +************************** + +The documentation is organized into five general sections: + +#. **Concepts**: Introduction and overview of |CL| specific concepts or + features. +#. **Get started**: Information about getting started with |CL|. +#. **Guides**: Detailed information and instruction on using |CL| features. +#. **Tutorials**: Step-by-step instruction for using |CL| in specific use cases. +#. **Reference**: Supplementary and reference information for |CL|. + +Page structure +============== + +Each page in the documentation should follow the basic format of: + +* Overview: 1-2 sentences describing what this page shows and why it matters +* Prerequisites: Describe any pre-work necessary to the content (if appropriate) +* Content +* Next steps: List links to next steps (if appropriate) +* Related topics: List links to related content (if appropriate) + +Headings +======== + +Use headings to section and organize your content for better readability and +clarity. + +* All files must have a top level heading, which is the title for the page. +* Up to three additional levels of headings are allowed under the title heading. +* Each heading should be followed by at least one paragraph of content. Avoid + two or more consecutive headings. + +Refer to the :ref:`writing-guide` for tips on using headings to create +:ref:`scannable content `. + +To mark up headings in the .rst file: + +* Use hash-tags to underline the file's main title: + + .. code-block:: rest + + Main title + ########## + +* Use asterisks to underline the file's first level headings: + + .. code-block:: rest + + First level heading + ******************* + +* Use equal signs to underline the file's second level of headings: + + .. code-block:: rest + + Second level heading + ==================== + +* Use dashes to underline the file's third level of headings: + + .. code-block:: rest + + Third level heading + ------------------- + +In-page navigation +================== + +If a page has three or more sections, provide quick links to each section. Place +the quick links after the overview section. + +Use the standard `reST contents directive`_ with depth: 1 for quick links. + +Inline text formatting +********************** + +We use the `Microsoft Writing Style Guide`_ as our starting point for text +formatting. We apply the formatting using reST and Sphinx markup. + +Use our quick reference for the most commonly used inline text elements: + ++--------------------------------+---------------------------------------+-----------------------------+ +| **Element** | **Convention** | **reST/Sphinx** | ++--------------------------------+---------------------------------------+-----------------------------+ +| Acronyms | Define acronym when first used. After | Use the ``:abbr:`` role, in | +| | first use and definition, use the | the following format: | +| | acronym only. | | +| | | ``:abbr:`Acronym (Def)``` | ++--------------------------------+---------------------------------------+-----------------------------+ +| Bundle names | Bold | Use the ``:command:`` role. | ++--------------------------------+---------------------------------------+-----------------------------+ +| Callouts | | Use ``.. note::`` | ++--------------------------------+---------------------------------------+-----------------------------+ +| Code/command examples | Monospace, visually distinct | Use ``.. code-block::`` | +| | from rest of text. Use an | with the correct language | +| | indented call-out box. | setting. | ++--------------------------------+---------------------------------------+-----------------------------+ +| Commands | Bold | Use the ``:command:`` role. | ++--------------------------------+---------------------------------------+-----------------------------+ +| Command flags | Bold | Use the ``:command:`` role. | ++--------------------------------+---------------------------------------+-----------------------------+ +| Console output | Monospace, visual distinction | Use ``.. code-block::`` | +| | from rest of text. Use an | with console as the | +| | indented call-out box. | language setting. | ++--------------------------------+---------------------------------------+-----------------------------+ +| Emphasis | Italic | ``*strong*`` | ++--------------------------------+---------------------------------------+-----------------------------+ +| Environment variables | Use the case format of the | Use ``:envvar:`` | +| | environment variable. | | ++--------------------------------+---------------------------------------+-----------------------------+ +| Example commands with | Use angle brackets for swapping | | +| optional or replaceable | in the specific name, | | +| parts | e.g. . | | +| | | | +| | Use square brackets for optional | | +| | parts, | | +| | e.g. [--build]. | | ++--------------------------------+---------------------------------------+-----------------------------+ +| Example URLs (not linked) | Plain text | | ++--------------------------------+---------------------------------------+-----------------------------+ +| File extensions | Lowercase | | ++--------------------------------+---------------------------------------+-----------------------------+ +| File names, directories, paths | Title style capitalization | Use the ``:file:`` role. | ++--------------------------------+---------------------------------------+-----------------------------+ +| GUI labels | | Use ``:guilabel:`` | ++--------------------------------+---------------------------------------+-----------------------------+ +| Inline comments | | Use ``..`` | ++--------------------------------+---------------------------------------+-----------------------------+ +| Keystrokes | | Use ``:kbd:`` | ++--------------------------------+---------------------------------------+-----------------------------+ +| Local navigation | | ``.. contents:: :local:`` | +| | | with a depth of 1 | ++--------------------------------+---------------------------------------+-----------------------------+ +| Menu selection | | Use ``:menuselection:`` | ++--------------------------------+---------------------------------------+-----------------------------+ +| New terms | Italic for first use, normal for all | ``*term*`` | +| | subsequent uses. | | +| | | | +| | If it is used outside of the source | | +| | of definition, link the term. | | ++--------------------------------+---------------------------------------+-----------------------------+ +| Product name | Follow correct trademark and | | +| | attribution guidelines. | | ++--------------------------------+---------------------------------------+-----------------------------+ +| Tool names | Correctly capitalized, no quotes, | | +| | bold, or italics as the basic rule. | | +| | | | +| | If the tool name is the command, like | | +| | most Linux tools, treat it like a | | +| | command. | | +| | | | +| | If the tool name is lowercase and | | +| | used at the start of a sentence, use | | +| | bold. | | ++--------------------------------+---------------------------------------+-----------------------------+ + +White space and line length +=========================== + +Limit line length to 78 characters. The GitHub web interface forces this +limitation for readability. + +Remove trailing whitespace from your documents. + +Code blocks and examples +************************ + +When providing example code or commands use the `Sphinx code-block directive`_. +Select the appropriate syntax highlighting for the example command or code. + +For example, if showing console output, use console highlighting: + +.. code-block:: rest + + .. code-block:: console + +Sphinx provides other ways of `marking up example code`_ if needed. + +Lists and instructions +********************** + +Use a numbered list when the order or priority of the items is important, such +as step-by-step instructions. + +Use a bulleted list when the order of the items is not important. + +For both list types, keep all items in the list parallel. See +:ref:`parallelism`. + +Use standard `reST list markup`_. + +Numbered lists +============== + +Numbered lists are most frequently used for procedures. Use numbered lists to +show sequence for the items. Follow our guidelines for numbered lists: + +* Make sure the list is sequential and not just a collection of items. +* Introduce a numbered list with a sentence. End the setup text with a + colon. Example: "To configure the unit, perform the following steps:" +* Each item in the list should be parallel. +* Treat numbered list items as full sentences with correct ending + punctuation. +* You may interrupt numbered lists with other content, if relevant, + e.g. explanatory text, commands, or code. +* Second-level steps are acceptable; avoid third-level steps. +* Avoid single-step procedures; the minimum number of steps in a procedure + is two. +* Do not create numbered lists that emulate flowcharts. The reader should be + able to execute the list of steps from first to last without branching or + looping. +* Avoid over-using numbered lists, except in procedural documents such as + tutorials and step-by-step guides. + +Bulleted lists +============== + +Use bulleted lists to reduce wordiness and paragraph density, especially when +a sequence is not required. Here are some guidelines for bulleted lists: + +* Introduce a bulleted list with a sentence. End the setup text with a + colon. Example: "To repair the unit, you will need the following items:" +* Each item in the list should be parallel. +* Avoid interrupting bulleted lists with other paragraph styles. +* Second-level bullets are acceptable; avoid third-level bullets. + +Use the correct ending punctuation for sentence style bullet lists. For example: + +**Use this:** + +:: + + When setting the user code, remember: + + * Use a number that has a meaning for you. + * Change the code once a month. + * Do not disclose the user code to anyone, including the security company. + +**Not this:** + +:: + + When setting the user code remember: + + * make the user code easy to remember. Use a number that has a meaning for you + * change the code once a month + * do not disclose the user code to anyone else. This includes the security + company + +Instructions +============ + +When presenting instructions, such as in a tutorial, present them in a numbered +list according to these guidelines: + +* Each step (list item) should describe one action. + +* If the same steps are repeated, refer to the earlier steps rather than + repeating them. + +* When a step includes a command or code block as an example, put the command + or code block after the step that includes them. + +* Use supporting images where appropriate. If the series of steps is supported + by one figure, refer to the figure in the introductory text. + + For example: "See Figure 15 and do the following:" + + When a series of steps is supported by two or more figures, refer to the + specific figure in the relevant step and show the figure immediately after + the reference. **Do not write**: "See figures 15 through 22 and do the + following:" + +Notices +******* + +We use four special types of notices: notes, cautions, warnings, and dangers. +Here are some specific rules and tips regarding use of these notices: + +* Do not use a notice directly after a heading. Notices must follow a variant of + body text. +* Do not include more than one notice in a single notice block. +* Avoid back-to-back notices. +* If back-to-back notices are not avoidable, make sure each distinct notice in + the notice block is clearly defined. + +Use the standard `reST admonition directive`_. + +Notes, cautions, and warnings +============================= + +Use notes sparingly. Avoid having more than one note per section. If you exceed +this number consistently, consider rewriting the notes as main body text. + +Use cautions and warnings to alert readers of potential problems or pitfalls. +Use conditional phrases in cautions and warnings, such as "If you do X, then Y +will occur." + +These are examples of typical notices and the conditions for their usage: + +.. note:: + Notes are extra bits of information that supplement the main content. Notes + should be relatively short. + +.. caution:: + Cautions are low-level hazard messages that alert the user of possible + equipment, product, and software damage, including loss of data. + +.. warning:: + Warnings are mid-level hazards that are likely to cause product damage. + +Links +***** + +Use the standard `reST markup for links`_. + +To add a cross-reference to another documentation page, use the `:ref:` role: + +.. code-block:: rest + + :ref:`structure-formatting` + +To add an external link, we use named references that refer to a defined +link/label at the bottom of the page. + +For example, an external link is defined at the bottom of the page like this: + +.. code-block:: rest + + .. _wiki about dogs: https://en.wikipedia.org/wiki/Dog + +The defined link is then used in the content like this: + +.. code-block:: rest + + Check out the great `wiki about dogs`_. + +Images +****** + +Use images or figures to convey information that may be difficult to explain +using words alone. Well-planned graphics reduce the amount of text required to +explain a topic or example. + +Follow these guidelines when using graphics in support of your documentation: + +* Keep it simple. Use images that serve a specific purpose in your document, + and contain only the information the reader needs. + +* Avoid graphics that will need frequent updating. Don't include information in + a graphic that might change with each release, such as product versions. + +* Use either PNG or JPEG bitmap files for screenshots and SVG files for vector + graphics. + +* Place the image immediately after the text it helps clarify, or as close as + possible. + +* Use the `Sphinx figure directive`_ to insert images and figures into the + document. Include both alt text, a figure name, and caption. + + For example: + + .. code-block:: rest + + .. figure:: figures/topic-1.png + :alt: An image supporting the topic. + + Figure 1: This is the figure 1 caption. + +* Include at least one direct reference to an image from the main text, using + the figure number. For example: + + **Use this:** :: + + Figure 1 + + **Not this:** :: + + The figure above or below + +Images should follow these naming and location conventions: + +* Save the image files in a :file:`figures` folder at the same level as the file + that will reference the image. +* Name image files according to the following rules: + + * Use only lower case letters. + * Separate multiple words in filenames using dashes. + * Name images using the filename of the file they appear on and add a number + to indicate their place in the file. For example, the third figure added to + the :file:`welcome.rst` file must be named :file:`welcome-3.png`. + +.. _Sphinx documentation: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html +.. _reStructuredText Primer: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +.. _documentation repository: https://github.com/clearlinux/clear-linux-documentation +.. _Sphinx toctree: https://www.sphinx-doc.org/en/master/usage/quickstart.html?highlight=toctree#defining-document-structure +.. _Sphinx ref role: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref +.. _reST contents directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents +.. _Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/ +.. _Sphinx code-block directive: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block +.. _marking up example code: http://www.sphinx-doc.org/en/1.6/markup/code.html +.. _reST list markup: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks +.. _reST admonition directive: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives +.. _reST markup for links: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks +.. _Sphinx figure directive: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives diff --git a/source/clear-linux/reference/collaboration/writing-guide.rst b/source/clear-linux/reference/collaboration/writing-guide.rst new file mode 100644 index 00000000..f69a0344 --- /dev/null +++ b/source/clear-linux/reference/collaboration/writing-guide.rst @@ -0,0 +1,410 @@ +.. _writing-guide: + +Writing guide +############# + +We want our documentation to be easy to read and understand. This document +describes guidelines for writing documentation that is clear, concise, +confident, and courteous. + +Refer to :ref:`structure-formatting` for details on organizing content and how +we use reStructuredText and Sphinx. + +.. contents:: :local: + :depth: 1 + +Use simple English +****************** + +Write using simple English: Be brief and communicate only the information that +is needed. Be friendly and informative. Emphasize clarity and avoid +unecessary complicated or technical terms. Make the content accessible to +non-native speakers. + +Be brief +======== + +Use short sentences and paragraphs. Stick to the principle of one main +idea per sentence, plus one additional point if needed. Each paragraph +should address one main idea. Remember the basic structure of a paragraph: +Introduction, body, and conclusion. + +Be friendly +=========== + +We write for our peers and want to be familiar. Take a personal tone as if you +were speaking directly to the reader. Use "you" to address the reader and "we" +to refer to our view. Be professional, respectful, and cooperative. + +Assume your audience has the same level of technical understanding and expertise +as you did when you first started collaborating. Do not talk down to our +readers, but also do not assume they know everything about the subject. Offer +brief explanations or summaries of common knowledge if a significant portion of +readers might benefit. + +Use simple words +================ + +Use simple words to increase reader comprehension and reduce ambiguity. Follow +our tips for making good word choices: + +* **Avoid jargon**: Write for your audience, using everyday language where + possible, and technical terms where appropriate. Avoid clichés, idioms, and + metaphors. +* **Be consistent**: Use one term for each concept or action and use it + consistently. +* **Avoid "fancy" words and phrases**: If there is a simpler word or phrase, + use it. + + For example: + + =================== =================== + Use this Not this + =================== =================== + start, begin commence + so consequently + more than in excess of + if in the event of + before prior to + if you want should one wish + use utilize + example instance + =================== =================== + +Avoid overuse of product name +============================= + +Use product names only when necessary. Typically, you can rewrite sentences to +remove the product name with no change in meaning, which keeps the content +concise and scannable. + +Avoid using the product name in page titles and headings. + +.. _scannable-content: + +Make content scannable +********************** + +Organize your content to make it scannable for the reader, which helps them find +what they need quickly, and to understand the information more efficiently. + +* **Put the most important content first.** Make sure your introduction clearly + communicates what the reader can find on the page. Present the point of the + document first, and organize supporting information towards the end of the + page. +* **Write scannable headings.** Expect readers of documentation to skim and scan + the content, and to leave if they dont find what they need quickly. Good + headings add organization to your content and help the reader to find and + understand content more effectively. Follow our guidelines for writing + effective `Headings`_. +* **Write great link text.** Great link text tells the reader what they can + expect when they click on a link. It also helps make the page more scannable. + Follow our guidelines for writing `Link text`_. + +Headings +======== + +Use these guidelines to write effective headings: + +* **Be concise and descriptive.** Use only the words necessary to describe the + section. +* **Use sentence case.** Capitalize only the first word and proper nouns in a + heading. +* **Avoid punctuation.** Unless your heading is a question, don't use sentence + punctuation in headings. +* **Use parallel structure.** Headings at the same level should use the same + grammatical pattern. This provides structure to the document and helps users + find information more easily. See :ref:`parallelism`. +* **Use strong verbs.** Strong, active verbs get to the point. Avoid -ing verbs, + such as *Running*, *Testing*, etc. + +For example, two headings at the same level: + +**Use this:** :: + + Install software + + Configure software + +**Not this:** :: + + Installing the Software on the Platform + + Software Configuration. + +Link text +========= + +All links in content should follow these guidelines: + +* **Write descriptive link text**: Link text should describe where the link + goes, without having to read the surrounding text. +* **Keep link text concise**: Use only the words needed to accurately describe + the destination. +* **Use unique link text**: Each link on a page should be unique. If users see + the same link text twice on a page, they'll assume it goes to the same place. +* **Start link text with keywords**: Frontload the link text with the most + important words to help users scan the text. +* **Avoid generic text**: Don't use generic, uninformative link text such as + "click here" or "read more". + +For example: + +**Use this:** :: + + For more information about dogs, read the `dog wiki article`_. + +**Not this:** :: + + For more information about dogs, `click here`_. + +Use strong verbs +**************** + +Passive verbs make writing stuffy and formal. Use strong verbs to get to the +point and avoid unnecessary words and phrases. + +Use imperatives +=============== + +Commands, also called imperatives, are the fastest and most direct way of giving +someone instructions. For example: + +**Use this:** :: + + Send it to me. + +**Not this:** :: + + I would appreciate it if you would send it to me. + +Use present tense +================= + +Use simple present tense instead of future tense for most text. Search for the +words "will" or "shall" to find future tense instances. Future tense is +acceptable for conditional statements, such as in a caution or a warning. For +example: + +**Use this:** :: + + The system operates at a nominal temperature of 180 degrees Fahrenheit. + +**Not this:** :: + + The system will operate at a nominal temperature of 180 degrees Fahrenheit. + +Avoid nominalizations +===================== + +Avoid nominalizations, which are nouns formed from verbs. + +For example: + +===================== ===================== + Verb Nominalization +===================== ===================== + complete completion + provide provision + fail failure + install installation +===================== ===================== + +For example: + +**Use this:** :: + + We discussed the matter. + +**Not this:** :: + + We had a discussion about the matter. + +Or: + +**Use this:** :: + + IT has installed the software. + +**Not this:** :: + + IT has completed the installation of the software. + +Avoid words ending in -ing +========================== + +Avoid using words ending in -ing unless they are part of a technical name. For +example: + +**Use this:** :: + + There is no way to verify this. + +**Not this:** :: + + There is no way of verifying this. + +Use the active voice +==================== + +Use active voice whenever possible to show who or what is performing an +action. + +* Active voice follows standard English word order: SUBJECT–VERB–OBJECT + (where the OBJECT is optional). +* Passive voice reverses the order and weakens the verb: OBJECT–be VERB–by + SUBJECT (where the OBJECT is optional). + +For example: + +**Use this:** :: + + I made a mistake. + +**Not this:** :: + + A mistake was made. *(By whom?)* + +Or: + +**Use this:** :: + + We released version 2.0 in June. + +**Not this:** :: + + Version 2.0 was released in June. + +Avoid long noun phrases +*********************** + +Noun phrases (a noun and other words that describe or modify it) can be +difficult to understand. Try to limit the number of modifiers in a noun phrase +to two. For example: + +**Use this:** :: + + Integration policies for power management mechanisms. + +**Not this:** :: + + Power management mechanism integration policies. + +.. _parallelism: + +Parallelism +*********** + +Parallelism refers to the practice of using similar patterns of grammar, and +sometimes length, to coordinate words, phrases, and clauses. + +Use parallel construction in lists. The table below shows some unparallel +structures and how they can be made parallel with a little rewording. + ++----------------------------------+----------------------------------+ +| Parallel (do) | Unparallel (don't) | ++==================================+==================================+ +| 1. Mount the panel. | 1. Mount the panel. | +| 2. Install the battery. | 2. Battery installation. | +| 3. Wire the keypad. | 3. Wiring the keypad. | ++----------------------------------+----------------------------------+ +| I like practicing my accordion, | I like practicing my accordion, | +| reading sci-fi, and eating | reading sci-fi, and to eat | +| peanut butter and pickle | peanut butter and pickle | +| sandwiches. | sandwiches. | ++----------------------------------+----------------------------------+ +| For breakfast he likes coffee | For breakfast he likes coffee | +| and bacon. | and to fry bacon. | ++----------------------------------+----------------------------------+ +| Apples or bananas are a good | Apples or a banana are a good | +| snack. | snack. | ++----------------------------------+----------------------------------+ + +Grammar and punctuation +*********************** + +This section covers common grammatical topics relevant to our +documentation. For detailed explanations of correct grammar and punctuation, +use one of our :ref:`preferred references `. + +Capitalization +============== + +The capitalization style for all documentation is sentence case. Words should +only be capitalized when they are proper nouns or refer to trademarked product +names. + +.. note:: + Do not capitalize a word to indicate it is more important than other + words. Never change the case of variable, function or file names - always + keep the original case. + +Menu capitalization +------------------- + +When referring to software menu items by name, use the same capitalization as +seen in the actual menu. + +A few other tips when referring to menu items: + +* Reference the specific menu item using "Select :menuselection:`File --> New`." + +* Put the option to be selected last. "Select + :menuselection:`View --> Side Bar --> Hide Side Bar`" + +* Do not include more than 3 navigation steps in a menu selection. If + more than three steps are needed, divide the steps using + ``:guilabel:`` or ``:menuselection:``. + + For example: "Go to :guilabel:`File` and select + :menuselection:`Print --> Print Preview --> Set Up`." + +Software version capitalization +------------------------------- + +When listing software or hardware version numbers, the word “version” or letter +"v" are lowercase. The v is closed with the number (no period). + +For example: + +* Widget Pro version 5.0 +* Widget Master v2.1.12 + +Contractions +============ + +Avoid using contractions, such as it's, they're, and you're, because they may be +unclear to non-native English-speaking audiences. + +Quotation marks +=============== + +Follow these guidelines for quotation marks: + +* Restrict use of quotation marks to terms as terms. +* Do not use quotation marks for emphasis; use *italics* for emphasis. +* Avoid using single-quote marks. + +Commas and colons +================= + +This section addresses common use of commas, semicolons, and colons in our +documentation. Refer to one of our :ref:`preferred references ` +for further details. + +Use the serial comma +-------------------- + +When writing a series of items, use the serial comma before the final *and* and +*or* to avoid confusion and ambiguity. For example: + +**Use this:** :: + + Mom, Dad, and I are going to the game. + +**Not this:** :: + + Mom, Dad and I are going to the game. + +.. _click here: https://en.wikipedia.org/wiki/Dog +.. _dog wiki article: https://en.wikipedia.org/wiki/Dog diff --git a/source/clear-linux/tutorials/dlrs.rst b/source/clear-linux/tutorials/dlrs.rst new file mode 100644 index 00000000..af828320 --- /dev/null +++ b/source/clear-linux/tutorials/dlrs.rst @@ -0,0 +1,252 @@ +.. _dlrs: + +Deep Learning Reference Stack +############################# + +This tutorial shows you how to run benchmarking workloads in |CL-ATTR| using +TensorFlow\* and Kubeflow with the Deep Learning Reference Stack. + +The Deep Learning Reference Stack is available in two versions. +The first is `Eigen`_, which includes `TensorFlow`_ optimized for Intel® +architecture. The second is `Intel MKL-DNN`_, which includes the TensorFlow +framework optimized using Intel® Math Kernel Library for Deep Neural +Networks (Intel® MKL-DNN) primitives. + +.. contents:: :local: + :depth: 1 + +Release notes +============= + +View current `release notes`_ for the Deep Learning Reference Stack. + +View current `benchmark results`_ for the Deep Learning Reference Stack. + +.. note:: + + Performance test numbers in the Deep Learning Reference Stack were obtained using `runc` as the runtime. + +Prerequisites +============= + +* |CL| installed on host system. If not installed, :ref:`bare-metal-install` +* `containers-basic` bundle +* `cloud-native-basic` bundle + +In |CL|, `containers-basic` provides Docker\*, which is required for +TensorFlow benchmarking. Use the :command:`swupd` utility to check if +`containers-basic` and `cloud-native-basic` are present: + +.. code-block:: bash + + sudo swupd bundle-list + +If you need to install the `containers-basic` or `cloud-native-basic`, enter: + +.. code-block:: bash + + sudo swupd bundle-add containers-basic cloud-native-basic + +To ensure that kubernetes is correctly installed and configured, +:ref:`kubernetes`. + +We have validated these steps against the following software package +versions: + +* |CL| 26240--lowest version permissible. +* Docker 18.06.1 +* Kubernetes 1.11.3 +* Go 1.11.12 + +TensorFlow single and multi-node benchmarks +============================================ + +This section describes running the `TensorFlow benchmarks`_ in single node. +For multi-node testing, replicate these steps for each node. These steps +provide a template to run other benchmarks, provided that they can invoke +TensorFlow. + +#. Download either the `Eigen`_ or the `Intel MKL-DNN`_ docker image + from `Docker Hub`_. + +#. Run the image with Docker: + + .. code-block:: bash + + docker run --name --rm -i -t bash + + .. note:: + + You will enter the following commands in the running container. + + Replace with the you specified above. + +#. Clone the benchmark repository: + + .. code-block:: bash + + docker exec -t bash -c 'git clone http://github.com/tensorflow/benchmarks -b cnn_tf_v1.12_compatible' + +#. Next, execute the benchmark script to run the benchmark. + + .. code-block:: bash + + docker exec -i bash -c 'python benchmarks/scripts/tf_cnn_benchmarks/tf_cnn_benchmarks.py --device=cpu --model=resnet50 --data_format=NHWC '. + +.. note:: + + You can replace the model with one of your choice supported by the + TensorFlow benchmarks. + +Kubeflow multi-node benchmarks +============================== + +The benchmark workload will run in a Kubernetes cluster. We will use +`Kubeflow`_ for the Machine Learning workload deployment on three nodes. + +Kubernetes setup +**************** + +Follow the instructions in the :ref:`kubernetes` tutorial to get set up on +|CL|. The kubernetes community also has +`instructions for creating a cluster`_. + +Kubernetes networking +********************* + +We used `flannel`_ as the network provider for these tests. If you are +comfortable with another network layer, refer to the Kubernetes +`networking documentation`_ for setup. + +Images +****** + +We need to add `launcher.py` to our docker image to include the Deep +Learning Reference Stack and put the benchmarks repo in the correct +location. From the docker image, run the following: + +.. code-block:: bash + + mkdir -p /opt + git clone https://github.com/tensorflow/benchmarks.git /opt/tf-benchmarks + cp launcher.py /opt + chmod u+x /opt/* + +Your entry point now becomes "/opt/launcher.py". + +This will build an image which can be consumed directly by TFJob from +kubeflow. We are working to create these images as part of our release +cycle. + +ksonnet\* +********* + +Kubeflow uses ksonnet* to manage deployments, so we need to install that before setting up Kubeflow. On |CL|, follow these steps: + +.. code-block:: bash + + swupd bundle-add go-basic-dev + export GOPATH=$HOME/go + export PATH=$PATH:$GOPATH/bin + go get github.com/ksonnet/ksonnet + cd $GOPATH/src/github.com/ksonnet/ksonnet + make install + +After the ksonnet installation is complete, ensure that binary `ks` is +accessible across the environment. + +Kubeflow +******** + +Once you have Kubernetes running on your nodes, you can setup `Kubeflow`_ by +following these instructions from their `quick start guide`_. + +.. code-block:: bash + + export KUBEFLOW_SRC=$HOME/kflow + export KUBEFLOW_TAG="v0.4.1" + export KFAPP="kflow_app" + export K8S_NAMESPACE="kubeflow" + + mkdir ${KUBEFLOW_SRC} + cd ${KUBEFLOW_SRC} + ks init ${KFAPP} + cd ${KFAPP} + ks registry add kubeflow github.com/kubeflow/kubeflow/tree/${KUBEFLOW_TAG}/kubeflow + ks pkg install kubeflow/common + ks pkg install kubeflow/tf-training + +Now you have all the required kubeflow packages, and you can deploy the primary one for our purposes: tf-job-operator. + +.. code-block:: bash + + ks env rm default + kubectl create namespace ${K8S_NAMESPACE} + ks env add default --namespace "${K8S_NAMESPACE}" + ks generate tf-job-operator tf-job-operator + ks apply default -c tf-job-operator + +This creates the CustomResourceDefinition(CRD) endpoint to launch a TFJob. + +Run a TFJob +=========== + +#. Select this link for the `ksonnet registries for deploying TFJobs`_. + + #. Install the TFJob componets as follows: + + .. code-block:: bash + + ks registry add dlrs-tfjob github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow/dlrs-tfjob + + ks pkg install dlrs-tfjob/dlrs-bench + +#. Export the image name you'd like to use for the deployment: + + .. code-block:: bash + + export DLRS_IMAGE= + + .. note:: + + Replace with the image name you specified in previous steps. + +#. Next, generate Kubernetes manifests for the workloads and apply them to + create and run them using these commands + + .. code-block:: bash + + ks generate dlrs-resnet50 dlrsresnet50 --name=dlrsresnet50 --image=${DLRS_IMAGE} + ks generate dlrs-alexnet dlrsalexnet --name=dlrsalexnet --image=${DLRS_IMAGE} + ks apply default -c dlrsresnet50 + ks apply default -c dlrsalexnet + +This will replicate and deploy three test setups in your Kubernetes cluster. + +Results of Running this Tutorial +================================ +You need to parse the logs of the Kubernetes pod to get the performance +numbers. The pods will still be around post completion and will be in +‘Completed’ state. You can get the logs from any of the pods to inspect the +benchmark results. More information about `Kubernetes logging`_ is available from the Kubernetes community. + +.. _TensorFlow: https://www.tensorflow.org/ +.. _Kubeflow: https://www.kubeflow.org/ +.. _Docker Hub: https://hub.docker.com/ +.. _TensorFlow benchmarks: https://www.tensorflow.org/guide/performance/benchmarks +.. _instructions for creating a cluster: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/ +.. _flannel: https://github.com/coreos/flannel +.. _networking documentation: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#pod-network +.. _quick start guide: https://www.kubeflow.org/docs/started/getting-started/ + +.. _Eigen: https://hub.docker.com/r/clearlinux/stacks-dlrs-oss/ +.. _Intel MKL-DNN: https://hub.docker.com/r/clearlinux/stacks-dlrs-mkl/ + +.. _release notes: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs + +.. _ksonnet registries for deploying TFJobs: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow/dlrs-tfjob + + +.. _Kubernetes logging: https://kubernetes.io/docs/concepts/cluster-administration/logging/ + +.. _benchmark results: https://clearlinux.org/stacks/deep-learning-reference-stack diff --git a/source/clear-linux/tutorials/docker/docker.rst b/source/clear-linux/tutorials/docker/docker.rst index 284850e2..c61ce9f6 100644 --- a/source/clear-linux/tutorials/docker/docker.rst +++ b/source/clear-linux/tutorials/docker/docker.rst @@ -169,7 +169,7 @@ an the official Docker image for nginx, an open source reverse proxy server. 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` + by browsing to \http://127.0.0.1:8080 or by running this :command:`curl` command from your |CL| machine: .. code-block:: bash diff --git a/source/clear-linux/tutorials/greengrass.rst b/source/clear-linux/tutorials/greengrass.rst index 61c2c772..f0db1859 100644 --- a/source/clear-linux/tutorials/greengrass.rst +++ b/source/clear-linux/tutorials/greengrass.rst @@ -5,14 +5,14 @@ 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 +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 @@ -27,17 +27,17 @@ Supported Platforms Description of Samples ********************** -The AWS Greengrass samples are located at the `Edge-Analytics-FaaS`_. +The AWS Greengrass samples are located at the `Edge-Analytics-FaaS`_. For this tutorial we will use the 1.0 version of the source code. 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 @@ -45,61 +45,6 @@ We provide the following AWS Greengrass samples: 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 ********************************** @@ -129,13 +74,6 @@ services to use (see Greengrass user below). 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. .. code-block:: bash @@ -151,8 +89,8 @@ services to use (see Greengrass user below). 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 @@ -165,6 +103,67 @@ enable the OpenVINO software stack: 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 =================================== @@ -176,7 +175,9 @@ cloud and edge. `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:: @@ -184,43 +185,40 @@ cloud and edge. of Module 1 of the `AWS Greengrass developer guide`_ because this is enabled already in |CL|. -Creating and Packaging Lambda Functions -======================================= - -#. Complete the tutorial at `Configure AWS Greengrass on AWS IoT`_ . - - .. note:: - - This creates the tarball needed to create the AWS Greengrass - environment on the edge device. - -#. Assure to download both the security resources and the AWS Greengrass +#. Be sure to download both the security resources and the AWS Greengrass core software. .. note:: Security certificates are linked to your AWS* account. -#. Replace greengrassHelloWorld.py with Greengrass samples: - * greengrass_classification_sample.py +Creating and Packaging Lambda Functions +======================================= - * greengrass_object_detection_sample_ssd.py +#. Complete steps 1-4 of the tutorial at `Create and Package Lambda Function`_ . -#. Zip these files with extracted Greengrass SDK folders from the previous + .. note:: + + This creates the tarball needed to create the AWS Greengrass + environment on the edge device. + + +#. In step 5, replace greengrassHelloWorld.py with the classification or object detection + Greengrass sample from `Edge-Analytics-Faas`_: + + * Classification: `greengrass_classification_sample.py`_ + + * Object Detection: `greengrass_object_detection_sample_ssd.py`_ + +#. 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,11 +227,11 @@ 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`_. +#. Return to the AWS Documentation and follow steps 6-11 to `complete creating lambdas`_. .. note:: - In the AWS documentation, step 9(a), while uploading the zip file, + 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: @@ -266,12 +264,14 @@ configuring the lambda function for AWS Greengrass. - Value * - PARAM_MODEL_XML - /, where is user specified and - contains IR.xml, the Intermediate Representation file from Intel® Model Optimizer + 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 @@ -375,9 +375,15 @@ References 2. AWS Lambda: https://aws.amazon.com/lambda/ 3. AWS Kinesis: https://aws.amazon.com/kinesis/ -.. _Edge-Analytics-FaaS: https://github.com/intel/Edge-Analytics-FaaS/tree/master/AWS%20Greengrass +.. _Edge-Analytics-FaaS: https://github.com/intel/Edge-Analytics-FaaS/tree/v1.0/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/v1.0/AWS%20Greengrass/greengrass_classification_sample.py + +.. _greengrass_object_detection_sample_ssd.py: https://github.com/intel/Edge-Analytics-FaaS/blob/v1.0/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 @@ -401,4 +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/kubernetes.rst b/source/clear-linux/tutorials/kubernetes.rst index 794e92e6..f05d4109 100644 --- a/source/clear-linux/tutorials/kubernetes.rst +++ b/source/clear-linux/tutorials/kubernetes.rst @@ -4,32 +4,31 @@ Run Kubernetes\* on |CL-ATTR| ############################# This tutorial describes how to install, configure, and run the -`Kubernetes container orchestration system`_ on |CL-ATTR| using different -container engines and runtimes. +`Kubernetes container orchestration system`_ on |CL-ATTR| using CRI+O and +kata-runtime. Kubernetes\* is an open source system for automating deployment, scaling, and management of containerized applications. It groups containers that make up an application into logical units for easy management and discovery. -Runc and Kata Containers\* kata-runtime adhere to :abbr:`OCI (Open Container Initiative*)` -guidelines and work seamlessly with Kubernetes. `Kata Containers`_ provide -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. +Kata Containers\* kata-runtime adheres to +:abbr:`OCI (Open Container Initiative*)` guidelines and work seamlessly with +Kubernetes. `Kata Containers`_ provide strong isolation for untrusted +workloads or multi-tenant scenarios. 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: - -* Kubernetes with Docker and runc -* Kubernetes with CRI-O and kata-runtime +.. contents:: :local: + :depth: 1 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 -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`. +This tutorial assumes you have already installed |CL|. For detailed +instructions on installing |CL| on a bare metal system, follow the +:ref:`bare metal installation tutorial`. Learn about the +benefits of having an up-to-date system for cloud orchestration on the +:ref:`swupd-about` page. Before you install any new packages, update |CL| with the following command: @@ -40,9 +39,16 @@ 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 -framework, enter the following command: +Kubernetes, a set of supported :abbr:`CRI (Container Runtime Interface)` +runtimes, and networking plugins, are included in the `cloud-native-basic`_ +bundle. + +.. note:: + + CRI-O’s default plugin_dir is :file:`/opt/bin/cni`. + CNI plugins are installed as part of ``cloud-native-basic``. + +To install this framework, enter the following command: .. code-block:: bash @@ -105,7 +111,7 @@ deployment and your security needs. On systems with limited resources, some performance degradation may be observed while swap is disabled. -#. Switch to root to modify `hostname`: +#. Switch to root to modify the `hosts` file: .. code-block:: bash @@ -127,49 +133,7 @@ deployment and your security needs. Configure and run Kubernetes **************************** -This section describes how to configure and run Kubernetes with: - -* Docker and runc -* CRI-O and kata-runtime - -Configure and run Docker + runc -=============================== - -#. Enable the Docker service: - - .. code-block:: bash - - sudo systemctl enable docker.service - -#. Create (or edit if it exists) the file - :file:`/etc/systemd/system/docker.service.d/51-runtime.conf` and include the following lines: - - .. code-block:: bash - - [Service] - Environment="DOCKER_DEFAULT_RUNTIME=--default-runtime runc" - -#. Create (or edit if it exists) the file :file:`/etc/systemd/system/kubelet.service.d/10-kubeadm.conf` and include the following lines: - - .. code-block:: bash - - [Service] - Environment="KUBELET_EXTRA_ARGS=" - -#. Enter the commands: - - .. code-block:: bash - - sudo systemctl daemon-reload - sudo systemctl restart docker - sudo systemctl restart kubelet - -#. Initialize the master control plane with the command: - - .. code-block:: bash - - sudo kubeadm init --ignore-preflight-errors=SystemVerification - +This section describes how to configure and run Kubernetes with CRI-O and kata-runtime. Configure and run CRI-O + kata-runtime ====================================== @@ -211,67 +175,57 @@ If you choose the `flannel` add-on, then you must add the following to the --pod-network-cidr 10.244.0.0/16 -If you are using CRI-O and `flannel` and you want to use Kata Containers, edit -the :file:`/etc/crio/crio.conf` file to add: +If you are using CRI-O and `flannel` and you want to use Kata Containers, edit the :file:`/etc/crio/crio.conf` file to add: .. code-block:: bash [crio.runtime] manage_network_ns_lifecycle = true +Create a symlink for the network overlays: + +.. code-block:: bash + + sudo ln -s /usr/libexec/cni /opt/cni/bin + +.. note:: + + |CL| installs CNI plugins that are part of the `cloud-native-basic` + bundle to :file:`/usr/libexec/cni`. The directory is required because ` + swupd verify` may use it to repair a system to a known good state. + **Notes about Weave Net add-on** -If you choose the `Weave Net` add-on, then you must make the following changes -because it installs itself in the :file:`/opt/cni/bin` directory. +If you choose the `Weave Net` add-on, you must make the following +changes because it installs itself in the :file:`/opt/cni/bin` directory. -If you are using Docker and `Weave Net`, edit the :file:`kubeadm.conf` file to -add: +For using CRI-O and ``Weave Net``, complete the following step. -.. code-block:: bash +Add the `loopback` CNI plugin to the plugin path with the command: - Environment="KUBELET_NETWORK_ARGS=--network-plugin=cni --cni-conf-dir=/etc/cni/net.d --cni-bin-dir=/opt/cni/bin" - -If you are using CRI-O and `Weave Net`, you must complete the following steps. - -#. Edit the :file:`/etc/crio/crio.conf` file to change `plugin_dir` from: - - .. code-block:: bash - - plugin_dir = "/usr/libexec/cni/" - - to: - - .. code-block:: bash - - plugin_dir = "/opt/cni/bin" - -#. Add the `loopback` CNI plugin to the plugin path with the command: - - .. code-block:: bash - - sudo ln -s /usr/libexec/cni/loopback /opt/cni/bin/loopback +.. code-block:: bash + sudo ln -s /usr/libexec/cni/loopback /opt/bin/cni/loopback Use your cluster **************** Once your master control plane is successfully initialized, instructions on how to use your cluster and its *IP*, *token*, and *hash* values are -displayed. It is important that you record the cluster values because they are -needed when joining worker nodes to the cluster. Some values have a valid +displayed. It is important that you record the cluster values because they +are needed when joining worker nodes to the cluster. Some values have a valid period. The values are presented in a format similar to: .. code-block:: bash kubeadm join : --token --discovery-token-ca-cert-hash - **Congratulations!** -You've successfully installed and set up Kubernetes in |CL| using Docker and -runc or CRI-O and kata-runtime. You are now ready to follow on-screen -instructions to deploy a pod network to the cluster and join worker nodes -with the displayed token and IP information. +You've successfully installed and set up Kubernetes in |CL| using CRI-O and +kata-runtime. You are now ready to follow on-screen instructions to deploy a +pod network to the cluster and join worker nodes with the displayed token +and IP information. Related topics ************** @@ -314,8 +268,7 @@ Proxy configuration (optional) ****************************** If you use a proxy server, you must set your proxy environment variables and -create an appropriate proxy configuration file for both CRI-O and Docker -services. Consult your IT department if you are behind a corporate proxy for +create an appropriate proxy configuration file for both CRI-O services. Consult your IT department if you are behind a corporate proxy for the appropriate values. Ensure that your local IP is **explicitly included** in the environment variable *NO_PROXY*. (Setting *localhost* is not enough.) @@ -324,17 +277,17 @@ commands as a shell script to configure all of these services in one step: .. code-block:: bash - services=('crio' 'docker') - for s in "${services[@]}"; do - sudo mkdir -p "/etc/systemd/system/${s}.service.d/" - cat << EOF | sudo tee "/etc/systemd/system/${s}.service.d/proxy.conf" - [Service] - Environment="HTTP_PROXY=${http_proxy}" - Environment="HTTPS_PROXY=${https_proxy}" - Environment="SOCKS_PROXY=${socks_proxy}" - Environment="NO_PROXY=${no_proxy}" - EOF - done + services=('crio') + for s in "${services[@]}"; do + sudo mkdir -p "/etc/systemd/system/${s}.service.d/" + cat << EOF | sudo tee "/etc/systemd/system/${s}.service.d/proxy.conf" + [Service] + Environment="HTTP_PROXY=${http_proxy}" + Environment="HTTPS_PROXY=${https_proxy}" + Environment="SOCKS_PROXY=${socks_proxy}" + Environment="NO_PROXY=${no_proxy}" + EOF + done Troubleshooting *************** @@ -376,6 +329,45 @@ Troubleshooting to set the proxy variables permanently, and how to make them available for all the types of access that you will use, such as remote SSH access. + If the result of the above commands is blank, you may need to add a + ``profile`` to the :file:`/etc` directory. To do so, follow these steps. + + #. Create a `profile` in :file:`/etc` + + .. code-block:: bash + + sudo touch profile + + #. With a preferred editor, open `profile`, and enter your proxy settings. + Example shown below. + + .. code-block:: bash + + export "HTTP_PROXY=http://proxy.example.com:443" + export "HTTPS_PROXY=http://proxy.example.com:445" + export "SOCKS_PROXY=http://proxy.example.com:1080" + export "NO_PROXY= site.com,.site.com,localhost,127.0.0.1, + + .. note:: + + can be obtained by running :command:`ifconfig`. + + #. Save and exit the `profile`. + + #. Run: + + .. code-block:: bash + + sudo source profile + + #. To ensure your system isn't running previous session variables, run: + + .. code-block:: bash + + sudo kubeadm reset --cri-socket=/run/crio/crio.sock + + #. Continue below while passing `-E` in the command as shown. + * Missing environment variables. If you are behind a proxy server, pass environment variables by adding *-E* @@ -383,12 +375,8 @@ Troubleshooting .. code-block:: bash - /* Kubernetes with Docker + runc */ - sudo -E kubeadm init --ignore-preflight-errors=SystemVerification - - /* Kubernetes with CRI-O + kata-runtime */ - sudo -E kubeadm init --cri-socket=/run/crio/crio.sock - + /* Kubernetes with CRI-O + kata-runtime */ + sudo -E kubeadm init --cri-socket=/run/crio/crio.sock .. _Kubernetes container orchestration system: https://kubernetes.io/ diff --git a/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst b/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst index 40ce9c58..d0293d96 100644 --- a/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst +++ b/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst @@ -386,7 +386,6 @@ server onto and type in ``localhost`` in the address bar. You should see a web page similar to the one shown in figure 1: .. figure:: figures/telemetry-backend-1.png - :scale: 50 % :alt: Telemetry UI Figure 1: :guilabel:`Telemetry UI` @@ -429,11 +428,11 @@ setting to your new server location. You can also use the fully qualified domain name for your server instead of :guilabel:`localhost`. -#. Restart the :command:`telemd` daemon to reload the configuration file. +#. Restart the telemetry daemons to reload the configuration file. .. code-block:: console - systemctl restart telemd + telemctl restart Test the new telemetry backend server ************************************* @@ -450,7 +449,6 @@ command to send a ``hello`` record to the server as follows: The record should show up on your new server console as shown in figure 2: .. figure:: figures/telemetry-backend-2.png - :scale: 50 % :alt: Telemetry UI Figure 2: :guilabel:`Telemetry UI` diff --git a/source/clear-linux/tutorials/telemetry-e2e.rst b/source/clear-linux/tutorials/telemetry-e2e.rst new file mode 100644 index 00000000..7cf8e38f --- /dev/null +++ b/source/clear-linux/tutorials/telemetry-e2e.rst @@ -0,0 +1,617 @@ +.. _telemetry-e2e: + +Develop with telemetry +###################### + +This tutorial shows you how to set up a telemetry backend server to +manage your records and how to instrument your application with the telemetry +API. + +|CL-ATTR| includes a telemetry and analytics solution (also known as +telemetrics) as part of the OS, which records events of interest and reports +them back to the development team using the telemetrics client daemons. + +The |CL| telemetry client can be enabled or disabled and records can be +redirected to a desired location. More detailed information about using and +configuring the telemetrics client is found in +the :ref:`telemetrics` guide. + + +.. contents:: :local: + :depth: 1 + + +Prerequisites +============= + + +For this tutorial, you can use an existing |CL| system, or you can start with a clean installation of |CL| on a new system. + +New Installation +**************** + +To setup a new system for your telemetry backend server, follow the :ref:`bare-metal-install` getting started guide and: + +#. Choose to install |CL|. +#. Join the :guilabel:`Stability Enhancement Program` during the installation process to enable the telemetrics client components. +#. Select the manual installation method with the following settings: + * Set the hostname to :guilabel:`clr-telem-server` + * Create an administrative user named :guilabel:`clear` and add this user to sudoers :ref:`enable-user-space` + * Choose the :file:`dev-utils`, :file:`network-basic`, and :file:`openssh-server` bundles from the bundle list + + +.. note:: + + Bundles can also be added to your system after this install process completed. The bundles listed here are a minimal set needed to complete the setup of the telemetry backend server and applications. + +Existing System +*************** + +If you are using an existing |CL| system, make sure you have installed the telemetry and dev-utils bundles. Use the :command:`swupd` utility with the `bundle-list` option and check for "telemetrics" in the list: + +.. code-block:: bash + + sudo swupd bundle-list + +If you need to install the bundles, use :command:`swupd` to do so. + +.. code-block:: bash + + sudo swupd bundle-add telemetrics dev-utils + +More information about enabling and configuring the telemetry client can be found at :ref:`telemetry-enable`. + +You will need to run some of the commands in this tutorial with root privileges. You can create a new user or add your user to the sudoers list :ref:`enable-user-space`. + +Setting up the telemetry backend server +======================================= +We'll be using the :file:`deploy.sh` file from the `clearlinux/telemetrics-backend`_ Git repository to install required dependencies for the web server applications. The script also configures nginx and uwsgi, deploys snapshots of the applications, and starts all required services. + +Clone the clearlinux/telemetrics-backend Git repository +******************************************************* + +With all prerequisite software bundles installed, log in with your administrative user, and from your :file:`$HOME` directory, run :command:`git` to clone the :guilabel:`telemetrics-backend` repository into the :file:`$HOME/telemetrics-backend` directory: + +.. code-block:: bash + + git clone https://github.com/clearlinux/telemetrics-backend + +.. note:: + + You may need to set up the :envvar:`https_proxy` environment variable if you have issues reaching github.com. + +Run the deploy.sh script to install the backend server +****************************************************** + +Change your current working directory to :file:`telemetrics-backend/scripts`. + +.. code-block:: bash + + cd telemetrics-backend/scripts + +Run the :command:`./deploy.sh -h` to see the list of options for the :command:`deploy.sh` script: + +.. code-block:: console + + ./deploy.sh -h + Deploy snapshot of the telemetrics-backend + + -a Perform specified action (deploy, install, migrate, resetdb, + restart, uninstall; default: deploy) + -d Distro to deploy to (ubuntu, centos or clr; default: ubuntu) + -h Print these options + -H Set domain for deployment (only accepted value is "localhost" for + now) + -r Set repo location to deploy from + (default: https://github.com/clearlinux/telemetrics-backend) + -s Set source location (default: "master" branch from git repo) + -t Set source type (tarball, or git; default: git) + -u Perform complete uninstallation + +The :command:`deploy.sh` is a bash shell script that allows you to perform the following actions: + +* *deploy* - install a complete instance of the telemetrics backend server and all required components. This is the default action if no *-a* argument is given on the command line. +* *install* - installs and enables all required components for the telemetrics backend server. +* *migrate* - migrate database to new schema. +* *resetdb* - reset the database. +* *restart* - restart the nginx and uWSGI services. +* *uninstall* - uninstall all packages. + +.. note:: + + 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 + +Next, we will install the telemetrics backend server with the following options: + +* *-a install* to perform an install +* *-d clr* to install to a |CL| distro +* *-H localhost* to set the domain to localhost + +We do not need to set the following options since the values are set to the correct values we want by default: + +* *-r https://github.com/clearlinux/telemetrics-backend* sets the repo location for :command:`git` to clone from. +* *-s master* to set the location, or branch. +* *-t git* to set the source type to git. + +.. caution:: + + The :file:`deploy.sh` shell script has minimal error checking and makes several changes to your system. Be sure that the options you define on the cmdline are correct before proceeding. + +To begin the installation with the options defined: + +Run the shell script from the :file:`$HOME/telemetrics-backend/scripts` directory: + +.. code-block:: bash + + ./deploy.sh -H localhost -a install -d clr + +The script will start and list all the defined options and prompt you for the :guilabel:`PostgreSQL` database password as shown below: + +.. code-block:: console + + Options: + host: localhost + distro: clr + action: install + repo: https://github.com/clearlinux/telemetrics-backend + source: master + type: git + DB password: (default: postgres): + +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 the following: + +.. code-block:: console + + swupd-client bundle adder 3.12.7 + Copyright (C) 2012-2017 Intel Corporation + + Downloading packs... + + Extracting application-server pack for version 18740 + ...5% + Extracting database-basic-dev pack for version 18670 + ...10% + Extracting database-basic pack for version 18670 + ...15% + ... + + Extracting c-basic pack for version 18800 + ...89% + Extracting os-core-dev pack for version 18800 + ...94% + Extracting web-server-basic pack for version 18680 + ...100% + Installing bundle(s) files... + ...100% + Calling post-update helper scripts. + Possible filedescriptor leak : 8 (socket:[30833]) + Bundle(s) installation done. + +.. note:: + + This script uses :command:`sudo` to run commands and you may be prompted to enter your user password at any time while the script is executing. If this occurs, enter your user password to execute the :command:`sudo` command. + + .. code-block:: console + + Password: + + You may also see an informational message about setting the :envvar:` + https_proxy` environment variable if this variable isn't set. + +Once the :command:`swupd` command is complete, the script begins processing +the requirements to install and implement the telemetrics server. Finally, +the script enables the server and provides output that finishes with +something similar to: + +.. code-block:: console + + . + . + Successfully built alembic Flask-Migrate itsdangerous Mako MarkupSafe python-editor SQLAlchemy uWSGI WTForms + Installing collected packages: SQLAlchemy, MarkupSafe, Mako, python-editor, six, python-dateutil, alembic, click, Werkzeug, Jinja2, itsdangerous, Flask, Flask-SQLAlchemy, Flask-Migrate, WTForms, Flask-WTF, psycopg2, uWSGI + Running setup.py install for psycopg2 ... done + Successfully installed Flask-0.12.2 Flask-Migrate-2.1.0 Flask-SQLAlchemy-2.2 Flask-WTF-0.14.2 Jinja2-2.9.6 Mako-1.0.7 MarkupSafe-1.0 SQLAlchemy-1.1.13 WTForms-2.1 Werkzeug-0.12.2 alembic-0.9.5 click-6.7 itsdangerous-0.24 psycopg2-2.7.3 python-dateutil-2.6.1 python-editor-1.0.3 six-1.10.0 uWSGI-2.0.15 + +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: + passwd: password updated successfully + +Enter `postgres` for the current value of the password and then enter a new +password, retype it to verify the new password and the :guilabel:`PostgreSQL` +database password will be updated. + +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. + remote: Compressing objects: 100% (53/53), done. + remote: Total 344 (delta 30), reused 50 (delta 20), pack-reused 268 + Receiving objects: 100% (344/344), 130.20 KiB | 1.40 MiB/s, done. + Resolving deltas: 100% (177/177), done. + ... + Already using interpreter /usr/bin/python3 + Using base prefix '/usr' + New python executable in /var/www/telemetry/venv/bin/python3 + Not overwriting existing python script /var/www/telemetry/venv/bin/python (you must use /var/www/telemetry/venv/bin/python3) + Installing setuptools, pip, wheel...done. + INFO [alembic.runtime.migration] Context impl PostgresqlImpl. + INFO [alembic.runtime.migration] Will assume transactional DDL. + INFO [alembic.runtime.migration] Running upgrade -> 3230c615d6e0, empty message + INFO [alembic.runtime.migration] Running upgrade 3230c615d6e0 -> 466cf2f35d67, empty message + + Install complete (installation folder: /var/www/telemetry) + +Once the installation is complete you can use your web browser and view the new server by opening the web browser on your system and type in +``localhost`` in the address bar. + +You should see a web page similar to the one shown in figure 1: + + .. figure:: telemetry-backend/figures/telemetry-backend-1.png + :alt: Telemetry UI + :scale: 50% + + Figure 1: :guilabel:`Telemetry UI` + +Redirect telemetry records +************************** + +Telemetry records generated by the telemetrics clients are sent to the +server location defined in the :file:`/usr/share/defaults/telemetrics/ +telemetrics.conf` configuration file. You can customize this setting by +copying this file to :file:`/etc/telemetrics/telemetrics.conf` and changing +the ``server=`` setting to your new server location. + +#. Create the :file:`/etc/telemetrics` directory and make it your current + working directory. + + .. code-block:: bash + + sudo mkdir -p /etc/telemetrics + cd /etc/telemetrics + +#. Copy the default :file:`telemetrics.conf` file to the new + :file:`/etc/telemetrics` directory. + + .. code-block:: bash + + sudo cp /usr/share/defaults/telemetrics/telemetrics.conf + +#. Edit the new :file:`/etc/telemetrics/telemetrics.conf` file with your + editor using the :command:`sudo` directive and change the + :guilabel:`server=` setting to ``http://localhost/v2/collector`` and save + this change in the new file. + + .. code-block:: console + + server=http://localhost/v2/collector + + You can also use the fully qualified domain name for your server instead of :guilabel:`localhost`. + +#. Restart the telemetry daemons to reload the configuration file. + + .. code-block:: bash + + telemctl restart + +Test the new telemetry backend server +************************************* + +|CL| includes a telemetry test probe called :command:`hprobe` that will send +a ``hello`` record to the telemetry backend server. To test that the +telemetry records are now going to your new destination, run the :command:` +hprobe` command to send a ``hello`` record to the server as follows: + +.. code-block:: bash + + hprobe + +The record should show up on your new server console as shown in figure 2: + + .. figure:: telemetry-backend/figures/telemetry-backend-2.png + :alt: Telemetry UI + :scale: 50% + + Figure 2: :guilabel:`Telemetry UI` + +You have now set up the |CL| telemetry backend server, and redirected records from your client to your server. + +Creating custom telemetry events +================================ +For the following steps, we'll be sending records to the backend server we've just set up. If you prefer to keep records locally and not send them to a server, follow the :ref:`telemetrics` guide and enable :record_retention_enabled: in your :file:`etc/telemetrics/telemetrics.conf` to keep the records locally. + +There are two ways to create custom telemetry events: using :command:`telem-record-gen` and using the telemetry API in your applications. + +Using telem-record-gen +********************** + +Enabling telemetry during installation gives us everything we need to create custom telemetry events, even from C programs, because the telemetry bundle provides a simple pipe-based :abbr:`CLI (Commandline Interface)` program named :file:`telem-record-gen` that can be called trivially: + + +.. code-block:: bash + + ~ $ telem-record-gen --help + +.. code-block:: console + + Usage: + telem-record-gen [OPTIONS] - create and send a custom telemetry record + + Help Options: + -h, --help Show help options + + Application Options: + -f, --config-file Path to configuration file (not implemented yet) + -V, --version Print the program version + -s, --severity Severity level (1-4) - (default 1) + -c, --class Classification level_1/level_2/level_3 + -p, --payload Record body (max size = 8k) + -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 + + +.. note:: + + The C library (:file:`libtelemetry.so - man 3 telemetry`) uses the same API parameters and will yield the same effect as :command:`telem-record-gen`. + +Let's try generating a simple heartbeat event with +:command:`telem-record-gen`, similar to the hprobe heartbeat probe that |CL| +includes by default. + +.. code-block:: bash + + ~ $ telem-record-gen -c org.clearlinux/hello/world -p "hello there" + +We won't see anything happen on the console, but we can track existing and +previous telemetry events with :command:`telemctl`: + +.. code-block:: bash + + ~$ sudo telemctl journal -V -c org.clearlinux/hello/world -i + +.. code-block:: console + + org.clearlinux/hello/world Tue 2018-11-06 23:00:48 UTC 72e55923fd21c75142c24dcfe0ae0a79 143f2580dcf80267f8f1dfe448f3c975 75f547ff-e55b-44b1-9333-1106098bd448 + hello there + +Using the telemetry API in your C application +********************************************* + +.. note:: + + More details about the :ref:`the telemetry API ` are + available in the telemetry guide. + +Confirm that the telemetrics header file is located on the system at +:file:`usr/include/telemetry.h` The `latest version`_ of the file can also +be found on github for reference, but installing the `telemetry` bundle will +install the header file that matches your |CL| version. + +You will need to include the following headers in your code to use the API: + +:: + + #define _GNU_SOURCE + #include + #include + #include + #include + + +Use the following code to create the variables we need to hold the data for the record we will be creating: + +:: + + uint32_t severity = 1; + uint32_t payload_version = 1; + char classification[30] = "org.clearlinux/hello/world"; + struct telem_ref *tm_handle = NULL; + char *payload; + int ret = 0; + + + +Severity: + | Type: uint32_t + | Value: Severity field value. Accepted values are in the range 1-4, with 1 being the lowest severity, and 4 being the highest severity. Values provided outside of this range are clamped to 1 or 4. [low, med, high, crit] + +Payload_version: + | Type: uint32_t + | Value: Payload format version. The only supported value right now is 1, which indicates that the payload is a freely-formatted (unstructured) string. Values greater than 1 are reserved for future use. + +Classification: + | Type: char array + | Value: It should have the form, DOMAIN/PROBENAME/REST: DOMAIN is the reverse domain to use as a namespace for the probe (e.g. org.clearlinux); PROBENAME is the name of the probe; and REST is an arbitrary value that the probe should use to classify the record. The maximum length for the classification string is 122 bytes. Each sub-category may be no longer than 40 bytes long. Two / delimiters are required. + +Tm_handle: + | Type: Telem_ref struct pointer + | Value: Struct pointer declared by the caller, The struct is initialized if the function returns success. + +Payload: + | Type: char pointer + | Value: The payload to set + + + +For this example, we'll set the payload to “hello” by using ``asprintf()`` + +:: + + if (asprintf(&payload, "hello\n") < 0) { + exit(EXIT_FAILURE); + } + + + +The functions ``asprintf()`` and ``vasprintf()`` are analogs of ``sprintf(3)`` and ``vsprintf(3)``, except that they allocate a string large enough to hold the output including the terminating null byte ('\0'), and return a pointer to it via the first argument. This pointer should be passed to ``free(3)`` to release the allocated storage when it is no longer needed. + + +Create the new telemetry record +******************************* + +The function ``tm_create_record()`` initializes a telemetry record and sets the severity and classification of that record, as well as the payload version number. The memory needed to store the telemetry record is allocated and should be freed with ``tm_free_record()`` when no longer needed. + +:: + + if ((ret = tm_create_record(&tm_handle, severity, classification, payload_version)) < 0) { + printf("Failed to create record: %s\n", strerror(-ret)); + ret = 1; + goto fail; + } + + +Set the payload field of a telemetrics record +********************************************* + +The function ``tm_set_payload()`` attaches the provided telemetry record data to the telemetry record. The current maximum payload size is 8192b. + +:: + + if ((ret = tm_set_payload(tm_handle, payload)) < 0) { + printf("Failed to set record payload: %s\n", strerror(-ret)); + ret = 1; + goto fail; + } + free(payload); + +The ``free()`` function frees the memory space pointed to by ptr, which must have been returned by a previous call to ``malloc()``, ``calloc()``, or ``realloc()``. Otherwise, or if ``free(ptr)`` has already been called before, undefined behavior occurs. If ptr is NULL, no operation is performed. + +Send a record to the telemetrics daemon +*************************************** + +The function ``tm_send_record()`` delivers the record to the local +``telemprobd(1)`` service. Since the telemetry record was allocated by the +program it should be freed with ``tm_free_record()`` when it is no longer +needed. + +:: + + if ((ret = tm_send_record(tm_handle)) < 0) { + printf("Failed to send record to daemon: %s\n", strerror(-ret)); + ret = 1; + goto fail; + } else { + printf("Successfully sent record to daemon.\n"); + ret = 0; + } + fail: + tm_free_record(tm_handle); + tm_handle = NULL; + + return ret; + + +Full sample application with compiling flags +============================================ + +Create a new file test.c add the following code. + +:: + + #define _GNU_SOURCE + #include + #include + #include + #include + + int main(int argc, char **argv) + { + uint32_t severity = 1; + uint32_t payload_version = 1; + char classification[30] = "org.clearlinux/hello/world"; + struct telem_ref *tm_handle = NULL; + char *payload; + + int ret = 0; + + if (asprintf(&payload, "hello\n") < 0) { + exit(EXIT_FAILURE); + } + + if ((ret = tm_create_record(&tm_handle, severity, classification, + payload_version)) < 0) { + printf("Failed to create record: %s\n", strerror(-ret)); + ret = 1; + goto fail; + } + + if ((ret = tm_set_payload(tm_handle, payload)) < 0) { + printf("Failed to set record payload: %s\n", strerror(-ret)); + ret = 1; + goto fail; + } + + free(payload); + + if ((ret = tm_send_record(tm_handle)) < 0) { + printf("Failed to send record to daemon: %s\n", strerror(-ret)); + ret = 1; + goto fail; + } else { + printf("Successfully sent record to daemon.\n"); + ret = 0; + } + fail: + tm_free_record(tm_handle); + tm_handle = NULL; + + return ret; + } + + + +Compile with the gcc compiler, using this command: + +.. code-block:: bash + + gcc test.c -ltelemetry -o test_telem + + +Test to ensure the program is working: + +.. code-block:: bash + + ./test_telem + Successfully sent record to daemon. + +Verify record was received +***************************** + +To verify that the heartbeat message was received by the telemetry backend +server you can check the telemetry client journal, and specify the +classification as org.clearlinux/hello/world + +.. code-block:: bash + + sudo telemctl journal -V -c org.clearlinux/hello/world -i + +.. code-block:: console + + Classification Time stamp Record ID Event ID Boot ID + org.clearlinux/hello/world Tue 2018-11-06 22:58:25 UTC b11db07c58c90d8f496ff963df6c43de 24699c2d60c12d154692875b599ca957 75f547ff-e55b-44b1-9333-1106098bd448 + hello + Total records: 1 + + + +A full example of the `heartbeat probe`_ in C is documented in the source code. For more information about telemetrics in |CL| refer to the +:ref:`telemetrics` guide. + +You can also look for the record on the telemetry backend server. + +.. _latest version: https://github.com/clearlinux/telemetrics-client/tree/master/src + +.. _heartbeat probe: https://github.com/clearlinux/telemetrics-client/tree/master/src/probes/hello.c + + +.. _clearlinux/telemetrics-backend: https://github.com/clearlinux/telemetrics-backend diff --git a/source/clear-linux/tutorials/tutorials.rst b/source/clear-linux/tutorials/tutorials.rst index e5d51254..a7069048 100644 --- a/source/clear-linux/tutorials/tutorials.rst +++ b/source/clear-linux/tutorials/tutorials.rst @@ -24,6 +24,7 @@ Explore our tutorials to discover what you can do with |CL|! hadoop fmv aws-web/aws-web + telemetry-e2e telemetry-backend/telemetry-backend smb/smb spark @@ -31,3 +32,4 @@ Explore our tutorials to discover what you can do with |CL|! kata_migration kubernetes greengrass + dlrs diff --git a/source/clear-linux/tutorials/wordpress/web-server-install.rst b/source/clear-linux/tutorials/wordpress/web-server-install.rst index e9788ef3..dce6ed5f 100644 --- a/source/clear-linux/tutorials/wordpress/web-server-install.rst +++ b/source/clear-linux/tutorials/wordpress/web-server-install.rst @@ -55,7 +55,7 @@ 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 message shown in figure 1. @@ -157,7 +157,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 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` @@ -175,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. @@ -221,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: @@ -409,7 +409,7 @@ 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 diff --git a/source/clear-linux/tutorials/wordpress/wp-install.rst b/source/clear-linux/tutorials/wordpress/wp-install.rst index 8b4375e3..d87ff674 100644 --- a/source/clear-linux/tutorials/wordpress/wp-install.rst +++ b/source/clear-linux/tutorials/wordpress/wp-install.rst @@ -42,7 +42,7 @@ Download WordPress and manage directories ========================================= For this tutorial, you will create a WordPress blog that can be accessed at: -http:///blog. +\http:///blog. To accomplish this setup, you must add WordPress components to the :file:`/var/www/html/blog` directory. @@ -87,7 +87,7 @@ Recall that you created a database and user when you installed phpMyAdmin when y 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`. @@ -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/index.rst b/source/index.rst index 18009e35..4aecff65 100644 --- a/source/index.rst +++ b/source/index.rst @@ -7,6 +7,7 @@ Clear Linux - Documentation :maxdepth: 1 clear-linux/clear-linux + sitemap License and disclaimers ======================= diff --git a/source/scripts/_python/Makefile b/source/scripts/_python/Makefile new file mode 100644 index 00000000..d7b5ffc2 --- /dev/null +++ b/source/scripts/_python/Makefile @@ -0,0 +1,9 @@ + +py: + python bundle_lister.py + cp bundles.html.txt ../../clear-linux/reference/bundles + rm -rf cloned_repo/* + rm bundles.html.txt + @echo "Python script finished successfully!" + + diff --git a/source/scripts/_python/README.md b/source/scripts/_python/README.md new file mode 100644 index 00000000..5903bdb3 --- /dev/null +++ b/source/scripts/_python/README.md @@ -0,0 +1,26 @@ +bundle_lister.py +---------------- + +`bundle_lister.py` is a Python (3.6.0) web scraper and html file generator. First, it clones the +[clr-bundles directory](https://github.com/clearlinux/clr-bundles). Second, it parses the content of all bundles in the clr-bundles/ directory and the `packages` file. Third, it uses Jinja2 template engine to output the result as: bundles.html.txt. This file is copied to reference/bundles location, and it is invoked in `bundles.rst`, which currently appears as [Available bundles](https://clearlinux.org/documentation/clear-linux/reference/bundles). + +`bundle_lister.py` automates clear linux documentation so it reflects +current bundles and packages per developer updates to the +[clr-bundles GitHub repository](https://github.com/clearlinux/clr-bundles). Therefore, it increases efficiency, automatically aligns documentation with Clear Linux Engineering development, and it eliminates potential for human error, and saves labor hours in contrast to the previous manual method. + +`bundle_lister.py` will be invoked in a bash script in the `source/Makefile` of clear-linux documentation. Therefore, `bundle_lister.py` will automatically create newly scraped and parsed data upon each build of the +[website](https://clearlinux.org) and output an accurate, up-to-date table showing all bundles and packages for interested developers and admins. + +See `requirements.txt` for dependencies necessary to run this application. + +Built in:`Python==3.6.0` + +To run `bundle_lister.py` in the terminal, enter: `python bundle_lister.py`. + +Note: The `cloned_repo` directory must remain in the parent directory in order for this code to work; the template.html must remain as +well. + +Note: A successful build will produce a file `bundles.html.txt` showing a table of current bundles and pundles (packages) alphabetized, with a (UTC) time and date stamp in the upper right corner. + + +`~$~` diff --git a/source/scripts/_python/bundle_lister.py b/source/scripts/_python/bundle_lister.py new file mode 100644 index 00000000..8440ab61 --- /dev/null +++ b/source/scripts/_python/bundle_lister.py @@ -0,0 +1,98 @@ +import io +import os +import re +import urllib +import jinja2 +from jinja2 import Environment, FileSystemLoader, Template +import git +from operator import itemgetter +from datetime import datetime + +GITHUB_BASE = "https://github.com/clearlinux/clr-bundles/tree/master/bundles/" +PUNDLES = "https://github.com/clearlinux/clr-bundles/blob/master/packages" + +PATTERN1 = re.compile(r"#\s?\[TITLE]:\w?(.*)") +PATTERN2 = re.compile(r"#\s?\[DESCRIPTION]:\w?(.*)") +PATTERN3 = re.compile(r"\(([^()]*|include)\)", re.MULTILINE) +PATTERN4 = re.compile(r"^((?:(?!#)\w+[^-\s][-])\w+|\w+[^\s-])", re.MULTILINE) +# ALT PATTERN4 = re.compile(r"^((?:(?!#)(\w+[^-\s])[-]\w+.)[^\s]{1,}[^\s]|\w+[^\s-])", re.MULTILINE) + +PATTERN5 = re.compile(r"^(?!=a)\w.+\s[#]\s(\w+.*)?", re.MULTILINE) +# Previous version: PATTERN5 = re.compile(r"^[^#].*(?<=\s\-\s)(\w+.*)?", re.MULTILINE) + +def extractor(lines): + bundle_title = "title" + data_desc = "description" + url = "url" + include_list = [] + + for i in lines: + title = PATTERN1.match(i) + desc = PATTERN2.match(i) + includes = PATTERN3.findall(i) + + if title: + bundle_title = title.groups(0)[0].strip() + if desc: + data_desc = desc.groups(0)[0].strip() + if url: + url = os.path.join(GITHUB_BASE, bundle_title) + + if includes: + include_text = includes[0].strip("()") + include_list.append(include_text) + return {"title": bundle_title, "data_desc": data_desc, "include_list": include_list, "url": url} + +def pundler(): + with io.open("./cloned_repo/clr-bundles/packages") as file_obj: + lines = file_obj.readlines() + pundle_title = "pundle_title" + pundle_desc = "pundle_desc" + purl = "purl" + pundle_list = [] + pun_desc = [] + pundle_master = [] + + for i in lines: + pundle = PATTERN4.findall(i) + pundle_plus = PATTERN5.findall(i) + + if pundle: + pundle_title = pundle[0] + pundle_list.append(pundle_title) + + if pundle_plus: + pundle_desc = pundle_plus[0].strip("[]") + pun_desc.append(pundle_desc) + + for pun, desc in zip(pundle_list, pun_desc): + pundle_master.append({"title": pun, "pun_desc": desc, "purl": PUNDLES}) + return pundle_master + +def bundler(): + data = [] + try: + git.Git("./cloned_repo/").clone("https://github.com/clearlinux/clr-bundles.git") + except: + pass + for root, dirs, files in os.walk("./cloned_repo/clr-bundles/bundles", topdown=False): + for name in files: + with open(os.path.join(root, name)) as file_obj: + lines = file_obj.readlines() + data.append(extractor(lines)) + + pundle_master = pundler() + data = data + pundle_master + filtered = list(filter(lambda x: x.get('title'), data)) + sortedData = sorted(filtered, key=lambda x:x['title'].lower()) + #ALT sortedData2 = sorted(sortedData, key=itemgetter('title')) + loader = jinja2.FileSystemLoader(searchpath='./') + env = jinja2.Environment(loader=loader) + template = env.get_template('template.html') + template.globals['now'] = datetime.utcnow + + output = template.render(data=sortedData, now=datetime.utcnow()) + with io.open('bundles.html.txt', 'w') as file: + file.write(output) + +bundler() diff --git a/source/scripts/_python/cloned_repo/.gitkeep b/source/scripts/_python/cloned_repo/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/source/scripts/_python/linkcheck/link-whitelist.txt b/source/scripts/_python/linkcheck/link-whitelist.txt new file mode 100644 index 00000000..a33863a4 --- /dev/null +++ b/source/scripts/_python/linkcheck/link-whitelist.txt @@ -0,0 +1,19 @@ +http://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html +https://software.intel.com/en-us/articles/intel-virtualization-technology-for-directed-io-vt-d-enhancing-intel-platforms-for-efficient-virtualization-of-io-devices +http://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html +https://software.intel.com/en-us/articles/intel-virtualization-technology-for-directed-io-vt-d-enhancing-intel-platforms-for-efficient-virtualization-of-io-devices +https://software.intel.com/en-us/articles/intel-virtualization-technology-for-directed-io-vt-d-enhancing-intel-platforms-for-efficient-virtualization-of-io-devices +https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html +https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html +https://github.com/clearlinux/common#build-rpms-for-a-package +https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html +http://ark.intel.com +https://clearlinux.org/documentation/clear-linux/concepts/bundles-about#related-concepts +https://software.intel.com/en-us/articles/OpenVINO-ModelOptimizer +https://github.com/kata-containers/documentation/blob/master/Upgrading.md#maintenance-warning +https://github.com/clearcontainers/runtime#configuration +https://github.com/kata-containers/runtime#configuration +https://kubernetes.io/docs/user-journeys/users/application-developer/foundational/#section-3 +https://kubernetes.io/docs/user-journeys/users/application-developer/foundational/#section-2 +https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html +http://www.intel.com/content/www/us/en/nuc/nuc-kit-nuc6i5syh.html \ No newline at end of file diff --git a/source/scripts/_python/linkcheck/parse-link-check.py b/source/scripts/_python/linkcheck/parse-link-check.py new file mode 100644 index 00000000..cc943731 --- /dev/null +++ b/source/scripts/_python/linkcheck/parse-link-check.py @@ -0,0 +1,87 @@ +#!/usr/bin/env python + +#*********************************************************** +# +# parse-link-check.py +# +# Arguments: +# 1. path to input file +# +# External file dependencies: +# 1. output.txt - the output of sphinx-build +# 2. link-whitelist.txt - broken links that should be ignored +# +# Output: +# 1. broken_links.html - provides count of broken and whitelist +# matches. Also provides links to all flagged links. Will +# appear in the same directory as output.txt +# 2. Error code 255 if unexpected broken links are found +# +#*********************************************************** + + +import sys +import re +import os + +fileName = "output.txt" +outFile = "broken_links.html" +whitelistFile = "link-whitelist.txt" + +if len(sys.argv) < 2: + print ("Enter path of input directory") + sys.exit() + +scriptPath = sys.argv[0] +outputPath = sys.argv[1] +fileNamePath = outputPath + "/" + fileName +outFilePath = outputPath + "/" + outFile + +whitelistFilePath = os.path.dirname(scriptPath) + "/" + whitelistFile + +with open (whitelistFilePath) as w: + whLines = w.readlines() + +whitelist = [] +for line in whLines: + link = line.rstrip() + whitelist.append(link) + +with open (fileNamePath) as f: + lines = f.readlines() + +numBrokenLinks = 0 +numWhiteListMatches = 0 +newLines = [""] +whiteListLines = [] + +for line in lines: + if "[broken]" in line: + strings = line.split(" ") + link = strings[2][:-1] + link = link.strip() + if link in whitelist: + whiteListLines.append("" + strings[0] + "\n
[whitelist] " + link + "
\n") + numWhiteListMatches += 1 + else: + newLines.append("" + strings[0] + "\n
[broken] " + link + "
\n") + numBrokenLinks += 1 + +newLines.insert(0,"

" + str(numBrokenLinks + numWhiteListMatches) + " broken links found in Sphinx link check

\n") +newLines.insert(1,"

" + str(numBrokenLinks) + " unmatched broken links

\n") +newLines.append("

" + str(numWhiteListMatches) + " links matched whitelist

\n") +for line in whiteListLines: + newLines.append(line) +newLines.append("") + +with open (outFilePath, "w") as outF: + for line in newLines: + outF.write(line) + +print("See ./" + outFilePath + " for a detailed breakdown of broken links.") + +if numBrokenLinks != 0: + print (str(numBrokenLinks) + " detected. Exiting with error code 255.") + sys.exit(-1) +else: + print ("No unexpected broken links detected.") diff --git a/source/scripts/_python/requirements.txt b/source/scripts/_python/requirements.txt new file mode 100644 index 00000000..7b142b78 --- /dev/null +++ b/source/scripts/_python/requirements.txt @@ -0,0 +1,2 @@ +Jinja2==2.10 +GitPython==2.1.11 diff --git a/source/scripts/_python/styles.css b/source/scripts/_python/styles.css new file mode 100644 index 00000000..5f18a5af --- /dev/null +++ b/source/scripts/_python/styles.css @@ -0,0 +1,48 @@ +table { + margin: 32px; + border: 1px solid #e0e0e0; + border-collapse: collapse; + width: auto; +} +th { + font-family: IntelClear-Regular,Helvetica,Arial,sans-serif; + align-content: center; + padding: 5px; + border: #ccc solid 1px; + background-color: #555; + color: #fff; + text-transform: uppercase; + font-size: 18px; +} +tr { + padding-top: 20px ; + padding-bottom: 10px; +} + tbody tr:nth-child(odd) { + background-color: #e0e0e0; +} + .bundlename { + font-family: IntelClear-Regular,Helvetica,Arial,sans-serif; + font-size: 16px; + font-weight: bolder; + padding-left: 6px; + line-height: 18px; + padding-top:7px ; + padding-bottom: 5px; +} +.bundledesc { + font-family: IntelClear-Regular,Helvetica,Arial,sans-serif; + font: italic; + font-size: 16px; + padding-left: 6px; + line-height: 18px; + padding-top: 7px ; + padding-bottom: 5px; +} + ul, li { + margin-left: 8px; + /* padding: 0; */ + padding-left: 5px; + padding-top: 2px; + line-height: 16px; +} diff --git a/source/scripts/_python/template.html b/source/scripts/_python/template.html new file mode 100644 index 00000000..416d4e73 --- /dev/null +++ b/source/scripts/_python/template.html @@ -0,0 +1,55 @@ + + + + + + + Bundles in Clear Linux* OS + + + + + + + + + + + + + + + + + + + + + {% for d in data %} + {% if d.url %} + + + + + {% else %} + + + + + {% endif %} + {% endfor %} + +
+ Updated: {{ now.strftime('%x %H:%M') }} UTC +
Name Description
{{d.title}}{{d.data_desc}}
+ {% if d.include_list %} +

Includes bundle(s): + {% for include in d.include_list %} +

  • {{include}}
    • + {% endfor %} +

    + {% endif %} +
    {{d.title}} {{d.pun_desc}}
    + + + \ No newline at end of file diff --git a/source/sitemap.rst b/source/sitemap.rst new file mode 100644 index 00000000..7e747da5 --- /dev/null +++ b/source/sitemap.rst @@ -0,0 +1,13 @@ +.. _clear-linux-sitemap: + +Clear Linux - Documentation Sitemap +################################### + +.. toctree:: + :includehidden: + + clear-linux/concepts/concepts + clear-linux/get-started/get-started + clear-linux/guides/guides + clear-linux/reference/reference + clear-linux/tutorials/tutorials 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.