diff --git a/.github/ISSUE_TEMPLATE/identify--guides--type-by-role----for-guides-only-.md b/.github/ISSUE_TEMPLATE/identify--guides--type-by-role----for-guides-only-.md deleted file mode 100644 index fb6e16a1..00000000 --- a/.github/ISSUE_TEMPLATE/identify--guides--type-by-role----for-guides-only-.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Identify 'Guides' Type by Role -- For Guides only. -about: For new content in 'Guides', select 1 of 3 categories to which it belongs. - ---- - -New pages will appear here: https://clearlinux.org/documentation/clear-linux/guides - -1. Enter an 'x' in the category for the new "guide": -* [ ] Basics -* [ ] Developer -* [ ] Administrator - -Complete the field below, following the colon, that matches option selected above: - -I am a Clear Linux Beginner (Basics). I want to learn how to: - -I am a Clear Linux Developer. I want to learn how to: - -I am a Clear Linux Administrator. I want to learn how to: diff --git a/.github/ISSUE_TEMPLATE/modify-document.md b/.github/ISSUE_TEMPLATE/modify-document.md new file mode 100644 index 00000000..b61b9302 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/modify-document.md @@ -0,0 +1,19 @@ +--- +name: Modify document +about: Modify a document for the Clear Linux* Project + +--- + +**Describe the error/improvement to an existing document or image** +Provide a clear and concise description of the error or proposed improvement. + +**Screenshots** +If applicable, add screenshots to help explain the error or unexpected behavior. + +**Environment (please complete the following):** + - Clear Linux OS version: [`cat /usr/lib/os-release`] + - Third-party tool/software: [version] + - Command [ [e.g. `sudo -i`] + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/new-document.md b/.github/ISSUE_TEMPLATE/new-document.md new file mode 100644 index 00000000..cf63a349 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new-document.md @@ -0,0 +1,17 @@ +--- +name: New document +about: Request a new document for the Clear Linux* project + +--- + +**Do you think Clear Linux documentation needs a new document? Please describe.** +Please provide a clear and concise description of the title and content. Identify the target audience: Developer; System Administrator; or Basic User. + +**Should the new document be a guide, a reference, or a tutorial?** +Recommend a type of document, based on the structure here: https://clearlinux.org/documentation/clear-linux + +**Describe or provide examples of similar documents, if possible, from other web sites** +Please provide an example of similar documents if possible. + +**Additional context** +Add any other context or screenshots for the document request here. diff --git a/source/clear-containers/architecture-overview.rst b/source/clear-containers/architecture-overview.rst deleted file mode 100644 index 8b82814e..00000000 --- a/source/clear-containers/architecture-overview.rst +++ /dev/null @@ -1,409 +0,0 @@ -.. _architecture-overview: - -Architecture Overview -##################### - -Intel Clear Containers are architected around the Linux -:abbr:`Kernel Virtual Machine (KVM)` virtualization infrastructure to -make best use of Intel Architecture VT features. Operational speed -gets improved and overhead gets reduced by optimizing existing code, -removing redundant components, and implementing new techniques for -containers with :abbr:`KVM (Kernel Virtual Machine)`. - -The latest release of Intel® Clear Containers is release 3.0. You can find -detailed technical information on our `architecture overview`_ on GitHub. - -Version 1.0 of Clear Containers was designed as a lightweight container -system based around `kvmtool`_'s ``lkvm``, -:abbr:`KVM (Kernel Virtual Machine)` and Intel VT-x features; the -initial version was aimed primarily at Docker\* integration. Version -2.0 replaces ``lkvm`` with a lightweight version of -:abbr:`QEMU (Quick EMUlator)` `(link) `_. - -Version 2.0 also expands the feature set to include key technologies, such -as `SR-IOV`_, and the :abbr:`Open Container Initiative (OCI)` runtime API. - -V2.0 -==== - -Intel Clear Containers V2.0 adopts an optimized version of the established -`QEMU`_ host virtualization engine, in order to support extra features not -found in Clear Containers V1.0. Clear Containers. V2.0 is also compatible with -the :abbr:`OCI (Open Container Initiative)` runtime-specification standard, -introducing a host-side abstraction tool to ease host-side integration and to -isolate integration instances from future changes to the underlying Clear -Containers architecture. - -.. figure:: ./figures/clear-containers-v2.png - :align: center - :alt: Clear Containers V2.0 - -Host kernel optimizations -------------------------- - -V2.0 host kernel optimizations are currently the same as -the V1.0 optimizations. - -Host user space ---------------- - -Host user space is based around an optimized version of `QEMU`_ called -``qemu-lite``, with an :abbr:`OCI (Open Container Initiative)` -runtime-compliant wrapper called ``cor``. - -Our version of ``qemu-lite`` has the following modifications: - -* :abbr:`DAX (Direct Access)` support, **enabling fast and space efficient** - file access through zero-copy mapping and multi-container sharing of raw - client filesystem images from the host filesystem. -* **Reduced "slimline" PC model** to reduce startup costs in both `QEMU`_ - and the client kernel. -* **Removed need for BIOS**, saving boot time. -* **No bootloader requirement**, to speed up boot. -* **Reduced memory footprint** by disabling memory-hungry features that - are not required by the client system. -* **Direct kernel boot**, allowing fast booting by loading the kernel as - an uncompressed ELF binary. Although the kernel image is slightly larger - than a compressed one, it is faster to read and boot the larger - file than it is to uncompress and boot the slightly smaller file. -* **Added an** :abbr:`OCI (Open Container Initiative)` **runtime-compliant - wrapper**, AKA ``cor``, for easier integration with - :abbr:`OCI (Open Container Initiative)`-compliant host orchestration systems. - -Client mini-OS --------------- - -The Client mini-OS is based on the same Clear Linux OS-based system as -used in Intel Clear Containers V1.0; however, it may be built from more -recent versions and with more current components, such as the kernel version. - -Client customer images ----------------------- - -Client customer images are supported in the same manner as they are -in V1.0. - - -Legacy V1.0 -=========== - -V1.0 (also known as **Intel® Clear Containers for Docker Engine**) is based -around `kvmtool`_, with example host integrations for Docker and `rkt`_. - -.. figure:: ./figures/clear-containers-v1.png - :align: center - :alt: Intel Clear Containers V1.0 - - -Host kernel optimizations -------------------------- - -Intel Clear Containers operate better when a number of host kernel features and -optimizations are applied: - -* Enabling :abbr:`Kernel Samepage Merging (KSM)` in the host kernel - is recommended for efficient page sharing of VM pages. Kernel documentation - can be found in Documentation/vm/ksm.txt Config symbol: ``CONFIG_KSM`` -* Using a kernel version >= v4.0 (or backporting appropriate - patches if your kernel version is less than v4.0), to get the best - :abbr:`KVM (Kernel Virtual Machine)` VM startup times - - .. note:: - - Intel :abbr:`Extended Page Table (EPT)` acceleration will be - automatically detected and used by your host kernel if supported - by your hardware. You can check whether this feature is present by - looking for the ``ept`` string in the :file:`/proc/cpuinfo` of your - system. See `mmu.txt`_ for more details. - - -Host user space ---------------- - -Intel Clear Containers V1.0 host user space is based around `kvmtool`_ as a -fast and lightweight hypervisor. Optimizations to `kvmtool`_ include: - -* **File access**, enabling efficient *shmem* / *pci-bar* / :abbr:`Direct - Access (DAX)` file access to client. -* **Less verbosity**. -* **Minimal UART scanning** to improve speed. -* **TSC timer functionality changes** passing the client apic timer - calibration step speeds up container creation time. -* Adding ability to **skip unused features**, (such as creation of a - custom rootfs). -* **Removing need for BIOS** saves boot time. -* **No bootloader required** speeds up initial booting of a machine. -* **Direct kernel boot** -- The hypervisor can boot the kernel directly as - an uncompressed ELF binary. Although the kernel image is slightly larger - than a compressed one, it is faster to read and boot the larger - file than it is to uncompress and boot the slightly smaller file. - - -Client mini-OS --------------- - -Intel Clear Containers V1.0 uses an optimized client user space (mini-OS) as -its primary launch vehicle to execute workload commands. The mini-OS is built -with a Clear Linux distribution that has an optimized configuration for time -and space efficiency. The mini-OS includes: - -* Minimized ``systemd`` configuration -* Optimized ``libc`` -* Custom AutoFDO settings -* Optimized multi-lib runtime support -* Optimized kernel config (speed and size) - -The mini-OS configuration can be modified and rebuilt by customers for their -own use cases, which may preclude the need to load further client images. - - -Client customer images ----------------------- - -Intel Clear Containers V1.0 mini-OS workloads can be used to bootstrap further -customer images. These customer images would generally be mapped into the -client via the host filesystem using :abbr:`9p (Plan 9 9p remote filesystem -protocol)`, :abbr:`DAX (Direct Access)` or other filesystem and virtual -device interfaces. These customer images could, for example: - -* Mount a new subtree containing a payload and execute it. -* Mount a new subsystem and chroot to it for contained execution. - -The mini-OS image has been optimized for size and speed. It may be replaced -or superseded -- in whole or in part -- by customer-created images. Keep -in mind, of course, that any benefits the mini-OS provides may be lost -unless equivalent optimizations exist in the customer-created image, or have -been migrated into the image they create. - - -Architectural component details -=============================== - -Host kernel components ----------------------- - -:abbr:`Kernel SamePage Merging (KSM)` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Linux Kernel Documentation: Documentation/vm/ksm.txt - -:abbr:`KSM (Kernel Samepage Merging)` allows the kernel to locate -and merge (share) identical memory pages within the system, even -when they are not sourced from the same binary. When sourced from -the same binary, the kernel will naturally share through the -:abbr:`copy-on-write (COW)` method. - -:abbr:`KSM (Kernel Samepage Merging)` also allows the kernel to -localize and to coalesce pages from within virtual machine memory -spaces that would not normally be shared, thus saving memory space. - -To enable :abbr:`KSM (Kernel Samepage Merging)`, check that your host kernel -config includes ``CONFIG_KSM``, and that your host system is running the -``ksmd`` daemon. - -:abbr:`EPT (Extended Page Tables)` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Linux Kernel Documentation: Documentation/virtual/kvm/mmu.txt - -:abbr:`EPT (Extended Page Tables)` is an acceleration technology for virtual -machine memory mappings. It reduces the number of Virtual Machine Manager -entry/exits from the host system, thus improving system performance. If your -hardware system supports :abbr:`EPT (Extended Page Tables)`, you'll see the -``ept`` feature listed in the ``/proc/cpuinfo`` information from your system. -The kernel, :abbr:`KVM (Kernel Virtual Machine)` and `QEMU`_ will -automatically use and benefit from :abbr:`EPT (Extended Page Tables)` -when supported by your system hardware. - -You can also check on the `Intel ARK website`_ to see if your Intel CPU -supports **Intel VT-x with Extended Page Tables**; check under the -*Advanced Technologies* table on the specific page for your CPU. - -:abbr:`KVM (Kernel Virtual Machine)` startup optimizations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Host kernel startup was optimized before the Linux kernel v4.0 -release by removing some unnecessary ``synchronize_rcu()`` calls. You -should ensure your kernel is at least v4.0, or that you have backported -any appropriate patches to your host kernel: the ``synchronize_rcu() opt``, -at the very least. - -.. We should add a Persistent data (how do we do that on R/O or COW'd - filesystems for instance? - [do we have a standard pattern to do for these docs?] - Persistence - ~~~~~~~~~~~ - - -Host tooling ------------- - -Kvmtool -~~~~~~~ - -Kvmtool is used in Intel Clear Containers V1.0 for virtual machine -configuration and management. It was chosen because it is lighter -and faster than the alternatives, and it's also easy to modify. - -Modifications to `kvmtool`_ include: - -* Implementation of **copy-free** :abbr:`DAX (Direct Access)` **file-system - access**. -* **Less verbosity**. -* **Minimal UART scanning** to improve speed. -* **TSC timer functionality changes** passing the client apic timer - calibration step speeds up container creation time. -* Adding ability to **skip unused features**, (such as creation of a - custom rootfs). -* **Removing need for BIOS** saves boot time. -* **No bootloader required** speeds up initial booting of a machine. -* **Direct kernel boot** -- The hypervisor can boot the kernel directly as - an uncompressed ELF binary. Although the kernel image is slightly larger - than a compressed one, it ends up being faster to read and boot the larger - file than it is to uncompress and boot the slightly smaller file. - - -.. _qemu-lite: - -qemu-lite -~~~~~~~~~ - -``qemu-lite`` is a modified version of `QEMU`_ used for the virtual -machine configuration and management in Intel Clear Containers 2.0. - -The modifications made beyond generic `QEMU`_ are described in the -following sections: - -:abbr:`DAX (Direct Access)` enablement -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:abbr:`DAX (Direct Access)` enablement under ``qemu-lite`` utilizes -existing `QEMU`_ ``nvdimm memdev`` functionality. - -PC-lite -^^^^^^^ - -A new `QEMU`_ PC model, called ‘pc-lite’, has been added that removes -all unused or unnecessary PC style elements from the machine emulation -that are not required for the client VM. This improves both speed of -execution and memory footprint. - -Cor -^^^ - -Cor (the Clear :abbr:`OCI (Open Container Initiative)` runtime manager) -implements the :abbr:`OCI (Open Container Initiative)` runtime specification -atop of the V2.0 infrastructure (such as ``qemu-lite``). By -utilizing Cor, your :abbr:`OCI (Open Container Initiative)`-compliant system -can be implemented with Clear Containers whilst also insulating -the user against any future underlying changes in Clear Containers, -thus allowing easier future integration of upgrades. Cor currently -supports :abbr:`OCI (Open Container Initiative)` runtime version 0.6.0. - -Client components -~~~~~~~~~~~~~~~~~ - -The client-side components consist of the mini-OS kernel and root -filesystem, and optionally further customer specific items, such as -a further fuller distribution or system to load. The intention is -that customers may either extend and expand the mini-OS as required, -or they can use the mini-OS to further load a complete self-contained -image of their choice. - -Client mini-OS -^^^^^^^^^^^^^^ - -The mini-OS is an optimized version of Clear Linux OS for Intel Architecture -which has been designed for the fastest and smallest container boot. The -mini-OS consists of a Linux kernel image and root filesystem image. - -* **Kernel** -- The mini-OS's kernel is a Clear Linux kernel containing - the minimum feature set required to boot the client container. The kernel - has optimized for space and speed. This kernel can be modified and - re-built as desired, for specific requirements. - -* **DAX** -- The :abbr:`Direct Access (DAX)` filesystem. - (Linux Kernel Documentation: ``Documentation/filesystems/dax.txt``). - Mapping host-side files into the memory map of the client allows the use of - :abbr:`DAX (Direct Access)` to directly mount those files, bypassing the - client side page cache and the virtual device mechanisms between host and - client. This allows efficient zero-copy mapping and replaces costly virtual - device manipulations with efficient page fault handling, thus being faster - and more space-efficient than other filesystem mount methods. :abbr:`DAX - (Direct Access)` is enabled in Intel Clear Containers V1.0 using a shmem - PCI-BAR mechanism configured by `kvmtool`_. - - .. figure:: ./figures/dax-v1.png - :align: center - - :abbr:`DAX (Direct Access)` is enabled in Intel Clear Containers - V2.0 using an NVDIMM `QEMU`_ memdev mechanism: - - .. figure:: ./figures/dax-v2.png - :align: center - - :abbr:`DAX (Direct Access)` can only be used to mount single flat files - from the host side (such as uncompressed filesystems), and not trees of - files in the host filesystem. More than one :abbr:`DAX (Direct Access)` - mount can be utilized though. :abbr:`DAX (Direct Access)` is limited only - by the virtual address space available, so it can easily accommodate large - file mappings. - - :abbr:`DAX (Direct Access)` support was introduced in v4.0 of the kernel. - Also see the `qemu-lite`_ section. - -* **Rootfs image** -- The mini-OS rootfs image is a Clear Linux - rootfs. It can execute the client workload and be modified and - extended using the bundle method to enable further features as - necessary. It can also be used to further execute another client - container image, such as a different Linux distribution. - - -Customer Client images and workloads -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Customers may use their own client images by instructing -the mini-OS to execute them using the mini-OS workload. Please -refer to the :ref:`Intel Clear Containers integration -guide` for further detail. - -.. removed this section since it is in the GSG - -FAQ -=== - -**Q.** "Can I run Clear Containers on any host Linux?" - -**A.** Yes, any up-to-date or recent Linux host should be able to run Clear - Containers, as long as the host system kernel contains the necessary - features and is configured with the necessary support enabled. - -.. [to do: finish this section] - -**Q.** "Do I need to use all of Clear Containers, or can I cherry pick parts?" - -**A.** You can cherry pick the parts of Clear Containers you need. Some parts - will make your life generally easier (such as the `QEMU`_ wrapper tool - ``cor``) and will help insulate you from future development changes, so you - should consider which parts you need for which features. The client - side obviously can be quite flexible in its configuration depending - on the deployment environment. - -**Q.** "Can I use Clear Containers technology to run other VMs, not just - container style ones?" - -**A.** Yes, the underlying mechanisms and accelerations used for Clear - Containers can be applied to any Virtual Machine setup, not just - those that are based around a container style workflow. - - -.. _SR-IOV: http://www.intel.com/content/www/us/en/pci-express/pci-sig-sr-iov-primer-sr-iov-technology-paper.html -.. _QEMU: http://www.qemu.org -.. _mmu.txt: - https://www.kernel.org/doc/Documentation/virtual/kvm/mmu.txt - -.. _Intel ARK website: http://ark.intel.com -.. _kvmtool: https://git.kernel.org/cgit/linux/kernel/git/will/kvmtool.git/ -.. _rkt: https://coreos.com/rkt/ -.. _architecture overview: - https://github.com/clearcontainers/runtime/blob/master/docs/architecture/architecture.md diff --git a/source/clear-containers/clear-containers.rst b/source/clear-containers/clear-containers.rst deleted file mode 100644 index 9b74c090..00000000 --- a/source/clear-containers/clear-containers.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _clear-containers.rst: - -Intel® Clear Containers -####################### - -Intel® Clear Containers is a collection of tools, configurations, -and techniques anchored on an implementation that leverages Intel® -Architecture to optimize container launching and execution workflow. -These optimizations improve speed, size, and efficiency while offering -a number of benefits that can be derived only from hardware-backed -virtual machines (hardware-enforced isolation and security, for -example) on Intel® VT technology. - -These methods are applied across all levels of the host/virtual machine -hierarchy: from the host-side userland software stack down through the host -Linux\* kernel, and into the client-side kernel and userland. - -Although it is available as a standalone offering, the Clear Containers -technology works best when it is able to leverage optimizations designed -into the Clear Linux Project. - -Customers can integrate all or parts of Intel Clear Containers into a -container infrastructure. - -.. toctree:: - :maxdepth: 2 - - getting-started - architecture-overview diff --git a/source/clear-containers/figures/clear-containers-v1.png b/source/clear-containers/figures/clear-containers-v1.png deleted file mode 100644 index 9a3318df..00000000 Binary files a/source/clear-containers/figures/clear-containers-v1.png and /dev/null differ diff --git a/source/clear-containers/figures/clear-containers-v2.png b/source/clear-containers/figures/clear-containers-v2.png deleted file mode 100644 index 33e6feaa..00000000 Binary files a/source/clear-containers/figures/clear-containers-v2.png and /dev/null differ diff --git a/source/clear-containers/figures/dax-v1.png b/source/clear-containers/figures/dax-v1.png deleted file mode 100644 index d06368dc..00000000 Binary files a/source/clear-containers/figures/dax-v1.png and /dev/null differ diff --git a/source/clear-containers/figures/dax-v2.png b/source/clear-containers/figures/dax-v2.png deleted file mode 100644 index 6d4e11ac..00000000 Binary files a/source/clear-containers/figures/dax-v2.png and /dev/null differ diff --git a/source/clear-containers/getting-started.rst b/source/clear-containers/getting-started.rst deleted file mode 100644 index 6b37c673..00000000 --- a/source/clear-containers/getting-started.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _cc-getting-started: - -Clear Containers getting started guide -###################################### - -The Intel® Clear Containers enable executing existing Docker applications in -the secure and fast Intel Clear Containers environment under Docker\* -v17.05.0-ce and beyond via an :abbr:`Open Container Initiative (OCI)` -compatible `runtime`. - -Visit our `architecture overview`_ for detailed architectural -information. - -Installation instructions -========================= - -The primary host platform is Clear Linux\* Project for Intel® Architecture. -For instructions on installing Docker and Clear Containers under Clear Linux, -please refer to instructions from the runtime source tree: - - • https://github.com/clearcontainers/runtime/wiki/Installation - -If you have any feedback, questions, or would like to participate and -contribute, then please consult the contact details (mailing list, IRC etc.) -in the document at: - -- https://github.com/clearcontainers/runtime/CONTRIBUTING.md - -Source Code -=========== - -The source code for the Clear Containers 2.0 runtime and corresponding -qemu-lite are publicly hosted on github: - -- https://github.com/clearcontainers/runtime/ - -.. _architecture overview: - https://github.com/clearcontainers/runtime/blob/master/docs/architecture/architecture.md \ No newline at end of file diff --git a/source/clear-linux/clear-linux.rst b/source/clear-linux/clear-linux.rst index b0c4258a..bc5cd177 100644 --- a/source/clear-linux/clear-linux.rst +++ b/source/clear-linux/clear-linux.rst @@ -1,28 +1,40 @@ .. _clear-linux: -Clear Linux\* Project for Intel® Architecture +|CL-PRJ| ############################################# -Welcome to the |CLOSIA| documentation pages. Our documentation is divided -into five sections: +Welcome to the |CLOSIA| documentation pages, the source for |CL| documentation. +Our documentation is divided into the following sections: -* :ref:`get-started` Information about installing |CL| on - bare metal, in a virtual environment, or as a live image on a USB stick +* :ref:`get-started` -* :ref:`concepts` Detailed technical information about - |CL| features and what differentiates it from other |CL| distros + If you are new to |CL|, get started fast with tutorials for installing |CL| on + bare metal, in a virtual environment, or as a live image on a USB stick. -* :ref:`guides` Step-by-step instructions on how to complete - common tasks that help you leverage |CL| native features +* :ref:`concepts` + + Wondering what makes |CL| different? Learn about |CL| features and what + differentiates |CL| from other Linux distros. -* :ref:`tutorials` Step-by-step instructions for applying specific use - cases with |CL| that often involve third-party tools +* :ref:`guides` -* :ref:`reference` Technical descriptions that provide context or - important details about |CL| + Guides show how to complete common tasks that help you leverage |CL| native + features effectively. From basic system configuration to advanced management + of a cloud installation, there is a guide for you. + +* :ref:`tutorials` + + |CL| tutorials provide step-by-step instructions on how |CL| features can + be used and extended, frequently with third-party tools. + +* :ref:`reference` + + Find the detailed information you need to enable your configuration or task + in our |CL| reference section. .. toctree:: :maxdepth: 2 + :hidden: get-started/get-started concepts/concepts diff --git a/source/clear-linux/concepts/bundles-about.rst b/source/clear-linux/concepts/bundles-about.rst index f6cccf3b..0db3efb2 100644 --- a/source/clear-linux/concepts/bundles-about.rst +++ b/source/clear-linux/concepts/bundles-about.rst @@ -14,18 +14,17 @@ distributions deploy their software. With those kinds of distributions, system administrators can then install and update sub-packages individually or as a set, using tools such as "yum" and "apt-get." -The |CLOSIA| takes a slightly different approach. While we also use the +The |CL-ATTR| takes a slightly different approach. While we also use the concept of packages to manage compiling source code into binaries, we do not use the package concept to deploy software. Instead, we provide software -"bundles" that are installed and managed using :ref:`swupd`. Each -bundle contains as many or as few open source projects needed to provide a -complete functionality. +"bundles" that are installed and managed using :ref:`swupd`. +Each bundle contains as many or as few open source projects needed to provide a complete functionality. Next steps ========== To put this concept into practice, see the following resources: -* :ref:`available-bundles` +* :ref:`bundles` * :ref:`bundle-commands` * :ref:`compatible-kernels` diff --git a/source/clear-linux/concepts/concepts.rst b/source/clear-linux/concepts/concepts.rst index 496e31e5..3f78eda3 100644 --- a/source/clear-linux/concepts/concepts.rst +++ b/source/clear-linux/concepts/concepts.rst @@ -15,4 +15,5 @@ details relevant to the |CL| features. bundles-about autospec-about restart + security telemetry-about diff --git a/source/clear-linux/concepts/figures/telemetry-about-1.png b/source/clear-linux/concepts/figures/telemetry-about-1.png index 37463254..57ede5cd 100644 Binary files a/source/clear-linux/concepts/figures/telemetry-about-1.png and b/source/clear-linux/concepts/figures/telemetry-about-1.png differ diff --git a/source/clear-linux/concepts/security.rst b/source/clear-linux/concepts/security.rst new file mode 100644 index 00000000..5b6b250f --- /dev/null +++ b/source/clear-linux/concepts/security.rst @@ -0,0 +1,204 @@ +.. _security: + +|CL-ATTR| OS Security +************************* + +|CL-ATTR| aims to make systemic and layered security-conscious decisions +that are both performant and practical. This security philosophy is rooted +within the project's codebase and operating culture. + + +.. contents:: :local: + :depth: 2 + + + +Security in Updates +=================== + +The |CL| team believes in the benefits of +software security through open sourcing, incremental updates, and +rapidly resolving known security advisories. + + + +The latest Linux codebase +------------------------- + +|CL| uses the newest version of the Linux kernel which allows the operating +system to leverage the latest features from the upstream Linux kernel, +including security fixes. + + + + +Automated Effective Updating +---------------------------- + +|CL| is incrementally updated multiple times per day. + +This `rolling release model`_ allows |CL| to consume the latest security +fixes of software packages as soon as they become available. +There is no waiting for major or minor releases on |CL|. + +An update is not effective if it is just simply downloaded onto a system. +It needs to be obtained *AND* ensured that the new patched copy is being +used; not an older copy loaded into memory. |CL| will let you know when a +service needs to be rebooted or do it for your automatically after +a software update, if desired. + + +In |CL| updates are delivered automatically, efficiently, +and effectively. For more information see +`documentation about Software Updates`_ in |CL|. + + + + + +Automated CVE Scanning and Remediation +-------------------------------------- + +The sheer number of software packages and security vulnerabilities is growing +exponentially. Repositories of Common Vulnerabilities and Exposures (CVEs) +and their fixes, if known, are published by :abbr:`NIST` in a +National Vulnerability Database \ |NVD|\ and at \ |MITRE|\ . + + +|CL| employs a proactive and measured approach to addressing known +and fixable :abbr:`CVEs (Common Vulnerabilities and Exposures)`. +Packages are automatically scanned against +:abbr:`CVEs (Common Vulnerabilities and Exposures)` daily, and security +patches are deployed as soon as they are available. + +These combined practices minimize the amount of +time |CL| systems are exposed to unnecessary security risk. + + + + + +Security in Software +==================== + + +Minimized attack surface +------------------------- + +|CL| removes legacy, unneeded, or redundant standards and +components as much as possible to enable the use of best known security +standards. Below are some examples: + +* `RC4`, `SSLv3`, `3DES`, and `SHA-1` ciphers which have had known + vulnerabilities, have been explicitly disabled within many |CL| packages to + avoid their accidental usage. + +* Services and subsystems which expose sensitive system information + have been removed such as the `finger` and `tcpwrappers`. + +* `SFTP` has been disabled by default due to security + considerations. See the `openssh-server reference page`_ for more details. + + +Verified trust +-------------- + +|CL| encourages the use of secure practices such as encryption +and digital signature verification throughout the system and discourages blind +trust. Below are some examples: + +* All update operations from swupd are transparently encrypted and checked + against the |CL| maintainers' public key for authenticity. + More information can be found in this blog post: + `blog post about swupd security`_ + +* Before being built, packages available from |CL| verify checksums and + signatures provided by third party project codebases and maintainers. + +* |CL| features a unified certificate store, `clrtrust`_ which comes + ready to work with well-known Certificate Authorities out of the box. + `clrtrust`_ also offers an easy to use command line interface for managing + system-wide chains of trust, instead of ignoring foreign certificates. + + + + + + +Compiled with secure options +---------------------------- + +While |CL| packages are optimized for performance on +Intel® architecture, security conscious kernel and compiler options are +sensibly taken advantage of. Below are some examples: + + +* Kernels shipped with |CL| are signed and disallow the usage of + custom kernel modules to maintain verifiable system integrity. + +* `Address space layout randomization (ASLR)`_ and + `Kernel address space layout randomization (KASLR)`_ are kernel features + which defend against certain memory based attacks. + More information can be found in a `blog post about PIE executables`_ . + +* `dm-verity`_ is a kernel mechanism readily available in |CL| + which verifies integrity of the devices being written to, like hard disks, + to help ensure they have not been tampered with. + + + + + +Security in System Design +========================= + +Simple, yet effective, techniques are used throughout the +|CL| system design to defend against common attack vectors and enable +good security hygiene. Below are some examples: + + +* Full disk encryption using `Linux Unified Key Setup`_ (LUKS) is available + during installation. + +* |CL| uses the PAM cracklib module to harden user login and password + security resulting in: + + - No default username or root password set out of the box with + |CL|, you will be asked to set your own password immediately. + + - Simple password schemes, which are known to be easily compromised, + cannot be set in |CL|. + + - A password blacklist, to avoid system passwords being set to + passwords which have been compromised in the past. + +* `Tallow`_, a lightweight service which monitors and blocks suspicious SSH + login patterns, is installed with the :command:`openssh-server` bundle. + + + + + + +.. _`documentation about Software Updates`: https://clearlinux.org/documentation/clear-linux/concepts/swupd-about +.. _`cve-check-tool`: https://github.com/clearlinux/cve-check-tool +.. _`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 +.. _`Address space layout randomization (ASLR)`: https://en.wikipedia.org/wiki/Address_space_layout_randomization +.. _`Kernel address space layout randomization (KASLR)`: https://lwn.net/Articles/569635/ +.. _`dm-verity`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/device-mapper/verity.txt +.. _`SELinux`: https://github.com/SELinuxProject +.. _`Linux Unified Key Setup`: https://gitlab.com/cryptsetup/cryptsetup/ +.. _`blog post about PIE executables`: https://clearlinux.org/blogs/recent-gnu-c-library-improvements +.. _`Tallow`: https://github.com/clearlinux/tallow + +.. |NVD| raw:: html + + https://nvd.nist.gov/ + +.. |MITRE| raw:: html + + https://cve.mitre.org/ + diff --git a/source/clear-linux/concepts/swupd-about.rst b/source/clear-linux/concepts/swupd-about.rst index 167cc215..f132c229 100644 --- a/source/clear-linux/concepts/swupd-about.rst +++ b/source/clear-linux/concepts/swupd-about.rst @@ -3,53 +3,52 @@ Software update ############### -The traditional way -=================== +|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 +specific function. -Traditional Linux-based operating systems are often a mix of several -hundred, if not thousands, of open source projects. To make them -manageable, most distributions use the concept of "packages" to configure -and compile source code into binaries for installation. +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. -Many distributions then combine these compiled binaries into so-called -packages, resolving dependencies and providing everything needed to -install. This is the granularity at which typical distributions deploy -their software, enabling system administrators to install and update -each package individually or as a set, using tools such as ``yum`` and -``apt-get``. +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. -The Clear way -============= - -Clear Linux OS for Intel® Architecture does things a little differently. -The following are a few notable features that distinguish it from -standard OSes: bundles, versioning, updating, and update speed. Bundles -------- +======= -While we use the concept of packages to manage compiling source code into -installable binaries, we do not deploy software through packages. Instead, -we provide "bundles" which operate as a self-contained set of functionality -for the system administrator -- functionality that gets enabled by composing -all the required upstream open-source projects into one logical unit: a -bundle. +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` +page. Versioning ----------- +========== -On a traditional distribution, the process of describing current software +In a traditional distribution, the process of describing current software versioning usually involves: - Listing and keeping track of the current OS release (generally - uninformative about any singular packages or functionality), + uninformative about any singular packages or functionality). -- Keeping track of packages and repositories being used, updating them - individually, +- Keeping track of packages and repositories being used, and updating them + individually. - Listing and tracking every package available and installed on the - system, none of which are directly tied to the current OS release + system, none of which are directly tied to the current OS release. This can be done effectively, but given the nearly endless combinations of packages and versions of packages a server may have, it quickly becomes @@ -57,7 +56,7 @@ non-trivial to define what "version" the system is and what software it is running without explicitly going through each system and inspecting every package. -With the Clear Linux OS for Intel Architecture, we need only track: +With |CL|, we need only track: - One single number @@ -66,50 +65,43 @@ 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, and on what -other pieces. 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 Clear Linux OS for Intel Architecture. +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|. Updating --------- +======== -Another notable difference between package-based distributions and Clear Linux +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 -Clear Linux OS for Intel Architecture, 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 Clear Linux. +|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 the ability 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. +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. -Clear Linux OS will automatically check for updates and apply them. This default -can be disabled by running:: +|CL| promotes regular updating of the OS and will automatically check +for updates and apply them by default. - # swupd autoupdate --disable - -And reenabled by running:: - - # swupd autoupdate --enable +To learn how to run an update of your system, visit our :ref:`swupd-guide` page. Update speed ------------- +============ -Software updates with Clear Linux OS for Intel Architecture 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 +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. It is quite common for a full OS update fixing a security hole to be @@ -121,15 +113,20 @@ those bits that changed, yielding very small update content (deltas) that can be applied exceedingly fast. As a result, major security patches and core update take merely seconds. + +Customize the OS +================ + While we realize our definition of bundles makes sense to us, data center operators may have special needs and ideas. Therefore, we provide a :ref:`mixer tool `. This tool allows users to customize and add bundles or even add their own software, while keeping the operating system and its updates as the basis. Using this tool, system administrators -can focus on the custom pieces their deployments require while staying on +can focus on the customization their deployments require while staying on a controlled update stream. -To learn how to run an update of your system, visit our :ref:`using swupd ` page. +To learn more about mixing, visit our :ref:`mixer-about` page. -.. [1] The software update technology for Clear Linux* OS for Intel - Architecture was first presented at the Linux Plumbers conference in 2012. + +.. [1] The software update technology for |CLOSIA| was first presented at the + Linux Plumbers conference in 2012. diff --git a/source/clear-linux/concepts/telemetry-about.rst b/source/clear-linux/concepts/telemetry-about.rst index b37e6d90..11943877 100644 --- a/source/clear-linux/concepts/telemetry-about.rst +++ b/source/clear-linux/concepts/telemetry-about.rst @@ -3,7 +3,7 @@ Telemetrics ########### -One of the key features of |CLOSIA| is telemetry, which is used to +One of the key features of |CL-ATTR| is telemetry, which is used to monitor system health. Telemetry enables developers to observe and proactively address issues before end users are impacted. @@ -47,11 +47,13 @@ Architecture The telemetry client provides the front end of a complete telemetrics solution and includes the following components: -* **telemd**, a daemon that prepares the records to send to a telemetrics server or - spools the records on disk in case it cannot successfully deliver them. -* Probes that collect specific types of data from the operating system. +* **telemprobd**, a daemon that prepares the telemetry records and spools them on disk prior to delivery +* **telempostd**, a daemon that sends the records to the telemetry backend server or leaves them on disk until deleting after the record expires. + +* **probes**, that collect specific types of data from the operating system. * **libtelemetry**, that telemetrics probes use to create telemetrics records and - send them to the telemd daemon for further processing. + send them to the telemprobd daemon for further processing. + The telemetry backend provides the server-side component of a complete telemetrics solution and consists of: 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 00c8cbe7..47045d37 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,16 +1,19 @@ .. _bare-metal-install: -Install Clear Linux OS on bare metal (automatic) -################################################ +Install |CL-ATTR| on bare metal (automatic) +########################################### -These instructions guide you through the installation of |CLOSIA| +These instructions guide you through the installation of |CL-ATTR| on bare metal using a bootable USB drive. -Before you begin, run our :ref:`compatibility-check`. +Before you begin, check that your system meets the requirements to install |CL|: + +* :ref:`system-requirements` +* :ref:`compatibility-check` -Download the latest Clear Linux installer image -*********************************************** +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: @@ -19,11 +22,11 @@ Look for the :file:`clear-[version number]-installer.img.xz` file. You can also curl -O https://download.clearlinux.org/image/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz -Once you have downloaded the image, verify and uncompress the file. +Once you have downloaded the image, verify and decompress the file. -.. include:: ../../guides/maintenance/download-verify-uncompress-linux.rst - :Start-after: verify-linux: - :end-before: To uncompress a GZ +.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst + :Start-after: incl-decompress-image: + :end-before: incl-decompress-image-end: .. include:: ../bootable-usb/bootable-usb-linux.rst :Start-after: copy-usb-linux: @@ -31,8 +34,8 @@ Once you have downloaded the image, verify and uncompress the file. .. _install-on-target: -Install Clear Linux on your target system -***************************************** +Install |CL| on your target system +********************************** We formatted the previously created USB drive as a UEFI boot device. Our target system has a hard drive installed containing a single primary @@ -54,25 +57,24 @@ Follow these steps to install |CL| on the target system: #. Reboot the target system. -#. The |CL| Installer menu will start as shown in Figure 1. +#. 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: Clear Linux boot menu + :alt: Boot menu - Figure 1: :guilabel:`Clear Linux boot menu` + Figure 1: :guilabel:`Boot menu` -#. This will take you into the :guilabel:`Clear Linux OS for Intel - Architecture Installer` menu as shown in figure 2 and explains how to +#. 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. .. figure:: figures/bare-metal-install-2.png :scale: 50 % - :alt: Clear Linux OS for Intel Architecture Installer + :alt: Installer menu - Figure 2: :guilabel:`Clear Linux OS for Intel Architecture Installer` + Figure 2: :guilabel:`Installer menu` Press the :kbd:`Enter` key. @@ -97,7 +99,7 @@ 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 4. .. figure:: figures/bare-metal-install-4.png :scale: 50 % @@ -134,11 +136,11 @@ 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 Clear Linux installer action -=================================== +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: +open a shell, or exit the |CL| installer. This menu is shown in figure 5. .. figure:: figures/bare-metal-install-5.png :scale: 50 % @@ -181,8 +183,8 @@ open a shell, or exit the |CL| installer. This menu is shown in figure 5: information is collected. Please visit our website to `learn more about telemetry.`_ -Choose Clear Linux installation type -************************************ +Choose |CL| installation type +***************************** Figure 7 shows the next step of the |CL| installer: :guilabel:`Choose installation Type`. Chose whether to install |CL| @@ -216,8 +218,8 @@ If you want to perform any of these additional tasks, select the :ref:`bare-metal-manual-install` to complete the |CL| manual installation process. Otherwise, you can follow the |CL| automatic installation steps. -Clear Linux automatic installation -********************************** +|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 @@ -279,7 +281,7 @@ 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: +console requests your login as shown in figure 12: .. figure:: figures/bare-metal-install-12.png :scale: 50 % @@ -300,18 +302,15 @@ You have now set your root password and are logged in with root privileges. You have successfully installed |CL| on a bare metal system using the automatic installation method and set the password for the ``root`` user. -The automatic installation of |CL| is designed to install with minimal -software overhead. Therefore, some housekeeping and package installations -could be needed before you can take full advantage of the |CL| operating -system. These instructions are captured in the :ref:`enable-user-space`. +Next steps +********** -* Create a new user -* Update the OS to its most current version using `swupd`. -* Install the most common applications for system administrators and - developers using bundles. -* Setup a new user. -* Setup `sudo` privileges for that new user. -* Install a GUI using those `sudo` privileges. +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`: diff --git a/source/clear-linux/get-started/bare-metal-install/bare-metal-manual-install.rst b/source/clear-linux/get-started/bare-metal-manual-install/bare-metal-manual-install.rst similarity index 95% rename from source/clear-linux/get-started/bare-metal-install/bare-metal-manual-install.rst rename to source/clear-linux/get-started/bare-metal-manual-install/bare-metal-manual-install.rst index 8f750061..512478fd 100644 --- a/source/clear-linux/get-started/bare-metal-install/bare-metal-manual-install.rst +++ b/source/clear-linux/get-started/bare-metal-manual-install/bare-metal-manual-install.rst @@ -1,10 +1,10 @@ .. _bare-metal-manual-install: -Install Clear Linux OS on bare metal (manual) +Install |CL-ATTR| on bare metal (manual) ############################################# -This section contains the steps for a |CL| manual installation. It picks up -where the :ref:`bare-metal-install` left off. +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). @@ -180,7 +180,7 @@ The next steps of the manual installer setup process allows you to: 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 +the :ref:`software bundle list ` and select the name for a specific bundle to show the contents within the bundle. Target system network configuration diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-1.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-1.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-10.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-10.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-11.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-11.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-12.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-12.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-13.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-13.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-14.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-14.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-15.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-15.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-16.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-16.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-2.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-2.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-3.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-3.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-4.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-4.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-5.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-5.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-6.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-6.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-7.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-7.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-8.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-8.png diff --git a/source/clear-linux/get-started/bare-metal-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 similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/bare-metal-manual-install-9.png rename to source/clear-linux/get-started/bare-metal-manual-install/figures/bare-metal-manual-install-9.png diff --git a/source/clear-linux/get-started/bootable-usb/bootable-usb-linux.rst b/source/clear-linux/get-started/bootable-usb/bootable-usb-linux.rst index 4767c26a..5df94cee 100644 --- a/source/clear-linux/get-started/bootable-usb/bootable-usb-linux.rst +++ b/source/clear-linux/get-started/bootable-usb/bootable-usb-linux.rst @@ -1,9 +1,9 @@ .. _bootable-usb-linux: -Create a bootable USB drive on Linux -#################################### +Create a bootable USB drive on Linux\* +###################################### -Follow these instructions to create a bootable |CLOSIA| USB drive. +Follow these instructions to create a bootable |CL-ATTR| USB drive. Use an **8GB** or larger USB drive. Download either a live image, ``clear--live.img.xz`` or an installer image, ``clear--installer.img.xz``, from our `image`_ download page. @@ -17,13 +17,13 @@ Instructions are also available for other operating systems: :start-after: incl-image-filename: :end-before: incl-image-filename-end: -.. include:: ../../guides/maintenance/download-verify-uncompress-linux.rst +.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst :Start-after: verify-linux: .. _copy-usb-linux: -Burn the Clear Linux image onto a USB drive -******************************************* +Burn the |CL| image onto a USB drive +************************************ .. caution:: @@ -35,7 +35,7 @@ Burn the Clear Linux image onto a USB drive sudo -s -#. Go to the directory with the uncompressed image. +#. 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 diff --git a/source/clear-linux/get-started/bootable-usb/bootable-usb-mac.rst b/source/clear-linux/get-started/bootable-usb/bootable-usb-mac.rst index 2aab17b2..3d55c209 100644 --- a/source/clear-linux/get-started/bootable-usb/bootable-usb-mac.rst +++ b/source/clear-linux/get-started/bootable-usb/bootable-usb-mac.rst @@ -3,7 +3,7 @@ Create a bootable USB drive on macOS #################################### -Follow these instructions to create a bootable |CLOSIA| USB drive. +Follow these instructions to create a bootable |CL-ATTR| USB drive. Use an **8GB** or larger USB drive. Download either a live image, ``clear--live.img.xz`` or an installer image, ``clear--installer.img.xz``, from our `image`_ download page. @@ -17,25 +17,25 @@ Instructions are also available for other operating systems: :start-after: incl-image-filename: :end-before: incl-image-filename-end: -.. include:: ../../guides/maintenance/download-verify-uncompress-mac.rst +.. include:: ../../guides/maintenance/download-verify-decompress-mac.rst :start-after: verify-mac: -Burn the Clear Linux image onto a USB drive -******************************************* +Burn the |CL| image onto a USB drive +************************************ .. caution:: |CAUTION-BACKUP-USB| #. Launch the Terminal app. -#. Go to the directory with the uncompressed image. +#. 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 + diskutil list .. figure:: figures/bootable-usb-mac-1.png :scale: 100 % @@ -48,14 +48,14 @@ Burn the Clear Linux image onto a USB drive .. code-block:: console - $ diskutil umountDisk /dev/disk2 + 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 + 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 @@ -67,7 +67,7 @@ Burn the Clear Linux image onto a USB drive .. code-block:: console - $ diskutil eject /dev/disk2 + diskutil eject /dev/disk2 Next steps ********** diff --git a/source/clear-linux/get-started/bootable-usb/bootable-usb-windows.rst b/source/clear-linux/get-started/bootable-usb/bootable-usb-windows.rst index d4dbd75e..8a6d3dca 100644 --- a/source/clear-linux/get-started/bootable-usb/bootable-usb-windows.rst +++ b/source/clear-linux/get-started/bootable-usb/bootable-usb-windows.rst @@ -1,9 +1,9 @@ .. _bootable-usb-windows: -Create a bootable USB drive on Windows -###################################### +Create a bootable USB drive on Windows\* +######################################## -Follow these instructions to create a bootable |CLOSIA| USB drive. +Follow these instructions to create a bootable |CL-ATTR| USB drive. Use an **8GB** or larger USB drive. Download either a live image, ``clear--live.img.xz`` or an installer image, ``clear--installer.img.xz``, from our `image`_ download page. @@ -17,11 +17,11 @@ Instructions are also available for other operating systems: :start-after: incl-image-filename: :end-before: incl-image-filename-end: -.. include:: ../../guides/maintenance/download-verify-uncompress-windows.rst +.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst :Start-after: verify-windows: -Burn the Clear Linux image onto a USB drive -******************************************* +Burn the |CL| image onto a USB drive +************************************ .. caution:: diff --git a/source/clear-linux/get-started/bootable-usb/bootable-usb.rst b/source/clear-linux/get-started/bootable-usb/bootable-usb.rst index 431e9e2f..f774b69c 100644 --- a/source/clear-linux/get-started/bootable-usb/bootable-usb.rst +++ b/source/clear-linux/get-started/bootable-usb/bootable-usb.rst @@ -1,23 +1,23 @@ .. _bootable-usb: -Create a bootable Clear Linux USB drive -####################################### +Create a bootable |CL-ATTR| USB drive +##################################### -Instructions to create a |CLOSIA| USB drive vary depending on your operating +Instructions to create a |CL-ATTR| USB drive vary depending on your operating system. .. _download-usb-image: -Download the latest Clear Linux image -************************************* +Download the latest |CL| image +****************************** There are 2 types of |CL| images suitable for burning onto and running off a USB drive: - * Live image: :file:`clear-[version number]-live.img.xz` - * Installer image: :file:`clear-[version number]-installer.img.xz` +* Live image: :file:`clear-[version number]-live.img.xz` +* Installer image: :file:`clear-[version number]-installer.img.xz` -Go to the Clear Linux `image`_ repository and download the desired type. +Go to the |CL| `image`_ repository and download the desired type. With the appropriate image downloaded, choose the step-by-step instructions applicable to your system: diff --git a/source/clear-linux/get-started/bootable-usb/figures/download-verify-uncompress-windows-fig-1.png b/source/clear-linux/get-started/bootable-usb/figures/download-verify-decompress-windows-fig-1.png similarity index 100% rename from source/clear-linux/get-started/bootable-usb/figures/download-verify-uncompress-windows-fig-1.png rename to source/clear-linux/get-started/bootable-usb/figures/download-verify-decompress-windows-fig-1.png diff --git a/source/clear-linux/get-started/bare-metal-install/cgdisk-manual-install.rst b/source/clear-linux/get-started/cgdisk-manual-install/cgdisk-manual-install.rst old mode 100755 new mode 100644 similarity index 93% rename from source/clear-linux/get-started/bare-metal-install/cgdisk-manual-install.rst rename to source/clear-linux/get-started/cgdisk-manual-install/cgdisk-manual-install.rst index 0c5eb624..653f83d0 --- a/source/clear-linux/get-started/bare-metal-install/cgdisk-manual-install.rst +++ b/source/clear-linux/get-started/cgdisk-manual-install/cgdisk-manual-install.rst @@ -1,11 +1,11 @@ .. _cgdisk-manual-install: -Create partitions for Clear Linux\* using CGDISK -################################################ +Create partitions for |CL-ATTR| using CGDISK +############################################ -As part of the |CL| manual installation processThese 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 +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 @@ -67,7 +67,7 @@ installation. Figure 4: :guilabel:`cgdisk` -Linux Partition setup +Linux partition setup ********************* In order to properly set up the |CL| partitioning scheme, we create three @@ -173,7 +173,7 @@ about it, review `Rod Smith's Partitioning advice about alignment`_. 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. @@ -278,7 +278,7 @@ partitions and select to format them. You have completed the process of manually partitioning your target system. Now, :ref:`return to the bare metal manual installation - ` to complete installation of Clear Linux. + ` to complete installation of |CL|. Continue at the section *Additional manual installer settings*. .. _`GPT fdisk tutorial`: diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-1.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-1.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-1.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-1.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-10.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-10.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-10.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-10.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-11.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-11.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-11.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-11.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-12.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-12.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-12.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-12.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-13.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-13.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-13.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-13.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-14.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-14.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-14.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-14.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-15.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-15.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-15.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-15.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-16.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-16.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-16.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-16.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-2.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-2.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-2.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-2.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-3.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-3.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-3.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-3.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-4.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-4.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-4.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-4.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-5.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-5.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-5.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-5.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-6.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-6.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-6.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-6.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-7.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-7.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-7.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-7.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-8.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-8.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-8.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-8.png diff --git a/source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-9.png b/source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-9.png similarity index 100% rename from source/clear-linux/get-started/bare-metal-install/figures/cgdisk-manual-install-9.png rename to source/clear-linux/get-started/cgdisk-manual-install/figures/cgdisk-manual-install-9.png diff --git a/source/clear-linux/get-started/compatibility-check.rst b/source/clear-linux/get-started/compatibility-check.rst index 0223bbe7..798a05a4 100644 --- a/source/clear-linux/get-started/compatibility-check.rst +++ b/source/clear-linux/get-started/compatibility-check.rst @@ -1,11 +1,11 @@ .. _compatibility-check: -Check processor and EFI firmware compatibility with Clear Linux\* -################################################################# +Check processor and EFI firmware compatibility with |CL-ATTR| +############################################################# -On a system that is currently running a Linux operating system, follow the +On a system that is currently running a Linux\* operating system, follow the instructions below to determine if your system's processor and EFI firmware is -capable of running |CLOSIA|. Otherwise, +capable of running |CL-ATTR|. Otherwise, :ref:`run Clear Linux as a Live image ` and then perform the steps below. @@ -19,13 +19,13 @@ below. .. code-block:: console - $ curl -O https://download.clearlinux.org/current/clear-linux-check-config.sh + curl -O https://download.clearlinux.org/current/clear-linux-check-config.sh #. Make the script executable. .. code-block:: console - $ chmod +x clear-linux-check-config.sh + chmod +x clear-linux-check-config.sh #. Run the script. @@ -34,13 +34,13 @@ below. .. code-block:: console - $ ./clear-linux-check-config.sh host + ./clear-linux-check-config.sh host #. Check to see if the host is capable of running |CL| in a container. .. code-block:: console - $ ./clear-linux-check-config.sh container + ./clear-linux-check-config.sh container The script will print a list of test results similar to the output below. All items should return a `SUCCESS` status. This example indicates the diff --git a/source/clear-linux/get-started/get-started.rst b/source/clear-linux/get-started/get-started.rst index 75a0849f..1bbe2c15 100644 --- a/source/clear-linux/get-started/get-started.rst +++ b/source/clear-linux/get-started/get-started.rst @@ -3,21 +3,33 @@ Get started ########### -This section contains information about the installation of |CLOSIA|. +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` -The :ref:`get-started` section provides step-by-step instructions to download -and run |CL| on :ref:`bare metal `, under -a :ref:`virtual machine `, or by way of a -:ref:`live image `. Additionally, it provides useful pre-install -information and instructions on how to complete pre-install tasks. .. toctree:: :maxdepth: 2 + :hidden: - ../reference/system-requirements bare-metal-install/bare-metal-install - bare-metal-install/bare-metal-manual-install - bare-metal-install/cgdisk-manual-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 diff --git a/source/clear-linux/get-started/live-image.rst b/source/clear-linux/get-started/live-image.rst index 79c480b1..05285773 100644 --- a/source/clear-linux/get-started/live-image.rst +++ b/source/clear-linux/get-started/live-image.rst @@ -1,12 +1,12 @@ .. _live-image: -Install Clear Linux as a live image -################################### +Install |CL-ATTR| as a live image +################################# -A live image contains the complete |CLOSIA| operating system and resides +A live image contains the complete |CL-ATTR| operating system and resides on a bootable media such as a USB drive or in a virtual machine -(see :ref:`virtual-machine-install`). This is a -great way to use |CL| without modifying your computer's hard disk. +(see :ref:`virtual-machine-install`). This is a great way to use |CL| +without modifying your computer's hard disk. To create a bootable USB drive with a live image, follow :ref:`our step-by-step instructions` and use the latest |CL| @@ -15,8 +15,8 @@ live image from the `image`_ directory. Look for the .. _boot-live-image: -Boot the Clear Linux live image -******************************* +Boot the |CL| live image +************************ #. Configure the BIOS/UEFI firmware settings of the target system: diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/download-verify-uncompress-windows-fig-1.png b/source/clear-linux/get-started/virtual-machine-install/figures/download-verify-decompress-windows-fig-1.png similarity index 100% rename from source/clear-linux/get-started/virtual-machine-install/figures/download-verify-uncompress-windows-fig-1.png rename to source/clear-linux/get-started/virtual-machine-install/figures/download-verify-decompress-windows-fig-1.png diff --git a/source/clear-linux/get-started/virtual-machine-install/hyper-v.rst b/source/clear-linux/get-started/virtual-machine-install/hyper-v.rst index f8da4baa..201df498 100644 --- a/source/clear-linux/get-started/virtual-machine-install/hyper-v.rst +++ b/source/clear-linux/get-started/virtual-machine-install/hyper-v.rst @@ -3,7 +3,7 @@ Use Hyper-V\* ############# -This section explains how to run |CLOSIA| inside a +This section explains how to run |CL-ATTR| inside a `Windows Server Virtualization`_\* or **Hyper-V** environment. Please ensure you have enabled `Intel® Virtualization Technology @@ -13,13 +13,13 @@ Please ensure you have enabled `Intel® Virtualization Technology (Intel® VT-d) in your BIOS/UEFI firmware configuration. Enable Hyper-V -============== +************** Please refer to the `Microsoft documentation`_ to enable and configure *Hyper-V* on your machine. Create a virtual network -======================== +************************ Once *Hyper-V* has been enabled on your Windows system you will need to create a virtual network in the **Hyper-V Manager**. Refer to the @@ -27,11 +27,11 @@ create a virtual network in the **Hyper-V Manager**. Refer to the a virtual network. Create a virtual machine -======================== +************************ -#. Download and uncompress the latest hyperv disk image +#. Download and decompress the latest hyperv disk image :file:`clear-XXXXX-hyperv.img.gz`, where XXXXX is the latest - available version of |CLOSIA| from our `downloads`_ section. + available version of |CL| from our `downloads`_ section. #. Create a virtual machine using the **Hyper-V Manager**: @@ -41,7 +41,7 @@ Create a virtual machine c. When finished, open VM settings, select Firmware Section and in Secure Boot config, **uncheck** Enable Secure Boot. - .. note:: Currently, Clear Linux does not boot with `secure boot` + .. note:: Currently, |CL| does not boot with `secure boot` enabled. #. Connect to your new VM and start it. You should see a prompt: @@ -52,7 +52,7 @@ Create a virtual machine #. Set a root user password. -Your virtual machine running |CLOSIA| is ready! +Your virtual machine running |CL| is ready! .. _Windows Server Virtualization: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/about/ .. _Microsoft documentation: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v diff --git a/source/clear-linux/get-started/virtual-machine-install/kvm.rst b/source/clear-linux/get-started/virtual-machine-install/kvm.rst index 58a9f986..ac192a9d 100644 --- a/source/clear-linux/get-started/virtual-machine-install/kvm.rst +++ b/source/clear-linux/get-started/virtual-machine-install/kvm.rst @@ -1,13 +1,13 @@ .. _kvm: -Run Clear Linux as a KVM guest OS -################################# +Run |CL-ATTR| as a KVM guest OS +############################### -This section explains how to run |CLOSIA| in a virtualized environment using +This section explains how to run |CL-ATTR| in a virtualized environment using :abbr:`KVM (Kernel-based Virtual Machine)`. Install QEMU-KVM -================ +**************** #. Enable the `Intel® Virtualization Technology`_ (Intel® VT) and the `Intel®Virtualization Technology for Directed I/O`_ (Intel® VT-d) in the @@ -16,38 +16,38 @@ Install QEMU-KVM #. Log in, open a terminal emulator, and get root privilege on the host machine: - .. code-block:: console + .. code-block:: bash - $ sudo -s + sudo -s #. Install `QEMU*-KVM` on the host machine. Below are some example distros. * On |CL|: - .. code-block:: console + .. code-block:: bash - # swupd bundle-add desktop-autostart kvm-host + swupd bundle-add desktop-autostart kvm-host * On Ubuntu\* 16.04 LTS Desktop: - .. code-block:: console + .. code-block:: bash - # apt-get install qemu-kvm + apt-get install qemu-kvm * On Mint\* 18.1 “Serena” Desktop: - .. code-block:: console + .. code-block:: bash - # apt-get install qemu-kvm + apt-get install qemu-kvm * On Fedora\* 25 Workstation: - .. code-block:: console + .. code-block:: bash - # dnf install qemu-kvm + dnf install qemu-kvm Download and launch the virtual machine -======================================= +*************************************** #. Download the latest pre-built |CL| KVM image file from the `image `_ directory. Look for @@ -59,9 +59,9 @@ Download and launch the virtual machine #. Uncompress the downloaded image: - .. code-block:: console + .. code-block:: bash - # unxz clear--kvm.img.xz + unxz clear--kvm.img.xz #. Download the `OVMF file`_ file that provides UEFI support for virtual machines from the `image `_ @@ -74,74 +74,75 @@ Download and launch the virtual machine #. Make the script executable: - .. code-block:: console + .. code-block:: bash - # chmod +x start_qemu.sh + chmod +x start_qemu.sh #. Start the |CL| KVM virtual machine: - .. code-block:: console + .. code-block:: bash - # ./start_qemu.sh clear--kvm.img + ./start_qemu.sh clear--kvm.img #. Log in as ``root`` user and set a new password. SSH access into the virtual machine -=================================== +*********************************** + To interact with the |CL| VM through SSH instead of the console it was launched from, follow these steps. #. Enable SSH in the |CL| VM: - .. code-block:: console + .. code-block:: bash - # cat > /etc/ssh/sshd_config << EOF + cat > /etc/ssh/sshd_config << EOF PermitRootLogin yes EOF #. From the host, SSH into the |CL| VM. The port number ``10022`` is defined in the ``start_qemu.sh`` script. - .. code-block:: console + .. code-block:: bash - # ssh -p 10022 root@localhost + ssh -p 10022 root@localhost Add the GNOME Display Manager (GDM) -=================================== +*********************************** To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps: #. Shutdown the active |CL| VM. - .. code-block:: console + .. code-block:: bash - # shutdown now + shutdown now #. Install a VNC viewer on the host machine. Below are some example distros. * On Clear Linux: - .. code-block:: console + .. code-block:: bash - # swupd bundle-add desktop-apps-extras + swupd bundle-add desktop-apps-extras * On Ubuntu\* 16.04 LTS Desktop: - .. code-block:: console + .. code-block:: bash - # apt-get install vncviewer + apt-get install vncviewer * On Mint\* 18.1 “Serena” Desktop: - .. code-block:: console + .. code-block:: bash - # apt-get install vncviewer + apt-get install vncviewer * On Fedora\* 25 Workstation: - .. code-block:: console + .. code-block:: bash - # dnf install tigervnc + dnf install tigervnc #. Modify the :file:`start_qemu.sh` script to increase memory (``-m``), add graphics driver (``-vga``), and add VNC (``-vnc``, ``-usb``, and @@ -169,48 +170,48 @@ To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps: #. Relaunch the |CL| VM. The UEFI shell will appear. - .. code-block:: console + .. code-block:: bash - # ./start_qemu.sh clear--kvm.img + ./start_qemu.sh clear--kvm.img #. At the UEFI shell, delete the :file:`NvVars` file: - .. code-block:: console + .. code-block:: bash Shell> del FS0:\NvVars #. Exit out of the UEFI shell: - .. code-block:: console + .. code-block:: bash Shell> reset -s #. Relaunch the |CL| VM: - .. code-block:: console + .. code-block:: bash - # ./start_qemu.sh clear--kvm.img + ./start_qemu.sh clear--kvm.img #. From the host machine, open a new terminal emulator window and VNC into the |CL| VM: - .. code-block:: console + .. code-block:: bash - # vncviewer 0.0.0.0 + vncviewer 0.0.0.0 #. Log in as ``root`` user into the |CL| VM. #. Add GDM to the |CL| VM: - .. code-block:: console + .. code-block:: bash - # swupd bundle-add desktop-autostart + swupd bundle-add desktop-autostart #. Reboot the |CL| VM to enable GDM: - .. code-block:: console + .. code-block:: bash - # reboot + reboot #. Go through GDM's out-of-box experience (OOBE). 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 760f8500..7e9ae469 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 @@ -1,26 +1,26 @@ .. _virtual-machine-install: -Install Clear Linux in a virtual machine -######################################## +Install |CL-ATTR| in a virtual machine +###################################### -There are some considerations to make when installing |CL| in a VM. +There are some considerations to make when installing |CL-ATTR| in a VM. First, you need to decide which kernel to use. This document will walk you through the available kernel options to help this decision. At the end of this document, you will be able to select the set of installation steps most suitable to you and install |CL| under a VM. Compatible kernels -================== +****************** -The |CLOSIA| provides the following Linux kernels with a respective +The |CL| provides the following Linux kernels with a respective :ref:`bundle ` for VMs. Specific use cases these bundles serve are provided along with links to their source code. .. include:: ../../reference/compatible-kernels.rst :Start-after: vm-kernels: -Next steps: -=========== +Next steps +********** Now that you have read about the |CL| compatible kernels, choose the appropriate set of step-by-step instructions to proceed. diff --git a/source/clear-linux/get-started/virtual-machine-install/virtualbox.rst b/source/clear-linux/get-started/virtual-machine-install/virtualbox.rst index 520f02fa..3765aa8b 100644 --- a/source/clear-linux/get-started/virtual-machine-install/virtualbox.rst +++ b/source/clear-linux/get-started/virtual-machine-install/virtualbox.rst @@ -1,34 +1,40 @@ .. _virtualbox: -Run pre-configured Clear Linux\* as a VirtualBox\* guest OS +Run pre-configured |CL-ATTR| as a VirtualBox\* guest OS ########################################################### -This section shows how to deploy a pre-configured Clear Linux\* image as a guest on the `VirtualBox hypervisor`_ . +This instruction explains how to deploy a pre-configured |CL-ATTR| image as a guest on the `VirtualBox hypervisor`_ . Download VirtualBox -=================== +******************* VirtualBox\* is a type 2 hypervisor from Oracle. Download and use **version 5.0 or greater** from the `official VirtualBox website`_. .. _create_vm_vbox: -Install VirtualBox -=================== +Prerequisites +************* -#. Enable `Intel® Virtualization Technology`_ (Intel® VT) and - `Intel® Virtualization Technology for Directed I/O`_ (Intel® VT-d) in the - host machine’s BIOS. +The instruction assumes that you have: -#. Log in and open a terminal emulator. +#. Enabled virtualization technology in the host machine's BIOS. + + .. note:: -#. Install VirtualBox on your host machine per the - `appropriate instructions`_. + For help, see: Intel® `Virtualization Technology`_ (Intel® VT). + +#. Installed VirtualBox on your host machine per the + `appropriate instructions`_ for your platform. + +If you have not completed the above steps, do so before continuing. Create a virtual machine in VirtualBox -====================================== +************************************** + +#. Log in to your host and open a terminal emulator. #. Download the `latest`_ **live** version (clear-XXXX-live.img.xz) of - Clear Linux. You can also use this command: + |CL|. You can also use this command: .. code-block:: bash @@ -97,7 +103,7 @@ Create a virtual machine in VirtualBox Run your new VM -=============== +*************** |CL| supports VirtualBox kernel modules used by the Linux kernel 4.14 :abbr:`LTS (Long Term Support)` @@ -140,30 +146,31 @@ To install the VirtualBox kernel modules, here are the steps: clr-boot-manager update - Install Guest Additions ------------------------ +======================= -The kernel modules are shipped with the ``kernel-lts`` bundle; however, -you'll need to install the *user* Linux Guest Additions. To install the -VirtualBox Guest Additions, follow these steps: +The kernel modules are shipped with the ``kernel-lts`` bundle. Insert Guest +Additions CD image using *Devices* menu you'll need to install the *user* +Linux Guest Additions. To install the VirtualBox Guest Additions, +follow these steps: -#. Insert Guest Additions CD image using *Devices* menu - .. image:: ./figures/vbox-cd.png - :alt: VirtualBox CD +#. Insert Guest Additions CD image using *Devices* menu -#. Install Linux users Guest Additions:: + .. image:: ./figures/vbox-cd.png + :alt: VirtualBox CD - install-vbox-lga +#. Install Linux users Guest Additions:: -#. Reboot your system:: + install-vbox-lga - reboot +#. Reboot your system:: + + reboot Troubleshooting ---------------- +=============== On Windows OS, *VirtualBox* cannot do a **Hardware Virtualization** when *Hyper-V* is enabled. @@ -181,11 +188,9 @@ To enable Hyper-V again, you should execute:: bcdedit /set {current} hypervisorlaunchtype Auto -.. _Intel® Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/ - intel-virtualization-technology.html -.. _Intel® Virtualization Technology for Directed I/O: https://software.intel.com/en-us/articles/intel-virtualization-technology-for-directed-io-vt-d-enhancing-intel-platforms-for-efficient-virtualization-of-io-devices .. _appropriate instructions: https://www.virtualbox.org/manual/ch02.html .. _official VirtualBox website: https://www.virtualbox.org/wiki/Downloads .. _VirtualBox hypervisor: https://www.virtualbox.org/ .. _latest: https://download.clearlinux.org/image/ .. _7zip: http://www.7-zip.org/ +.. _Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html \ No newline at end of file diff --git a/source/clear-linux/get-started/virtual-machine-install/vmw-player-preconf.rst b/source/clear-linux/get-started/virtual-machine-install/vmw-player-preconf.rst index d090222b..1355506c 100644 --- a/source/clear-linux/get-started/virtual-machine-install/vmw-player-preconf.rst +++ b/source/clear-linux/get-started/virtual-machine-install/vmw-player-preconf.rst @@ -1,11 +1,11 @@ .. _vmw-player-preconf: -Run pre-configured Clear Linux image as a VMware\* Workstation Player guest OS -############################################################################## +Run pre-configured |CL-ATTR| image as a VMware\* Workstation Player guest OS +############################################################################ `VMware Workstation 14 Player`_ is a type 2 hypervisor. It runs on top of another operating system such as Windows\* or Linux\*. With VMware ESXi, you -can create, configure, manage, and run |CLOSIA| :abbr:`VMs (Virtual Machines)` +can create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)` on your local system. This section shows how to deploy a pre-configured |CL| VMware image on @@ -13,18 +13,12 @@ VMware Workstation 14 Player. In this tutorial, we perform the following steps: -#. Install the VMware Workstation Player hypervisor -#. Download the latest |CL| pre-configured image -#. VMware image Verify the integrity of the |CL| image -#. Uncompress the |CL| image -#. Create and configure a new VM -#. Attach the pre-configured VMware |CL| image -#. Enable EFI boot support -#. Power on the VM +.. contents:: :local: + :depth: 1 .. note:: - The screenshots on this document show the Windows\* version of the + The screenshots on this document show the Windows version of the VMware Workstation 14 Player. The menus and prompts are similar to those in the Linux version save some minor wording differences. @@ -61,14 +55,8 @@ Install the VMware Workstation Player hypervisor For additional help, see the `VMware Workstation Player guide`_. -Clear Linux image types -*********************** - -.. include:: ../../reference/image-types.rst - :Start-after: image-types-content: - -Download the latest Clear Linux VMware image -******************************************** +Download the latest |CL| VMware image +************************************* Get the latest |CL| VMware image from the `image`_ repository. Look for :file:`clear-[version number]-vmware.vmdk.xz`. You can also use @@ -78,13 +66,15 @@ this command: curl -O https://download.clearlinux.org/image/clear-$(curl https://download.clearlinux.org/latest)-vmware.vmdk.xz -.. include:: ../../guides/maintenance/download-verify-uncompress-windows.rst +Visit :ref:`image-types` for additional information about all available |CL| images. + +.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst :Start-after: verify-windows: We also provide instructions for other operating systems: -* :ref:`download-verify-uncompress-linux` -* :ref:`download-verify-uncompress-mac` +* :ref:`download-verify-decompress-linux` +* :ref:`download-verify-decompress-mac` Create and configure a new VM ***************************** @@ -189,10 +179,10 @@ Create and configure a new VM #. Click the :guilabel:`Finish` button. -Attach the pre-configured Clear Linux VMware image -************************************************** +Attach the pre-configured |CL| VMware image +******************************************* -#. Move the downloaded and uncompressed pre-configured |CL| VMware image file +#. Move the downloaded and decompressed pre-configured |CL| VMware image file :file:`clear-[version number]-basic.vmdk` to the directory where your newly-created VM resides. @@ -304,6 +294,9 @@ After configuring the settings above, power on your |CL| virtual machine. #. Click :guilabel:`Play virtual machine`. +Related topics +************** + For other guides on using the VMWare Player and ESXi, see: * :ref:`vmw-player` diff --git a/source/clear-linux/get-started/virtual-machine-install/vmw-player.rst b/source/clear-linux/get-started/virtual-machine-install/vmw-player.rst index 06dc38ee..c7f0f6ab 100644 --- a/source/clear-linux/get-started/virtual-machine-install/vmw-player.rst +++ b/source/clear-linux/get-started/virtual-machine-install/vmw-player.rst @@ -1,11 +1,11 @@ .. _vmw-player: -Install Clear Linux as a VMware\* Workstation Player guest OS -############################################################# +Install |CL-ATTR| as a VMware\* Workstation Player guest OS +########################################################### `VMware Workstation 14 Player`_ is a type 2 hypervisor. It runs on top of -another operating system such as Windows or Linux. With VMware ESXi, you can -create, configure, manage, and run |CLOSIA| :abbr:`VMs (Virtual Machines)` on +another operating system such as Windows\* or Linux\*. With VMware ESXi, you can +create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)` on your local system. This section shows how to create a new VM and install |CL| into it with the @@ -15,17 +15,8 @@ size, number of partitions, installed bundles, etc. In this tutorial, we perform the following steps: -#. Install the VMware Workstation Player hypervisor -#. Download the latest |CL| installer ISO -#. Verify the integrity of the |CL| image -#. Uncompress the |CL| image -#. Create and configure a new VM -#. Attach the |CL| installer ISO to the VM -#. Install |CL| into the new VM -#. Detach the |CL| installer ISO from the VM -#. Power off the VM -#. Enable EFI boot support -#. Power on the VM +.. contents:: :local: + :depth: 1 If you prefer to use a pre-configured |CL| VMware image instead, see our :ref:`vmw-player-preconf` guide. @@ -36,7 +27,7 @@ it, see :ref:`vmware-esxi-install-cl`. .. note:: - The screenshots on this document show the Windows\* version of the + The screenshots on this document show the Windows version of the VMware Workstation 14 Player. The menus and prompts are similar to those in the Linux version save some minor wording differences. @@ -55,42 +46,37 @@ Install the VMware Workstation Player hypervisor * On supported Linux distros: - #. Enable a GUI desktop. - #. Start a terminal emulator. - #. Start the installer by issuing the command below and follow the - guided steps. + #. Enable a GUI desktop. + #. Start a terminal emulator. + #. Start the installer by issuing the command below and follow the + guided steps. - .. code-block:: console + .. code-block:: console - $ sudo sh ./VMware-Player-[version number].x86_64.bundle + sudo sh ./VMware-Player-[version number].x86_64.bundle * On Windows: - #. Start the installer. - #. Follow the setup wizard. + #. Start the installer. + #. Follow the setup wizard. For additional help, see the `VMware Workstation Player guide`_. -Clear Linux image types -*********************** - -.. include:: ../../reference/image-types.rst - :Start-after: image-types-content: - - -Download the latest Clear Linux installer ISO -********************************************* +Download the latest |CL| installer ISO +************************************** Get the latest |CL| installer ISO image from the `image`_ repository. Look for :file:`clear-[version number]-installer.iso.xz`. -.. include:: ../../guides/maintenance/download-verify-uncompress-windows.rst +Visit :ref:`image-types` for additional information about all available |CL| images. + +.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst :Start-after: verify-windows: We also provide instructions for other operating systems: -* :ref:`download-verify-uncompress-linux` -* :ref:`download-verify-uncompress-mac` +* :ref:`download-verify-decompress-linux` +* :ref:`download-verify-decompress-mac` Create and configure a new VM ***************************** @@ -117,7 +103,7 @@ Create and configure a new VM Figure 2: VMware Workstation 14 Player - Select |CL| installer ISO -#. Click the :guilabel:`Browse` button and select the uncompressed |CL| +#. Click the :guilabel:`Browse` button and select the decompressed |CL| installer ISO. #. Click the :guilabel:`Next` button. @@ -204,8 +190,8 @@ Create and configure a new VM #. Click the :guilabel:`Finish` button. -Install Clear Linux into the new VM -*********************************** +Install |CL| into the new VM +**************************** #. Select the newly-created VM and click the :guilabel:`Play virtual machine` button. See Figure 9. @@ -267,7 +253,7 @@ Enable UEFI boot support |CL| needs UEFI support to boot. To enable UEFI, add the following line to the end of your VM's :file:`.vmx` file: -.. code-block:: bash +.. code-block:: console firmware = "efi" @@ -294,6 +280,9 @@ After configuring the settings above, power on your |CL| virtual machine. #. Click :guilabel:`Play virtual machine`. +Related topics +************** + For other guides on using the VMWare Player and ESXi, see: * :ref:`vmw-player-preconf` diff --git a/source/clear-linux/get-started/virtual-machine-install/vmware-esxi-install-cl.rst b/source/clear-linux/get-started/virtual-machine-install/vmware-esxi-install-cl.rst index b99659dc..6436f172 100644 --- a/source/clear-linux/get-started/virtual-machine-install/vmware-esxi-install-cl.rst +++ b/source/clear-linux/get-started/virtual-machine-install/vmware-esxi-install-cl.rst @@ -1,26 +1,18 @@ .. _vmware-esxi-install-cl: -Install Clear Linux as a VMware\* ESXi guest OS -############################################### +Install |CL-ATTR| as a VMware\* ESXi guest OS +############################################# -`VMware ESXi`_ is a type 1 bare-metal hypervisor which runs directly on top of -server hardware. With VMware ESXi, you can create, configure, manage, and run -|CLOSIA| virtual machines in the cloud. +`VMware ESXi`_ is a type 1 bare-metal hypervisor which runs directly on top +of server hardware. With VMware ESXi, you can create, configure, manage, and +run |CL-ATTR| virtual machines in the cloud. This section shows you how to create a new :abbr:`VM (Virtual Machine)` and -install |CL| into it with VMware ESXi 6.5 Update 1. Some of the advantages of -installing |CL| into a new VM is that it provides you flexibility in configuring, -for example: its size, the number of partitions, bundles, etc. -We will perform these steps: +manually install |CL| into it with VMware ESXi 6.5. -#. Download the latest |CL| installer ISO. -#. Verify the integrity of the |CL| image. -#. Uncompress the |CL| image. -#. Upload the |CL| installer ISO to the VMware server. -#. Create and configure a new VM. -#. Install |CL| into the new VM. -#. Reconfigure the VM's settings to boot the newly-installed |CL|. -#. Power on the VM and boot |CL|. +Manually installing |CL| into a new VM provides you some additional +configuration flexibility during installation. For example: alternate +disk sizes, number of partitions, pre-installed bundles, etc. If you would prefer to use a preconfigured |CL| VMware image instead, see :ref:`vmware-esxi-preconfigured-cl-image`. @@ -30,25 +22,33 @@ see :ref:`vmware-esxi-preconfigured-cl-image`. VMware also offers a type 2 hypervisor called `VMware Workstation Player`_ which is designed for the desktop environment. -Visit :ref:`image-types` to learn more about the available images. + See :ref:`vmw-player-preconf` or see :ref:`vmw-player` + + Visit :ref:`image-types` to learn more about all available images. -Download the latest Clear Linux installer ISO -********************************************* +Install steps: + +.. contents:: :local: + :depth: 1 + + +Download the latest |CL| installer ISO +************************************** Get the latest |CL| installer ISO image from the `image`_ repository. Look for :file:`clear-[version number]-installer.iso.xz`. -.. include:: ../../guides/maintenance/download-verify-uncompress-linux.rst - :Start-after: verify-linux: - :end-before: To uncompress a GZ +.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst + :Start-after: incl-decompress-image: + :end-before: incl-decompress-image-end: For alternative instructions on other operating systems, see: -* :ref:`download-verify-uncompress-mac` -* :ref:`download-verify-uncompress-windows` +* :ref:`download-verify-decompress-mac` +* :ref:`download-verify-decompress-windows` -Upload the Clear Linux installer ISO to the VMware server -********************************************************* +Upload the |CL| installer ISO to the VMware server +************************************************** #. Connect to the VMware server and log into an account with sufficient permission to create and manage VMs. @@ -81,7 +81,7 @@ Upload the Clear Linux installer ISO to the VMware server Figure 3: VMware ESXi - Datastore > Upload ISO -#. Select the uncompressed |CL| installer ISO file :file:`clear-[version number]-installer.iso` +#. Select the decompressed |CL| installer ISO file :file:`clear-[version number]-installer.iso` and upload it. Create and configure a new VM @@ -185,8 +185,8 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I #. Click the :guilabel:`Next` button. #. Click the :guilabel:`Finish` button. -Install Clear Linux into the new VM -*********************************** +Install |CL| into the new VM +**************************** #. Power on the VM. @@ -208,8 +208,8 @@ Install Clear Linux into the new VM #. After the installation is complete, follow the |CL| instruction to reboot it. This will restart the installer again. -Reconfigure the VM's settings to boot the newly-installed Clear Linux -********************************************************************* +Reconfigure the VM's settings to boot the newly-installed |CL| +************************************************************** After |CL| has been installed using the installer ISO, it must be detached so it will not run again. Also, in order to boot the newly-installed |CL|, you must @@ -265,8 +265,8 @@ enable UEFI support. #. Click the :guilabel:`Save` button. -Power on the VM and boot Clear Linux -************************************ +Power on the VM and boot |CL| +***************************** After configuring the settings above, power on the VM. @@ -283,8 +283,8 @@ After configuring the settings above, power on the VM. Figure 16: VMware ESXi - Navigator > Virtual Machines > Power on VM -Also see: -********* +Related topics +************** * :ref:`vmware-esxi-preconfigured-cl-image` diff --git a/source/clear-linux/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst b/source/clear-linux/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst index e9f35d57..a1d84fa3 100644 --- a/source/clear-linux/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst +++ b/source/clear-linux/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst @@ -1,31 +1,34 @@ .. _vmware-esxi-preconfigured-cl-image: -Run preconfigured Clear Linux\* image as a VMware\* ESXi guest OS -################################################################# +Run preconfigured |CL-ATTR| image as a VMware\* ESXi guest OS +############################################################# `VMware ESXi`_ is a type 1 bare-metal hypervisor which runs directly on top of server hardware. With VMware ESXi, you can create, configure, manage, -and run |CLOSIA| virtual machines at scale. +and run |CL-ATTR| virtual machines at scale. -This section shows you how to deploy a preconfigured |CL| VMware image on -VMware ESXi 6.5. +This section shows you how to deploy a preconfigured |CL| VMware +:abbr:`VM (Virtual Machine)` image on a VMware ESXi 6.5 host. If you would prefer to perform a manual installation of |CL| into a new VMware ESXi :abbr:`VM (Virtual Machine)` instead, see -:ref:`vmware-esxi-install-cl`. Visit :ref:`image-types` to learn more about -the available images. +:ref:`vmware-esxi-install-cl`. .. note:: VMware also offers a type 2 hypervisor called `VMware Workstation Player` which is designed for the desktop environment. + See :ref:`vmw-player-preconf` or see :ref:`vmw-player`. -.. contents:: :local: - :depth: 2 -Download the latest Clear Linux VMware image -******************************************** +Install steps: + +.. contents:: :local: + :depth: 1 + +Download the latest |CL| VMware image +************************************* Get the latest |CL| VMware prebuilt image from the `image`_ repository. Look for :file:`clear-[version number]-vmware.vmdk.xz`. You can also use @@ -35,20 +38,22 @@ this command: curl -O https://download.clearlinux.org/image/clear-$(curl https://download.clearlinux.org/latest)-vmware.vmdk.xz -.. include:: ../../guides/maintenance/download-verify-uncompress-linux.rst - :Start-after: verify-linux: - :end-before: To uncompress a GZ +Visit :ref:`image-types` for additional information about all available |CL| images. + +.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst + :Start-after: incl-decompress-image: + :end-before: incl-decompress-image-end: For alternative instructions on other operating systems, see: -* :ref:`download-verify-uncompress-mac` -* :ref:`download-verify-uncompress-windows` +* :ref:`download-verify-decompress-mac` +* :ref:`download-verify-decompress-windows` -Upload the Clear Linux image to the VMware server -************************************************* +Upload the |CL| image to the VMware server +****************************************** Once the |CL| VMware prebuilt image has been downloaded and -uncompressed on your local system, it must be uploaded to a datastore +decompressed on your local system, it must be uploaded to a datastore on the VMware ESXi server. The steps in this section can also be referenced from the `VMware documentation on Using the Datastore File Browser`_ @@ -87,11 +92,11 @@ The steps in this section can also be referenced from the `VMware documentation Figure 3: VMware ESXi - Datastore > Upload VMware image -#. Select the uncompressed |CL| VMware image file +#. Select the decompressed |CL| VMware image file :file:`clear-[version number]-vmware.vmdk` and upload it. -Convert the Clear Linux image to an ESXi-supported format -********************************************************* +Convert the |CL| image to an ESXi-supported format +************************************************** Once the |CL| VMware prebuilt image has been uploaded to the VMware ESXi datastore, it must be converted to a format for usable with VMware's ESXi @@ -254,8 +259,8 @@ VMware image. Also, in order to boot |CL|, you must enable UEFI support. #. Click the :guilabel:`Next` button. #. Click the :guilabel:`Finish` button. -Power on the VM and boot Clear Linux -************************************ +Power on the VM and boot |CL| +***************************** After configuring the settings above, power on the VM. @@ -272,8 +277,8 @@ After configuring the settings above, power on the VM. Figure 13: VMware ESXi - Navigator > Virtual Machines > Power on VM -Also see: -========= +Related topics +************** * :ref:`vmware-esxi-install-cl` diff --git a/source/clear-linux/guides/deploy-at-scale.rst b/source/clear-linux/guides/deploy-at-scale.rst new file mode 100644 index 00000000..9b819057 --- /dev/null +++ b/source/clear-linux/guides/deploy-at-scale.rst @@ -0,0 +1,287 @@ +.. _deploy-at-scale.rst: + +Deploying |CL| 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. + +In this document the term *endpoint* refers to a system targeted for +|CL| installation, whether that is a datacenter system or unit deployed in +field. + +.. note:: + + This is not a replacement or blueprint for designing your own IT + operating environment. + + Your |CL| deployment should complement the existing environment and + available tools. It is assumed foundational core IT dependencies of your + environment, such as your network, are healthy and scaled to suit the + deployment. + +.. contents:: :local: + :depth: 2 + +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| +distribution or the option to fork away from the |CL| distribution and +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. + +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 +|CL| upstream. + +#. 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 + act as an intermediary buffer between the OS releases. If you do decide + to act as a gate to |CL| versions, define a desired release cadence for + 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. + |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 *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 + webservers which are serving update content to production machines. + +* swupd update webservers which are serving update content to + production machines (see `mixer process`_ for more information) should be + appropriately scaled. + + 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. + +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 +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 + should include: + + * 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 + +* 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. + + - Generate |CL| bundles and potentially bootable images with your + customizations, if any. + + - Measure against metrics and indicators which are relevant to your + business (e.g. performance, power, etc) from release to release. + + - Integrate with your organization's governance processes, such as change + control. + +Versioning Infrastructure +------------------------- + +|CL| version numbers are very important as they apply to the whole +infrastructure stack from OS components to libraries and +applications. + +Good record keeping is important, so you should keep a detailed registry +and history of previously deployed versions and their contents. + +With a glance at the |CL| version numbers deployed, you should be +able to tell if your Clear systems are patched against a +particular security vulnerability or incorporate a critical new feature. + +Pick an image distribution strategy +=================================== + +Once you have decided on a usage and update strategy, you should understand +*how* |CL| will be deployed to your endpoints. In a large scale +deployment, interactive installers should be avoided in favor of automated +installations or prebuilt images. + +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`_ + +Below are some common ways to install |CL| to systems at scale: + +Baremetal +--------- + +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. + +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`_ + +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. + +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`_. + +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 +applications. + +|CL| is capable of running a Docker host, has a container image which can +be pulled from DockerHub, or can be built as a customized container. +For more information visit the `containers page`_. + +Considerations with stateless systems +===================================== +An important |CL| concept is statelessness and partitioning of system data +from user data. This concept can change the way you think about an at scale +deployment. + +Backup strategy +--------------- + +A |CL| system and its infrastructure should be considered a commodity and +be easily reproducible. Avoid focusing on backing up the operating system +itself or default values. + +Instead, focus on backing up what's important and unique - the application +and data. In other words, only focus on backing up critical areas like +`/home`, `/etc`, and `/var`. + +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`_ + +* |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. + + Your telemetry server is just like any other web application. + |WEB-SERVER-SCALE| + +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`_, +through the *os-cloudguest* bundles which allow you to configure many Day 1 +tasks such as setting hostname, creating users, or placing +SSH keys in an automated way at boot. For more information on +automating configuration during deployment of |CL| endpoints see +the `documentation on bulk provisioning`_ . + +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. + +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 +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, +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 + 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 + necessary. \ No newline at end of file diff --git a/source/clear-linux/guides/guides.rst b/source/clear-linux/guides/guides.rst index 2be109e1..f2c65575 100644 --- a/source/clear-linux/guides/guides.rst +++ b/source/clear-linux/guides/guides.rst @@ -18,3 +18,4 @@ after completing the |CL| :ref:`installation `. maintenance/maintenance network/network + deploy-at-scale diff --git a/source/clear-linux/guides/maintenance/bulk-provision.rst b/source/clear-linux/guides/maintenance/bulk-provision.rst index 6badd952..71e6e1d1 100644 --- a/source/clear-linux/guides/maintenance/bulk-provision.rst +++ b/source/clear-linux/guides/maintenance/bulk-provision.rst @@ -3,7 +3,7 @@ Bulk provision ############## -The |CLOSIA| can be automatically provisioned in bulk using a combination of +The |CL-ATTR| can be automatically provisioned in bulk using a combination of the |CL| installer, **Ister**, and :abbr:`ICIS (Ister Cloud Init Service)`. This guide covers how to perform a bulk provision of |CL| using **Ister** and **ICIS**. @@ -49,7 +49,7 @@ Configuration with the steps it needs to perform an installation. The file outlines what partitions, file systems, and mount points **Ister** should set up. Lastly, the file outlines which bundles to install. See our - :ref:`available-bundles` document for the list of available bundles. The + :ref:`bundles` document for the list of available bundles. The following example shows the contents of an Ister installation file: .. code-block:: json diff --git a/source/clear-linux/guides/maintenance/download-verify-uncompress-linux.rst b/source/clear-linux/guides/maintenance/download-verify-decompress-linux.rst similarity index 69% rename from source/clear-linux/guides/maintenance/download-verify-uncompress-linux.rst rename to source/clear-linux/guides/maintenance/download-verify-decompress-linux.rst index e90c0170..596fd3cc 100644 --- a/source/clear-linux/guides/maintenance/download-verify-uncompress-linux.rst +++ b/source/clear-linux/guides/maintenance/download-verify-decompress-linux.rst @@ -1,15 +1,15 @@ -.. _download-verify-uncompress-linux: +.. _download-verify-decompress-linux: -Download, verify, and uncompress a Clear Linux image on Linux -############################################################# +Download, verify, and decompress a |CL-ATTR| image on Linux +########################################################### -This guide describes the types of |CLOSIA| images available, where to download -them, how to verify the integrity of an image, and how to uncompress it. +This guide describes the types of |CL| images available, where to download +them, how to verify the integrity of an image, and how to decompress it. Instructions for other operating systems are available: -* :ref:`download-verify-uncompress-mac` -* :ref:`download-verify-uncompress-windows` +* :ref:`download-verify-decompress-mac` +* :ref:`download-verify-decompress-windows` Image types *********** @@ -19,8 +19,8 @@ Image types .. _verify-linux: -Verify the integrity of the Clear Linux image -********************************************* +Verify the integrity of the |CL| image +************************************** Before you use a downloaded |CL| image, verify its integrity. This action eliminates the small chance of a corrupted image due to download issues. To @@ -45,24 +45,28 @@ the screen followed by `OK`. For a more in-depth discussion of image verification including checking the certificate see :ref:`image-content-validation`. -Uncompress the Clear Linux image -******************************** +.. incl-decompress-image: + +Decompress the |CL| image +************************* Released |CL| images are compressed with either GNU zip (*.gz*) or XZ (*.xz*). The compression type depends on the target platform or -environment. To uncompress the image, follow these steps: +environment. To decompress the image, follow these steps: #. Start a terminal emulator. #. Go to the directory with the downloaded image. - To uncompress an XZ image, enter: + To decompress an XZ image, enter: .. code-block:: bash unxz clear-[version number]-[image type].xz - To uncompress a GZ image, enter: + To decompress a GZ image, enter: .. code-block:: bash gunzip clear-[version number]-[image type].gz + +.. incl-decompress-image-end: \ No newline at end of file diff --git a/source/clear-linux/guides/maintenance/download-verify-uncompress-mac.rst b/source/clear-linux/guides/maintenance/download-verify-decompress-mac.rst similarity index 68% rename from source/clear-linux/guides/maintenance/download-verify-uncompress-mac.rst rename to source/clear-linux/guides/maintenance/download-verify-decompress-mac.rst index d94be7b6..2507fe3b 100644 --- a/source/clear-linux/guides/maintenance/download-verify-uncompress-mac.rst +++ b/source/clear-linux/guides/maintenance/download-verify-decompress-mac.rst @@ -1,15 +1,15 @@ -.. _download-verify-uncompress-mac: +.. _download-verify-decompress-mac: -Download, verify, and uncompress a Clear Linux image on macOS\* -############################################################### +Download, verify, and decompress a |CL-ATTR| image on macOS\* +############################################################# -This guide describes the types of |CLOSIA| images available, where to download -them, how to verify the integrity of an image, and how to uncompress it. +This guide describes the types of |CL| images available, where to download +them, how to verify the integrity of an image, and how to decompress it. Instructions for other operating systems are available: -* :ref:`download-verify-uncompress-linux` -* :ref:`download-verify-uncompress-windows` +* :ref:`download-verify-decompress-linux` +* :ref:`download-verify-decompress-windows` Image types *********** @@ -19,8 +19,8 @@ Image types .. _verify-mac: -Verify the integrity of the Clear Linux image -********************************************* +Verify the integrity of the |CL| image +************************************** Before you use a downloaded |CL| image, verify its integrity. This action eliminates the small chance of a corrupted image due to download issues. To @@ -41,16 +41,16 @@ If the checksum of the downloaded image is different than the original checksum, the differences will be displayed. Otherwise, an empty output indicates a match and your downloaded image is good. -Uncompress the Clear Linux image -******************************** +Decompress the |CL| image +************************* We compress all released |CL| images by default with either GNU zip (`.gz`) or xz (`.xz`). The compression type we use depends on the target -platform or environment. To uncompress the image, follow these steps: +platform or environment. To decompress the image, follow these steps: #. Start the Terminal app. #. Go to the directory with the downloaded image. -#. Use the :command:`gunzip` command to uncompress either compression type. For example: +#. Use the :command:`gunzip` command to decompress either compression type. For example: .. code-block:: bash diff --git a/source/clear-linux/guides/maintenance/download-verify-uncompress-windows.rst b/source/clear-linux/guides/maintenance/download-verify-decompress-windows.rst similarity index 69% rename from source/clear-linux/guides/maintenance/download-verify-uncompress-windows.rst rename to source/clear-linux/guides/maintenance/download-verify-decompress-windows.rst index 03b892fb..2ee1898f 100644 --- a/source/clear-linux/guides/maintenance/download-verify-uncompress-windows.rst +++ b/source/clear-linux/guides/maintenance/download-verify-decompress-windows.rst @@ -1,15 +1,15 @@ -.. _download-verify-uncompress-windows: +.. _download-verify-decompress-windows: -Download, verify, and uncompress a Clear Linux image on Windows\* -################################################################# +Download, verify, and decompress a |CL-ATTR| image on Windows\* +############################################################### -This guide describes the types of |CLOSIA| images available, where to download -them, how to verify the integrity of an image, and how to uncompress it. +This guide describes the types of |CL-ATTR| images available, where to download +them, how to verify the integrity of an image, and how to decompress it. Instructions for other operating systems are available: -* :ref:`download-verify-uncompress-linux` -* :ref:`download-verify-uncompress-mac` +* :ref:`download-verify-decompress-linux` +* :ref:`download-verify-decompress-mac` Image types *********** @@ -19,8 +19,8 @@ Image types .. _verify-windows: -Verify the integrity of the Clear Linux image -********************************************* +Verify the integrity of the |CL| image +************************************** Before you use a downloaded |CL| image, verify its integrity. This action eliminates the small chance of a corrupted image due to download issues. To @@ -39,19 +39,19 @@ checksum file designated with the suffix `-SHA512SUMS`. #. Manually compare the output with the original checksum value shown in the downloaded checksum file and make sure they match. -Uncompress the Clear Linux image +Decompress the |CL| image ******************************** Released |CL| images are compressed with either GNU zip (*.gz*) or XZ (*.xz*). The compression type depends on the target platform or -environment. To uncompress the image, follow these steps: +environment. To decompress the image, follow these steps: #. Download and install `7-Zip`_. #. Go to the directory with the downloaded image and right-click it. #. From the pop-up menu, select :guilabel:`7-Zip` and select :guilabel:`Extract Here` as shown in Figure 1. - .. figure:: figures/download-verify-uncompress-windows-fig-1.png + .. figure:: figures/download-verify-decompress-windows-fig-1.png :scale: 80 % :alt: 7-Zip extract file diff --git a/source/clear-linux/guides/maintenance/figures/download-verify-uncompress-windows-fig-1.png b/source/clear-linux/guides/maintenance/figures/download-verify-decompress-windows-fig-1.png old mode 100755 new mode 100644 similarity index 100% rename from source/clear-linux/guides/maintenance/figures/download-verify-uncompress-windows-fig-1.png rename to source/clear-linux/guides/maintenance/figures/download-verify-decompress-windows-fig-1.png diff --git a/source/clear-linux/guides/maintenance/hostname.rst b/source/clear-linux/guides/maintenance/hostname.rst new file mode 100644 index 00000000..04c7108e --- /dev/null +++ b/source/clear-linux/guides/maintenance/hostname.rst @@ -0,0 +1,74 @@ +.. _hostname: + +Modify hostname on |CL-ATTR| +############################ + +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 +names: + +* *regression-test* +* *sally-test-box1* +* *az-bldg2-lab* + +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. + +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 + + sudo hostnamectl set-hostname telemetry-test-2-h15 + sudo reboot + +.. 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. + + 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. + +View your hostname +****************** + +View your current hostname using the following command: + +.. code-block:: bash + + hostnamectl + +You should see output similar to: + +.. code-block:: console + + Static hostname : telemetry-test-2-h15 + Pretty hostname : telemetry-test-2-h15 + Icon name : computer-desktop + Chassis : desktop + Machine ID : 4d0d60207a904ebbab96680a51ac1339 + Boot ID : 98d3514e5a984e8cbbdf46a2f0d6b397 + Operating System : Clear Linux OS + 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/maintenance.rst b/source/clear-linux/guides/maintenance/maintenance.rst index 09737c90..712e3844 100644 --- a/source/clear-linux/guides/maintenance/maintenance.rst +++ b/source/clear-linux/guides/maintenance/maintenance.rst @@ -3,8 +3,9 @@ Maintenance guide ################# -This guide provides step-by-step instructions for common tasks associated with -maintaining |CLOSIA| after :ref:`installation ` is completed. +These guides provide step-by-step instructions for common tasks associated +with maintaining |CL-ATTR| after :ref:`installation ` is +completed. .. toctree:: :maxdepth: 2 @@ -19,8 +20,9 @@ maintaining |CLOSIA| after :ref:`installation ` is completed. validate-signatures telemetry-enable time + hostname increase-virtual-disk-size - download-verify-uncompress-linux - download-verify-uncompress-mac - download-verify-uncompress-windows + download-verify-decompress-linux + download-verify-decompress-mac + download-verify-decompress-windows autospec diff --git a/source/clear-linux/guides/maintenance/mixer.rst b/source/clear-linux/guides/maintenance/mixer.rst index b6f7cb3c..9c6e9f66 100644 --- a/source/clear-linux/guides/maintenance/mixer.rst +++ b/source/clear-linux/guides/maintenance/mixer.rst @@ -1,10 +1,10 @@ .. _mixer: -Use mixer tool -############## +Use the mixer tool +################## *Mixing* refers to composing an operating system for specific use cases. -While the default |CLOSIA| provides options to install bundles for various +While the default |CL-ATTR| provides options to install bundles for various server capabilities, some developers may wish to either augment the operating system itself with functionality from their own packages or modify the structure of current bundles to cater to their particular needs. @@ -22,37 +22,39 @@ add it with the :command:`swupd bundle-add` command as follows: Current mixing workflow *********************** +Mixer by default runs *all* build commands in a container to ensure the +correct version of the tooling is being used. This also allows custom mixes +to automatically perform downstream format bumps when upstream releases +a format bump. You can still run mixer natively by appending the *--native* flag to +any of the commands. + +.. note:: + You cannot run mixer if you are already in a container, unless you pass + *--native* to the command. Nested containerization is not supported, nor + is building images using the container mode. There are two different workflows to create your own mix. -First, if your mix only uses |CL| content, *skip step 5* below. +First, if your mix only uses |CL| content, *skip Create custom RPMs* below. Second, if your mix includes your own -:abbr:`RPMs (RPM Package Manager files)`, follow all these steps. +:abbr:`RPMs (RPM Package Manager files)`, follow all steps below. -#. `Create ngninx web server to host mixer updates`_ -#. `Create a workspace`_ -#. `Generate the starting point for your mix`_ -#. `Edit builder.conf`_ -#. `Create custom RPMs`_ - #. `Create or locate RPMs for the mix`_ - #. `Import RPMs into workspace`_ - #. `Create a local RPM repo`_ -#. `List, edit, create, add, remove, or validate bundles`_ -#. `Build the bundle chroots`_ -#. `Create an update`_ -#. `Create an image`_ +.. contents:: + :local: + :depth: 2 + :backlinks: top The following sections contain detailed information on every step of these workflows. .. _create-nginx-web-server: -Create ngninx web server to host mixer updates -********************************************** +Create nginx web server to host mixer updates +============================================= Follow these steps to set up a HTTP service with ``nginx`` web -server, where you can host custom |CL| mixes. +server, where you can host custom |CL| mixes: -#. Install ``web-server-basic``: +#. Install ``web-server-basic``. .. code-block:: bash @@ -68,7 +70,12 @@ server, where you can host custom |CL| mixes. .. code-block:: bash - sudo ln -sf $HOME/mixer/update/www /var/www/mixer + sudo ln -sf /home/clr/mix/update/www /var/www/mixer + + .. note:: + + `/home/clr/mix` is the workspace for the mix (read `Create workspace`) + #. Set up ``nginx`` configuration. @@ -110,7 +117,7 @@ server, where you can host custom |CL| mixes. sudo systemctl start nginx -#. To verify the web server is running, enter in an Internet browser: +#. To verify the web server is running, check it in an Internet browser: .. code-block:: bash @@ -128,7 +135,7 @@ server, where you can host custom |CL| mixes. and a few worker processes. Connect the URL to mixer -======================== +------------------------ Add the URL of the `nginx` server to builder.conf. Your |CL| clients connect to this URL to find the update content. @@ -153,7 +160,7 @@ to this URL to find the update content. VERSIONURL=http://192.168.25.52 Create a workspace -****************** +================== Use the following command to create an empty directory in your |CL| image to use as a **workspace** for mixing: @@ -165,7 +172,7 @@ use as a **workspace** for mixing: This guide assumes your workspace location is :file:`/home/clr/mix`. Generate the starting point for your mix -**************************************** +======================================== In your workspace, initialize mixer with the following command: @@ -186,7 +193,7 @@ For example: .. code-block:: bash - mixer init --clear-version 21060 --mix-version 100 + mixer init --upstream-version 21060 --mix-version 10 Additionally, to build a mix with your own custom RPMs, use the optional @@ -223,10 +230,10 @@ up automatically with the optional *--git* flag, for example: .. code-block:: bash - mixer init --clear-version 21060 --mix-version 100 --local-rpms --all-upstream --git + mixer init --upstream-version 21060 --mix-version 10 --local-rpms --all-upstream --git Edit builder.conf -***************** +================= To configure the mixer tool, edit the :file:`builder.conf` as needed. @@ -255,26 +262,29 @@ following example: .. code-block:: console - [Mixer] - LOCAL_BUNDLE_DIR=/home/clr/mix/local-bundles + #VERSION 1.0 [Builder] - SERVER_STATE_DIR=/home/clr/mix/update - BUNDLE_DIR=/home/clr/mix/mix-bundles - YUM_CONF=/home/clr/mix/.yum-mix.conf - CERT=/home/clr/mix/Swupd_Root.pem - VERSIONS_PATH=/home/clr/mix + CERT = "/home/clr/mix/Swupd_Root.pem" + SERVER_STATE_DIR = "/home/clr/mix/update" + VERSIONS_PATH = "/home/clr/mix" + YUM_CONF = "/home/clr/mix/.yum-mix.conf" - [swupd] - BUNDLE=os-core-update - CONTENTURL= - VERSIONURL= - FORMAT=1 + [Swupd] + BUNDLE = "os-core-update" + CONTENTURL = "" + VERSIONURL = "" [Server] - debuginfo_banned=true - debuginfo_lib=/usr/lib/debug/ - debuginfo_src=/usr/src/debug/ + DEBUG_INFO_BANNED = "true" + DEBUG_INFO_LIB = "/usr/lib/debug" + DEBUG_INFO_SRC = "/usr/src/debug" + + [Mixer] + LOCAL_BUNDLE_DIR = "/home/clr/mix/local-bundles" + LOCAL_REPO_DIR = "" + LOCAL_RPM_DIR = "" + DOCKER_IMAGE_PATH = "clearlinux/mixer" The following variables require further explanation: @@ -287,13 +297,6 @@ The following variables require further explanation: content. Mixer automatically creates the path for you, but the path can be set to any location. In this example, we use the workspace directory. -* The `BUNDLE_DIR` variable sets the path where mixer temporarily stores the - bundle definition files while building chroots. Only the legacy - chroot-builder uses this path. By default, mixer does not generate this - directory until the directory is needed. In our example, the path is set to - :file:`/home/clr/mix/mix-bundles`. The new chroot-builder does not generate - the folder at all. - * The `YUM_CONF` variable sets the path where mixer automatically generates the :file:`.yum-mix.conf` yum configuration file. The yum configuration file points the chroot-builder to the path where the RPMs are stored. @@ -328,24 +331,23 @@ The following variables require further explanation: from where to download the updated content. These links are equivalent to the |CL| `update page`_ but for the mix. -* The `FORMAT` variable relates to format bumps. To learn more about the - `FORMAT` option, refer to :ref:`mixer-format` and the `format bumps wiki`_. - For now, leave the `FORMAT` value unchanged. - * The `VERSIONS_PATH` variable sets the path for the mix version and upstream |CL| version's two state files: :file:`mixversion` and :file:`upstreamversion`. Mixer creates both files for you when you set up the workspace. +* The `DOCKER_IMAGE_PATH` variable sets the base name of the docker image + mixer will pull down in order to run builds in the proper container. + .. note:: If you are working only with |CL| bundles, then skip to `List, edit, create, add, remove, or validate bundles`_. Create custom RPMs -****************** +================== Create or locate RPMs for the mix -================================= +--------------------------------- If you create RPMs from scratch, you can use `autospec`, `mock`, `rpmbuild`, or similar tools to build them. If the RPMs are not built on |CL|, ensure @@ -354,7 +356,7 @@ there is no guarantee they will be compatible. For more information on building the RPMs properly, refer to our `build RPMs instructions`_. Import RPMs into workspace -========================== +-------------------------- #. Create a :file:`local-rpms` directory in your workspace, for example, :file:`/home/clr/mix/local-rpms`. @@ -371,7 +373,7 @@ Mixer uses this directory to find the RPMs to build a local RPM repo for yum to use. Create a local RPM repo -======================= +----------------------- #. Create an empty directory in your workspace named :file:`local-yum`. #. Add the path to your :file:`builder.conf` file: @@ -385,7 +387,7 @@ Create a local RPM repo .. code-block:: bash - sudo mixer add-rpms + mixer add-rpms After the tool exits, you should see the RPMs and a repository data directory in :file:`/home/clr/mix/local-yum`. If the RPMs are not all in this @@ -393,7 +395,7 @@ directory in :file:`/home/clr/mix/local-yum`. If the RPMs are not all in this and not corrupt. List, edit, create, add, remove, or validate bundles -**************************************************** +==================================================== The bundles in the mix are specified in the mix bundle list. Mixer stores this list as a flat file called :file:`mixbundles` in the path set by the @@ -403,7 +405,7 @@ initialization. Mixer reads and writes the bundle list file when you change the bundles of the mix. List the bundles in the mix -=========================== +--------------------------- To view the bundles already in the mix, enter the following command: @@ -463,7 +465,7 @@ Both the local and upstream :command:`bundle list` commands accept the between the bundles in the mix. Edit the bundles in the mix -=========================== +--------------------------- **Mixer always checks local bundles first and the upstream bundles second.** @@ -499,7 +501,7 @@ can edit multiple bundles with the following command: mixer bundle edit bundle1 bundle2 [bundle3 ...] Create bundles for the mix -========================== +-------------------------- To create a totally **new bundle**, the bundle name you specify cannot exist upstream. If that is the case, create a :file:`new-bundle` with the following @@ -526,7 +528,7 @@ as part of the bundle. mixer bundle edit new-bundle1 new-bundle2 [new-bundle3 ...] Add bundles to the mix -====================== +---------------------- Add `bundle1` to your mix with the following command: @@ -549,7 +551,7 @@ To add multiple bundles at once, use the following command: mixer bundle add bundle1 bundle2 [bundle3 ...] Remove bundles from the mix -=========================== +--------------------------- Remove `bundle1` from your mix with the following command: @@ -584,7 +586,7 @@ keep the bundle in the mix bundles list, mixer will not find a valid bundle definition file and will produce an error. Validate the bundles in the mix -=============================== +------------------------------- Mixer performs basic validation on all bundles when used throughout the system. @@ -616,7 +618,7 @@ Validate multiple bundles with the following command: mixer bundle validate bundle1 bundle2 [bundle3 ...] Managing bundles with Git -========================= +------------------------- If you initialized your workspace to be tracked as a git repository with the :command:`mixer init --git` command, it might be useful to apply a @@ -632,63 +634,43 @@ when the command completes, for example: mixer bundle remove --git bundle1 Build the bundle chroots -************************ +======================== To build all the ``chroots`` based on the defined bundles, use the following command in your workspace: .. code-block:: bash - sudo mixer build chroots + mixer build bundles If the mix has many bundles, this step might take some time. -By default, mixer uses the legacy chroot-builder. In this mode, mixer -automatically gathers the bundle definition files for the bundles in the mix -into a :file:`mix-bundles` directory. The directory's path is set in the -`BUNDLE_DIR` variable in the :file:`builder.conf`. **Do not edit these -files.** Mixer automatically deletes the contents of the :file:`mix-bundles` -directory before repopulating the directory on-the-fly as mixer builds the -chroots. +Mixer automatically gathers the bundle definition files for the upstream +bundles into a :file:`upstream-bundles` directory, and user bundles should +be placed directly into :file:`local-bundles`. The local path is set in +the `LOCAL_BUNDLE_DIR` variable in the :file:`builder.conf`. **Do not edit +files in upstream-bundles.** Mixer automatically deletes the contents of +the :file:`upstream-bundles` directory before repopulating the directory +on-the-fly if a new version must be downloaded. -We have added a new chroot-builder to the mixer tool itself. While this is -currently an experimental feature, you should use the new chroot-builder. To -use the new chroot-builder, use the following command with the -*--new-chroots* flag: - -.. code-block:: bash - - sudo mixer build chroots --new-chroots - -We will soon deprecate the legacy chroot-builder. When we do, mixer will use -the new version automatically. Create an update -**************** +================ Create an update with the following command: .. code-block:: bash - sudo mixer build update + mixer build update When the build completes, you can find the mix update content under :file:`/home/clr/mix/update/www/VER`. In our example, the update content is found in :file:`/home/clr/mix/update/www/{}`. `` is the defined mix version, which is 10 by default. -By default, mixer uses the legacy `swupd-server` to generate the update -content. However, we have built a new implementation into the mixer tool -itself. While this is currently an experimental feature, you should use the -new `swupd-server`. To use the the new `swupd-server`, use the following -command with the *--new-swupd* flag: - .. code-block:: bash - sudo mixer build update --new-swupd - -We will soon deprecate the legacy `swupd-server`. When we do, mixer will use -the new version automatically. + mixer build update Mixer creates all the content needed to make a fully usable mix with this step. However, only *zero packs* are automatically generated. Zero packs are @@ -700,19 +682,18 @@ mix version to another, with the following command: .. code-block:: bash - sudo mixer-pack-maker.sh --to --from -S /home/clr/mix/update + mixer build delta-packs --to --from -The pack-maker generates all delta packs for the bundles changed from -`PAST_VERSION` to `MIX_VERSION`. If your `STATE_DIR` is in a different -location, specify the location with the *-S* flag. Mixer cannot -create delta packs for the first build because the update is from version 0. -Version 0 implicitly has no content. Thus, mixer can generate no deltas. +This command generates all delta packs for the bundles changed from +`PAST_VERSION` to `MIX_VERSION`. Mixer cannot create delta packs for the +first build because the update is from version 0. Version 0 implicitly has +no content, thus mixer can generate no deltas. For subsequent builds, you can run :file:`mixer-pack-maker.sh` to generate delta content between them, for example: 10 to 20. Create an image -***************** +=============== Since mixer uses the `ister` tool to create a bootable image from your updated content, we must first configure the `ister` tool. To configure the @@ -721,7 +702,7 @@ with the default values from the `ister` package with the following command: .. code-block:: bash - sudo cp /usr/share/defaults/ister/ister.json relase-image-config.json + sudo cp /usr/share/defaults/ister/ister.json release-image-config.json For reference, you can inspect the `Clear Linux ister configuration file`_ used for releases. @@ -750,7 +731,7 @@ With the `ister` tool configured, build the image with the following command: .. code-block:: bash - sudo mixer build image --format 1 + sudo mixer build image Mixer automatically looks for the :file:`release-image-config.json` file, but you can freely choose the filename. To use a different name, simply pass the @@ -758,7 +739,7 @@ you can freely choose the filename. To use a different name, simply pass the .. code-block:: bash - sudo mixer build image --format 1 --template path/to/file.config + sudo mixer build image --template path/to/file.config By default, `ister` uses the format version of the build machine it runs on. Therefore, if the format you are building differs from the format of the |CL| @@ -770,7 +751,7 @@ flag. Find the current format version of your OS with the following command: sudo cat /usr/share/defaults/swupd/format Update the next mix version information -*************************************** +======================================= Increment the mix version number for the next mix with the following command: @@ -784,14 +765,14 @@ amount, use the *--increment* flag, for example: .. code-block:: bash - mixer versions update --increment 100 + mixer versions update --increment 10 Alternatively, to set the mix version to a specific value, use the *--mix-version* flag, for example: .. code-block:: bash - mixer versions update --mix-version 200 + mixer versions update --mix-version 20 The :command:`mixer versions update` command does not allow you to set the mix version to a value less than its current value. The mix version is @@ -837,25 +818,24 @@ modifications as needed, for example: .. code-block:: bash - sudo mixer build chroots + mixer build chroots #. Build and update with: .. code-block:: bash - sudo mixer build update + mixer build update #. Optionally, you can create delta packs with: .. code-block:: bash - sudo mixer-pack-maker.sh --to --from -S / - home/clr/mix/update + mixer build delta-packs --to --from .. _mixer-format: Format version -************** +============== The `Format` variable set in the :file:`builder.conf` file can be more precisely referred to as an OS *compatibility epoch*. Versions of the OS @@ -876,9 +856,10 @@ reaching the final release in the old format can a client continue to update to releases in the new format. When creating a custom mix, the format version should start at "1" or some -known number. The format version should increment only when a compatibility -breakage is introduced. Normal updates, like updating a software package for -example, do not require a format increment. +known number such as the host system format. The format version should +increment only when a compatibility breakage is introduced. Normal updates, +like updating a software package for example, do not require a format +increment. .. _update page: https://cdn.download.clearlinux.org/update/ diff --git a/source/clear-linux/guides/maintenance/swupd-guide.rst b/source/clear-linux/guides/maintenance/swupd-guide.rst index e22a2695..db0ba772 100644 --- a/source/clear-linux/guides/maintenance/swupd-guide.rst +++ b/source/clear-linux/guides/maintenance/swupd-guide.rst @@ -3,7 +3,7 @@ Use swupd ######### -*swupd* manages the software update capability of |CLOSIA|. It can check for +*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. @@ -165,7 +165,7 @@ binary. Note that it may be present in multiple bundles: Adding a bundle =============== -Start by selecting a bundle from the list of :ref:`available-bundles`. In +Start by selecting a bundle from the list of :ref:`bundles`. In this example we're adding dev-utils-dev, which is useful for development. .. code-block:: bash diff --git a/source/clear-linux/guides/maintenance/swupd-search.rst b/source/clear-linux/guides/maintenance/swupd-search.rst index 2a066451..835775ab 100644 --- a/source/clear-linux/guides/maintenance/swupd-search.rst +++ b/source/clear-linux/guides/maintenance/swupd-search.rst @@ -3,12 +3,8 @@ Use swupd search to find bundles ################################ -.. contents:: - :local: - :depth: 2 - -This document shows you how to use `swupd search` to find and add -bundles. +This document explains how to use `swupd search` to find and add +bundles in |CL-ATTR|. Assumptions *********** @@ -18,15 +14,15 @@ This guide assumes you: * Possess a basic knowledge of :ref:`swupd ` * Understand :ref:`how swupd differs ` from other Linux\* distributions -* May use :ref:`mixer` to build your own |CL| OS +* May :ref:`mixer` to produce a custom distribution/image How do I search for a bundle? ***************************** Use `swupd search` to locate the bundle where the application binary exists. -Example: Kata Containers -======================== +Example: Kata\* Containers +========================== Containers have revolutionized the way we manage cloud infrastructure. Traditional containers often share the same OS kernel, which raises @@ -34,7 +30,7 @@ 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 `this 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? @@ -118,24 +114,24 @@ We need to find *kata* containers in a bundle. How do we search for it? Calling post-update helper scripts. Successfully installed 1 bundle -FAQ -=== +Related Topics +============== -Find answers to these common questions: +Learn how to: -* How do I install and *use* :ref:`Kata Containers ` on |CL|? +* :ref:`kata` -* How do I :ref:`kata_migration`? +* :ref:`kata_migration` -* How do I show all :ref:`bundles available `? +* :ref:`swupd-guide` -* How do I :ref:`update swupd`? +* :ref:`Show all available bundles ` -* How do I :ref:`remove bundles`? +* :ref:`Remove bundles` .. _Kata Containers: https://clearlinux.org/blogs/clear-linux-os-announces-support-kata-containers -.. _this bundle: https://github.com/clearlinux/clr-bundles/blob/master/bundles/containers-virt +.. _one bundle: https://github.com/clearlinux/clr-bundles/blob/master/bundles/containers-virt .. _Bundle Definition Files: https://github.com/clearlinux/clr-bundles diff --git a/source/clear-linux/guides/maintenance/telemetry-enable.rst b/source/clear-linux/guides/maintenance/telemetry-enable.rst index 6d401226..7b8fc2b5 100644 --- a/source/clear-linux/guides/maintenance/telemetry-enable.rst +++ b/source/clear-linux/guides/maintenance/telemetry-enable.rst @@ -1,12 +1,12 @@ .. _telemetry-enable: -Enable and disable telemetry in Clear Linux -########################################### +Enable and disable telemetry in |CL-ATTR| +######################################### -|CLOSIA| includes a telemetry solution as part of the OS that records events +|CL-ATTR| includes a telemetry solution as part of the OS that records events of interest and reports them back to the development team via the telemetrics -daemon, **telemd**. This functionality is maintained in the -**telemetrics** software bundle. +client daemons, **telempobd** and **telempostmd**. This functionality is +maintained in the **telemetrics** software bundle. .. note:: The telemetry functionality adheres to `Intel privacy policies`_ @@ -21,7 +21,7 @@ Install the telemetry software bundle ************************************* During the initial installation of |CL|, you are requested to join the -stability enhancement program and allow |CLOSIA| to collect anonymous reports +stability enhancement program and allow |CL| to collect anonymous reports to improve system stability. If you choose not to join this program, then the telemetry software bundle is not added to your system. @@ -35,29 +35,29 @@ root user or with :command:`sudo` privileges: This adds the telemetrics-client to your system and you will automatically opt-in for the service. -Enable Telemetry -**************** +Enable telemetry +***************** To start telemetry on your system, run the following command: .. code-block:: bash - sudo telemctl start + sudo telemctl start -This enables and starts the :command:`telemd` daemon and your system will +This enables and starts the :command:`telemprobd` and :command:`telempostd` daemons and your system will begin to send telemetry data to the server defined in the file :file:`/etc/telemetrics/telemetrics.conf`. If this file does not exist, the -:command:`telemd` daemon will use the file +:command:`telemprobd` and :command:`telempostd` daemons will use the file :file:`/usr/share/defaults/telemetrics/telemetrics.conf`. -Disable Telemetry +Disable telemetry ***************** -To disable the telemetry daemon, run the following command: +To disable both of the telemetry daemons, run the following command: .. code-block:: bash - sudo telemctl stop + sudo telemctl stop Opt-out of telemetry ******************** @@ -67,7 +67,7 @@ telemetry service: .. code-block:: bash - sudo telemctl opt-out + sudo telemctl opt-out This creates the file :file:`/etc/telemetrics/opt-out` and stops the telemetry services. @@ -80,16 +80,17 @@ command and start the service: .. code-block:: bash - sudo telemctl opt-in + sudo telemctl opt-in This removes the file :file:`/etc/telemetrics/opt-out` file, if it exists, and starts the telemetry services. .. note:: - To opt-in but not immediately start telemetry services, you will need to - run the command :command:`sudo telemctl stop` after the :command:`opt-in` - command is entered. Once you are ready to start the service, enter the - command :command:`sudo telemctl start`. + + To opt-in but not immediately start telemetry services, you will need to + run the command :command:`sudo telemctl stop` after the :command:`opt-in` + command is entered. Once you are ready to start the service, enter the + command :command:`sudo telemctl start`. Remove the telemetry software bundle ************************************ @@ -99,7 +100,7 @@ To completely remove telemetrics from your system, use the command .. code-block:: bash - sudo swupd bundle-remove telemetrics + sudo swupd bundle-remove telemetrics Additional resources ******************** @@ -109,8 +110,7 @@ Additional resources * :ref:`telemetry-backend` * https://github.com/clearlinux/telemetrics-client -.. _`Intel privacy policies`: - https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html +.. _Intel privacy policies: https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html .. _`Telemetry feature description`: https://clearlinux.org/features/telemetry diff --git a/source/clear-linux/guides/maintenance/validate-signatures.rst b/source/clear-linux/guides/maintenance/validate-signatures.rst index 1001369a..1a99afc6 100644 --- a/source/clear-linux/guides/maintenance/validate-signatures.rst +++ b/source/clear-linux/guides/maintenance/validate-signatures.rst @@ -49,13 +49,7 @@ used for illustrative purposes. You may use any image of |CL| you choose. .. code-block:: console - sha512sum ./clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz > sha512sum.out - - .. important:: - - The ``./`` in the file name must be included because it is part of the - SHA512 sum of the image. Without it, the validation of the signature - of the image will fail. + 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 @@ -84,7 +78,7 @@ these steps manually when performing a ``swupd update``. # MoM curl -O https://download.clearlinux.org/update/$(curl https://download.clearlinux.org/latest)/Manifest.MoM # Signature of MoM - curl -O https://download.clearlinux.org/update/$(curl https://download.clearlinux.org/latest)/Manifest.sig + curl -O https://download.clearlinux.org/update/$(curl https://download.clearlinux.org/latest)/Manifest.MoM.sig # Swupd certificate curl -O https://download.clearlinux.org/releases/$(curl https://download.clearlinux.org/latest)/clear/Swupd_Root.pem diff --git a/source/clear-linux/guides/network/custom-clear-container.rst b/source/clear-linux/guides/network/custom-clear-container.rst index 5615a1d8..5f4b1009 100644 --- a/source/clear-linux/guides/network/custom-clear-container.rst +++ b/source/clear-linux/guides/network/custom-clear-container.rst @@ -1,11 +1,11 @@ .. _custom-clear-container: -Build a custom Clear Linux based Docker container image +Build a custom |CL-ATTR| based Docker container image ####################################################### -The official base |CLOSIA| 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. +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 ************* @@ -117,7 +117,7 @@ Build the base container image #. Optionally, you can include additional bundles with the base image. #. Identify the desired bundles on the |CL| website's - :ref:`available-bundles` page or execute the + :ref:`bundles` page or execute the :command:`swupd bundle-list -a` command. #. Create reference files for the identified bundles. For example, @@ -370,9 +370,4 @@ Example output: ---> ec23189ef954 Removing intermediate container 7694989e97de Successfully built ec23189ef954 - Successfully tagged my-clearlinux-remove-pxe-server-bundle:latest - -For more details, refer to: - -* :ref:`cc-getting-started` -* :ref:`architecture-overview` + Successfully tagged my-clearlinux-remove-pxe-server-bundle:latest \ No newline at end of file diff --git a/source/clear-linux/guides/network/figures/pktgen_lw3fd.png b/source/clear-linux/guides/network/figures/pktgen_lw3fd.png index 0e5a660c..d17318b1 100644 Binary files a/source/clear-linux/guides/network/figures/pktgen_lw3fd.png and b/source/clear-linux/guides/network/figures/pktgen_lw3fd.png differ diff --git a/source/clear-linux/reference/bundle-commands.rst b/source/clear-linux/reference/bundle-commands.rst index 81c8edd8..47c1f5d2 100644 --- a/source/clear-linux/reference/bundle-commands.rst +++ b/source/clear-linux/reference/bundle-commands.rst @@ -15,7 +15,8 @@ To see the list of all available bundles, enter: sudo swupd bundle-list --all -Alternatively, you may reference the `available bundle list`_ webpage. +Alternatively, you can view our :ref:`available bundles ` +webpage. To search for bundles and their contents, enter: @@ -44,4 +45,3 @@ To reference the :command:`swupd` man page, enter: man swupd -.. _available bundle list: https://clearlinux.org/documentation/clear-linux/reference/bundles/available-bundles diff --git a/source/clear-linux/reference/bundles/bundles.html b/source/clear-linux/reference/bundles/bundles.html index a0d14250..2cfc7caa 100644 --- a/source/clear-linux/reference/bundles/bundles.html +++ b/source/clear-linux/reference/bundles/bundles.html @@ -68,30 +68,63 @@ R-extras

