Merge pull request #4 from clearlinux/master
Update from upstream master
@@ -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:
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
Before Width: | Height: | Size: 328 KiB |
|
Before Width: | Height: | Size: 360 KiB |
|
Before Width: | Height: | Size: 50 KiB |
|
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
|
||||
@@ -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`
|
||||
|
||||
@@ -15,4 +15,5 @@ details relevant to the |CL| features.
|
||||
bundles-about
|
||||
autospec-about
|
||||
restart
|
||||
security
|
||||
telemetry-about
|
||||
|
||||
|
Before Width: | Height: | Size: 59 KiB After Width: | Height: | Size: 131 KiB |
@@ -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>
|
||||
|
||||
@@ -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
|
||||
|
Before Width: | Height: | Size: 87 KiB After Width: | Height: | Size: 87 KiB |
|
Before Width: | Height: | Size: 91 KiB After Width: | Height: | Size: 91 KiB |
|
Before Width: | Height: | Size: 110 KiB After Width: | Height: | Size: 110 KiB |
|
Before Width: | Height: | Size: 131 KiB After Width: | Height: | Size: 131 KiB |
|
Before Width: | Height: | Size: 159 KiB After Width: | Height: | Size: 159 KiB |
|
Before Width: | Height: | Size: 90 KiB After Width: | Height: | Size: 90 KiB |
|
Before Width: | Height: | Size: 861 KiB After Width: | Height: | Size: 861 KiB |
|
Before Width: | Height: | Size: 633 KiB After Width: | Height: | Size: 633 KiB |
|
Before Width: | Height: | Size: 138 KiB After Width: | Height: | Size: 138 KiB |
|
Before Width: | Height: | Size: 124 KiB After Width: | Height: | Size: 124 KiB |
|
Before Width: | Height: | Size: 138 KiB After Width: | Height: | Size: 138 KiB |
|
Before Width: | Height: | Size: 215 KiB After Width: | Height: | Size: 215 KiB |
|
Before Width: | Height: | Size: 63 KiB After Width: | Height: | Size: 63 KiB |
|
Before Width: | Height: | Size: 106 KiB After Width: | Height: | Size: 106 KiB |
|
Before Width: | Height: | Size: 117 KiB After Width: | Height: | Size: 117 KiB |
|
Before Width: | Height: | Size: 366 KiB After Width: | Height: | Size: 366 KiB |
@@ -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:
|
||||
|
||||
|
Before Width: | Height: | Size: 44 KiB After Width: | Height: | Size: 44 KiB |
@@ -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`:
|
||||
|
Before Width: | Height: | Size: 87 KiB After Width: | Height: | Size: 87 KiB |
|
Before Width: | Height: | Size: 153 KiB After Width: | Height: | Size: 153 KiB |
|
Before Width: | Height: | Size: 153 KiB After Width: | Height: | Size: 153 KiB |
|
Before Width: | Height: | Size: 134 KiB After Width: | Height: | Size: 134 KiB |
|
Before Width: | Height: | Size: 60 KiB After Width: | Height: | Size: 60 KiB |
|
Before Width: | Height: | Size: 59 KiB After Width: | Height: | Size: 59 KiB |
|
Before Width: | Height: | Size: 151 KiB After Width: | Height: | Size: 151 KiB |
|
Before Width: | Height: | Size: 138 KiB After Width: | Height: | Size: 138 KiB |
|
Before Width: | Height: | Size: 134 KiB After Width: | Height: | Size: 134 KiB |
|
Before Width: | Height: | Size: 87 KiB After Width: | Height: | Size: 87 KiB |
|
Before Width: | Height: | Size: 106 KiB After Width: | Height: | Size: 106 KiB |
|
Before Width: | Height: | Size: 107 KiB After Width: | Height: | Size: 107 KiB |
|
Before Width: | Height: | Size: 811 KiB After Width: | Height: | Size: 811 KiB |
|
Before Width: | Height: | Size: 127 KiB After Width: | Height: | Size: 127 KiB |
|
Before Width: | Height: | Size: 127 KiB After Width: | Height: | Size: 127 KiB |
|
Before Width: | Height: | Size: 149 KiB After Width: | Height: | Size: 149 KiB |
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
|
Before Width: | Height: | Size: 44 KiB After Width: | Height: | Size: 44 KiB |
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
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
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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|:
|
||||
|
||||
|
||||
|
After Width: | Height: | Size: 1.3 MiB |
|
After Width: | Height: | Size: 823 KiB |
|
Before Width: | Height: | Size: 20 KiB |
|
Before Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 43 KiB |
|
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:
|
||||
|
||||
|
||||
@@ -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'),
|
||||
]
|
||||
|
||||