Merge pull request #4 from clearlinux/master

Update from upstream master
This commit is contained in:
puneetse
2018-10-03 11:10:55 -07:00
committed by GitHub
102 changed files with 2359 additions and 1547 deletions
@@ -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:
+19
View File
@@ -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.
+17
View File
@@ -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.
@@ -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) <http:www.qemu.org>`_.
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<cc-getting-started>` 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
@@ -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
Binary file not shown.

Before

Width:  |  Height:  |  Size: 328 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 360 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 50 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 50 KiB

@@ -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
+25 -13
View File
@@ -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
@@ -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<swupd-about>`. 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<swupd-about>`.
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`
+1
View File
@@ -15,4 +15,5 @@ details relevant to the |CL| features.
bundles-about
autospec-about
restart
security
telemetry-about
Binary file not shown.

Before

Width:  |  Height:  |  Size: 59 KiB

After

Width:  |  Height:  |  Size: 131 KiB

+204
View File
@@ -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
<a href="https://nvd.nist.gov/" target="_blank">https://nvd.nist.gov/</a>
.. |MITRE| raw:: html
<a href="https://cve.mitre.org/" target="_blank">https://cve.mitre.org/</a>
+60 -63
View File
@@ -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 <mixer>`. 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 <swupd-guide>` 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.
@@ -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:
@@ -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`:
@@ -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<available-bundles>` and select the name for a
the :ref:`software bundle list <bundles>` and select the name for a
specific bundle to show the contents within the bundle.
Target system network configuration
@@ -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-<version>-live.img.xz`` or an installer image,
``clear-<version>-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
@@ -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-<version>-live.img.xz`` or an installer image,
``clear-<version>-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
**********
@@ -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-<version>-live.img.xz`` or an installer image,
``clear-<version>-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::
@@ -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:
@@ -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
<bare-metal-manual-install>`.
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
<bare-metal-manual-install>` to complete installation of Clear Linux.
<bare-metal-manual-install>` to complete installation of |CL|.
Continue at the section *Additional manual installer settings*.
.. _`GPT fdisk tutorial`:
@@ -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 <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
+21 -9
View File
@@ -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 <bare-metal-install>`, under
a :ref:`virtual machine <virtual-machine-install>`, or by way of a
:ref:`live image <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
@@ -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<bootable-usb>` 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:
@@ -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
@@ -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 <https://download.clearlinux.org/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-<version>-kvm.img.xz
unxz clear-<version>-kvm.img.xz
#. Download the `OVMF file`_ file that provides UEFI support for
virtual machines from the `image <https://download.clearlinux.org/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-<version>-kvm.img
./start_qemu.sh clear-<version>-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-<version>-kvm.img
./start_qemu.sh clear-<version>-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-<version>-kvm.img
./start_qemu.sh clear-<version>-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).
@@ -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 <bundles-about>` 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.
@@ -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
@@ -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`
@@ -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`
@@ -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`
@@ -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`
@@ -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.
+1
View File
@@ -18,3 +18,4 @@ after completing the |CL| :ref:`installation <get-started>`.
maintenance/maintenance
network/network
deploy-at-scale
@@ -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
@@ -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:
@@ -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
@@ -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

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 44 KiB

@@ -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.
@@ -3,8 +3,9 @@
Maintenance guide
#################
This guide provides step-by-step instructions for common tasks associated with
maintaining |CLOSIA| after :ref:`installation <get-started>` is completed.
These guides provide step-by-step instructions for common tasks associated
with maintaining |CL-ATTR| after :ref:`installation <get-started>` is
completed.
.. toctree::
:maxdepth: 2
@@ -19,8 +20,9 @@ maintaining |CLOSIA| after :ref:`installation <get-started>` 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
+102 -121
View File
@@ -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=<URL where the content will be hosted>
VERSIONURL=<URL where the version of the mix will be hosted>
FORMAT=1
[Swupd]
BUNDLE = "os-core-update"
CONTENTURL = "<URL where the content will be hosted>"
VERSIONURL = "<URL where the version of the mix will be hosted>"
[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/{<MIXVERSION>}`. `<MIXVERSION>`
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 <MIX_VERSION> --from <PAST_VERSION> -S /home/clr/mix/update
mixer build delta-packs --to <MIX_VERSION> --from <PAST_VERSION>
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 <NEWVERSION> --from <PREV_VERSION> -S /
home/clr/mix/update
mixer build delta-packs --to <NEWVERSION> --from <PREV_VERSION>
.. _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/
@@ -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
@@ -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 <swupd-guide>`
* Understand :ref:`how swupd differs <swupd-about>` 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 <kata>` on |CL|?
* :ref:`kata`
* How do I :ref:`kata_migration`?
* :ref:`kata_migration`
* How do I show all :ref:`bundles available <swupd-guide>`?
* :ref:`swupd-guide`
* How do I :ref:`update swupd<swupd-guide>`?
* :ref:`Show all available bundles <swupd-guide>`
* How do I :ref:`remove bundles<swupd-guide>`?
* :ref:`Remove bundles<swupd-guide>`
.. _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
@@ -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
@@ -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
@@ -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
Binary file not shown.

Before

Width:  |  Height:  |  Size: 43 KiB

After

Width:  |  Height:  |  Size: 17 KiB

@@ -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 <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
File diff suppressed because it is too large Load Diff
@@ -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
+7 -7
View File
@@ -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
+1 -1
View File
@@ -11,7 +11,7 @@ features.
compatible-hardware
bundle-commands
bundles/available-bundles
bundles/bundles
how-to-clear-overview
collaboration/collaboration
compatible-kernels
@@ -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|:
Binary file not shown.

After

Width:  |  Height:  |  Size: 1.3 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 823 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 977 KiB

@@ -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
@@ -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:
+5 -5
View File
@@ -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
# "<project> v<release> 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'),
]

Some files were not shown because too many files have changed in this diff Show More