Improve the user experience with a common set of pre-built R libraries.

  • Includes (R-basic) bundle.
  • -
  • Includes (libX11client) bundle.
  • +
  • Includes (R-datasets) bundle.
  • amateur-radio -

    Applications to support amateur radio operations. + + +

    Applications to support amateur radio operations.

  • Includes (desktop-gnomelibs) bundle.
  • -
  • Includes (libX11client) bundle.
  • +
  • Includes (libX11client) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +

    ansible -

    + +

    + Automates software provisioning, configuration management, and application deployment. +

    + application-server -

    Run an application server via HTTP. -

  • Includes (web-server-basic) bundle.
  • + +

    Run an application server via HTTP. +

  • Includes (web-server-basic) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +

    + + + audit + + +

    System audit tools.

    + + + + + + axel + + +

    Download accelerator.

    + + + bc -

    + +

    + Basic calculator, an arbitrary-precision calculator language. +

    + @@ -99,16 +132,17 @@

    Tools and frameworks for big data management.

  • Includes (R-basic) bundle.
  • Includes (java-basic) bundle.
  • -
  • Includes (libX11client) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • Includes (python3-basic) bundle.
  • bmap-tools -

    + +

    + Tools for creating the block map (bmap) for a file and copying files. Alternative to "dd" or "cp". +

    + @@ -122,63 +156,96 @@ - c-basic -

    Build and run C/C++ language programs.

    + casync + +

    + Content Addressable Data Synchronizer to distribute frequently-updated file system images over the Internet. +

    + - clamav -

    + c-basic + +

    Build and run C/C++ language programs. +

  • Includes (perl-basic).
  • +

    + + c-basic-legacy + +

    Build and run 32-bit C/C++ language programs. +

    + + + + clamav + +

    + Clam AntiVirus is an anti-virus toolkit for Unix. +

    + + + + + cloud-api + +

    API helpers for cloud access. +

  • Includes (python3-basic) bundle.
  • +

    + + + cloud-control

    Run a cloud orchestration server.

  • Includes (kvm-host) bundle.
  • -
  • Includes (libX11client) bundle.
  • Includes (network-basic) bundle.
  • -
  • Includes (perl-basic) bundle.
  • +
  • Includes (openssl) bundle.
  • Includes (python3-basic) bundle.
  • +
  • Includes (cloud-api) bundle.
  • cloud-native-basic

    Contains ClearLinux native software for Cloud. -

  • Includes (containers-basic) bundle.
  • Includes (containers-virt) bundle.
  • -
  • Includes (kernel-container) bundle.
  • +
  • Includes (ethtool) bundle.
  • clr-devops

    Run all Clear Linux devops workloads. -

  • Includes (java-basic) bundle.
  • -
  • Includes (koji) bundle.
  • -
  • Includes (libX11client) bundle.
  • -
  • Includes (mixer) bundle.
  • -
  • Includes (os-core-update) bundle.
  • Includes (os-installer) bundle.
  • -
  • Includes (package-utils) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +
  • Includes (os-core-update) bundle.
  • +
  • Includes (mixer) bundle.
  • +
  • Includes (java-basic) bundle.
  • Includes (rust-basic) bundle.
  • +
  • Includes (koji) bundle.
  • Includes (scm-server) bundle.
  • -
  • Includes (sysadmin-basic) bundle.
  • Includes (web-server-basic) bundle.
  • cockpit -

    + +

    + Web based administration for GNU/Linux servers. +

    + containers-basic -

    Run container applications from Dockerhub.

    + +

    Run container applications from Dockerhub. +

  • Includes (iproute2) bundle.
  • +
  • Includes (p11-kit) bundle.
  • +

    @@ -191,111 +258,125 @@ - containers-virt + containers-virt

    Run container applications from Dockerhub in lightweight virtual machines.

  • Includes (containers-basic) bundle.
  • -
  • Includes (kernel-container) bundle.
  • containers-virt-dev

    All packages required to build the containers-virt bundle. -

  • Includes (containers-basic) bundle.
  • +
  • Includes (containers-basic-dev) bundle.
  • Includes (containers-virt) bundle.
  • Includes (dev-utils) bundle.
  • -
  • Includes (kernel-container) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • cpio -

    + +

    + File archiver utility. +

    + cryptography -

    Encrypt, decrypt, sign and verify objects.

    + +

    Encrypt, decrypt, sign and verify objects. +

  • Includes (openssl) bundle.
  • +

    curl -

    + +

    + Transfer data to/from a URL. +

    + darktable -

    + +

    + Photography workflow application. +

    + database-basic -

    Run an SQL database.

    + +

    Run an SQL database. +

  • Includes (python3-basic) bundle.
  • +

    - database-basic-dev -

    All packages required to build the database-basic bundle. + database-basic-dev + +

    All packages required to build the database-basic bundle.

  • Includes (database-basic) bundle.
  • Includes (dev-utils) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +

    desktop

    Run the GNOME GUI desktop environment. +

  • Includes (libX11client) bundle.
  • Includes (desktop-apps) bundle.
  • Includes (desktop-assets) bundle.
  • Includes (desktop-gnomelibs) bundle.
  • Includes (desktop-locales) bundle.
  • -
  • Includes (libX11client) bundle.
  • -
  • Includes (python3-basic) bundle.
  • -
  • Includes (sysadmin-basic) bundle.
  • +
  • Includes (openssl) bundle.
  • +
  • Includes (sysadmin-basic) bundle.
  • +
  • Includes (which) bundle.
  • +
  • Includes (wpa_supplicant)
  • +

    desktop-apps

    Applications for the desktop. -

  • Includes (desktop-gnomelibs) bundle.
  • Includes (libX11client) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +
  • Includes (desktop-gnomelibs) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +

    desktop-apps-extras

    Larger set of applications for the desktop.

  • Includes (desktop-gnomelibs) bundle.
  • -
  • Includes (libX11client) bundle.
  • +
  • Includes (desktop-kde-apps) bundle.
  • Includes (python3-basic) bundle.
  • desktop-assets -

    Images and Icons for the desktop. -

  • Includes (desktop-gnomelibs) bundle.
  • -
  • Includes (libX11client) bundle.
  • + +

    Images and Icons for the desktop. +

  • Includes (desktop-gnomelibs) bundle.
  • - desktop-autostart -

    Bundle to cause the UI to automatically start at boot. + desktop-autostart + + +

    Bundle to cause the UI to automatically start at boot.

  • Includes (desktop) bundle.
  • -
  • Includes (desktop-apps) bundle.
  • -
  • Includes (desktop-assets) bundle.
  • -
  • Includes (desktop-gnomelibs) bundle.
  • -
  • Includes (desktop-locales) bundle.
  • -
  • Includes (libX11client) bundle.
  • -
  • Includes (python3-basic) bundle.
  • -
  • Includes (sysadmin-basic) bundle.
  • +

    @@ -303,17 +384,8 @@ desktop-dev

    All packages required to build the desktop bundle.

  • Includes (desktop) bundle.
  • -
  • Includes (desktop-apps) bundle.
  • -
  • Includes (desktop-assets) bundle.
  • -
  • Includes (desktop-dev) bundle.
  • -
  • Includes (desktop-gnomelibs) bundle.
  • -
  • Includes (desktop-locales) bundle.
  • Includes (dev-utils) bundle.
  • -
  • Includes (libX11client) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • -
  • Includes (sysadmin-basic) bundle.
  • Includes (sysadmin-basic-dev) bundle.
  • @@ -326,9 +398,46 @@ desktop-i3 -

    + +

    + Run the i3 desktop environment. +

    + + + desktop-kde + +

    + Applications for the desktop from the KDE ecosystem. +

  • Includes (desktop-kde-libs) bundle.
  • +
  • Includes (desktop-kde-apps) bundle.
  • +
  • Includes (qt-basic) bundle.
  • +

    + + + + + desktop-kde-apps + +

    + Applications for the desktop from the KDE ecosystem. +

  • Includes (desktop-kde-libs) bundle.
  • +
  • Includes (qt-basic) bundle.
  • +

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

    + Helper libraries from the KDE ecosystem. +

  • Includes (qt-basic) bundle.
  • +

    + + + desktop-locales

    Translations and documentation for desktop components.

    @@ -337,8 +446,11 @@ dev-utils

    Assist application development. +

  • Includes (git) bundle.
  • +
  • Includes (openssl) bundle
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +

    @@ -347,15 +459,17 @@

    All packages required to build the dev-utils bundle.

  • Includes (dev-utils) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • Includes (perl-basic-dev) bundle.
  • -
  • Includes (python3-basic) bundle.
  • dfu-util -

    + +

    + Device Firmware Upgrade Utilities. +

    + @@ -365,65 +479,225 @@ diffoscope -

    + +

    + In-depth comparison of files, archives, and directories. +

    + - + + + diffutils + +

    + Tools for file comparisons and differences. +

    + + + + + docutils + +

    + Tools for converting text to other formats (e.g. HTML, XML, LaTeX). +

    + + + + + + domotica + +

    Home automation software collection. +

  • Includes (cloud-api) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +

    + + + + + dovecot + +

    + Security focused IMAP and POP3 email serverSecurity focused IMAP and POP3 email server. +

    + + + dtc -

    + +

    + Device Tree Compiler, to describe non-discoverable hardware. +

    + - + editors

    Run popular terminal text editors.

  • Includes (emacs) bundle.
  • -
  • Includes (perl-basic-dev) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +
  • Includes (joe) bundle.
  • Includes (vim) bundle.
  • editors-dev -

    All packages required to build the editors bundle. + +

    All packages required to build the editors bundle.

  • Includes (dev-utils) bundle.
  • Includes (editors) bundle.
  • -
  • Includes (emacs) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • -
  • Includes (vim) bundle.
  • +

    + + education + +

    Educational applications. +

  • Includes (desktop-gnomelibs) bundle.
  • +
  • Includes (desktop-kde-libs) bundle.
  • +
  • Includes (libX11client) bundle.
  • +
  • Includes (qt-basic) bundle.
  • +
  • Includes (education-preschool) bundle.
  • +
  • Includes (education-primary) bundle.
  • +
  • Includes (education-secondary) bundle.
  • +
  • Includes (education-tertiary) bundle.
  • +

    + + + + + education-preschool + +

    Educational applications for the preschool level. +

  • Includes (desktop-gnomelibs) bundle.
  • +
  • Includes (desktop-kde-libs) bundle.
  • +
  • Includes (libX11client) bundle.
  • +
  • Includes (qt-basic) bundle.
  • +

    + + + + + education-primary + +

    Educational applications for the primary school level. +

  • Includes (desktop-gnomelibs) bundle.
  • +
  • Includes (desktop-kde-libs) bundle.
  • +
  • Includes (libX11client) bundle.
  • +
  • Includes (qt-basic) bundle.
  • +

    + + + + + education-secondary + +

    Educational applications for the secondary school level. +

  • Includes (desktop-gnomelibs) bundle.
  • +
  • Includes (desktop-kde-libs) bundle.
  • +
  • Includes (libX11client) bundle.
  • +
  • Includes (qt-basic) bundle.
  • +

    + + + + + education-secondary + +

    Educational applications for the secondary school level. +

  • Includes (desktop-gnomelibs) bundle.
  • +
  • Includes (desktop-kde-libs) bundle.
  • +
  • Includes (libX11client) bundle.
  • +
  • Includes (qt-basic) bundle.
  • +

    + + + + + education-tertiary + +

    Educational applications for the tertiary school/university level. +

  • Includes (desktop-gnomelibs) bundle.
  • +
  • Includes (desktop-kde-libs) bundle.
  • +
  • Includes (libX11client) bundle.
  • +
  • Includes (qt-basic) bundle.
  • +

    + + + + emacs

    The popular emacs terminal text editor.

    - file -

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

    + + + fwupdate + +

    + Firmware update tool. +

    + + + + games -

    Play games in Clear Linux. -

  • Includes (libX11client) bundle.
  • + +

    Play games in Clear Linux. +

  • Includes (libX11client) bundle.
  • +
  • Includes (p11-kit) bundle.
  • +

    @@ -431,26 +705,81 @@

    All packages required to build the games bundle.

  • Includes (dev-utils) bundle.
  • Includes (games) bundle.
  • -
  • Includes (libX11client) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +

    + + gdb + +

    + GNU debugger. +

    + + + + + gftp + +

    + Text mode and GUI FTP client. +

    + + + gimp -

    + +

    + GNU Image Manipulation Program. +

    + git -

    + +

    + Distributed Version Control System. +

    + + + glmark2 + +

    + OpenGL 2.0 and ES 2.0 benchmark. +

    + + + + + goaccess + +

    + Real-time web log analyzer. +

    + + + + + git +

    git SCM tool. +

  • Includes (openssl) bundle.
  • +
  • Includes (p11-kit) bundle.
  • +

    + + + go-basic -

    Build and run go language programs.

    + +

    Build and run go language programs. +

  • Includes (git) bundle
  • +
  • Includes (p11-kit) bundle
  • +

    @@ -459,14 +788,16 @@
  • Includes (dev-utils) bundle.
  • Includes (go-basic) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • gzip -

    + +

    + Lossless data compression/decompression utility. +

    + @@ -477,8 +808,10 @@ haskell-basic

    Build and run haskell language programs. -

  • Includes (c-basic) bundle.
  • -
  • Includes (perl-basic) bundle.
  • +
  • Includes (git) bundle.
  • +
  • Includes (p11-kit) bundle.
  • +
  • Includes (perl-basic) bundle.
  • +
  • Includes (c-basic) bundle.
  • @@ -490,41 +823,111 @@ htop -

    + +

    + Interactive text-mode process viewer. +

    + httpd -

    + +

    + Apache HyperText Transfer Protocol (HTTP) Server daemon. +

    + hugo -

    + +

    + Static Web site generator. +

    + + + + + iasimage + +

    + For creating Intel Automotive Service (IAS) images, a binary file format understood by Intel© Slim Bootloader. +

    + icdiff -

    + +

    + Improved Color Differences between similar files. +

    + + + iftop + +

    + Display bandwidth usage on an interface. +

    + + + + + + ImageMagick +

    Many console image manipulation utilities, screen capture, viewer. +

  • Includes (libX11client) bundle.
  • + + + inotify-tools -

    + +

    + Monitor for file system events. +

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

    Build and run java language programs.

  • Includes (libX11client) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +
  • Includes (p11-kit) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +
  • Includes (which) bundle.
  • @@ -537,23 +940,39 @@ java9-basic

    Build and run java9 language programs. -

  • Includes (libX11client) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +
  • Includes (libX11client) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +
  • Includes (which) bundle.
  • joe -

    + +

    + Text editor. +

    + jq -

    + +

    + Lightweight and flexible command-line JSON processor. +

    + + + keepassxc + +

    + KeePassXC is a password manager. +

    + + + kernel-aws

    Run the kvm specific kernel. @@ -590,7 +1009,7 @@ kernel-hyperv-mini

    Run the hyperv mini-os specific kernel. -

  • Includes (bootloader) bundle.
  • +
  • Includes ( kernel-hyperv) bundle.
  • @@ -627,13 +1046,21 @@
  • Includes (bootloader) bundle.
  • + + keychain + +

    + Manage SSH and GPG keys. +

    + + + + koji

    Sets up a koji build service based on NFS mounts.

  • Includes (package-utils) bundle.
  • -
  • Includes (python-basic) bundle.
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • Includes (web-server-basic) bundle.
  • @@ -644,47 +1071,87 @@
  • Includes (libX11client) bundle.
  • + + kvm-host-dev + +

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

  • Includes (dev-utils) bundle.
  • +
  • Includes (kvm-host) bundle.
  • +
  • Includes (os-core-dev) bundle.
  • +

    + + letsencrypt-client -

    Obtain and renew valid SSL certificates through Let's Encrypt's ACME service. -

  • Includes (python3-basic) bundle.
  • + +

    Obtain and renew valid SSL certificates through Let's Encrypt's ACME service. +

  • Includes (python3-basic) bundle.
  • +
  • Includes (cloud-api) bundle.
  • +

    libX11client

    Grouping only bundle for use in X using bundles.

    + + + libva-utils + +

    + Collection of utilities and examples to exercise VA-API (Video Acceleration API). +

    + + linux-dev -

    + +

    + Programs for developing Linux. +

    + linux-tools -

    + +

    + Tools for use in Linux. +

    + + + + + logrotate + +

    + Manages the automatic rotation and compression of log files. +

    + machine-learning-basic -

    Build machine learning applications. + +

    Build machine learning applications.

  • Includes (c-basic) bundle.
  • -
  • Includes (python) bundle.
  • +
  • Includes (cloud-api) bundle.
  • Includes (python-extras) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +
  • Includes (python-data-science) bundle.
  • +

    machine-learning-web-ui -

    Web based, interactive tools for machine learning. -

  • Includes (R-basic) bundle.
  • + +

    Web based, interactive tools for machine learning. +

  • Includes (cloud-api) bundle.
  • Includes (R-extras) bundle.
  • -
  • Includes (libX11client) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +
  • Includes (python-data-science) bundle.
  • +

    @@ -695,22 +1162,32 @@ mail-utils-dev -

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

    All packages required to build the mail-utils bundle.

  • Includes (dev-utils) bundle.
  • Includes (mail-utils) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +

    + + + meld + +

    + Visual file difference and merging tool for developers. +

    + + + mixer

    Create Clear Linux releases. +

  • Includes (containers-basic) bundle.
  • +
  • Includes (git) bundle.
  • +
  • Includes (openssl) bundle.
  • Includes (os-installer) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • Includes (python3-basic) bundle.
  • Includes (sysadmin-basic) bundle.
  • @@ -718,39 +1195,69 @@ mkosi -

    + +

    + Generate disk images. +

    + + + ncdu + +

    + Curses disk space usage management tool. +

    + + network-basic

    Run network utilities and modify network settings. +

  • Includes (ethtool) bundle.
  • +
  • Includes (iproute2) bundle.
  • +
  • Includes (openssl) bundle.
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +
  • Includes (wpa_supplicant) bundle.
  • +

    network-basic-dev -

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

    All packages required to build the network-basic bundle.

  • Includes (dev-utils) bundle.
  • Includes (network-basic) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • Includes (perl-basic-dev) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +

    nginx -

    + +

    + HTTP server, reverse proxy, IMAP/POP3 proxy server. +

    + nodejs-basic

    Run javascript server side.

    - + + + octave + +

    + High-level programming language, primarily intended for numerical computations. +

    + + + openssh-server

    Run an ssh server.

    @@ -758,7 +1265,11 @@ openssl -

    + +

    + Toolkit for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols. +

    + @@ -769,33 +1280,45 @@ os-cloudguest

    Run any initialization processes required of a generic cloud guest VM. -

  • Includes (openssh-server) bundle.
  • +
  • Includes (ethtool) bundle.
  • +
  • Includes (openssh-server) bundle.
  • +
  • Includes (sudo) bundle.
  • +

    os-cloudguest-aws -

    Run any initialization processes required of an AWS cloud guest VM.

    +

    Run any initialization processes required of an AWS cloud guest VM. +

  • Includes (sudo) bundle.
  • +

    os-cloudguest-azure

    Run any initialization process required of an Azure cloud guest VM. +

  • Includes (ethtool) bundle.
  • Includes (openssh-server) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +
  • Includes (openssl) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +
  • Includes (sudo) bundle.
  • os-cloudguest-gce -

    Run any initialization processes required of an GCE cloud guest VM.

    + +

    Run any initialization processes required of an GCE cloud guest VM. +

  • Includes (sudo) bundle.
  • +
  • Includes (which) bundle.
  • +

    os-cloudguest-oracle

    Run any initialization processes required of an Oracle Cloud guest. -

  • Includes (openssh-server) bundle.
  • +
  • Includes (openssh-server) bundle.
  • +
  • Includes (sudo) bundle.
  • +

    @@ -805,76 +1328,51 @@ os-clr-on-clr -

    Run any process required for Clear Linux development. + +

    Run any process required for Clear Linux development.

  • Includes (c-basic) bundle.
  • Includes (dev-utils) bundle.
  • Includes (dev-utils-dev) bundle.
  • Includes (editors) bundle.
  • -
  • Includes (emacs) bundle.
  • Includes (go-basic) bundle.
  • Includes (koji) bundle.
  • Includes (kvm-host) bundle.
  • -
  • Includes (libX11client) bundle.
  • Includes (mail-utils) bundle.
  • Includes (mail-utils-dev) bundle.
  • Includes (mixer) bundle.
  • Includes (network-basic) bundle.
  • Includes (network-basic-dev) bundle.
  • Includes (openssh-server) bundle.
  • +
  • Includes (os-core) bundle.
  • Includes (os-core-dev) bundle.
  • Includes (os-core-update-dev) bundle.
  • -
  • Includes (os-installer) bundle.
  • -
  • Includes (package-utils) bundle.
  • Includes (perl-basic) bundle.
  • -
  • Includes (perl-basic-dev) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • Includes (python3-basic) bundle.
  • Includes (storage-utils) bundle.
  • Includes (storage-utils-dev) bundle.
  • Includes (sysadmin-basic) bundle.
  • Includes (sysadmin-basic-dev) bundle.
  • -
  • Includes (vim) bundle.
  • -
  • Includes (web-server-basic) bundle.
  • +

    os-clr-on-clr-dev -

    All packages required to build the os-clr-on-clr bundle. -

  • Includes (c-basic) bundle.
  • + +

    All packages required to build the os-clr-on-clr bundle.

  • Includes (dev-utils) bundle.
  • Includes (dev-utils-dev) bundle.
  • -
  • Includes (editors) bundle.
  • Includes (editors-dev) bundle.
  • -
  • Includes (emacs) bundle.
  • -
  • Includes (go-basic) bundle.
  • Includes (go-basic-dev) bundle.
  • -
  • Includes (koji) bundle.
  • -
  • Includes (kvm-host) bundle.
  • -
  • Includes (libX11client) bundle.
  • -
  • Includes (mail-utils) bundle.
  • +
  • Includes (kvm-host-dev) bundle.
  • Includes (mail-utils-dev) bundle.
  • Includes (mixer) bundle.
  • -
  • Includes (network-basic) bundle.
  • -
  • Includes (network-basic-dev) bundle.
  • -
  • Includes (openssh-server) bundle.
  • +
  • Includes (os-clr-on-clr) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (os-core-update-dev) bundle.
  • -
  • Includes (os-installer) bundle.
  • -
  • Includes (package-utils) bundle.
  • -
  • Includes (perl-basic) bundle.
  • Includes (perl-basic-dev) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python-basic-dev) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • -
  • Includes (storage-utils) bundle.
  • Includes (storage-utils-dev) bundle.
  • -
  • Includes (sysadmin-basic) bundle.
  • Includes (sysadmin-basic-dev) bundle.
  • -
  • Includes (vim) bundle.
  • -
  • Includes (web-server-basic) bundle.
  • +

    @@ -885,40 +1383,58 @@ os-core-dev -

    All packages required to build the os-core bundle. + +

    All packages required to build the os-core bundle.

  • Includes (dev-utils) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +

    os-core-update -

    Provides basic suite for running the Clear Linux for iA Updater.

    + +

    Provides basic suite for running the Clear Linux for iA Updater. +

  • Includes (os-core) bundle.
  • +

    os-core-update-dev -

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

    All packages required to build the os-core-update bundle.

  • Includes (dev-utils) bundle.
  • Includes (os-core-dev) bundle.
  • Includes (os-core-update) bundle.
  • -
  • Includes (os-core-update-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +

    os-installer -

    Run image creation and installation for Clear Linux.

    + +

    Run image creation and installation for Clear Linux. +

  • Includes (python3-basic) bundle.
  • +
  • Includes (wpa_supplicant) bundle.
  • +

    os-testsuite

    Provides minimal functionality for core testing functions. -

  • Includes (openssh-server) bundle.
  • +
  • Includes (git) bundle.
  • +
  • Includes (openssh-server) bundle.
  • +

    + + + + os-testsuite-0day +

    Helpers for the 0day kernel testing framework. +

  • Includes (c-basic) bundle.
  • +
  • Includes (dev-utils) bundle.
  • +
  • Includes (python-extras) bundle.
  • +
  • Includes (perl-extras) bundle.
  • +

    @@ -927,23 +1443,17 @@
  • Includes (R-basic) bundle.
  • Includes (c-basic) bundle.
  • Includes (database-basic) bundle.
  • -
  • Includes (desktop) bundle.
  • -
  • Includes (desktop-apps) bundle.
  • -
  • Includes (desktop-apps-extras) bundle.
  • -
  • Includes (desktop-assets) bundle.
  • -
  • Includes (desktop-autostart) bundle.
  • -
  • Includes (desktop-gnomelibs) bundle.
  • -
  • Includes (desktop-locales) bundle.
  • +
  • Includes (desktop-autostart) bundle.
  • +
  • Includes (desktop-apps-extras) bundle.
  • Includes (games) bundle.
  • +
  • Includes (git) bundle.
  • Includes (go-basic) bundle.
  • -
  • Includes (libX11client) bundle.
  • +
  • Includes (java-basic) bundle.
  • Includes (machine-learning-basic) bundle.
  • +
  • Includes (octave) bundle.
  • Includes (php-basic) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python-extras) bundle.
  • -
  • Includes (python2-basic) bundle.
  • Includes (python3-basic) bundle.
  • -
  • Includes (sysadmin-basic) bundle.
  • +
  • Includes (qt-basic-dev) bundle.
  • @@ -951,52 +1461,67 @@ os-utils-gui

    Provides a graphical desktop environment.

  • Includes (cryptography) bundle.
  • -
  • Includes (libX11client) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • +
  • Includes (openssl) bundle.
  • Includes (python3-basic) bundle.
  • -
  • Includes (xfce4-desktop) bundle.
  • +
  • Includes (wpa_supplicant) bundle.
  • +
  • Includes (xfce4-desktop) bundle.
  • +
  • Includes (xemacs) bundle.
  • +
  • Includes (darktable) bundle.
  • +
  • Includes (thunderbird) bundle.
  • +

    os-utils-gui-dev -

    All packages required to build the os-utils-gui bundle. -

  • Includes (cryptography) bundle.
  • + +

    All packages required to build the os-utils-gui bundle.

  • Includes (dev-utils) bundle.
  • -
  • Includes (libX11client) bundle.
  • Includes (os-core-dev) bundle.
  • Includes (os-utils-gui) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python-basic-dev) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • -
  • Includes (xfce4-desktop) bundle.
  • +

    + + + p11-kit + +

    + Load and enumerate PKCS#11 modules for cryptography. +

    + + + package-utils

    Utilities for creating, building, and managing packages. -

  • Includes (python3-basic) bundle.
  • +
  • Includes (python2-basic) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +

    parallel -

    + +

    + Shell tool for executing jobs in parallel using one or more computers. +

    patch -

    + +

    + Updates text files according to instructions contained in a separate file. +

    performance-tools

    Run performance and power measurements. -

  • Includes (libX11client) bundle.
  • +
  • Includes (ethtool) bundle.
  • Includes (perl-basic) bundle.
  • Includes (python3-basic) bundle.
  • Includes (tcl-basic) bundle.
  • @@ -1010,11 +1535,12 @@ perl-basic-dev -

    All packages required to build the perl-basic bundle. + +

    All packages required to build the perl-basic bundle.

  • Includes (dev-utils) bundle.
  • Includes (os-core-dev) bundle.
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +

    @@ -1032,7 +1558,10 @@ pmdk -

    + +

    + Persistent Memory Development Kit - Tools and libraries for working with non-volatile memory. +

    @@ -1042,31 +1571,46 @@ postgresql -

    +

    Database

    powertop -

    + +

    + Diagnose issues with power consumption and power management. +

    productivity

    A set of console utilities for task management and communication.

  • Includes (mail-utils) bundle.
  • -
  • Includes (python2-basic) bundle.
  • Includes (python3-basic) bundle.
  • + + pwgen + +

    + Generates passwords which are designed to be easily memorized by humans, while being as secure as possible. +

    + + + pxe-server -

    Run a PXE server.

    + +

    Run a PXE server. +

  • Includes (python3-basic) bundle
  • +

    python-basic

    Run python language programs. +

  • Includes (p11-kit) bundle.
  • Includes (python2-basic) bundle.
  • Includes (python3-basic) bundle.
  • @@ -1074,34 +1618,47 @@ python-basic-dev -

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

    All packages required to build the python-basic bundle.

  • Includes (dev-utils) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • Includes (python-basic) bundle.
  • -
  • Includes (python-basic-dev) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +

    + + python-data-science + +

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

  • Includes (c-basic) bundle
  • +
  • Includes (python-extras) bundle
  • +

    + + python-extras

    Improve user experience with a common set of pre-built python libraries. -

  • Includes (python-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +
  • Includes (cloud-api) bundle.
  • +

    python2-basic -

    Run legacy python language programs.

    + +

    Run legacy python language programs. +

  • Includes (p11-kit) bundle.
  • +

    python3-basic -

    Run python language programs.

    + +

    Run python language programs. +

  • Includes (p11-kit) bundle.
  • +

    @@ -1115,25 +1672,53 @@

    All packages required to build the qt-basic bundle.

  • Includes (dev-utils) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • Includes (qt-basic) bundle.
  • + + redis-native + +

    + Key-value database. +

    + + + + quassel + +

    Quassel IRC. +

  • Includes (libX11client) bundle.
  • +
  • Includes (qt-basic) bundle.
  • +

    + + + ruby-basic -

    Run ruby language programs.

    + +

    Run ruby language programs. +

  • Includes (p11-kit) bundle.
  • +

    rust-basic -

    Build and run rust language programs.

    + +

    Build and run rust language programs. +

  • Includes (git) bundle.
  • +
  • Includes (p11-kit) bundle.
  • +

    + scm-server -

    Run a source code management server.

    + +

    Run a source code management server. +

  • Includes (git) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +

    @@ -1142,6 +1727,16 @@
  • Includes (bootloader) bundle.
  • + + service-os-dev + +

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

  • Includes (dev-utils) bundle.
  • +
  • Includes (os-core-dev) bundle.
  • +
  • Includes (service-os) bundle.
  • +

    + + shells

    Run a shell.

    @@ -1149,7 +1744,10 @@ software-defined-cockpit -

    Run the automotive software defined cockpit which has graphic, media, sound and connectivity.

    + +

    Run the automotive software defined cockpit which has graphic, media, sound and connectivity. +

  • Includes (wpa_supplicant) bundle.
  • +

    @@ -1172,15 +1770,17 @@

    All packages required to build the storage-utils bundle.

  • Includes (dev-utils) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • Includes (storage-utils) bundle.
  • strace -

    + +

    + System call diagnostic, instructional, and debugging tool. +

    + @@ -1190,17 +1790,50 @@ subversion -

    + +

    + Version Control System. +

    + + sudo + +

    + Allows a user to run a program as another user. +

    + + suricata -

    + +

    + Network threat detection engine. +

    + + + synergy + +

    Keyboard and mouse sharing across networks. +

  • Includes (qt-basic) bundle.
  • +
  • Includes (postgresql) bundle.
  • +

    + + + + sysadmin-basic -

    Run common utilities useful for managing a system.

    + +

    Run common utilities useful for managing a system. +

  • Includes (iproute2) bundle
  • +
  • Includes (p11-kit) bundle
  • +
  • Includes (sudo) bundle
  • +
  • Includes (which) bundle
  • +

    + @@ -1208,8 +1841,6 @@

    All packages required to build the sysadmin-basic bundle.

  • Includes (dev-utils) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • Includes (sysadmin-basic) bundle.
  • @@ -1217,6 +1848,7 @@ sysadmin-hostmgmt

    Utilities and Services for managing large-scale clusters of networked hosts. +

  • Includes (git) bundle
  • Includes (pxe-server) bundle.
  • Includes (python3-basic) bundle.
  • @@ -1225,15 +1857,19 @@ sysadmin-remote

    Enable the host to be managed remotely by configuration management tools.

  • Includes (openssh-server) bundle.
  • -
  • Includes (python-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +
  • Includes (python3-basic) bundle.
  • +
  • Includes (cockpit) bundle.
  • +
  • Includes (sudo) bundle.
  • systemd-cryptsetup -

    + +

    + Responsible for setting up encrypted block devices. +

    + @@ -1248,9 +1884,22 @@

    Run telemetrics client.

    + + texlive + +

    + Major TeX-related typesetting programs, macro packages, and fonts. +

    + + + thunderbird -

    + +

    + Email client. +

    + @@ -1260,89 +1909,105 @@ tmux -

    + +

    + Terminal multiplexer (similar to screen). +

    + + + unison + +

    + Bidirectional file synchronization tool. +

    + + + + unzip -

    + +

    + List, test, or extract files from a ZIP archive. +

    user-basic -

    Meta bundle capturing most console user work flows. + +

    Meta bundle capturing most console user work flows.

  • Includes (dev-utils) bundle.
  • Includes (editors) bundle.
  • Includes (emacs) bundle.
  • Includes (kvm-host) bundle.
  • -
  • Includes (libX11client) bundle.
  • Includes (mail-utils) bundle.
  • Includes (network-basic) bundle.
  • Includes (openssh-server) bundle.
  • Includes (os-core-update) bundle.
  • -
  • Includes (perl-basic) bundle.
  • -
  • Includes (python2-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • -
  • Includes (shells) bundle.
  • +
  • Includes (shells) bundle.
  • Includes (storage-utils) bundle.
  • Includes (sysadmin-basic) bundle.
  • -
  • Includes (vim) bundle.
  • +

    user-basic-dev -

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

    All packages required to build the user-basic bundle.

  • Includes (dev-utils) bundle.
  • Includes (dev-utils-dev) bundle.
  • Includes (editors) bundle.
  • Includes (editors-dev) bundle.
  • -
  • Includes (emacs) bundle.
  • -
  • Includes (kvm-host) bundle.
  • -
  • Includes (libX11client) bundle.
  • -
  • Includes (mail-utils) bundle.
  • +
  • Includes (kvm-host-dev) bundle.
  • Includes (mail-utils-dev) bundle.
  • -
  • Includes (network-basic) bundle.
  • Includes (network-basic-dev) bundle.
  • -
  • Includes (openssh-server) bundle.
  • Includes (os-core-dev) bundle.
  • -
  • Includes (os-core-update) bundle.
  • Includes (os-core-update-dev) bundle.
  • -
  • Includes (perl-basic) bundle.
  • +
  • Includes (storage-utils) bundle.
  • +
  • Includes (sysadmin-basic-dev) bundle.
  • +
  • Includes (user-basic) bundle.
  • +

    valgrind -

    + +

    + Suite of tools for debugging and profiling software code. +

    vim -

    The popular vim text editor + +

    The popular vim text editor. +

  • Includes (python3-basic) bundle.
  • Includes (perl-basic) bundle.
  • -
  • Includes (python3-basic) bundle.
  • +

    vlc -

    + +

    + VideoLAN Client, multimedia player and framework. +

    + vnc-server -

    Enable the host to be a vnc desktop server. + +

    Enable the host to be a vnc desktop server.

  • Includes (desktop) bundle.
  • -
  • Includes (desktop-apps) bundle.
  • -
  • Includes (desktop-assets) bundle.
  • -
  • Includes (desktop-gnomelibs) bundle.
  • -
  • Includes (desktop-locales) bundle.
  • -
  • Includes (libX11client) bundle.
  • -
  • Includes (openssh-server) bundle.
  • -
  • Includes (python3-basic) bundle.
  • -
  • Includes (sysadmin-basic) bundle.
  • +
  • Includes (openssh-server) bundle.
  • +

    @@ -1353,28 +2018,95 @@ weechat -

    - - - - wireshark -

    + +

    + Internet Relay Chat (IRC) client. +

    + - xfce4-desktop + weston-extras + +

    + Utilities and tools for the Wayland graphics compositor. +

    + + + + + which + +

    + Locate executables in the system. +

    + + + + + wireshark + +

    + Network protocol analyzer. +

  • Includes (postgresql) bundle.
  • +
  • Includes (qt-basic) bundle.
  • +

    + + + + + wpa_supplicant + +

    + Backend component controlling the wireless connections. +

    + + + + + x11-tools

    Run GUI desktop environment.

  • Includes (libX11client) bundle.
  • + + + + xemacs + +

    + Tools useful when running under X11. +

  • Includes (libX11client) bundle.
  • +

    + + + + + xfce4-desktop + +

    Run GUI desktop environment. +

  • Includes (libX11client) bundle.
  • +
  • Includes (which) bundle.
  • +

    + + + xz -

    + +

    + Data compression/decompression tool. +

    + zsh -

    + +

    + Z Shell, an interactive shell and powerful command-line interpreter for scripting language. +

    + diff --git a/source/clear-linux/reference/bundles/available-bundles.rst b/source/clear-linux/reference/bundles/bundles.rst similarity index 54% rename from source/clear-linux/reference/bundles/available-bundles.rst rename to source/clear-linux/reference/bundles/bundles.rst index 79a2d6ef..e063c3c5 100644 --- a/source/clear-linux/reference/bundles/available-bundles.rst +++ b/source/clear-linux/reference/bundles/bundles.rst @@ -1,10 +1,10 @@ -.. _available-bundles: +.. _bundles: Available bundles ################# -This document provides a current list of available `bundles`_ as of -``7 May 2018``. +This document provides a current list of `available bundles`_ as +of ``12 September 2018``. See in depth descriptions of the following bundles: @@ -22,4 +22,4 @@ Bundle list .. raw:: html :file: bundles.html -.. _bundles: https://github.com/clearlinux/clr-bundles +.. _available bundles: https://github.com/clearlinux/clr-bundles diff --git a/source/clear-linux/reference/image-types.rst b/source/clear-linux/reference/image-types.rst index 50f81dfc..e3d94205 100644 --- a/source/clear-linux/reference/image-types.rst +++ b/source/clear-linux/reference/image-types.rst @@ -1,11 +1,11 @@ .. _image-types: -Clear Linux\* image types +|CL-ATTR| image types ######################### .. _image-types-content: -|CLOSIA| offers many types of `images`_ for different platforms and environments. +|CL-ATTR| offers many types of `images`_ for different platforms and environments. .. _incl-image-filename: @@ -28,7 +28,7 @@ The naming convention of a |CL| image filename is: Table 1 lists the currently available images that are platform independent. Table 2 lists the currently available images that are platform specific. -.. list-table:: Table 1: Types of platform-independent Clear Linux images +.. list-table:: Table 1: Types of platform-independent |CL| images :widths: 15, 85 :header-rows: 1 @@ -36,15 +36,15 @@ Table 2 lists the currently available images that are platform specific. - Description * - installer.img - - Preferred image of Clear Linux with interactive installer. + - Preferred image of |CL| with interactive installer. * - installer.iso - - ISO of Clear Linux with interactive installer. Only for special cases where ISO image format is required (not for use with a USB key) + - ISO of |CL| with interactive installer. Only for special cases where ISO image format is required (not for use with a USB key) * - live.img - - image for live booting into memory, without requiring installaton. + - Image for live booting into memory, without requiring installaton. -.. list-table:: Table 2: Types of platform-specific Clear Linux images +.. list-table:: Table 2: Types of platform-specific |CL| images :widths: 15, 85 :header-rows: 1 diff --git a/source/clear-linux/reference/reference.rst b/source/clear-linux/reference/reference.rst index 1ad206a7..2f8286d3 100644 --- a/source/clear-linux/reference/reference.rst +++ b/source/clear-linux/reference/reference.rst @@ -11,7 +11,7 @@ features. compatible-hardware bundle-commands - bundles/available-bundles + bundles/bundles how-to-clear-overview collaboration/collaboration compatible-kernels diff --git a/source/clear-linux/reference/system-requirements.rst b/source/clear-linux/reference/system-requirements.rst index 7849ced7..25f2bc0d 100644 --- a/source/clear-linux/reference/system-requirements.rst +++ b/source/clear-linux/reference/system-requirements.rst @@ -3,9 +3,8 @@ Recommended minimum system requirements ####################################### -Clear Linux\* OS for Intel® Architecture can run on very minimal hardware. -For example, it can run on a system with a single core CPU, 128MB of memory, -and 600MB of disk space. +|CL-ATTR| can run on very minimal hardware. For example, it can run on a +system with a single core CPU, 128MB of memory, and 600MB of disk space. Different use cases and applications will require different configurations. For general |CL| use, in addition to a supported processor, the recommended @@ -13,9 +12,8 @@ minimum requirements include: * Processors: - Clear Linux\* OS for Intel® Architecture can run on any Intel® 64bit - processors which support UEFI\* and SSE\* v4.1 streaming SIMD\* - instructions. + |CL-ATTR| can run on any Intel® 64bit processors which support UEFI\* + and SSE\* v4.1 streaming SIMD\* instructions. The following processor families have been verified to run |CL|: diff --git a/source/clear-linux/tutorials/flatpak/figures/01-install-libreoffice.gif b/source/clear-linux/tutorials/flatpak/figures/01-install-libreoffice.gif new file mode 100644 index 00000000..62775293 Binary files /dev/null and b/source/clear-linux/tutorials/flatpak/figures/01-install-libreoffice.gif differ diff --git a/source/clear-linux/tutorials/flatpak/figures/02-openlibreoffice.gif b/source/clear-linux/tutorials/flatpak/figures/02-openlibreoffice.gif new file mode 100644 index 00000000..92ff6b7b Binary files /dev/null and b/source/clear-linux/tutorials/flatpak/figures/02-openlibreoffice.gif differ diff --git a/source/clear-linux/tutorials/flatpak/figures/flatpak1.png b/source/clear-linux/tutorials/flatpak/figures/flatpak1.png deleted file mode 100644 index aa37e875..00000000 Binary files a/source/clear-linux/tutorials/flatpak/figures/flatpak1.png and /dev/null differ diff --git a/source/clear-linux/tutorials/flatpak/figures/flatpak2.png b/source/clear-linux/tutorials/flatpak/figures/flatpak2.png deleted file mode 100644 index de7b1077..00000000 Binary files a/source/clear-linux/tutorials/flatpak/figures/flatpak2.png and /dev/null differ diff --git a/source/clear-linux/tutorials/flatpak/figures/flatpak3.png b/source/clear-linux/tutorials/flatpak/figures/flatpak3.png deleted file mode 100644 index f83426e4..00000000 Binary files a/source/clear-linux/tutorials/flatpak/figures/flatpak3.png and /dev/null differ diff --git a/source/clear-linux/tutorials/flatpak/figures/gnome1.png b/source/clear-linux/tutorials/flatpak/figures/gnome1.png deleted file mode 100644 index e06f12d1..00000000 Binary files a/source/clear-linux/tutorials/flatpak/figures/gnome1.png and /dev/null differ diff --git a/source/clear-linux/tutorials/flatpak/flatpak.rst b/source/clear-linux/tutorials/flatpak/flatpak.rst index c3df152f..335d0a00 100644 --- a/source/clear-linux/tutorials/flatpak/flatpak.rst +++ b/source/clear-linux/tutorials/flatpak/flatpak.rst @@ -1,16 +1,16 @@ .. _flatpak: -Use Flatpak\* to install applications on |CLOSIA| -################################################# +Use Flatpak\* to install applications on |CL-ATTR| +################################################## This tutorial provides all the required steps to install Flatpak as well as -downloading, installing, and running LibreOffice on |CL|. +downloading, installing, and running LibreOffice\* on |CL-ATTR|. Please visit the `Flatpak website`_ for more information about Flatpak and -how to use it. +how to use it. You can also `download it here`_. Before you begin -================ +**************** This tutorial assumes you have installed |CL| on your host system. For detailed instructions on installing |CL| on a bare metal system, visit @@ -22,9 +22,9 @@ Install Flatpak on your host system Flatpak is included as part of the bundle `desktop`. To install the application, log in to your user account and enter the following command: -.. code-block:: console +.. code-block:: bash - $ sudo swupd bundle-add desktop + sudo swupd bundle-add desktop Install and run the LibreOffice Flatpak image @@ -32,82 +32,68 @@ Install and run the LibreOffice Flatpak image Application developers have the option to bundle their applications using Flatpak to allow the installation of a single distribution of their -application on different distributions of Linux, including Clear Linux. -Flatpak provides a `list of applications`_ available through Flatpak. +application on different distributions of Linux, including |CL|. +Flatpak provides a `list of applications`_ available through Flathub. -Download and install the Latest LibreOffice Flatpak ---------------------------------------------------- +|CL| enables the Flathub repository by default. -To get the latest version of the LibreOffice Flatpak repository, either -`download it here`_ or you can enter the following command: -.. code-block:: console +Installing using gnome software +------------------------------- - $ curl –O -L http://download.documentfoundation.org/libreoffice/flatpak/latest/LibreOffice.flatpak +All you need to do is to launch `gnome software`, search for the LibreOffice +app, and click the install button. -The command downloads the latest LibreOffice.flatpak and saves it in your -current directory. +.. figure:: figures/01-install-libreoffice.gif + :alt: install libreoffice step by step -Once the download is complete, the next step is to install LibreOffice along -with the runtime environment LibreOffice needs to execute. As mentioned on -the `Flatpak website`_, with the release of Flatpak 0.8.0 and -LibreOffice.flatpak 4.2.4, you no longer have to specifically install the -runtime required to execute LibreOffice since it will automatically install -the runtime referenced in the LibreOffice.flatpak file. + Figure 1: Installing LibreOffice using gnome-software -To install LibreOffice run the following command: -.. code-block:: console - $ sudo flatpak install --bundle LibreOffice.flatpak +Installing using the command line +--------------------------------- -The output from this command will look similar to the following. +Open the `gnome-terminal` and type the following command to install the +LibreOffice app. -.. note:: +.. code-block:: bash - You will be prompted to install the runtime environment if it is not - already installed. Type :kbd:`y` to allow this task to execute. + flatpak install --user flathub org.libreoffice.LibreOffice + Installing in user: + org.libreoffice.LibreOffice/x86_64/stable flathub 2aff77bd5cf1 + permissions: ipc, network, pulseaudio, wayland, x11, dri + file access: host, xdg-run/dconf + dbus access: ca.desrt.dconf, org.gtk.vfs.* + dbus ownership: org.libreoffice.LibreOfficeIpc0 + org.libreoffice.LibreOffice.Locale/x86_64/stable flathub 924157b3b009 + Is this ok [y/n]: y + Installing for user: org.libreoffice.LibreOffice/x86_64/stable from flathub + [####################] 403 metadata, 4661 content objects fetched; 222574 KiB transferred in 99 seconds + Now at 2aff77bd5cf1. + Installing for user: org.libreoffice.LibreOffice.Locale/x86_64/stable from flathub + [####################] 10 metadata, 71 content objects fetched; 1013 KiB transferred in 3 seconds + Now at 924157b3b009. -.. code-block:: console - GLib-GIO-Message: Using the 'memory' GSettings backend. - Your settings will not be saved or shared with other applications. - This application depends on runtimes from: - http://sdk.gnome.org/repo/ - Configure this as new remote 'gnome' [y/n]: y - Required runtime for org.libreoffice.LibreOffice/x86_64/fresh - (org.gnome.Platform/x86_64/3.20) is not installed, searching... - Found in remote gnome, do you want to install it? [y/n]: y - Installing: org.gnome.Platform/x86_64/3.20 from gnome - - Receiving delta parts: 0/11 2.5 MB/s 4.9 MB/223.2 MB 1 minutes 28 seconds - remain - Receiving delta parts: 0/11 2.9 MB/s 8.7 MB/223.2 MB 1 minutes 13 seconds - remain - 11 delta parts, 84 loose fetched; 218002 KiB transferred in 17 seconds - Installing: org.gnome.Platform.Locale/x86_64/3.20 from gnome - - 5 metadata, 1 content objects fetched; 13 KiB transferred in 1 seconds - Installing: org.libreoffice.LibreOffice/x86_64/fresh from bundle - LibreOffice.flatpak - -Once the LibreOffice Flatpak application has been installed, you can launch -LibreOffice with the following command from the command line: - -.. code-block:: console - - $ flatpak run org.libreoffice.LibreOffice - -Add LibreOffice to your Gnome desktop -===================================== -A new icon will appear in your Gnome applications list titled :guilabel:`LibreOffice.` To +Launch LibreOffice +================== +A new set of icons will appear in your Gnome applications list titled :guilabel:`LibreOffice.` To execute the application, highlight the application and click on the :guilabel:`LibreOffice` icon. LibreOffice will start normally. -.. figure:: figures/gnome1.png - :alt: Gnome desktop +.. figure:: figures/02-openlibreoffice.gif + :alt: Opening LibreOffice app + + Figure 2: Select :guilabel:`LibreOffice` app + +Using the command line +---------------------- + +.. code-block:: bash + + flatpak run org.libreoffice.LibreOffice - Figure 1: Select :guilabel:`Gnome applications list` .. _Flatpak website: http://flatpak.org diff --git a/source/clear-linux/tutorials/web-server-install/web-server-install.rst b/source/clear-linux/tutorials/web-server-install/web-server-install.rst index 3c526468..24793b97 100644 --- a/source/clear-linux/tutorials/web-server-install/web-server-install.rst +++ b/source/clear-linux/tutorials/web-server-install/web-server-install.rst @@ -3,7 +3,7 @@ Create a Clear Linux\* based web server ####################################### -This tutorial shows you how to create a LAMP server using |CLOSIA| and how to use phpMyAdmin\* to manage an associated database. +This tutorial shows you how to create a LAMP server using |CL-ATTR| and how to use phpMyAdmin\* to manage an associated database. In order to create a web server using |CL| as the host OS, your host system must be running |CL|. This tutorial assumes you have successfully installed @@ -360,7 +360,7 @@ our |CL| host system. This example downloads and uses version 4.6.4. -#. Once the file has been successfully downloaded and verified, uncompress +#. Once the file has been successfully downloaded and verified, decompress the file and directories into the Apache web server document root directory. Use the following commands: diff --git a/source/conf.py b/source/conf.py index 448e260b..c6993a9e 100644 --- a/source/conf.py +++ b/source/conf.py @@ -52,7 +52,7 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'Clear Linux* Project for Intel® Architecture' +project = u'Clear Linux* project' copyright = u'2016, many' author = u'many' @@ -130,7 +130,7 @@ html_theme_path = ['_themes'] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -html_title = "Documentation for Clear Linux* Project for Intel(r) Architecture" +html_title = "Documentation for Clear Linux* project" # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None @@ -232,7 +232,7 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'clr.tex', u'Documentation for Clear Linux* Project for Intel® Architecture', + (master_doc, 'clr.tex', u'Documentation for Clear Linux* project', u'many', 'manual'), ] @@ -262,7 +262,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'clearlinux', u'Documentation for Clear Linux* Project for Intel® Architecture', + (master_doc, 'clearlinux', u'Documentation for Clear Linux* project', [author], 1) ] @@ -276,7 +276,7 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'clearlinux', u'Documentation for Clear Linux* Project for Intel® Architecture', + (master_doc, 'clearlinux', u'Documentation for Clear Linux* project', author, 'Clear Linux', 'One line description of project.', 'Miscellaneous'), ] diff --git a/source/index.rst b/source/index.rst index 8b4c503e..18009e35 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,14 +1,13 @@ .. Clear Technologies documentation master file. -Clear technologies - Documentation -################################## +Clear Linux - Documentation +########################### .. toctree:: - :maxdepth: 2 + :maxdepth: 1 clear-linux/clear-linux - clear-containers/clear-containers - + License and disclaimers ======================= diff --git a/source/substitutions.txt b/source/substitutions.txt index b8bc7513..7a156671 100644 --- a/source/substitutions.txt +++ b/source/substitutions.txt @@ -1,6 +1,10 @@ -.. |CL| replace:: Clear Linux +.. |CL| replace:: Clear Linux OS -.. |CLOSIA| replace:: Clear Linux* OS for Intel® Architecture +.. |CLOSIA| replace:: Clear Linux* OS + +.. |CL-ATTR| replace:: Clear Linux* OS + +.. |CL-PRJ| replace:: Clear Linux* project .. |CC| replace:: Clear Containers