clearlinux/clear-linux-documentation
2
0
Fork 0
mirror of https://github.com/clearlinux/clear-linux-documentation.git synced 2026-07-09 22:25:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into mv-edits-telemetry-enable

Browse Source
This commit is contained in:
Michael Vincerra
2018-10-02 14:30:17 -07:00
parent 820e69f383 3d6f5b631a
commit 9b716482db
29 changed files with 148 additions and 616 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/identify--guides--type-by-role----for-guides-only-.md
-20
View File
@@ -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:
.github/ISSUE_TEMPLATE/modify-document.md
+19
View File
@@ -0,0 +1,19 @@
---
name: Modify document
about: Modify a document for the Clear Linux* Project
---
**Describe the error/improvement to an existing document or image**
Provide a clear and concise description of the error or proposed improvement.
**Screenshots**
If applicable, add screenshots to help explain the error or unexpected behavior.
**Environment (please complete the following):**
- Clear Linux OS version: [`cat /usr/lib/os-release`]
- Third-party tool/software: [version]
- Command [ [e.g. `sudo -i`]
**Additional context**
Add any other context about the problem here.
.github/ISSUE_TEMPLATE/new-document.md
+17
View File
@@ -0,0 +1,17 @@
---
name: New document
about: Request a new document for the Clear Linux* project
---
**Do you think Clear Linux documentation needs a new document? Please describe.**
Please provide a clear and concise description of the title and content. Identify the target audience: Developer; System Administrator; or Basic User.
**Should the new document be a guide, a reference, or a tutorial?**
Recommend a type of document, based on the structure here: https://clearlinux.org/documentation/clear-linux
**Describe or provide examples of similar documents, if possible, from other web sites**
Please provide an example of similar documents if possible.
**Additional context**
Add any other context or screenshots for the document request here.
source/clear-containers/architecture-overview.rst
-409
View File
@@ -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
source/clear-containers/clear-containers.rst
-29
View File
@@ -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
source/clear-containers/figures/clear-containers-v1.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 328 KiB

source/clear-containers/figures/clear-containers-v2.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 360 KiB

source/clear-containers/figures/dax-v1.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 50 KiB

source/clear-containers/figures/dax-v2.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 50 KiB

source/clear-containers/getting-started.rst
-38
View File
@@ -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
source/clear-linux/get-started/bare-metal-install/bare-metal-install.rst
+4 -4
View File
@@ -22,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:
source/clear-linux/get-started/bootable-usb/bootable-usb-linux.rst
+2 -2
View File
@@ -17,7 +17,7 @@ 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:
@@ -35,7 +35,7 @@ Burn the |CL| 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
source/clear-linux/get-started/bootable-usb/bootable-usb-mac.rst
+2 -2
View File
@@ -17,7 +17,7 @@ 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:
@@ -29,7 +29,7 @@ Burn the |CL| image onto a USB drive
|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.
source/clear-linux/get-started/bootable-usb/bootable-usb-windows.rst
+1 -1
View File
@@ -17,7 +17,7 @@ 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 |CL| image onto a USB drive
source/clear-linux/get-started/bootable-usb/figures/download-verify-uncompress-windows-fig-1.png → source/clear-linux/get-started/bootable-usb/figures/download-verify-decompress-windows-fig-1.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 44 KiB

source/clear-linux/get-started/virtual-machine-install/figures/download-verify-uncompress-windows-fig-1.png → source/clear-linux/get-started/virtual-machine-install/figures/download-verify-decompress-windows-fig-1.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 44 KiB

source/clear-linux/get-started/virtual-machine-install/hyper-v.rst
+1 -1
View File
@@ -29,7 +29,7 @@ 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 |CL| from our `downloads`_ section.
source/clear-linux/get-started/virtual-machine-install/vmw-player-preconf.rst
+4 -4
View File
@@ -68,13 +68,13 @@ this command:
Visit :ref:`image-types` for additional information about all available |CL| images.
.. include:: ../../guides/maintenance/download-verify-uncompress-windows.rst
.. 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
*****************************
@@ -182,7 +182,7 @@ Create and configure a new VM
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.
source/clear-linux/get-started/virtual-machine-install/vmw-player.rst
+4 -4
View File
@@ -70,13 +70,13 @@ Look for :file:`clear-[version number]-installer.iso.xz`.
Visit :ref:`image-types` for additional information about all available |CL| images.
.. include:: ../../guides/maintenance/download-verify-uncompress-windows.rst
.. 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
*****************************
@@ -103,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.
source/clear-linux/get-started/virtual-machine-install/vmware-esxi-install-cl.rst
+6 -6
View File
@@ -38,14 +38,14 @@ 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 |CL| installer ISO to the VMware server
**************************************************
@@ -81,7 +81,7 @@ Upload the |CL| 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
source/clear-linux/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst
+7 -7
View File
@@ -40,20 +40,20 @@ this command:
Visit :ref:`image-types` for additional information about all available |CL| images.
.. 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 |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`_
@@ -92,7 +92,7 @@ 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 |CL| image to an ESXi-supported format
source/clear-linux/guides/maintenance/download-verify-uncompress-linux.rst → source/clear-linux/guides/maintenance/download-verify-decompress-linux.rst
+18 -14
View File
@@ -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:
source/clear-linux/guides/maintenance/download-verify-uncompress-mac.rst → source/clear-linux/guides/maintenance/download-verify-decompress-mac.rst
+13 -13
View File
@@ -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
source/clear-linux/guides/maintenance/download-verify-uncompress-windows.rst → source/clear-linux/guides/maintenance/download-verify-decompress-windows.rst
+12 -12
View File
@@ -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
source/clear-linux/guides/maintenance/figures/download-verify-uncompress-windows-fig-1.png → source/clear-linux/guides/maintenance/figures/download-verify-decompress-windows-fig-1.png
Executable → Regular
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 44 KiB

source/clear-linux/guides/maintenance/maintenance.rst
+6 -5
View File
@@ -3,8 +3,9 @@
Maintenance guide
#################
These guides provide step-by-step instructions for common tasks associated with
maintaining |CL-ATTR| 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
@@ -21,7 +22,7 @@ maintaining |CL-ATTR| after :ref:`installation <get-started>` is completed.
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
source/clear-linux/guides/maintenance/mixer.rst
+29 -37
View File
@@ -1,10 +1,10 @@
.. _mixer:
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.
@@ -34,22 +34,14 @@ any of the commands.
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 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.
@@ -57,7 +49,7 @@ these workflows.
.. _create-nginx-web-server:
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:
@@ -143,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.
@@ -168,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:
@@ -180,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:
@@ -241,7 +233,7 @@ up automatically with the optional *--git* flag, for example:
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.
@@ -352,10 +344,10 @@ The following variables require further explanation:
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
@@ -364,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`.
@@ -381,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:
@@ -403,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
@@ -413,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:
@@ -473,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.**
@@ -509,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
@@ -536,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:
@@ -559,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:
@@ -594,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.
@@ -626,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
@@ -642,7 +634,7 @@ 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:
@@ -663,7 +655,7 @@ on-the-fly if a new version must be downloaded.
Create an update
****************
================
Create an update with the following command:
@@ -701,7 +693,7 @@ 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
@@ -759,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:
@@ -843,7 +835,7 @@ modifications as needed, for example:
.. _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
source/clear-linux/guides/network/custom-clear-container.rst
+1 -6
View File
@@ -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
source/clear-linux/tutorials/web-server-install/web-server-install.rst
+2 -2
View File
@@ -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: