diff --git a/source/FAQ/faq.rst b/source/FAQ/faq.rst deleted file mode 100644 index 4b7be4f2..00000000 --- a/source/FAQ/faq.rst +++ /dev/null @@ -1,189 +0,0 @@ -.. _faq: - -FAQ -### - -Below is a list of commonly asked questions with answers sourced from the -|CL-ATTR| team and `Clear Linux community forums`_. - -.. contents:: :local: - :depth: 2 - - -General -******* - -Why did you make another distro? -================================ - -The |CL| team felt that performance was left on the table with Linux software. -|CL| takes a holistic approach to improving performance across the stack. We -also wanted to take more modern approaches with OS updates and tooling. - -| - -Can other distros copy |CL| improvements? -========================================= - -Yes, we absolutely love open source reuse and upstreaming improvements. - -| - -How often do you update? -======================== - -The |CL| team puts out multiple releases a week, often releasing 2 or more -times a day. This rolling release approach allows |CL| to remain agile to -upstream changes and security patches. - -| - -Is telemetry required? -====================== - -The telemetry solution provided by |CL| is entirely optional and customizable. -It is disabled by default. If you do choose to enable telemetry, the data -helps the |CL| team proactively identify and resolve bugs. See the -:ref:`telemetry ` page for more information. - -| - -What is the default firewall? -============================= - -|CL| packages :command:`iptables` as a bundle, however, there are no default -firewall rules. All network traffic is allowed by default. - -| - -Where are the files that I usually see under /etc like fstab? -============================================================= - -|CL| has a stateless design that maintains a separation between system files -and user files. Default values are stored under :file:`/usr/share/defaults/`. -Files under :file:`/etc/` are not created unless you create one. - -A blog post explaining how this is accomplished with :file:`/etc/fstab/` -specifically is available here: -https://clearlinux.org/news-blogs/where-etcfstab-clear-linux - -| - -Software packages -***************** - -How is software installed and updated? -====================================== - -|CL| provides software in the form of :ref:`bundles ` and -updates software with :ref:`swupd `. - -:ref:`FlatPak\* ` is an application virtualization solution that allows -more software to be available to |CL| users by augmenting the software |CL| -packages natively with software available through FlatPak. - -Our goal is to have software packaged natively and made available through -bundles whenever possible. - -| - -Does |CL| use RPMs like other distros? -====================================== - -|CL| provides software in the form of :ref:`bundles `. The RPM -format is used as an intermediary step for packaging and determining software -dependencies at OS build time. - -Individual RPMs can sometimes be manually installed on a |CL| system with the -right tools, but that is not the intended use case. - -| - -Can I install a software package from another OS on |CL|? -========================================================= - -Software that is packaged in other formats for other Linux distributions is -not guaranteed to work on |CL| and may be impacted by |CL| updates. - -If the software you're seeking is open source, please submit a request to add -it to |CL|. Submit requests on GitHub\* here: -https://github.com/clearlinux/distribution/issues - -| - -Software availability -********************* - -What software is available on |CL|? -=================================== - -Available software can be found in the `Software Store`_, through the GNOME\* -Software application on the desktop, or by using :ref:`swupd search `. - -| - -Is Google\* Chrome\* available? -=============================== - -The Google Chrome web browser is not distributed as a bundle in |CL| due to -copyright and licensing complexities. - -A discussion on manually installing and maintaining Google Chrome can be found -on GitHub: https://github.com/clearlinux/distribution/issues/422 - -| - -Is FFmpeg available? -==================== - -`FFmpeg`_ is a multimedia software suite, which is commonly used for -various media encoding/decoding, streaming, and playback. - -|CL| does not distribute FFmpeg due to well-known licensing and legal -complexities (See https://www.ffmpeg.org/legal.html and -http://blog.pkh.me/p/13-the-ffmpeg-libav-situation.html). - -Read more in the |CL| repository, including discussion of an alternative -hardware-based solution: -https://github.com/clearlinux/distribution/issues/429. - -While |CL| cannot distribute FFmpeg, a manual solution to build and install -FFmpeg under :file:`/usr/local` has been shared on the community forums: -https://community.clearlinux.org/t/how-to-h264-etc-support-for-firefox-including-ffmpeg-install. - -| - -Is ZFS\* available? -=================== - -ZFS is not available with |CL| because of copyright and licensing -complexities. BTRFS is an alternative filesystem that is available in |CL| -natively. - -A user on GitHub notes that the ZFS kernel module can be compiled, built, and -installed manually: https://github.com/clearlinux/distribution/issues/631 - -| - -Can you add a driver that I need? -================================= - -If a kernel module is available as part of the Linux kernel source tree but -not enabled in the |CL| kernels, in many cases the |CL| team will enable it -upon request. Submit requests on GitHub here: -https://github.com/clearlinux/distribution/issues - -The |CL| team does not typically add out-of-tree kernel modules as a matter of -practice because of the maintenance overhead. If the driver was unable to be -merged upstream, there is a good chance we may be unable to merge it for -similar reasons. - -Kernel modules can be individually built and installed on |CL|. See the -:ref:`kernel modules ` page for more information. - -| - - -.. _`Clear Linux community forums`: https://community.clearlinux.org -.. _`Software Store`: https://clearlinux.org/software -.. _`FFmpeg`: https://ffmpeg.org/ diff --git a/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css b/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css index 478f2f6e..28546ac9 100644 --- a/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css +++ b/source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css @@ -249,9 +249,4 @@ th,td { font-family: "IntelClear-Bold", Helvetica, Arial, sans-serif; margin-left: 0.67em; line-height: 100px; -} - -/*Adds a bit of spacing after the last paragraph in a bulleted list*/ -.wy-plain-list-disc li p:last-child, .rst-content .section ul li p:last-child, .rst-content .toctree-wrapper ul li p:last-child, article ul li p:last-child { - margin-bottom: 10px; } \ No newline at end of file diff --git a/source/clear-linux/clear-linux.rst b/source/clear-linux/clear-linux.rst new file mode 100644 index 00000000..8436cd1c --- /dev/null +++ b/source/clear-linux/clear-linux.rst @@ -0,0 +1,48 @@ +.. _clear-linux: + +|CL-PRJ| +############################################# + +Welcome to the |CL-ATTR| documentation pages, the source for |CL| documentation. + +.. raw:: html + + + +Our documentation is divided into the following sections: + +* :ref:`get-started` + + 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:`concepts` + + Wondering what makes |CL| different? Learn about |CL| features and what + differentiates |CL| from other Linux distros. + +* :ref:`guides` + + 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 + guides/guides + tutorials/tutorials + reference/reference diff --git a/source/concepts/autospec-about.rst b/source/clear-linux/concepts/autospec-about.rst similarity index 100% rename from source/concepts/autospec-about.rst rename to source/clear-linux/concepts/autospec-about.rst diff --git a/source/concepts/bundles-about.rst b/source/clear-linux/concepts/bundles-about.rst similarity index 100% rename from source/concepts/bundles-about.rst rename to source/clear-linux/concepts/bundles-about.rst diff --git a/source/clear-linux/concepts/concepts.rst b/source/clear-linux/concepts/concepts.rst new file mode 100644 index 00000000..1a324c33 --- /dev/null +++ b/source/clear-linux/concepts/concepts.rst @@ -0,0 +1,18 @@ +.. _concepts: + +Concepts +######## + +|CL-ATTR| does things differently than other Linux distributions. Use the concepts section to learn in detail about the features that make |CL| +different. + +.. toctree:: + :maxdepth: 2 + + swupd-about + mixer-about + bundles-about + autospec-about + restart + security + telemetry-about diff --git a/source/concepts/figures/mixer-about-1.png b/source/clear-linux/concepts/figures/mixer-about-1.png similarity index 100% rename from source/concepts/figures/mixer-about-1.png rename to source/clear-linux/concepts/figures/mixer-about-1.png diff --git a/source/concepts/figures/mixer-about-2.png b/source/clear-linux/concepts/figures/mixer-about-2.png similarity index 100% rename from source/concepts/figures/mixer-about-2.png rename to source/clear-linux/concepts/figures/mixer-about-2.png diff --git a/source/concepts/figures/telemetry-about-1.png b/source/clear-linux/concepts/figures/telemetry-about-1.png similarity index 100% rename from source/concepts/figures/telemetry-about-1.png rename to source/clear-linux/concepts/figures/telemetry-about-1.png diff --git a/source/concepts/mixer-about.rst b/source/clear-linux/concepts/mixer-about.rst similarity index 100% rename from source/concepts/mixer-about.rst rename to source/clear-linux/concepts/mixer-about.rst diff --git a/source/concepts/restart.rst b/source/clear-linux/concepts/restart.rst similarity index 100% rename from source/concepts/restart.rst rename to source/clear-linux/concepts/restart.rst diff --git a/source/concepts/security.rst b/source/clear-linux/concepts/security.rst similarity index 100% rename from source/concepts/security.rst rename to source/clear-linux/concepts/security.rst diff --git a/source/concepts/swupd-about.rst b/source/clear-linux/concepts/swupd-about.rst similarity index 89% rename from source/concepts/swupd-about.rst rename to source/clear-linux/concepts/swupd-about.rst index 8d6e5bb4..99edfa1b 100644 --- a/source/concepts/swupd-about.rst +++ b/source/clear-linux/concepts/swupd-about.rst @@ -60,8 +60,12 @@ to update. Update integrity ---------------- -This is the basis of the :command:`swupd diagnose` subcommand, which allows a |CL| system to check for any discrepancies to system files. As necessary, -:command:`swupd repair` provides a useful way for software developers to remediate these discrepancies and return to a known filesystem state. +:command:`swupd` operates against a published manifest of files for a +particular |CL| version that contains the unique hash of each file. This is +the basis of the :command:`swupd verify` subcommand, which allows a |CL| +system to check for and remediate any discrepancies to system files. As +necessary, :command:`swupd verify` provides a useful way for software +developers to return to a known filesystem state. Bundles ======= diff --git a/source/concepts/telemetry-about.rst b/source/clear-linux/concepts/telemetry-about.rst similarity index 92% rename from source/concepts/telemetry-about.rst rename to source/clear-linux/concepts/telemetry-about.rst index 34a12d1e..1c371078 100644 --- a/source/concepts/telemetry-about.rst +++ b/source/clear-linux/concepts/telemetry-about.rst @@ -24,10 +24,6 @@ for debugging purposes. You can use **libtelemetry** in your code to create cust telemetry records. You can also use **telem-record-gen** in script files or call it from another program. -.. note:: - - The |CL| telemetry client is disabled by default until you decide to enable it. Telemetry is an **opt-in** solution and can be easily enabled or disabled. - Architecture ************ @@ -78,5 +74,10 @@ own records, then you must set up your own telemetry backend server. Next steps ********** -To put this concept into practice, refer to :ref:`telem-guide`. +To put this concept into practice, see the following resources: +* :ref:`telem-guide` +* `Telemetry feature description`_ + +.. _`Telemetry feature description`: + https://clearlinux.org/features/telemetry diff --git a/source/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst b/source/clear-linux/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst similarity index 95% rename from source/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst rename to source/clear-linux/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst index 0185619e..1ed63f1d 100644 --- a/source/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst +++ b/source/clear-linux/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst @@ -70,8 +70,8 @@ Confirm network connection ========================== Confirm there is a network connection before launching the installer. -Choose a method: `Wired Connection`, or `WiFi Connected`. This guide shows -an example of a **Wired Connection**. +Choose a method: `Wired Connection`, or `WiFi Connected`. +This guide shows an example of a **Wired Connection**. #. In the upper right of the top menu bar, select the square icon to view Network settings, shown in Figure 2. @@ -243,16 +243,6 @@ Use this method to safely install |CL| on media with available space, or alongside existing partitions, and accept the `Default partition schema`_. If enough free space exists, safe installation is allowed. -.. note:: - - |CL| allows installation alongside another OS. Typically, when you boot - your system, you can press an `F key` to view and select a bootable - device or partition during the BIOS POST stage. Some BIOSes present the - |CL| partition, and you can select and boot it. However, other - BIOSes may only show the primary partition, in which case you will not be - able boot |CL|. Be aware of this possible limitation. - - Destructive Installation ------------------------ @@ -354,7 +344,11 @@ team for improvements. For more information, see :ref:`telemetry-about`. #. From :guilabel:`Required Options`, select :guilabel:`Telemetry`. -#. Select :kbd:`Yes`. +#. Select :kbd:`Confirm`. + +#. If you don't wish to participate, deselect :kbd:`Enable Telemetry`. + +#. Select :kbd:`Confirm`. .. figure:: figures/bare-metal-install-desktop-12.png :scale: 100% @@ -362,8 +356,6 @@ team for improvements. For more information, see :ref:`telemetry-about`. Figure 12: Enable Telemetry -#. If you don't wish to participate, select :kbd:`No`. - Advanced options **************** diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-beta-29.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-beta-29.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-beta-29.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-beta-29.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-01.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-01.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-01.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-01.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-02.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-02.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-02.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-02.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-03.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-03.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-03.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-03.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-04.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-04.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-04.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-04.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-05.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-05.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-05.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-05.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-06.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-06.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-06.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-06.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-07.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-07.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-07.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-07.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-08.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-08.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-08.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-08.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-09.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-09.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-09.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-09.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-10.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-10.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-10.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-10.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-11.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-11.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-11.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-11.png diff --git a/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-12.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-12.png new file mode 100644 index 00000000..c2bcc90e Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-12.png differ diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-13.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-13.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-13.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-13.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-14.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-14.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-14.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-14.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-15.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-15.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-15.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-15.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-16.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-16.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-16.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-16.png diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-17.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-17.png similarity index 100% rename from source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-17.png rename to source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-17.png diff --git a/source/get-started/bare-metal-install-server/bare-metal-install-server.rst b/source/clear-linux/get-started/bare-metal-install-server/bare-metal-install-server.rst similarity index 99% rename from source/get-started/bare-metal-install-server/bare-metal-install-server.rst rename to source/clear-linux/get-started/bare-metal-install-server/bare-metal-install-server.rst index afa4cf8a..9c6069f7 100644 --- a/source/get-started/bare-metal-install-server/bare-metal-install-server.rst +++ b/source/clear-linux/get-started/bare-metal-install-server/bare-metal-install-server.rst @@ -49,11 +49,6 @@ Follow these steps to install |CL| on the target system: #. Open the system BIOS setup menu by pressing the :kbd:`F2` key. Your BIOS setup menu entry point may vary. - .. note:: - |CL| supports UEFI boot. Some hardware may list UEFI and non-UEFI USB - boot entries. In this case, you should select the `UEFI` boot - option. - #. In the setup menu, enable the UEFI boot and set the USB drive as the first option in the device boot order. diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-01.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-01.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-01.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-01.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-02.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-02.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-02.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-02.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-03.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-03.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-03.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-03.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-04.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-04.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-04.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-04.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-05.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-05.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-05.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-05.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-06.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-06.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-06.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-06.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-07.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-07.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-07.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-07.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-08.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-08.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-08.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-08.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-09.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-09.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-09.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-09.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-10.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-10.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-10.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-10.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-11.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-11.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-11.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-11.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-12.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-12.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-12.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-12.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-13.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-13.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-13.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-13.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-14.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-14.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-14.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-14.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-15.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-15.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-15.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-15.png diff --git a/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-16.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-16.png new file mode 100644 index 00000000..651c2c94 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-16.png differ diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-17.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-17.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-17.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-17.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-18.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-18.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-18.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-18.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-19.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-19.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-19.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-19.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-20.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-20.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-20.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-20.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-21.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-21.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-21.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-21.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-22.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-22.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-22.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-22.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-23.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-23.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-23.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-23.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-24.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-24.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-24.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-24.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-25.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-25.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-25.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-25.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-26.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-26.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-26.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-26.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-27.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-27.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-27.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-27.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-28.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-28.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-28.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-28.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-29.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-29.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-29.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-29.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-30.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-30.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-30.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-30.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-31.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-31.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-31.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-31.png diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-32.png b/source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-32.png similarity index 100% rename from source/get-started/bare-metal-install-server/figures/bare-metal-install-server-32.png rename to source/clear-linux/get-started/bare-metal-install-server/figures/bare-metal-install-server-32.png diff --git a/source/get-started/bootable-usb/bootable-usb.rst b/source/clear-linux/get-started/bootable-usb/bootable-usb.rst similarity index 100% rename from source/get-started/bootable-usb/bootable-usb.rst rename to source/clear-linux/get-started/bootable-usb/bootable-usb.rst diff --git a/source/get-started/bootable-usb/figures/bootable-usb-mac-01.png b/source/clear-linux/get-started/bootable-usb/figures/bootable-usb-mac-01.png similarity index 100% rename from source/get-started/bootable-usb/figures/bootable-usb-mac-01.png rename to source/clear-linux/get-started/bootable-usb/figures/bootable-usb-mac-01.png diff --git a/source/get-started/bootable-usb/figures/bootable-usb-windows-02.png b/source/clear-linux/get-started/bootable-usb/figures/bootable-usb-windows-02.png similarity index 100% rename from source/get-started/bootable-usb/figures/bootable-usb-windows-02.png rename to source/clear-linux/get-started/bootable-usb/figures/bootable-usb-windows-02.png diff --git a/source/get-started/bootable-usb/figures/bootable-usb-windows-03.png b/source/clear-linux/get-started/bootable-usb/figures/bootable-usb-windows-03.png similarity index 100% rename from source/get-started/bootable-usb/figures/bootable-usb-windows-03.png rename to source/clear-linux/get-started/bootable-usb/figures/bootable-usb-windows-03.png diff --git a/source/get-started/bootable-usb/figures/download-verify-decompress-windows-fig-1.png b/source/clear-linux/get-started/bootable-usb/figures/download-verify-decompress-windows-fig-1.png similarity index 100% rename from source/get-started/bootable-usb/figures/download-verify-decompress-windows-fig-1.png rename to source/clear-linux/get-started/bootable-usb/figures/download-verify-decompress-windows-fig-1.png diff --git a/source/get-started/compatibility-check.rst b/source/clear-linux/get-started/compatibility-check.rst similarity index 100% rename from source/get-started/compatibility-check.rst rename to source/clear-linux/get-started/compatibility-check.rst diff --git a/source/get-started/get-started.rst b/source/clear-linux/get-started/get-started.rst similarity index 52% rename from source/get-started/get-started.rst rename to source/clear-linux/get-started/get-started.rst index 8a2745b8..8715b8dd 100644 --- a/source/get-started/get-started.rst +++ b/source/clear-linux/get-started/get-started.rst @@ -10,40 +10,20 @@ from a live desktop or to a virtual machine. Pre-install *********** -There are a couple of things to take care of before you install. - * :ref:`system-requirements` -* :ref:`compatibility-check` -* :ref:`bootable-usb` - -When installing |CL-ATTR| in a VM, consider which kernel to use. - -* :ref:`Compatible VM kernels ` .. toctree:: :maxdepth: 1 - :hidden: compatibility-check bootable-usb/bootable-usb -Install -******* +Install |CL| +************ .. toctree:: :maxdepth: 1 bare-metal-install-desktop/bare-metal-install-desktop bare-metal-install-server/bare-metal-install-server - -.. _virtual-machine-install: - -Install in a virtual machine -**************************** - -.. toctree:: - :maxdepth: 1 - :glob: - - virtual-machine-install/* - ../../guides/maintenance/increase-virtual-disk-size.rst \ No newline at end of file + virtual-machine-install/virtual-machine-install diff --git a/source/get-started/virtual-machine-install/figures/confirmation-screen.png b/source/clear-linux/get-started/virtual-machine-install/figures/confirmation-screen.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/confirmation-screen.png rename to source/clear-linux/get-started/virtual-machine-install/figures/confirmation-screen.png diff --git a/source/get-started/virtual-machine-install/figures/download-verify-decompress-windows-fig-1.png b/source/clear-linux/get-started/virtual-machine-install/figures/download-verify-decompress-windows-fig-1.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/download-verify-decompress-windows-fig-1.png rename to source/clear-linux/get-started/virtual-machine-install/figures/download-verify-decompress-windows-fig-1.png diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-cl-first-login.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-cl-first-login.png new file mode 100644 index 00000000..5e8ed691 Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-cl-first-login.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-cl-remove-non-lts-kernels.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-cl-remove-non-lts-kernels.png new file mode 100644 index 00000000..2a253748 Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-cl-remove-non-lts-kernels.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-convert-raw-to-VDI.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-convert-raw-to-VDI.png new file mode 100644 index 00000000..3c20c833 Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-convert-raw-to-VDI.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-disk.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-disk.png new file mode 100644 index 00000000..7995d8d7 Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-disk.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-choose-disk.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-choose-disk.png new file mode 100644 index 00000000..c672ac9b Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-choose-disk.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-existing-disk.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-existing-disk.png new file mode 100644 index 00000000..d8b4846a Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-existing-disk.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-new-disk.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-new-disk.png new file mode 100644 index 00000000..7c2d1cc6 Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-new-disk.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-no-disk.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-no-disk.png new file mode 100644 index 00000000..68f9dddf Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-no-disk.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-extract-cl-IMG.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-extract-cl-IMG.png new file mode 100644 index 00000000..6aeb25e1 Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-extract-cl-IMG.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-extract-cl-ISO.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-extract-cl-ISO.png new file mode 100644 index 00000000..c9b8932f Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-extract-cl-ISO.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-new-vm.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-new-vm.png new file mode 100644 index 00000000..ae8929bb Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-new-vm.png differ diff --git a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-12.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-no-vtx.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-12.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-no-vtx.png diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-shutdown-vm.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-shutdown-vm.png new file mode 100644 index 00000000..11ef90fe Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-shutdown-vm.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-start-vm.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-start-vm.png new file mode 100644 index 00000000..76c012ec Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-start-vm.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-created.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-created.png new file mode 100644 index 00000000..1e23ccbd Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-created.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-insert-ga-cd.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-insert-ga-cd.png new file mode 100644 index 00000000..4eae68ce Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-insert-ga-cd.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-EFI.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-EFI.png new file mode 100644 index 00000000..2dc55dff Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-EFI.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-browse-ISO.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-browse-ISO.png new file mode 100644 index 00000000..ed229d3f Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-browse-ISO.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-mount-ISO.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-mount-ISO.png new file mode 100644 index 00000000..765df5ca Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-mount-ISO.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-unmount-ISO.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-unmount-ISO.png new file mode 100644 index 00000000..4e08843f Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-unmount-ISO.png differ diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-01.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-01.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-01.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-01.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-02.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-02.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-02.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-02.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-03.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-03.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-03.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-03.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-04.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-04.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-04.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-04.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-05.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-05.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-05.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-05.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-06.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-06.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-06.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-06.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-07.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-07.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-07.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-07.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-08.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-08.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-08.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-08.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-09.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-09.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-09.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-09.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-10.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-10.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-10.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-10.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-11.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-11.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-11.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-11.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-12.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-12.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-12.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-12.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-13.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-13.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-13.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-13.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-14.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-14.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-14.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-14.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-15.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-15.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-15.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player-preconf/vmw-player-preconf-15.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-01.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-01.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-01.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-01.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-02.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-02.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-02.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-02.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-03.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-03.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-03.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-03.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-04.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-04.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-04.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-04.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-05.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-05.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-05.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-05.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-06.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-06.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-06.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-06.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-07.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-07.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-07.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-07.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-08.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-08.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-08.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-08.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-09.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-09.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-09.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-09.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-10.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-10.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-10.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-10.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-11.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-11.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-11.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-11.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-12.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-12.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-12.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-12.png diff --git a/source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-13.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-13.png similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmw-player/vmw-player-13.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmw-player/vmw-player-13.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-1.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-1.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-1.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-1.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-10.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-10.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-10.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-10.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-11.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-11.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-11.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-11.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-12.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-12.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-12.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-12.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-13.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-13.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-13.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-13.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-14.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-14.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-14.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-14.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-15.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-15.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-15.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-15.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-16.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-16.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-16.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-16.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-2.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-2.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-2.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-2.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-3.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-3.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-3.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-3.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-4.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-4.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-4.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-4.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-5.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-5.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-5.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-5.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-6.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-6.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-6.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-6.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-7.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-7.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-7.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-7.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-8.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-8.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-8.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-8.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-9.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-9.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-9.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-install-cl-9.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-1.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-1.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-1.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-1.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-10.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-10.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-10.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-10.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-11.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-11.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-11.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-11.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-12.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-12.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-12.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-12.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-13.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-13.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-13.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-13.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-2.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-2.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-2.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-2.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-3.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-3.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-3.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-3.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-4.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-4.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-4.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-4.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-5.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-5.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-5.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-5.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-6.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-6.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-6.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-6.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-7.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-7.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-7.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-7.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-8.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-8.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-8.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-8.png diff --git a/source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-9.png b/source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-9.png old mode 100644 new mode 100755 similarity index 100% rename from source/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-9.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-9.png diff --git a/source/get-started/virtual-machine-install/hyper-v.rst b/source/clear-linux/get-started/virtual-machine-install/hyper-v.rst similarity index 100% rename from source/get-started/virtual-machine-install/hyper-v.rst rename to source/clear-linux/get-started/virtual-machine-install/hyper-v.rst diff --git a/source/get-started/virtual-machine-install/kvm.rst b/source/clear-linux/get-started/virtual-machine-install/kvm.rst similarity index 51% rename from source/get-started/virtual-machine-install/kvm.rst rename to source/clear-linux/get-started/virtual-machine-install/kvm.rst index 5cb677e0..8176bedf 100644 --- a/source/get-started/virtual-machine-install/kvm.rst +++ b/source/clear-linux/get-started/virtual-machine-install/kvm.rst @@ -3,7 +3,7 @@ Run |CL-ATTR| as a KVM guest OS ############################### -This guide explains how to run |CL-ATTR| 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 @@ -13,7 +13,12 @@ Install QEMU-KVM `Intel®Virtualization Technology for Directed I/O`_ (Intel® VT-d) in the host machine’s BIOS. -#. Log in and open a terminal emulator. +#. Log in, open a terminal emulator, and get root privilege on the host + machine: + + .. code-block:: bash + + sudo -s #. Install `QEMU*-KVM` on the host machine. Below are some example distros. @@ -21,25 +26,31 @@ Install QEMU-KVM .. code-block:: bash - sudo swupd bundle-add kvm-host + swupd bundle-add kvm-host - * On Ubuntu\* 18.04 LTS Desktop: + * |CL| option: Add this bundle to lanch the GUI upon boot. .. code-block:: bash - sudo apt-get install qemu-kvm + swupd bundle-add desktop-autostart - * On Mint\* 19.1 “Cinnamon” Desktop: + * On Ubuntu\* 16.04 LTS Desktop: .. code-block:: bash - sudo apt-get install qemu-kvm + apt-get install qemu-kvm - * On Fedora\* 30 Workstation: + * On Mint\* 18.1 “Serena” Desktop: .. code-block:: bash - sudo dnf install qemu-kvm + apt-get install qemu-kvm + + * On Fedora\* 25 Workstation: + + .. code-block:: bash + + dnf install qemu-kvm Download and launch the virtual machine *************************************** @@ -50,32 +61,32 @@ Download and launch the virtual machine .. code-block:: bash - curl -O https://cdn.download.clearlinux.org/image/$(curl https://cdn.download.clearlinux.org/image/latest-images | grep '[0-9]'-kvm'\.') + curl -O https://cdn.download.clearlinux.org/image/$(curl https://cdn.download.clearlinux.org/image/latest-images | grep '[0-9]'-kvm) #. Uncompress the downloaded image: .. code-block:: bash - unxz -v clear--kvm.img.xz + unxz clear--kvm.img.xz -#. Download the 3 OVMF files (`OVMF.fd`, `OVMF_CODE.fd`, `OVMF_VARS.fd`) that - provides UEFI support for virtual machines. +#. Download the `OVMF file`_ file that provides UEFI support for + virtual machines. .. code-block:: bash curl -O https://cdn.download.clearlinux.org/image/OVMF.fd - curl -O https://cdn.download.clearlinux.org/image/OVMF_CODE.fd - curl -O https://cdn.download.clearlinux.org/image/OVMF_VARS.fd + +#. Copy :file:`OVMF.fd` to the working directory, as shown below. + + .. code-block:: bash + + cp OVMF.fd .. note:: - The default OVMF files from |CL| may not work for some distro version(s). - You may get an `ASSERT` in the `debug.log` file when starting the VM. - If that is the case, use the distro-specific-OVMF files instead. - For example, the |CL| OVMF files work for Ubuntu 18.04 LTS, but not for Ubuntu 19.04 LTS. - Installing and using the OVMF files for Ubuntu 19.04 LTS resolved the `ASSERT` issue. + Replace with your own. -#. Download the `QEMU-KVM launcher`_ script from the +#. Download the sample `QEMU-KVM launcher`_ script from the `image `_ directory. This script will launch the |CL| VM and provide console interaction within the same terminal emulator window. @@ -94,7 +105,7 @@ Download and launch the virtual machine .. code-block:: bash - sudo ./start_qemu.sh clear--kvm.img + ./start_qemu.sh clear--kvm.img #. Log in as ``root`` user and set a new password. @@ -112,28 +123,21 @@ launched from, follow these steps. PermitRootLogin yes EOF -#. Enable and start SSH server in the |CL| VM: +#. Start SSH server in the |CL| VM: .. code-block:: bash - systemctl enable sshd systemctl start sshd -#. Determine the IP address of the host on which you will launch the VM. - Substitute in the next step with this information. +#. From the host, SSH into the |CL| VM. The port number ``10022`` is defined + in the ``start_qemu.sh`` script. .. code-block:: bash - ip a + ssh -p 10022 root@localhost -#. SSH into the |CL| VM using the default port of `10022`: - - .. code-block:: bash - - ssh -p 10022 root@ - -Optional: Add the GNOME Display Manager (GDM) -********************************************* +Add the GNOME Display Manager (GDM) +*********************************** To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps: @@ -141,90 +145,90 @@ To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps: .. code-block:: bash - poweroff + shutdown now -#. Install the Spice viewer on the local host or remote system. Below are some - example distros. +#. Install a VNC viewer on the host machine. Below are some example distros. * On Clear Linux: .. code-block:: bash - sudo swupd bundle-add virt-viewer + swupd bundle-add tigervnc - * On Ubuntu\* 18.04 LTS Desktop: + * On Ubuntu\* 16.04 LTS Desktop: .. code-block:: bash - sudo apt-get install virt-viewer + apt-get install vncviewer - * On Mint\* 19.1 “Cinnamon” Desktop: + * On Mint\* 18.1 “Serena” Desktop: .. code-block:: bash - sudo apt-get install virt-viewer + apt-get install vncviewer - * On Fedora\* 30 Workstation: + * On Fedora\* 25 Workstation: .. code-block:: bash - sudo dnf install virt-viewer + dnf install tigervnc -#. Modify the :file:`start_qemu.sh` script to increase memory (`-m`), add - graphics driver (`-vga`), and add Spice (`-spice`, `-usb`, and - `-device`) support. +#. Modify the :file:`start_qemu.sh` script to increase memory (``-m``), add + graphics driver (``-vga``), and add VNC (``-vnc``, ``-usb``, and + ``-device``) support. .. code-block:: console qemu-system-x86_64 \ -enable-kvm \ - ${UEFI_BIOS} \ + -bios OVMF.fd \ -smp sockets=1,cpus=4,cores=2 -cpu host \ -m 4096 \ -vga qxl \ - -nographic \ - -spice port=5924,disable-ticketing \ + -vnc :0 -nographic \ -usb \ - -device usb-tablet,bus=usb-bus.0 \ + -device usb-tablet \ -drive file="$IMAGE",if=virtio,aio=threads,format=raw \ -netdev user,id=mynet0,hostfwd=tcp::${VMN}0022-:22,hostfwd=tcp::${VMN}2375-:2375 \ -device virtio-net-pci,netdev=mynet0 \ -debugcon file:debug.log -global isa-debugcon.iobase=0x402 $@ #. Due to changes in the :file:`start_qemu.sh` script from the previous step, - using the same OVMF files will result in the VM not booting properly and - you end up in the the UEFI shell. The easiest way to avoid this is to delete - the OVMF files and restore the originals before relaunching the VM. + the UEFI :file:`NvVars` + information for the previously-booted |CL| VM will need to be reset. -#. Increase the size of the VM by 10GB to accommodate the GDM installation: + #. Relaunch the |CL| VM. The UEFI shell will appear. + + .. code-block:: bash + + ./start_qemu.sh clear--kvm.img + + #. At the UEFI shell, delete the :file:`NvVars` file: + + .. code-block:: bash + + Shell> del FS0:\NvVars + + #. Exit out of the UEFI shell: + + .. code-block:: bash + + Shell> reset -s + + #. Relaunch the |CL| VM: + + .. code-block:: bash + + ./start_qemu.sh clear--kvm.img + +#. From the host machine, open a new terminal emulator window and VNC into the + |CL| VM: .. code-block:: bash - qemu-img resize -f raw clear--kvm.img +10G + vncviewer 0.0.0.0 -#. Relaunch the |CL| VM: - - .. code-block:: bash - - sudo ./start_qemu.sh clear--kvm.img - -#. Determine the IP address of the host on which you will launch the VM. - Substitute in the next step with this information. - - .. code-block:: bash - - ip a - -#. From the local host or remote system, open a new terminal emulator window - and connect into the |CL| VM using the Spice viewer: - - .. code-block:: bash - - remote-viewer spice://:5924 - -#. Log in as `root` user into the |CL| VM. - -#. Follow these steps to `resize the partition`_ of the virtual disk of the VM. +#. Log in as ``root`` user into the |CL| VM. #. Add GDM to the |CL| VM: @@ -232,20 +236,19 @@ To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps: swupd bundle-add desktop-autostart -#. Reboot the |CL| VM to start GDM: +#. Reboot the |CL| VM to enable GDM: .. code-block:: bash reboot -#. Go through the GDM out-of-box experience (OOBE). +#. Go through GDM's out-of-box experience (OOBE). -#. The default aspect ratio of the GDM GUI for the |CL| VM is 4:3. To change - it, use GDM's `Devices > Displays` setting tool (located at the top-right corner). +#. The default aspect ratio of the GDM GUI for the |CL| VM is 4:3. To change + it, use GDM's ``Displays`` setting tool (located at the top-right corner). .. _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 .. _QEMU-KVM launcher: https://cdn.download.clearlinux.org/image/start_qemu.sh .. _OVMF file: https://cdn.download.clearlinux.org/image/OVMF.fd -.. _resize the partition: https://clearlinux.org/documentation/clear-linux/guides/maintenance/increase-virtual-disk-size#id8 diff --git a/source/clear-linux/get-started/virtual-machine-install/virtual-machine-install.rst b/source/clear-linux/get-started/virtual-machine-install/virtual-machine-install.rst new file mode 100644 index 00000000..c257550e --- /dev/null +++ b/source/clear-linux/get-started/virtual-machine-install/virtual-machine-install.rst @@ -0,0 +1,40 @@ +.. _virtual-machine-install: + +Install |CL-ATTR| in a virtual machine +###################################### + +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 |CL| provides the following Linux kernels with a respective +:ref:`bundle ` for VMs. Specific use cases these bundles serve +are provided along with links to their source code. + +.. include:: ../../reference/compatible-kernels.rst + :Start-after: vm-kernels: + +Next steps +********** + +Now that you have read about the |CL| compatible kernels, choose the +appropriate set of step-by-step instructions to proceed. + +.. toctree:: + :maxdepth: 1 + + kvm + virtualbox + vmware-esxi-install-cl + vmware-esxi-preconfigured-cl-image + vmw-player + vmw-player-preconf + hyper-v + virtualbox-cl-installer + ../../guides/maintenance/increase-virtual-disk-size.rst + diff --git a/source/clear-linux/get-started/virtual-machine-install/virtualbox-cl-installer.rst b/source/clear-linux/get-started/virtual-machine-install/virtualbox-cl-installer.rst new file mode 100644 index 00000000..6de5bd1f --- /dev/null +++ b/source/clear-linux/get-started/virtual-machine-install/virtualbox-cl-installer.rst @@ -0,0 +1,275 @@ +.. _virtualbox-cl-installer: + +Install |CL-ATTR| as a VirtualBox\* Virtual Machine +################################################### + +VirtualBox\* is a type 2 hypervisor from Oracle. This document explains how +to create a virtual machine on the `VirtualBox hypervisor`_ with |CL-ATTR| +as the guest operating system. + +These instructions make use of the |CL| installer to create a brand new |CL| +installation. A preinstalled disk image is also available to get started +with |CL| faster. See: :ref:`virtualbox` + + +.. contents:: :local: + :depth: 2 + + +.. include:: virtualbox.rst + :start-after: vbox-prereqs-begin: + :end-before: vbox-prereqs-end: + + + +Download and extract the |CL| installer ISO image +************************************************* + +The appropriate |CL| installer image needs to be downloaded and extracted. + +.. note:: + The :file:`installer.iso` is for limited use on special cases where ISO + image format is required, such as |VB|. The preferred installer for |CL| + for UEFI systems is the :file:`-installer.img`. + +#. Download the **installer ISO** image (:file:`clear--installer.iso.xz`) of + |CL|. On the `downloads page`_, this is listed as + **Clear Linux OS for Virtual Provisioning**. + + + You can also use this command to download from a terminal: + + .. code-block:: bash + + curl -O https://cdn.download.clearlinux.org/image/$(curl https://cdn.download.clearlinux.org/image/latest-images | grep installer.iso) + +#. Validate the integrity of the downloaded image by checking the file hash + and signatures. Refer to the document on :ref:`validate-signatures` for + detailed steps. + +#. Decompress the downloaded image. Uncompressed image size is ~ **5GB**. + + - On Windows you can use `7zip`_ to extract the file by right-clicking the + file to *Extract Here* (in the same directory) + + .. image:: ./figures/vbox/vbox-extract-cl-ISO.png + :alt: 7zip extract here command + + - On Linux : + + .. code-block:: bash + + xz -d clear--installer.iso.xz + + + + +#. The originally downloaded compressed archive file + (:file:`clear--installer.iso.xz`) can now be deleted. + + +Create a new |VB| virtual machine +********************************* + +A new :abbr:`VM (Virtual Machine)` needs to be created in |VBM| for |CL| to be installed onto. + +General instructions for creating a virtual machine and details about using +different settings are available on the +`VirtualBox manual section on Creating a VM`_. + + +#. Launch the |VBM| from your host system. + + +#. Click the *New* button to create a new VM. + + .. image:: ./figures/vbox/vbox-new-vm.png + :alt: Create a new VM in VirtualBox + + +#. A *Create Virtual Machine* window will appear. + Select the following settings: + + - Type: **Linux** + - Version: **Linux 2.6 / 3.x / 4.x (64-bit)** + - Memory size: **1024 MB** (this can be adjusted appropriately) + - Hard disk: **Create a virtual hard disk now** + + .. image:: ./figures/vbox/vbox-create-vm-new-disk.png + :alt: Create a new VM in VirtualBox with a new disk + + +#. Click the *Create* button. + +#. A *Create Virtual Hard Disk* window will appear. + Select the following settings: + + - File size: **8.00 GB** (this can be adjusted appropriately) + + - Hard disk file type: **VDI (Virtual Box Disk Image)** + + - Storage on physical hard disk: **Dynamically allocated** + + .. image:: ./figures/vbox/vbox-create-disk.png + :alt: Create a new virtual hard disk in VirtualBox + +#. Click the *Create* button. + +#. A new virtual machine will be created and appear in the |VBM|. Click + *Settings* to configure the |CL| VM. + + .. image:: ./figures/vbox/vbox-vm-created.png + :alt: A VM selected in VirtualBox Manager + +#. A *VM - Settings* window will appear. Navigate to the *System* pane from + the left-hand and select the following setting: + + - **Enable I/O APIC** + - **Enable EFI (special OSes only)** + + + .. image:: ./figures/vbox/vbox-vm-settings-EFI.png + :alt: Enable EFI on a VirtualBox VM settings + +.. note:: + By default, only 1 virtual CPU is allocated to the new VM. Consider + increasing the number of virtual processors allocated to the virtual + machine under Settings --> System --> Processor for increased + performance. + + +Install |CL| on the |VB| VM +*************************** + +|CL| is ready to be installed. + + +Mount the installation ISO +========================== +At this point, the newly created VM has a blank virtual hard disk with no +operating system.The |CL| installer ISO needs to be mounted as a virtual +CD-ROM on the VM before powering the VM on. + +#. From the *VM - Settings* window, navigate to the *Storage* pane from the + left-hand side. + +#. From the middle *Storage Devices* column, click the blue CD disk labeled + *Empty* under the *Controller: IDE* from. + +#. From the right-hand *Attributes* column, click the blue CD disk next to + the *Optical Drive* drop down menu and click *Choose Virtual Optical + Disk File...* + + .. image:: ./figures/vbox/vbox-vm-settings-mount-ISO.png + :alt: Mounting an ISO in VirtualBox VM Settings + +#. A *choose a virtual optical disk file* browser window will appear. + Navigate to the extracted ISO file, select it, and click *Open*. + + .. image:: ./figures/vbox/vbox-vm-settings-browse-ISO.png + :alt: Mounting an ISO in VirtualBox VM Settings + +#. Click *OK* to exit the *VM Settings* menu and return to the main + |VBM|. + + + +Install |CL| using the installer +================================ + +#. Start the VM from the |VBM| by selecting the |CL| VM and + clicking *Start* + + .. image:: ./figures/vbox/vbox-start-vm.png + :alt: Starting a VirtualBox VM + +#. A new window of the VM console will appear and boot into the |CL| + installer. Follow the steps in :ref:`bare-metal-install-desktop` to + install |CL| onto the VM virtual disk. + +.. note:: + Do not choose a different kernel from the installer. **kernel-lts**, the + Long Term Support (LTS) kernel is required for |VB| driver compatibility. + + +#. After |CL| installation is complete, the VM will reboot and return to the + |CL| installer. + +.. note:: + To release the mouse cursor from the VM console window, press the right Ctrl key on the keyboard. + + +Unmount the installation ISO +============================ + +The |CL| installer ISO needs to be unmounted to allow the VM to boot from the +virtual hard disk, which |CL| has been installed to. + + +#. Power off the |CL| VM. + + .. image:: ./figures/vbox/vbox-shutdown-vm.png + :alt: Powering off a VirtualBox VM + +#. Click *Settings* to configure the |CL| VM. + + .. image:: ./figures/vbox/vbox-vm-created.png + :alt: A VM selected in VirtualBox Manager + +#. From the *VM - Settings* window, navigate to the *Storage* pane from the + left-hand side. + +#. From the middle *Storage Devices* column, click the blue CD disk labeled + *clear--installer.iso* under the *Controller: IDE* from. + +#. From the right-hand *Attributes* column, click the blue CD disk next to + the *Optical Drive* drop down menu and click *Remove Disk from Virtual + Drive* + + .. image:: ./figures/vbox/vbox-vm-settings-unmount-ISO.png + :alt: Unmounting an ISO in VirtualBox VM Settings + +#. Click *OK* to exit the *VM Settings* menu and return to the main + |VBM|. + + + + +.. include:: virtualbox.rst + :start-after: vbox-start-vm-and-lga-begin: + :end-before: vbox-start-vm-and-lga-end: + + + + + +.. include:: virtualbox.rst + :start-after: vbox-troubleshooting-begin: + :end-before: vbox-troubleshooting-end + + + + +.. |VB| replace:: VirtualBox +.. |VBM| replace:: VirtualBox Manager + + +.. _appropriate instructions: https://www.virtualbox.org/manual/ch02.html + +.. _official VirtualBox website: https://www.virtualbox.org/wiki/Downloads + +.. _VirtualBox hypervisor: https://www.virtualbox.org/ + +.. _downloads page: https://clearlinux.org/downloads + +.. _`VirtualBox manual section on Creating a VM`: https://www.virtualbox.org/manual/UserManual.html#gui-createvm + +.. _`VirtualBox manual section on Running a VM`: https://www.virtualbox.org/manual/ch01.html#intro-starting-vm-first-time + +.. _`Virtual Media Manager`: https://www.virtualbox.org/manual/ch05.html#vdis + +.. _7zip: http://www.7-zip.org/ + +.. _Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html + +.. _`VirtualBox manual section on VBoxManage`: https://www.virtualbox.org/manual/ch08.html#vboxmanage-convertfromraw \ No newline at end of file diff --git a/source/clear-linux/get-started/virtual-machine-install/virtualbox.rst b/source/clear-linux/get-started/virtual-machine-install/virtualbox.rst new file mode 100644 index 00000000..15fe127f --- /dev/null +++ b/source/clear-linux/get-started/virtual-machine-install/virtualbox.rst @@ -0,0 +1,368 @@ +.. _virtualbox: + +Run pre-configured |CL-ATTR| as a VirtualBox\* Virtual Machine +############################################################## + +VirtualBox\* is a type 2 hypervisor from Oracle. This document explains how +to create a virtual machine on the `VirtualBox hypervisor`_ with |CL-ATTR| +as the guest operating system. + +These instructions make use of a preinstalled |CL| disk image to setup a |CL| +virtual machine without manual installation. |CL| can also be installed from +scratch on a |VB| using the |CL| installed. +See: :ref:`virtualbox-cl-installer` + +.. contents:: :local: + :depth: 2 + + + +.. _vbox-prereqs-begin: + +Prerequisites +************* + +Before continuing make sure that you have: + +#. Enabled virtualization, such as Intel® + `Virtualization Technology`_ (Intel® VT), on the host system from + EFI/BIOS. + +#. Downloaded and installed |VB| **version 6.0 or greater** from + the `official VirtualBox website`_ per the `appropriate instructions`_ + for your platform. + +.. _vbox-prereqs-end: + + + +Download and extract |CL| +************************* + +The |CL| live image needs to be downloaded and extracted. The live image will +be used to created a |VB| virtual disk image that can be used with a +:abbr:`VM (Virtual Machine)`. + +#. Download the **live image** (:file:`clear--live.img.xz + +#. There originally downloaded compressed archive file + (:file:`clear--live.img.xz`) can now be deleted. + + + +Convert |CL| live image to a |VB| Disk Image +******************************************** + +The |CL| live image is in a RAW disk image. The live image needs to be +converted to a :abbr:`VDI (VirtualBox Disk Image)` format which |VB| +can utilize. + +#. Launch a terminal and navigate to the directory containing the + extracted live image. + + +#. Convert RAW live image to a :abbr:`VDI (VirtualBox Disk Image)` + format using the command-line VirtualBox Disk Utility. + + .. code-block:: bash + + VBoxManage convertfromraw clear--live.img clear-VM.vdi --format VDI + + .. note:: + The :command:`PATH` environment variable may need to be updated to make the + :command:`VBoxManage` command easily accessible from the terminal. + For example, using Windows PowerShell: + + .. code-block:: bash + + $env:PATH += ";C:\Program Files\Oracle\VirtualBox" + + + .. image:: ./figures/vbox/vbox-convert-raw-to-VDI.png + :alt: Convert image in Windows command prompt + + For more information on the :command:`VBoxManage` command, + see the `VirtualBox manual section on VBoxManage`_. + + +#. The originally extracted live image file + (:file:`clear--live.img`) can now be deleted. + + +#. Move the converted :file:`clear-VM.vdi` disk image file to a permanent + location. The VDI will be attached to the |VB| VM and should not be + deleted. + + + +Create a new |VB| virtual machine +********************************* + +A new VM needs to be created in |VBM| to attach the VDI with |CL| installed. + +General instructions for creating a virtual machine and details about using +different settings are available on the +`VirtualBox manual section on Creating a VM`_. + + +#. Launch the |VBM| from your host system. + + +#. Click the *New* button to create a new VM. + + .. image:: ./figures/vbox/vbox-new-vm.png + :alt: Create a new VM in VirtualBox + + +#. A *Create Virtual Machine* window will appear. + Select the following settings: + + - Type: **Linux** + - Version: **Linux 2.6 / 3.x / 4.x (64-bit)** + - Memory size: **1024 MB** (this can be adjusted appropriately) + - Hard disk: **Use an existing virtual hard disk file** + + Click the folder icon next to the drop down menu: + + .. image:: ./figures/vbox/vbox-create-vm-existing-disk.png + :alt: Create a new VM in VirtualBox with an existing disk + + +#. A new window will appear for choosing an existing disk. Click the *Add* + button, browse to the saved VDI file, and click *Choose*. + + .. image:: ./figures/vbox/vbox-create-vm-choose-disk.png + :alt: Create a new VM in VirtualBox with an existing disk + +#. Click the *Create* button. + + +#. A new virtual machine will be created and appear in the |VBM|. Click + *Settings* to configure the |CL| VM. + + .. image:: ./figures/vbox/vbox-vm-created.png + :alt: A VM selected in VirtualBox Manager + +#. A *VM - Settings* window will appear. Navigate to the *System* pane from + the left-hand and select the following setting: + + - **Enable I/O APIC** + - **Enable EFI (special OSes only)** + + + .. image:: ./figures/vbox/vbox-vm-settings-EFI.png + :alt: Enable EFI on a VirtualBox VM settings + + + +.. note:: + By default, only 1 virtual CPU is allocated to the new VM. Consider + increasing the number of virtual processors allocated to the virtual + machine under Settings --> System --> Processor for increased + performance. + +.. _vbox-start-vm-and-lga-begin: + +Start the |CL| VM +***************** + +The |CL| VM can now be powered on and setup. + +General instructions for using a |VB| virtual machine are available on the +`VirtualBox manual section on Running a VM`_. + +#. Start the VM from the |VBM| by selecting the |CL| VM and clicking *Start* + + .. image:: ./figures/vbox/vbox-start-vm.png + :alt: Starting a VirtualBox VM + +#. |CL| will boot and prompt for login. + + - Enter **root** for the username. + +#. You will be immediately prompted to set a new password for the **root** + user. Reference :ref:`security` for more information about |CL| security + concepts. + + .. image:: ./figures/vbox/vbox-cl-first-login.png + :alt: Initial login to Clear Linux OS on a VirtualBox VM + + + +Install |VB| Linux Guest Additions +================================== + +The |VB| Linux Guest Additions provide drivers for full compatibility and +functionality. + +|CL| provides |VB| guest drivers and an install script in the **kernel-lts** +(Long Term Support) bundle by |CL|. + + +#. Validate the installed kernel is **kernel-lts** by checking the output + of the :command:`uname -r` command. It should end in **.lts**. + + .. code-block:: bash + + uname -r + 4..lts + + If the running kernel is not **lts**: install the LTS kernel manually, + update the bootloader, and check again: + + .. code-block:: bash + + swupd bundle-add kernel-lts + clr-boot-manager set-kernel $(basename $(realpath /usr/lib/kernel/default-lts)) + clr-boot-manager update + reboot + +#. Remove any kernel bundles that are not *kernel-lts* or *kernel-install* + to simplify and avoid conflicts: + + .. code-block:: bash + + swupd bundle-list | grep kernel + swupd bundle-remove + + .. image:: ./figures/vbox/vbox-cl-remove-non-lts-kernels.png + :alt: Initial login to Clear Linux OS on a VirtualBox VM + +#. From the VM Console window, click *Devices* on the top menu bar, and + select *Insert Guest Additions CD image...* to mount the |VB| driver + installation to the |CL| VM. + + .. image:: ./figures/vbox/vbox-vm-insert-ga-cd.png + :alt: VirtualBox CD + +.. note:: + To release the mouse cursor from the VM console window, press the right Ctrl key on the keyboard. + + +#. |CL| provides a script called :command:`install-vbox-lga` to help patch + and install |VB| drivers for |CL|. Inside |CL| VM run this command: + + .. code-block:: bash + + install-vbox-lga + +#. After the script completes successfully, reboot the |CL| VM. + + .. code-block:: bash + + reboot + +#. After the VM reboot, login and verify the |VB| drivers are loaded: + + .. code-block:: bash + + lsmod | grep ^vbox + + You should see drivers loaded with names beginning with **vbox**: (vboxguest, vboxsf, vboxvideo). + + +The |CL| VM running on |VB| is ready to be used. + +.. _vbox-start-vm-and-lga-end: + +.. _vbox-troubleshooting-begin: + +Troubleshooting +*************** + +#. **Problem:** Out of disk space inside of |CL| and not be able to install + additional bundles. + + **Solution:** The |CL| images are small to minimize download time and + initial disk space . + + Power off the VM and resize the virtual disk for the |CL| VM using the |VB| + `Virtual Media Manager`_ found under the File menu. Afterwards, power the + |CL| VM on and follow the instructions here to have |CL| detect the resized + disk. :ref:`increase-virtual-disk-size` + +#. **Problem:** On a Microsoft Windows OS, |VB| encounters an error when + trying to start a VM indicating *VT-X/AMD-v hardware acceleration is not + available on your system.* + + + .. image:: ./figures/vbox/vbox-no-vtx.png + :alt: VirtualBox hardware acceleration error + + + **Solution:** First, double check the `Prerequisites`_ section to make sure + *Hardware accelerated virtualization* extensions have been enabled in the + host system's EFI/BIOS. + + *Hardware accelerated virtualization*, may get disabled for |VB| when another + hypervisor, such as *Hyper-V* is enabled. + + To disable *Hyper-V* execute this command in an + **Administrator: Command Prompt or Powershell**, and reboot the system: + + .. code-block:: bash + + bcdedit /set {current} hypervisorlaunchtype off + + + To enable Hyper-V again, execute this command in an + **Administrator: Command Prompt or Powershell**, and reboot the system: + + .. code-block:: bash + + bcdedit /set {current} hypervisorlaunchtype Auto + +.. _vbox-troubleshooting-end: + + + + +.. |VB| replace:: VirtualBox +.. |VBM| replace:: VirtualBox Manager + +.. _appropriate instructions: https://www.virtualbox.org/manual/ch02.html + +.. _official VirtualBox website: https://www.virtualbox.org/wiki/Downloads + +.. _VirtualBox hypervisor: https://www.virtualbox.org/ + +.. _downloads page: https://clearlinux.org/downloads + +.. _`VirtualBox manual section on Creating a VM`: https://www.virtualbox.org/manual/UserManual.html#gui-createvm + +.. _`VirtualBox manual section on Running a VM`: https://www.virtualbox.org/manual/ch01.html#intro-starting-vm-first-time + +.. _`Virtual Media Manager`: https://www.virtualbox.org/manual/ch05.html#vdis + +.. _7zip: http://www.7-zip.org/ + +.. _Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html + +.. _`VirtualBox manual section on VBoxManage`: https://www.virtualbox.org/manual/ch08.html#vboxmanage-convertfromraw diff --git a/source/get-started/virtual-machine-install/vmw-player-preconf.rst b/source/clear-linux/get-started/virtual-machine-install/vmw-player-preconf.rst similarity index 100% rename from source/get-started/virtual-machine-install/vmw-player-preconf.rst rename to source/clear-linux/get-started/virtual-machine-install/vmw-player-preconf.rst diff --git a/source/get-started/virtual-machine-install/vmw-player.rst b/source/clear-linux/get-started/virtual-machine-install/vmw-player.rst similarity index 100% rename from source/get-started/virtual-machine-install/vmw-player.rst rename to source/clear-linux/get-started/virtual-machine-install/vmw-player.rst diff --git a/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst b/source/clear-linux/get-started/virtual-machine-install/vmware-esxi-install-cl.rst similarity index 100% rename from source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst rename to source/clear-linux/get-started/virtual-machine-install/vmware-esxi-install-cl.rst diff --git a/source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst b/source/clear-linux/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst similarity index 100% rename from source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst rename to source/clear-linux/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst diff --git a/source/guides/deploy-at-scale.rst b/source/clear-linux/guides/deploy-at-scale.rst similarity index 100% rename from source/guides/deploy-at-scale.rst rename to source/clear-linux/guides/deploy-at-scale.rst diff --git a/source/guides/guides.rst b/source/clear-linux/guides/guides.rst similarity index 64% rename from source/guides/guides.rst rename to source/clear-linux/guides/guides.rst index ac082ca5..d773743d 100644 --- a/source/guides/guides.rst +++ b/source/clear-linux/guides/guides.rst @@ -4,10 +4,17 @@ Guides ###### The following guides provide step-by-step instructions on using |CL|. +Note: As of 22 May 2019 :file:`mixin` is no longer supported. -.. note:: +Tooling +======= - As of 22 May 2019 :file:`mixin` is no longer supported. +.. toctree:: + :maxdepth: 1 + :glob: + + tooling/* + telemetrics/telem-guide Maintenance =========== @@ -26,14 +33,4 @@ Network :maxdepth: 1 :glob: - network/* - - -Kernel -====== - -.. toctree:: - :maxdepth: 1 - :glob: - - kernel/* \ No newline at end of file + network/* \ No newline at end of file diff --git a/source/guides/maintenance/architect-lifecycle.rst b/source/clear-linux/guides/maintenance/architect-lifecycle.rst similarity index 100% rename from source/guides/maintenance/architect-lifecycle.rst rename to source/clear-linux/guides/maintenance/architect-lifecycle.rst diff --git a/source/clear-linux/guides/maintenance/assign-static-ip.rst b/source/clear-linux/guides/maintenance/assign-static-ip.rst new file mode 100644 index 00000000..444fbf21 --- /dev/null +++ b/source/clear-linux/guides/maintenance/assign-static-ip.rst @@ -0,0 +1,71 @@ +.. _assign-static-ip: + +Assign a static IP address to a network interface +################################################# + +Introduction +************ + +By default, your |CL-ATTR| system automatically gets an IP address from your +network via DHCP. If you do not have a DHCP server on your network or simply +want to use a static IP address, follow the steps in this guide. + +Process +******* + +#. Create this directory structure: + + .. code-block:: bash + + sudo mkdir -p /etc/systemd/network + +#. Identify the interface to be assigned the static IP address: + + .. code-block:: bash + + ip addr + + The system returns the following: + + .. code-block:: console + + 1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + + 2: wlp1s0: mtu 1500 qdisc mq state DOWN group default qlen 1000 + link/ether 4a:98:8d:e5:43:15 brd ff:ff:ff:ff:ff:ff + + 3: eno1: mtu 1500 qdisc fq state UP group default qlen 1000 + link/ether f4:4d:30:68:96:20 brd ff:ff:ff:ff:ff:ff + inet 10.0.1.2/24 brd 10.54.74.255 scope global dynamic eno1 + valid_lft 6766sec preferred_lft 6766sec + inet6 fe80::f64d:30ff:fe68:9620/64 scope link + valid_lft forever preferred_lft forever + + In this example, we will use the `eno1` interface. + +#. Create the :file:`70-static.network` file and add the following: + + .. code-block:: bash + + sudo $EDITOR /etc/systemd/network/70-static.network + + [Match] + Name=[interface name] + [Network] + Address=[IP address]/24 + DHCP=yes # to get DNS info, etc. + + Replace [interface name] and [IP address] with your specific settings. + +#. Restart the networkd service: + + .. code-block:: bash + + sudo systemctl restart systemd-networkd + +**Congratulations!** You have successfully assigned a static IP address. diff --git a/source/guides/maintenance/bulk-provision.rst b/source/clear-linux/guides/maintenance/bulk-provision.rst similarity index 100% rename from source/guides/maintenance/bulk-provision.rst rename to source/clear-linux/guides/maintenance/bulk-provision.rst diff --git a/source/guides/maintenance/developer-workstation.rst b/source/clear-linux/guides/maintenance/developer-workstation.rst similarity index 100% rename from source/guides/maintenance/developer-workstation.rst rename to source/clear-linux/guides/maintenance/developer-workstation.rst diff --git a/source/guides/maintenance/download-verify-decompress-linux.rst b/source/clear-linux/guides/maintenance/download-verify-decompress-linux.rst similarity index 100% rename from source/guides/maintenance/download-verify-decompress-linux.rst rename to source/clear-linux/guides/maintenance/download-verify-decompress-linux.rst diff --git a/source/guides/maintenance/download-verify-decompress-mac.rst b/source/clear-linux/guides/maintenance/download-verify-decompress-mac.rst similarity index 92% rename from source/guides/maintenance/download-verify-decompress-mac.rst rename to source/clear-linux/guides/maintenance/download-verify-decompress-mac.rst index 818b940f..2507fe3b 100644 --- a/source/guides/maintenance/download-verify-decompress-mac.rst +++ b/source/clear-linux/guides/maintenance/download-verify-decompress-mac.rst @@ -35,7 +35,7 @@ checksum file designated with the suffix `-SHA512SUMS`. .. code-block:: bash - shasum -a512 clear-[version number]-[image type].[compression type] | diff clear-[version number]-[image type].[compression type]-SHA512SUMS - + shasum -a512 ./clear-[version number]-[image type].[compression type] | diff ./clear-[version number]-[image type].[compression type]-SHA512SUMS - If the checksum of the downloaded image is different than the original checksum, the differences will be displayed. Otherwise, an empty output indicates @@ -44,8 +44,8 @@ a match and your downloaded image is good. 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 +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 decompress the image, follow these steps: #. Start the Terminal app. diff --git a/source/guides/maintenance/download-verify-decompress-windows.rst b/source/clear-linux/guides/maintenance/download-verify-decompress-windows.rst similarity index 100% rename from source/guides/maintenance/download-verify-decompress-windows.rst rename to source/clear-linux/guides/maintenance/download-verify-decompress-windows.rst diff --git a/source/guides/maintenance/enable-user-space.rst b/source/clear-linux/guides/maintenance/enable-user-space.rst similarity index 100% rename from source/guides/maintenance/enable-user-space.rst rename to source/clear-linux/guides/maintenance/enable-user-space.rst diff --git a/source/guides/maintenance/figures/7zipwin.png b/source/clear-linux/guides/maintenance/figures/7zipwin.png similarity index 100% rename from source/guides/maintenance/figures/7zipwin.png rename to source/clear-linux/guides/maintenance/figures/7zipwin.png diff --git a/source/guides/maintenance/figures/architect-lifecycle-1.png b/source/clear-linux/guides/maintenance/figures/architect-lifecycle-1.png similarity index 100% rename from source/guides/maintenance/figures/architect-lifecycle-1.png rename to source/clear-linux/guides/maintenance/figures/architect-lifecycle-1.png diff --git a/source/guides/maintenance/figures/bare-metal-install-desktop-01.png b/source/clear-linux/guides/maintenance/figures/bare-metal-install-desktop-01.png similarity index 100% rename from source/guides/maintenance/figures/bare-metal-install-desktop-01.png rename to source/clear-linux/guides/maintenance/figures/bare-metal-install-desktop-01.png diff --git a/source/guides/maintenance/figures/bulk-provision-flow.png b/source/clear-linux/guides/maintenance/figures/bulk-provision-flow.png similarity index 100% rename from source/guides/maintenance/figures/bulk-provision-flow.png rename to source/clear-linux/guides/maintenance/figures/bulk-provision-flow.png diff --git a/source/guides/maintenance/figures/distro-factory-1.png b/source/clear-linux/guides/maintenance/figures/distro-factory-1.png similarity index 100% rename from source/guides/maintenance/figures/distro-factory-1.png rename to source/clear-linux/guides/maintenance/figures/distro-factory-1.png diff --git a/source/guides/maintenance/figures/download-verify-decompress-windows-fig-1.png b/source/clear-linux/guides/maintenance/figures/download-verify-decompress-windows-fig-1.png similarity index 100% rename from source/guides/maintenance/figures/download-verify-decompress-windows-fig-1.png rename to source/clear-linux/guides/maintenance/figures/download-verify-decompress-windows-fig-1.png diff --git a/source/guides/maintenance/figures/gnomedt.png b/source/clear-linux/guides/maintenance/figures/gnomedt.png old mode 100644 new mode 100755 similarity index 100% rename from source/guides/maintenance/figures/gnomedt.png rename to source/clear-linux/guides/maintenance/figures/gnomedt.png diff --git a/source/guides/maintenance/figures/increase-virtual-disk-size-1.png b/source/clear-linux/guides/maintenance/figures/increase-virtual-disk-size-1.png old mode 100644 new mode 100755 similarity index 100% rename from source/guides/maintenance/figures/increase-virtual-disk-size-1.png rename to source/clear-linux/guides/maintenance/figures/increase-virtual-disk-size-1.png diff --git a/source/guides/maintenance/figures/increase-virtual-disk-size-2.png b/source/clear-linux/guides/maintenance/figures/increase-virtual-disk-size-2.png similarity index 100% rename from source/guides/maintenance/figures/increase-virtual-disk-size-2.png rename to source/clear-linux/guides/maintenance/figures/increase-virtual-disk-size-2.png diff --git a/source/guides/maintenance/fix-broken-install.rst b/source/clear-linux/guides/maintenance/fix-broken-install.rst similarity index 97% rename from source/guides/maintenance/fix-broken-install.rst rename to source/clear-linux/guides/maintenance/fix-broken-install.rst index 1ffe275d..864c9972 100644 --- a/source/guides/maintenance/fix-broken-install.rst +++ b/source/clear-linux/guides/maintenance/fix-broken-install.rst @@ -48,7 +48,7 @@ Mount root partition, verify, and fix sudo mount /dev/sda3 /mnt -#. Verify that you mounted the correct root partition by checking for some +#. Verify that you mounted the correct root partition by checking for some files commonly found on |CL| systems. .. code-block:: bash @@ -60,7 +60,7 @@ Mount root partition, verify, and fix .. code-block:: bash - sudo swupd repair --picky --path=/mnt + sudo swupd verify --fix --picky --path=/mnt :ref:`Learn more about how swupd works `. diff --git a/source/guides/maintenance/hostname.rst b/source/clear-linux/guides/maintenance/hostname.rst similarity index 100% rename from source/guides/maintenance/hostname.rst rename to source/clear-linux/guides/maintenance/hostname.rst diff --git a/source/guides/maintenance/increase-virtual-disk-size.rst b/source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst similarity index 100% rename from source/guides/maintenance/increase-virtual-disk-size.rst rename to source/clear-linux/guides/maintenance/increase-virtual-disk-size.rst diff --git a/source/guides/kernel/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst similarity index 99% rename from source/guides/kernel/kernel-development.rst rename to source/clear-linux/guides/maintenance/kernel-development.rst index 9dbbaaaf..91775c71 100644 --- a/source/guides/kernel/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -45,7 +45,7 @@ Then make changes to the kernel, build it, and install it. Install the |CL| development tooling framework ============================================== -.. include:: /tooling/autospec.rst +.. include:: ../tooling/autospec.rst :start-after: install-tooling-after-header: :end-before: install-tooling-end: diff --git a/source/guides/kernel/kernel-modules-dkms.rst b/source/clear-linux/guides/maintenance/kernel-modules-dkms.rst similarity index 95% rename from source/guides/kernel/kernel-modules-dkms.rst rename to source/clear-linux/guides/maintenance/kernel-modules-dkms.rst index 8c8ca6ad..3e3cf6fe 100644 --- a/source/guides/kernel/kernel-modules-dkms.rst +++ b/source/clear-linux/guides/maintenance/kernel-modules-dkms.rst @@ -129,8 +129,8 @@ Before you begin, you must: Obtain kernel module source =========================== -A required :file:`dkms.conf` file inside of the kernel module's source code -directory informs DKMS how the kernel module should be compiled. +A required :file:`dkms.conf` file inside of the kernel module's source code directory +informs DKMS how the kernel module should be compiled. Kernel modules may come packaged as: @@ -141,10 +141,10 @@ Kernel modules may come packaged as: - Precompiled module binaries only (without source code) Of the package types listed above, only precompiled kernel module binaries -will not work, because |CL| requires kernel modules to be built against the -same kernel source tree before they can be loaded. If you are only able to -obtain source code without a :file:`dkms.conf` file, you must manually create -a :file:`dkms.conf` file, described later in this document. +will not work, because |CL| requires kernel modules to be built against +the same kernel source tree before they can be loaded. If you are only able to +obtain source code without a :file:`dkms.conf` file, you must manually create a +:file:`dkms.conf` file, described later in this document. #. Download the kernel module's source code. @@ -210,8 +210,8 @@ If the kernel module source does not contain a :file:`dkms.conf` file or the create the file. Review the kernel module README documentation for guidance on what needs to be -in the :file:`dkms.conf` file, including special variables that may be -required to build successfully. +in the :file:`dkms.conf` file, including special variables that may be required to +build successfully. Here are some additional resources that can be used for reference: @@ -223,10 +223,6 @@ Here are some additional resources that can be used for reference: * `Sample dkms.conf file`_ in the GitHub\* repository for the DKMS project. -.. note:: - - :command:`AUTOINSTALL=yes` must be set in the dkms.conf for the module to - be automatically recompiled with |CL| updates. The instructions below show a generic example: @@ -244,7 +240,6 @@ The instructions below show a generic example: PACKAGE_NAME=custom_module PACKAGE_VERSION=1.0 DEST_MODULE_LOCATION=/kernel/drivers/other - AUTOINSTALL=yes This example identifies a kernel module named *custom_module* with version *1.0*. diff --git a/source/guides/kernel/kernel-modules.rst b/source/clear-linux/guides/maintenance/kernel-modules.rst similarity index 100% rename from source/guides/kernel/kernel-modules.rst rename to source/clear-linux/guides/maintenance/kernel-modules.rst diff --git a/source/guides/maintenance/time.rst b/source/clear-linux/guides/maintenance/time.rst similarity index 100% rename from source/guides/maintenance/time.rst rename to source/clear-linux/guides/maintenance/time.rst diff --git a/source/guides/maintenance/validate-signatures.rst b/source/clear-linux/guides/maintenance/validate-signatures.rst similarity index 100% rename from source/guides/maintenance/validate-signatures.rst rename to source/clear-linux/guides/maintenance/validate-signatures.rst diff --git a/source/guides/network/custom-clear-container.rst b/source/clear-linux/guides/network/custom-clear-container.rst similarity index 81% rename from source/guides/network/custom-clear-container.rst rename to source/clear-linux/guides/network/custom-clear-container.rst index 88ac8e7c..bcc0fcac 100644 --- a/source/guides/network/custom-clear-container.rst +++ b/source/clear-linux/guides/network/custom-clear-container.rst @@ -82,24 +82,76 @@ Build the base container image swupd bundle-add containers-basic systemctl start docker -#. Use `os-install` to download and install the bundles. +#. Create the directory structure to build the |CL| container. .. code-block:: bash - swupd os-install --url https://cdn.download.clearlinux.org/update --statedir "$PWD"/swupd-state --no-boot-update --version 29790 -B os-core-update,editors,network-basic base + mkdir -p ./custom-clear-linux-container/base/usr/share/clear/bundles + cd custom-clear-linux-container + + .. note:: + + * The directories :file:`custom-clear-linux-container` and + :file:`base` are used for staging. You can rename these directories. + + * The directories :file:`/usr/share/clear/bundles` are mandatory and + cannot be renamed. + +#. Create the reference files of the minimum required |CL| bundles, + :file:`os-core` and :file:`os-core-update`. The software updater + uses the reference filenames to determine which bundles to download and + install. + + + .. code-block:: bash + + touch ./base/usr/share/clear/bundles/os-core + touch ./base/usr/share/clear/bundles/os-core-update + + .. note:: + + * :file:`os-core` provides the minimal Linux namespace. + * :file:`os-core-update` provides the basic suite for running the |CL| + updater. + +#. Optionally, you can include additional bundles with the base image. + + #. Identify the desired bundles on the |CL| website's + :ref:`bundles` page or execute the + :command:`swupd bundle-list -a` command. + + #. Create reference files for the identified bundles. For example, + to include the :file:`editors` and :file:`network-basic` bundles, + enter the commands: + + .. code-block:: bash + + touch ./base/usr/share/clear/bundles/editors + touch ./base/usr/share/clear/bundles/network-basic + +#. Use `swupd` to download and install the bundles. + + .. code-block:: bash + + swupd verify --install --path="base" --manifest 17870 \ + --url https://cdn.download.clearlinux.org/update \ + --statedir "$PWD/swupd-state" --no-boot-update The `swupd` example uses the following flags: - * :command:`os-install` tells `swupd` to download and install. - * :command:`-V / --version` specifies the version of the |CL| bundles. + * :command:`verify –-install` tells `swupd` to download and install. + * :command:`--path` specifies the root path where the bundles are to be + installed. + * :command:`--manifest` specifies the version of the |CL| bundles. * :command:`--url` specifies the URL of the bundles repository. * :command:`--statedir` specifies the state directory where downloaded bundles and any state information are stored. * :command:`--no-boot-update` tells `swupd` to skip updating boot files because boot files are not required for a container. - For more information on `swupd` flags, enter the :command:`swupd os-install -h` command. + For more information on `swupd` flags, enter the :command:`swupd verify -h` + command. Example output: diff --git a/source/guides/network/dpdk.rst b/source/clear-linux/guides/network/dpdk.rst similarity index 100% rename from source/guides/network/dpdk.rst rename to source/clear-linux/guides/network/dpdk.rst diff --git a/source/guides/network/figures/network-boot-flow.png b/source/clear-linux/guides/network/figures/network-boot-flow.png similarity index 100% rename from source/guides/network/figures/network-boot-flow.png rename to source/clear-linux/guides/network/figures/network-boot-flow.png diff --git a/source/guides/network/figures/network-boot-setup.png b/source/clear-linux/guides/network/figures/network-boot-setup.png similarity index 100% rename from source/guides/network/figures/network-boot-setup.png rename to source/clear-linux/guides/network/figures/network-boot-setup.png diff --git a/source/guides/network/figures/pktgen_lw3fd.png b/source/clear-linux/guides/network/figures/pktgen_lw3fd.png similarity index 100% rename from source/guides/network/figures/pktgen_lw3fd.png rename to source/clear-linux/guides/network/figures/pktgen_lw3fd.png diff --git a/source/guides/network/figures/pyshical_net.png b/source/clear-linux/guides/network/figures/pyshical_net.png similarity index 100% rename from source/guides/network/figures/pyshical_net.png rename to source/clear-linux/guides/network/figures/pyshical_net.png diff --git a/source/guides/network/figures/use-case.png b/source/clear-linux/guides/network/figures/use-case.png similarity index 100% rename from source/guides/network/figures/use-case.png rename to source/clear-linux/guides/network/figures/use-case.png diff --git a/source/guides/network/figures/vnc/vnc-1.png b/source/clear-linux/guides/network/figures/vnc/vnc-1.png similarity index 100% rename from source/guides/network/figures/vnc/vnc-1.png rename to source/clear-linux/guides/network/figures/vnc/vnc-1.png diff --git a/source/guides/network/figures/vnc/vnc-10.png b/source/clear-linux/guides/network/figures/vnc/vnc-10.png similarity index 100% rename from source/guides/network/figures/vnc/vnc-10.png rename to source/clear-linux/guides/network/figures/vnc/vnc-10.png diff --git a/source/guides/network/figures/vnc/vnc-11.png b/source/clear-linux/guides/network/figures/vnc/vnc-11.png similarity index 100% rename from source/guides/network/figures/vnc/vnc-11.png rename to source/clear-linux/guides/network/figures/vnc/vnc-11.png diff --git a/source/guides/network/figures/vnc/vnc-2.png b/source/clear-linux/guides/network/figures/vnc/vnc-2.png similarity index 100% rename from source/guides/network/figures/vnc/vnc-2.png rename to source/clear-linux/guides/network/figures/vnc/vnc-2.png diff --git a/source/guides/network/figures/vnc/vnc-3.png b/source/clear-linux/guides/network/figures/vnc/vnc-3.png similarity index 100% rename from source/guides/network/figures/vnc/vnc-3.png rename to source/clear-linux/guides/network/figures/vnc/vnc-3.png diff --git a/source/guides/network/figures/vnc/vnc-4.png b/source/clear-linux/guides/network/figures/vnc/vnc-4.png similarity index 100% rename from source/guides/network/figures/vnc/vnc-4.png rename to source/clear-linux/guides/network/figures/vnc/vnc-4.png diff --git a/source/guides/network/figures/vnc/vnc-5.png b/source/clear-linux/guides/network/figures/vnc/vnc-5.png similarity index 100% rename from source/guides/network/figures/vnc/vnc-5.png rename to source/clear-linux/guides/network/figures/vnc/vnc-5.png diff --git a/source/guides/network/figures/vnc/vnc-6.png b/source/clear-linux/guides/network/figures/vnc/vnc-6.png similarity index 100% rename from source/guides/network/figures/vnc/vnc-6.png rename to source/clear-linux/guides/network/figures/vnc/vnc-6.png diff --git a/source/guides/network/figures/vnc/vnc-7.png b/source/clear-linux/guides/network/figures/vnc/vnc-7.png similarity index 100% rename from source/guides/network/figures/vnc/vnc-7.png rename to source/clear-linux/guides/network/figures/vnc/vnc-7.png diff --git a/source/guides/network/figures/vnc/vnc-8.png b/source/clear-linux/guides/network/figures/vnc/vnc-8.png similarity index 100% rename from source/guides/network/figures/vnc/vnc-8.png rename to source/clear-linux/guides/network/figures/vnc/vnc-8.png diff --git a/source/guides/network/figures/vnc/vnc-9.png b/source/clear-linux/guides/network/figures/vnc/vnc-9.png similarity index 100% rename from source/guides/network/figures/vnc/vnc-9.png rename to source/clear-linux/guides/network/figures/vnc/vnc-9.png diff --git a/source/guides/network/ipxe-install.rst b/source/clear-linux/guides/network/ipxe-install.rst similarity index 100% rename from source/guides/network/ipxe-install.rst rename to source/clear-linux/guides/network/ipxe-install.rst diff --git a/source/guides/network/network-bonding.rst b/source/clear-linux/guides/network/network-bonding.rst similarity index 100% rename from source/guides/network/network-bonding.rst rename to source/clear-linux/guides/network/network-bonding.rst diff --git a/source/guides/network/vnc.rst b/source/clear-linux/guides/network/vnc.rst similarity index 100% rename from source/guides/network/vnc.rst rename to source/clear-linux/guides/network/vnc.rst diff --git a/source/guides/telemetrics/figures/telemetry-backend-1.png b/source/clear-linux/guides/telemetrics/figures/telemetry-backend-1.png similarity index 100% rename from source/guides/telemetrics/figures/telemetry-backend-1.png rename to source/clear-linux/guides/telemetrics/figures/telemetry-backend-1.png diff --git a/source/guides/telemetrics/figures/telemetry-backend-2.png b/source/clear-linux/guides/telemetrics/figures/telemetry-backend-2.png similarity index 100% rename from source/guides/telemetrics/figures/telemetry-backend-2.png rename to source/clear-linux/guides/telemetrics/figures/telemetry-backend-2.png diff --git a/source/guides/telemetrics/figures/telemetry-e2e.png b/source/clear-linux/guides/telemetrics/figures/telemetry-e2e.png similarity index 100% rename from source/guides/telemetrics/figures/telemetry-e2e.png rename to source/clear-linux/guides/telemetrics/figures/telemetry-e2e.png diff --git a/source/guides/telemetrics/telem-guide.rst b/source/clear-linux/guides/telemetrics/telem-guide.rst similarity index 98% rename from source/guides/telemetrics/telem-guide.rst rename to source/clear-linux/guides/telemetrics/telem-guide.rst index d9b7f089..2b538a5b 100644 --- a/source/guides/telemetrics/telem-guide.rst +++ b/source/clear-linux/guides/telemetrics/telem-guide.rst @@ -5,15 +5,6 @@ Telemetrics Telemetrics in |CL-ATTR| is a client and server solution used to collect data from running |CL| systems to help quickly identify and fix bugs in the OS. Both client and server are customizable, and an API is available on the client side for instrumenting your code for debug and analysis. -.. important:: - - Telemetry in |CL| is **opt-in**. The telemetry client is **not** active and sends **no** data until you explicitly enable it. - -.. note:: - - The telemetry functionality adheres to `Intel privacy policies`_ regarding the collection and use of :abbr:`PII (Personally Identifiable Information)` and is open source. - Specifically, no intentionally identifiable information about the user or system owner is collected. - .. contents:: :local: :depth: 1 @@ -33,8 +24,6 @@ Telemetrics is a combination word made from: |CL| telemetry is fully customizable and can be used during software development for debugging purposes. You can use the libtelemetry library in your code to create custom telemetry records. You can also use the telem-record-gen utility in script files for light touch record creation where instrumenting code files doesn't make sense. -The |CL| telemetrics solution is an **opt-in** choice on the client side. By default, the telemetry client is disabled until you choose to enable it. Enabling the client is covered in this guide. - Architecture ============ @@ -68,7 +57,10 @@ The telemetry backend provides the server-side component of the telemetrics solu The default telemetry backend server is hosted by the Intel |CL| development team and is not viewable outside the Intel firewall. To collect your own records, you must set up your own telemetry backend server. +.. note:: + The telemetry functionality adheres to `Intel privacy policies`_ regarding the collection and use of :abbr:`PII (Personally Identifiable Information)` and is open source. + Specifically, no intentionally identifiable information about the user or system owner is collected. How To Use ********** diff --git a/source/tooling/autoproxy.rst b/source/clear-linux/guides/tooling/autoproxy.rst similarity index 85% rename from source/tooling/autoproxy.rst rename to source/clear-linux/guides/tooling/autoproxy.rst index 3b850229..129cae51 100644 --- a/source/tooling/autoproxy.rst +++ b/source/clear-linux/guides/tooling/autoproxy.rst @@ -20,22 +20,22 @@ manually configure the proxies. Corporate and private networks can be very complex, needing to restrict and control network connections for security reasons. The typical side effects -are limited or blocked connectivity, and require manual configuration of -proxies to perform the most mundane tasks, such as cloning a repo or checking +are limited or blocked connectivity and requiring manual configuration of +proxies to perform the most mundane tasks such as cloning a repo or checking for updates. With |CL|, all of the work is done behind the scenes to effortlessly use your network and have connections “just work”. -This feature removes severe complications with network connectivity due to -proxy issues. You can automate tasks, such as unit testing, without worrying -about the proxy not being set, and you can remove unset proxies from the +This feature removes massive complications in network connectivity due to +proxy issues. You can automate tasks like unit testing without worrying +about the proxy not being set and you can remove unset proxies from the equation when dealing with network unavailability across systems. How it works ************ -We designed Autoproxy around tools provided by most Linux\* +We designed Autoproxy around tools provided by most Linux distributions with a few minor additions and modifications. We leveraged the -DHCP and network information obtained from systemd and created a +DHCP and network information provided from systemd and created a PAC-discovery daemon. The daemon uses the information to resolve a URL for a PAC file. The daemon then passes the URL into PACrunner\*. PACrunner downloads the PAC file and uses the newly implemented Duktape\* engine to @@ -49,7 +49,7 @@ parse it. From that point on, any cURL\* or network requests query PACrunner for the correct proxy to use. We modified the cURL library to communicate with PACrunner over DBus. However, cURL will ignore PACrunner and run normally if -no PAC file is loaded or if you manually set any proxies. Thus, your +no PAC file is loaded or if you set any proxies manually. Thus, your environment settings are respected and no time is wasted trying to resolve a proxy. All these steps happen in the background with no user interaction. diff --git a/source/tooling/autospec.rst b/source/clear-linux/guides/tooling/autospec.rst similarity index 89% rename from source/tooling/autospec.rst rename to source/clear-linux/guides/tooling/autospec.rst index 000bb9e8..3779e52c 100644 --- a/source/tooling/autospec.rst +++ b/source/clear-linux/guides/tooling/autospec.rst @@ -3,8 +3,8 @@ autospec ######## -**autospec** is a tool used to assist with the automated creation and maintenance of -RPM packaging in |CL-ATTR|. Where a standard :abbr:`RPM (RPM Package Manager)` build process using +**autospec** is a tool to assist in the automated creation and maintenance of +RPM packaging in |CL-ATTR|. Where a standard RPM build process using :command:`rpmbuild` requires a tarball and :file:`.spec` file to start, autospec requires only a tarball and package name to start. @@ -16,17 +16,17 @@ Description *********** The autospec tool attempts to infer the requirements of the :file:`.spec` file -by analyzing the source code and :file:`Makefile` information. It -continuously runs updated builds based on new information discovered from build +by analyzing the source code and :file:`Makefile` information. It will +continuously run updated builds based on new information discovered from build failures until it has a complete and valid :file:`.spec` file. If needed, you can influence the behavior of autospec and customize the build by providing optional `control files`_ to the autospec tool. -autospec uses **mock** as a sandbox to run the builds. Visit the `mock wiki`_ for +autospec uses mock as a sandbox to run the builds. Visit the `mock wiki`_ for additional information on using mock. -For a general understanding of how an RPM works, visit -the `rpm website`_ or the `RPM Packaging Guide`_ . +For a general understanding of how RPMs work, visit the `rpm website`_ or the +`RPM Packaging Guide`_ . How it works ************ @@ -44,7 +44,7 @@ The setup for building source in |CL| must be completed before using the autospec tool. Refer to `Setup environment to build source`_ for instructions on completing -the setup. +setup. Create an RPM ============= @@ -52,7 +52,7 @@ Create an RPM The basic autospec process is described in the following steps: #. The :command:`make autospec` command generates a :file:`.spec` file based on - the analysis of code and existing control files. + analysis of code and existing control files. Any control files should be located in the same directory as the resulting :file:`.spec` file. @@ -65,13 +65,13 @@ The basic autospec process is described in the following steps: #. autospec detects any missed declarations in the :file:`.spec`. -#. If build errors occur, autospec scans the build log to try to detect +#. If build errors occur, autospec will scan the build log to try and detect the root cause. -#. If autospec detects the root cause and knows how to continue, it restarts +#. If autospec detects the root cause and knows how to continue, it will restart the build automatically at step 1 with updated build instructions. -#. Otherwise, autospec stops the build for user inspection to resolve the +#. Otherwise, autospec will stop the build for user inspection to resolve the errors. Respond to the build process output by fixing source code issues and/or editing control files to resolve issues, which may include dependencies or exclusions. See `autospec README`_ for more information on @@ -79,7 +79,7 @@ The basic autospec process is described in the following steps: The user resumes the process at step 1 after errors are resolved. - If a binary dependency doesn't exist in |CL|, you must build it + If a binary dependency doesn't exist in |CL|, you will need to build it before running autospec again. Following these steps, autospec continues to rebuild the package, based on @@ -95,10 +95,10 @@ Complete `Setup environment to build source`_ before using these examples. :local: :depth: 1 -Example 1: Build RPM with an existing spec file -=============================================== +Example 1: Build RPM with existing spec file +============================================ -This example shows how to build a RPM from a pre-packaged upstream package with +This example shows how to build a RPM from a pre-packaged upstream package, with an existing spec file. The example uses the ``dmidecode`` package. #. Navigate to the autospec workspace and clone the ``dmidecode`` package: @@ -110,7 +110,7 @@ an existing spec file. The example uses the ``dmidecode`` package. .. note:: - You can clone all package repos at once using the following command: + You can clone all package repos at once using: .. code-block:: bash @@ -147,7 +147,7 @@ create a simple helloclear RPM. cd ~/clearlinux make autospecnew URL="https://github.com/clearlinux/helloclear/archive/helloclear-v1.0.tar.gz" NAME="helloclear" - The resulting RPMs are in :file:`./packages/helloclear/rpms`. Build logs and + The resulting RPMs are in :file:`./packages/helloclear/rpms`. Builde logs and additional RPMs are in :file:`./packages/helloclear/results`. Example 3: Generate a new spec file with a pre-defined package @@ -198,8 +198,8 @@ Example 4: Provide control files to autospec ============================================ This example shows how to modify control files to correct build failures that -autospec is unable to resolve. In this example, you will add a missing license -and dependencies so autospec can complete a successful build. +autospec is unable to resolve. In this example you will add a missing license +and dependencies in order for autospec to complete a successful build. #. Navigate to the autospec workspace: @@ -226,7 +226,7 @@ and dependencies so autospec can complete a successful build. make autospecnew URL="https://github.com/OPAE/opae-sdk/archive/0.13.0.tar.gz" NAME="opae-sdk" - This results in an error for a missing license file: + This will give an error for a missing license file: .. code-block:: console @@ -238,7 +238,7 @@ and dependencies so autospec can complete a successful build. cd packages/opae-sdk -#. Add one or more valid license identifiers from the +#. Add one or more valid license identifier from the `SPDX License List `_. In the example below, two different licenses are appropriate based on the opae-sdk project licensing: @@ -253,7 +253,7 @@ and dependencies so autospec can complete a successful build. make autospec - This results in a generic error: + This will result in a generic error: .. code-block:: console @@ -265,7 +265,7 @@ and dependencies so autospec can complete a successful build. cat ./results/build.log - The build log contains details for the specific failures. In this + In the build log, you will find details for the specific failures. In this instance, there are missing dependencies: .. code-block:: console @@ -279,7 +279,7 @@ and dependencies so autospec can complete a successful build. linked by target "opae-c" in directory /builddir/build/BUILD/opae-sdk-0.13.0/libopae #. Search the spec files of upstream |CL| packages to see if the json-c library - is available. In this case, it does exist and we'll add the json-c 'dev' + is availabe. In this case, it does exist and we'll add the json-c 'dev' package into the buildreq_add: .. code-block:: bash @@ -302,7 +302,7 @@ and dependencies so autospec can complete a successful build. grep 'libuuid\.so$' ~/clearlinux/packages/*/*.spec echo "util-linux-dev" >> buildreq_add -#. Run autospec again and find the successfully-generated RPMs in the :file:`rpms` +#. Run autospec again and find the successfully-generated RPMs in the rpms directory: .. code-block:: bash @@ -384,7 +384,7 @@ To test an autospec-created package inside a VM: The code that makes this possible can be viewed by searching for the *install:* target in the `Makefile.common file on GitHub`_. -#. Return to the :file:`~/clearlinux` directory and start the |CL| VM: +#. Return back to the :file:`~/clearlinux` directory and start the |CL| VM: .. code-block:: bash @@ -411,7 +411,7 @@ Test directly on a development machine The |CL| development tooling also includes a method to extract autospec-created RPMs locally onto a |CL| development system for testing. -Extracting an RPM directly onto a system offers quicker testing; however +Extracting an RPM directly onto a system offers quicker testing, however conflicts may occur and responsibility to remove the software after testing is up to the developer. @@ -433,7 +433,7 @@ To test an autospec created package directly on the |CL| development system: tests. #. After testing has been completed, the software and any related files must - be identified and deleted. The :command:`swupd repair --picky` + be identified and deleted. The :command:`swupd verify --picky --fix` command can help restore the state of the :file:`/usr` directory (see :ref:`swupd `) however any other files must be cleaned up manually. @@ -442,7 +442,8 @@ To test an autospec created package directly on the |CL| development system: References ********** -Reference the `autospec README`_ for details regarding `autospec` commands and options. +Reference the `autospec README`_ for details regarding autospec commands and +options. Setup environment to build source ================================= @@ -456,7 +457,7 @@ automated for you with a setup script. It uses tools from the The setup script creates a workspace in the :file:`clearlinux` folder, with the subfolders :file:`Makefile`, :file:`packages`, and :file:`projects`. The :file:`projects` folder contains the main tools used for making packages in -|CL| :file:`autospec` and :file:`common`. +|CL|: `autospec` and `common`. Follow these steps to setup the workspace and tooling for building source: diff --git a/source/tooling/figures/autoproxy_0.png b/source/clear-linux/guides/tooling/figures/autoproxy_0.png similarity index 100% rename from source/tooling/figures/autoproxy_0.png rename to source/clear-linux/guides/tooling/figures/autoproxy_0.png diff --git a/source/tooling/ister.rst b/source/clear-linux/guides/tooling/ister.rst similarity index 75% rename from source/tooling/ister.rst rename to source/clear-linux/guides/tooling/ister.rst index bc8e399e..4f29229a 100644 --- a/source/tooling/ister.rst +++ b/source/clear-linux/guides/tooling/ister.rst @@ -3,7 +3,7 @@ ister.py image builder ###################### -The `ister.py tool`_ is a template-based installer used by |CL-ATTR| to produce +The `ister.py tool`_ is a template based installer used by |CL-ATTR| to produce images for each release. The same ister tool is available for use in |CL| to create custom images based on an upstream image. @@ -14,21 +14,21 @@ create custom images based on an upstream image. Description *********** -|CL| is a rolling release and produces an average of 10 releases per week using the +|CL| is a rolling release and produces on average 10 releases per week using the ister tool. With each release we produce multiple -:ref:`image types for different environments ` and use cases such -as installers, Hyper-V, KVM, or VMWare. +`image types for different environments`_ and use cases such as installers, +Hyper-V, KVM, or VMWare. -Each image has a JSON configuration file that is used by ister to generate the -image. These JSON configuration files describe the image type, partitions, version, -and bundles that will be preinstalled by default with the image. For each image -type we produce, the corresponding JSON configuration file for the image also is +Each image has a JSON configuration file used by ister to generate the image. +These JSON configuration files describe the image type, partitions, version, +and which bundles will be preinstalled by default with the image. For each image +type we produce, the corresponding JSON configuration file for the image is also published. The :ref:`mixer` tool also uses ister to build images for your custom mix. Like upstream images, a JSON configuration file is defined for the image, which ister uses to generate the image. Refer to the :ref:`mixer` guide -for instructions on using ister to build an image for a custom mix. +for instruction on using ister to build an image for a custom mix. Examples ******** @@ -37,7 +37,7 @@ Recreate an upstream image ========================== The published configuration files for upstream images may be used to recreate an -image. Here are some examples: +image, for example when you want to: * Use an older version of |CL| and the image is no longer available (only after March 2017). @@ -64,7 +64,7 @@ configuration file: :file:`/clear/config/image`. For example: ``https://cdn.download.clearlinux.org/releases/15700/clear/config/image/`` -#. Download the “PostNonChroot” script (if applicable). +#. Download “PostNonChroot” script (if applicable). The JSON configuration file for the image may have an accompanying “PostNonChroot” script that is executed at the end of the image creation @@ -88,6 +88,7 @@ Related topics * :ref:`bulk-provision` .. _ister.py tool: https://github.com/bryteise/ister +.. _image types for different environments: https://cdn.download.clearlinux.org/image/README-IMAGES.html .. _Configuration files for the current release: https://cdn.download.clearlinux.org/current/config/image/ .. _Previous releases: https://cdn.download.clearlinux.org/releases/ .. _Install a bundle: https://clearlinux.org/documentation/clear-linux/guides/maintenance/swupd-guide#adding-a-bundle \ No newline at end of file diff --git a/source/tooling/mixer.rst b/source/clear-linux/guides/tooling/mixer.rst similarity index 86% rename from source/tooling/mixer.rst rename to source/clear-linux/guides/tooling/mixer.rst index 9bcf25c4..4aa85479 100644 --- a/source/tooling/mixer.rst +++ b/source/clear-linux/guides/tooling/mixer.rst @@ -3,7 +3,7 @@ mixer ##### -**mixer** is the tool used by the |CL-ATTR| team to generate official update content +mixer is the tool used by the |CL-ATTR| team to generate official update content and releases. The update content generated by mixer is then consumed by swupd on a downstream client. The same mixer tool is available as part of |CL| to create your own customized update content and releases. @@ -23,13 +23,13 @@ mixer uses the following sources as inputs to generate update content: Using the mixer tool, you select which set of content from these sources will be part of your update. You can select content from each of these sources to make a -unique combination of functionality for your custom update content, known as a -**mix**. +unique combination of functionality for your custom update content (known as a +mix). The update content that mixer generates consists of various pieces of OS content, update metadata, as well as a complete image. The OS content includes all files in an update, as well as zero- and delta-packs for improved update -performance. The update metadata, stored as manifests, describes all of the bundle +performance. The metadata, stored as manifests, describes all of the bundle information for the update. Update content produced by mixer is then published to a web server and consumed by clients via swupd. Refer to :ref:`swupd ` for additional information regarding updates and @@ -52,9 +52,9 @@ Prerequisites Add the mixer tool with the :command:`mixer` bundle. Refer to `Install a bundle`_ for more details. -* Docker\* container +* Docker container - mixer by default runs all build commands in a Docker container to ensure + mixer by default runs all build commands in a Docker container to make sure the correct tool versions are used. This also allows custom mixes to automatically perform downstream format bumps when the upstream releases a format bump. See `Format version`_ for additional information regarding @@ -67,8 +67,8 @@ Prerequisites If you use a proxy server, you must set your proxy environment variables and create a proxy configuration file for the Docker daemon and container. - Consult your IT department for the correct values if you are behind a - corporate proxy. + Consult your IT department if you are behind a corporate proxy for the correct + values. Refer to `Configure Docker proxy info`_ for instruction. @@ -85,23 +85,23 @@ Mix setup ========== Follow these steps to create and initialize the mixer workspace. Complete -the setup before you create a mix. +setup before you create a mix. #. Create workspace. The mixer tool uses a simple workspace to contain all input and output in a - basic directory structure. The workspace is simply an empty folder from - which you execute the mixer commands. Each mix uses its own separate + basic directory structure. The workspace is simply an empty folder that you + will execute the mixer commands from. Each mix will use its own separate workspace. #. Initialize the workspace and mix. Before you create a mix, you must explicitly initialize the mixer workspace. During initialization, the mixer workspace is configured and the base for - your mix is defined. By default, your mix is based on the latest - upstream version and starts with the minimum set of bundles. Your first custom - mix version number starts at 10. Alternatively, you can select other - versions or bundle sets from which to start. + your mix is defined. By default, your mix will be based on the latest + upstream version and start with the minimum set of bundles. Your first custom + mix version number will start at 10. You can alternately select other + versions or bundle sets to start from. Initialization creates the directory structure within the workspace and adds the :file:`builder.conf` file, which is used to configure the mixer tool. @@ -109,7 +109,7 @@ the setup before you create a mix. View the `mixer.init man page`_ for more information on mixer initialization. - View the list of `suitable versions`_ from which to mix. + View the list of `suitable versions`_ to mix from. #. Edit builder.conf. @@ -129,7 +129,7 @@ A mix is created with the following steps: #. Add custom RPMs and set up local repo (optional). - If you are adding custom RPMs to your mix, you must add the RPMs to + If you are adding custom RPMs to your mix, you will need to add the RPMs to your mix workspace and set up a corresponding local repository. Go to the :ref:`autospec` guide to learn to build RPMs from @@ -143,7 +143,7 @@ A mix is created with the following steps: #. Update and build bundles. Add, edit, or remove bundles that will be part of your content and build - them. mixer automatically updates the :file:`mixbundles` file when you + them. mixer will automatically update the :file:`mixbundles` file when you update the bundles in your mix. View the `mixer.bundle man page`_ for more information on configuring bundles @@ -161,17 +161,17 @@ A mix is created with the following steps: (for all builds after version 0). A zero-pack is the full set of content needed to go from mix version 0 - (nothing) to the mix version for which you just built content. + (nothing) to the mix version you just built content for. A delta-pack provides the content *delta* between a `PAST_VERSION` to a - `MIX_VERSION` that allows the transition from one mix version to another. + `MIX_VERSION` which allows the transition from one mix version to another. View :ref:`swupd-guide` for more information on update content. #. Create image. mixer creates a bootable image from your updated content using - the :ref:`ister` tool. In this step you can specify which bundles you want + the ister tool. In this step you can specify which bundles you want *preinstalled* in the image. Users can later install other bundles available in your mix. @@ -185,7 +185,7 @@ A mix is created with the following steps: Maintain or modify mix ====================== -Update or modify your content to a new version by following the steps to +Update or modify your content to a new version by following the same steps to create a mix. Increment the mix version number for the next mix. Examples @@ -196,7 +196,7 @@ use: * A stock installation of |CL|. * A web server that comes with |CL| to host the content updates. -* A simple VM that updates against the locally produced content created in +* A simple VM that will update against the locally produced content created in Example 2. Complete all `Prerequisites`_ before using these examples. @@ -204,8 +204,7 @@ Complete all `Prerequisites`_ before using these examples. Example 1: Mix set up ====================== -This example shows the basic steps for the first-time setup of -mixer for a new mix. +This example shows the basic steps for first time setup of mixer for a new mix. #. Create an empty directory to use as a workspace for mixer: @@ -214,17 +213,18 @@ mixer for a new mix. mkdir ~/mixer #. In your mixer workspace, generate an initial mix based on the latest upstream - |CL| version, with minimum bundles. In the initialization output, be aware - that your initial mix version is set to 10 and that the minimum bundles have - been added. + |CL| version, with minimum bundles: .. code-block:: bash cd ~/mixer mixer init + Note in the initialization output, that your initial mix version is set to + 10 and that the minimum bundles have been added. + #. Edit :file:`builder.conf` to set the value of CONTENTURL and VERSIONURL to - the IP address of the nginx\* server you set up in the prerequisite + the IP address of the nginx server you set up in the prerequisite `Set up a nginx web server for mixer`_. For example: .. code-block:: console @@ -238,11 +238,11 @@ Example 2: Create a simple mix ============================== This example shows how to create a simple custom mix using upstream content. -We'll create an image for a QEMU virtual machine that we can use later to test +We'll create an image for a QEMU virtual machine which we can later use to test our mix. -We can use the default bundles that were added during initialization, but these -include the :command:`native-kernel` bundle that is intended to be used on a +We can use the default bundles that were added during intialization, but these +include the :command:`native-kernel` bundle which is intended to be used on a bare metal system instead of a VM. So we will modify the default bundle set to get a smaller kernel image, which will also be faster to load. @@ -327,13 +327,13 @@ set to get a smaller kernel image, which will also be faster to load. mixer build bundles mixer build update - Build optional delta-packs, which helps reduce client update time: + And build optional delta-packs, which will help reduce client update time: .. code-block:: bash mixer build delta-packs --from 10 --to 20 - Refresh your \http://localhost site to see the update content for + Refresh your \http://localhost site and now you can see the update content for mix version 20. Look in ~/mixer/update/www/ to see the update content in your @@ -344,7 +344,7 @@ Example 3: Deploy updates to target The image created in Example 2 is directly bootable in QEMU. In this example, we'll boot the image from Example 2 to verify it, and update the image from mix -version 10 (from which the image was built), to mix version 20. +version 10 (which the image was built from), to mix version 20. #. Set up the QEMU environment. @@ -381,10 +381,8 @@ version 10 (from which the image was built), to mix version 20. swupd bundle-list swupd bundle-list -a - .. note:: - - You cannot see the curl bundle that you added in Example 2 because - your mix is still on version 10. + Note that you cannot see the curl bundle that you added in Example 2 because + your mix is still on version 10. Check for updates. You should see that version 20 is available. Use swupd to update your mix: @@ -396,7 +394,7 @@ version 10 (from which the image was built), to mix version 20. swupd bundle-list -a Now your mix should be at version 20 and curl is now available. Try using - curl. This will fail because curl is not yet installed: + curl. This will fail as curl is not yet installed: .. code-block:: console @@ -410,7 +408,7 @@ version 10 (from which the image was built), to mix version 20. swupd bundle-add curl curl -O https://download.clearlinux.org/image/start_qemu.sh - Shutdown your VM: + And shutdown your VM: .. code-block:: bash @@ -480,11 +478,11 @@ Additional explanation of variables in :file:`builder.conf` is provided in Table | | :file:`Manifest.MoM` file to provide security for the | | | updated content you create. | | | | -| | chroot-builder uses the certificate file to sign | -| | the root :file:`Manifest.MoM` file to provide | +| | The chroot-builder uses the certificate file to sign | +| | the root :file:`Manifest.MoM` file, to provide | | | security for content verification. | | | | -| | swupd uses this certificate to verify the | +| | The swupd uses this certificate to verify the | | | :file:`Manifest.MoM` file's signature. | | | | | | For now, we strongly recommend that you do not modify | @@ -498,8 +496,8 @@ Additional explanation of variables in :file:`builder.conf` is provided in Table | | VERSIONURL is the IP address where the swupd client | | | looks to determine if a new version is available. | | | | -| | CONTENTURL is the location from which swupd pulls | -| | content updates. | +| | CONTENTURL is the location where swupd will pull content | +| | updates from. | | | | | | If the web server is on the same machine as the | | | SERVER_STATE_DIR directory, you can create a symlink to | @@ -508,16 +506,16 @@ Additional explanation of variables in :file:`builder.conf` is provided in Table | | | | | These URLs are embedded in the images created by mixer. | +-------------------------------+----------------------------------------------------------+ -| `DOCKER_IMAGE_PATH` | Sets the base name of the docker image that mixer pulls | -| | down to run builds in the proper container. | +| `DOCKER_IMAGE_PATH` | Sets the base name of the docker image mixer will pull | +| | down in order to run builds in the proper container. | +-------------------------------+----------------------------------------------------------+ | `LOCAL_BUNDLE_DIR` | Sets the path where mixer stores the local bundle | | | definition files. The bundle definition files include | | | any new, original bundles you create, along with any | | | edited versions of upstream bundles. | +-------------------------------+----------------------------------------------------------+ -| `SERVER_STATE_DIR` | Sets the path to which mixer outputs content. By | -| | default, mixer automatically sets the path. | +| `SERVER_STATE_DIR` | Sets the path for where mixer outputs content. By | +| | default, mixer will automatically set the path. | +-------------------------------+----------------------------------------------------------+ | `VERSIONS_PATH` | Sets the path for the mix version and upstream version's | | | two state files: :file:`mixversion` and | @@ -543,8 +541,8 @@ variable in the :file:`mixer.state` file. Variables in the :file:`mixer.state` are used by mixer between executions and should not be manually changed. If `Format` increments to a new epoch (a "format bump"), the OS has changed in -such a way that updating from build M in format X to build N in format Y will -not work. Generally, this scenario occurs when the software updater or the software +such a way that updating from build M in format X, to build N in format Y will +not work. Generally, this scenario occurs when the software updater/the software has a change such that it is no longer compatible with the previous update scheme, or when a package is removed from the update stream and the update must ensure the files associated with that package are removed from the system. @@ -552,7 +550,7 @@ must ensure the files associated with that package are removed from the system. Using a format increment, we make sure pre- and co-requisite changes flow out with proper ordering. The updated client will only update to the latest release in its respective format version, unless overridden by command line -flags. In this way, we can guarantee that all clients update to the final version +flags. This way we can guarantee that all clients update to the final version in their given format. The given format *must* contain all the changes needed to understand the content @@ -560,7 +558,7 @@ built in the next format. Only after reaching the final release in the old format can a client continue to update to releases in the new format. The format version is incremented only when a compatibility breakage is -introduced. Normal updates, such as updating a software package, do not require a +introduced. Normal updates, like updating a software package, do not require a format increment. .. rst-class:: content-collapse @@ -569,16 +567,16 @@ Bundles ======= mixer stores information about the bundles included in a mix in a flat file -called :file:`mixbundles`, which is located in the path set by the VERSIONS_PATH +called :file:`mixbundles`, located in the path set by the VERSIONS_PATH variable in :file:`builder.conf`. :file:`mixbundles` is automatically created when the mix is initiated. mixer will refresh the file each time you change the bundles in the mix. Bundles can include other bundles. Nested bundles can themselves include other bundles. If you see an unexpected bundle in your mix, it is likely a nested -bundle in one of the bundles you explicitly added. +bundle in one of the bundles you explicitley added. -A bundle will fill into one of two categories: upstream or local. Upstream +A bundle will fill into one of two categoris: upstream or local. Upstream bundles are those provided by |CL|. Local bundles are either modified upstream bundles or new local bundles. @@ -611,7 +609,7 @@ upstream bundles locally, and edit into a local variation. Bundle configuration -------------------- -mixer provides commands to configure the bundles for a mix, such as to add a +mixer provides commands to configure the bundles for a mix, for example to add a bundle to a mix, to create a new bundle for a mix, or to remove a bundle from a mix. View the `mixer.bundle man page`_ for a full list of commands and more information on configuring bundles in a mix. @@ -619,16 +617,14 @@ information on configuring bundles in a mix. Editing an existing local bundle is as simple as opening the bundle definition file in your favorite editor, making the desired edits, and saving your changes. -.. note:: +A note on removing bundles from a mix: By default, removing a bundle will only +remove the bundle from the mix. The local bundle defintion file will still +remain. To completely remove a bundle, including its local bundle definition +file, use the :command:`--local` flag. - Removing bundles from a mix: By default, removing a bundle will only - remove the bundle from the mix. The local bundle definition file will still - remain. To completely remove a bundle, including its local bundle definition - file, use the :command:`--local` flag. - - If you remove the bundle definition file for a local, edited version of an - upstream bundle in a mix, the mix reverts to reference the original upstream - version of the bundle. +If you remove the bundle definition file for a local, edited version of an +upstream bundle in a mix, the mix will revert to reference the original upstream +version of the bundle. .. rst-class:: content-collapse @@ -655,7 +651,7 @@ Use these steps to enable Docker for the mixer tool. Make sure to Pull Docker container manually (optional) ----------------------------------------- -By default, mixer automatically pulls a Docker container for mixing if one +By default, mixer will automatically pull a Docker container for mixing if one does not already exist. If you need to troubleshoot the mixer container, it may be useful to manually pull a mixer Docker container. @@ -690,13 +686,15 @@ Configure Docker proxy info If needed, use these steps to configure the Docker proxy information. +Configure the Docker daemon proxies: + #. Create the Docker daemon proxy config directory: .. code-block:: bash sudo mkdir -p /etc/systemd/system/docker.service.d -#. Create :file:`/etc/systemd/system/docker.service.d/http-proxy.conf` and + Create :file:`/etc/systemd/system/docker.service.d/http-proxy.conf` and add the following using your own proxy values: .. code-block:: console @@ -711,8 +709,8 @@ If needed, use these steps to configure the Docker proxy information. sudo systemctl daemon-reload -Configure the Docker container proxies, to pass proxy settings to -containers: +Configure the Docker container proxies, in order to pass proxy +settings to containers: #. Create a directory for your container config: @@ -743,8 +741,8 @@ containers: sudo chown "$USER":"$USER" /home/"$USER"/.docker -R sudo chmod g+rwx "$HOME/.docker" -R -Configure proxies to allow mixer to access upstream content from behind -a firewall. +Lastly, configure proxies to allow mixer to access upstream content from behind +a firewall. For example: #. Open your :file:`$HOME/.bashrc` file and add proxy and port values for the following: diff --git a/source/clear-linux/guides/tooling/swupd-guide.rst b/source/clear-linux/guides/tooling/swupd-guide.rst new file mode 100644 index 00000000..72cb8351 --- /dev/null +++ b/source/clear-linux/guides/tooling/swupd-guide.rst @@ -0,0 +1,355 @@ +.. _swupd-guide: + +swupd +##### + +:command:`swupd` links a |CL-ATTR| installation with upstream updates and +software. + +.. contents:: + :local: + :depth: 2 + +Description +*********** + +:command:`swupd` has two main functions: + +#. It manages software replacing APT or YUM, installing bundles + rather than packages. +#. It checks for system updates and installs them. + +:ref:`Bundles ` are the smallest granularity component that is +managed by |CL| and contain everything needed to deliver a software +capability. Rather than downloading a cascade of package dependencies when +installing a piece of software, a bundle comes with all of its dependencies. +:command:`swupd` manages overlapping dependencies behind the scenes ensuring +that all software is compatible across the system. + +Versioning +========== + +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). + +- 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. + +This can be done effectively, but given the nearly endless combinations of +packages and versions of packages a server may have, it quickly becomes +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 |CL|, we need track: + +- One number + +A number representing the **current** release of the OS is sufficient to +describe the versions of all the software on the OS. Each build is +composed of a specific set of bundles made from a particular version of +packages. This matters on a daily basis to system administrators, who +need to determine which of their systems do not have the latest security +fixes, or which combinations of software have been tested. Every release +of the same number is guaranteed to contain the same versions of software, +so there's no ambiguity between two systems running the same version of |CL|. + +Updating +======== + +|CL| enforces regular updating of the OS by default and will automatically +check for updates against a version server. The content server provides the +file and metadata content for all versions and can be the same as the +version server. The content url server provides metadata in the form of +manifests. These Manifest files list and describe file contents, symlinks, +and directories. Additionally, the actual content is +provided to clients in the form of archive files. + +Software updates with |CL| are also efficient. Unlike package-based +distributions, :command:`swupd` only updates files that have changed rather +than entire packages. For example, it is quite common for an OS security +patch to be as small as 15 KB. Using binary deltas, the |CL| is able to +apply only what is needed. + +To get a more detailed understanding of how to generate update content for +|CL| see the :ref:`mixer ` tool. + +How it works +************ + +Prerequisites +============= + +* The device is on a well-connected network. +* The device is able to connect to an update server. The default server is: + http://update.clearlinux.org + +Updates +======= + +|CL| updates are automatic by default but can be set to occur only on +demand. :command:`swupd` makes sure that regular updates are simple and +secure. It can also check the validity of currently installed files and +software and correct any problems. + +Manifests +--------- + +The Clear Linux OS software update content consists of data and +metadata. The data is the files that end up in the OS. The metadata +contains relevant information to properly provision the data to the OS +file system, as well as update the system and add or remove additional +content to the OS. + +The Manifests are mostly long lists of hashes that describe content. +Each bundle gets its own manifest file. There is a master manifest +file that describes all manifests to tie it all together. + +Fullfiles, packs, and delta packs +--------------------------------- + +The data that an update provisions to a system can be obtained in +three different ways. There are three different methods, and they +exist to optimize the delivery of content and speed up updates. + +Fullfiles are always generated for every file in every release. This +allows any Clear Linux OS to obtain the exact copy of the content +for each version directly. This would be used if the OS verification +needed to replace a single file, for instance. + +Packs are available for some releases and combine many files to speed +up the creation of installation media and large updates. Delta packs +are an optimized version of packs that only contain updates (binary +diffs) and cannot be used without having the original file content. + +Bundle Search +============= + +:command:`swupd` search downloads manifest data and searches for +bundles that match the term. Enter only one term, or hyphenated term, per +search. Use the command :command:`man swupd` to learn more. + +Only the base bundle is returned. Bundles can contain other bundles via +includes. For more details, see `Bundle Definition Files`_ and its +subdirectory bundles. + +Bundles that are already installed, will be marked [installed] in search +results. + +Optionally, you can review our `bundles`_ on GitHub. + +Examples +******** + +Example 1: Disable and Enable automatic updates +=============================================== + +|CL| updates are automatic by default but can be set to occur only +on demand. + +#. First verify your current auto-update setting. + + .. code-block:: bash + + sudo swupd autoupdate + + .. code-block:: console + + Enabled + +#. Disable automatic updates. + + .. code-block:: bash + + sudo swupd autoupdate --disable + + .. code-block:: console + + Warning: disabling automatic updates may take you out of compliance with your IT policy + + Running systemctl to disable updates + Created symlink /etc/systemd/system/swupd-update.service → /dev/null. + Created symlink /etc/systemd/system/swupd-update.timer → /dev/null. + +#. Check manually for updates. + + .. code-block:: bash + + sudo swupd check-update + +#. Install an update after identifying one that you need. + + .. code-block:: bash + + sudo swupd update -m + +#. Re-enable automatic installs. + + .. code-block:: bash + + sudo swupd autoupdate --enable + +.. _swupd-guide-example-install-bundle: + +Example 2: Find and install Kata\* Containers +============================================= + +Kata Containers is a popular container implementation. Unlike other +container implementations, each Kata Container has its own +kernel instance and runs on its own :abbr:`Virtual Machine (VM)` for +improved security. + +|CL| makes it very easy to install, since you only need to add +`one bundle`_ to use `Kata Containers`_: `containers-virt`, despite a +number of dependencies. Also, check out our tutorial: :ref:`kata`. + +#. Find the right bundle. + + * To return all possible matches for the search string enter + :command:`swupd search`, followed by 'kata': + + .. code-block:: bash + + sudo swupd search kata + + The output should be similar to: + + .. code-block:: console + + Bundle with the best search result: + + containers-virt - Run container applications from Dockerhub in lightweight virtual machines + + This bundle can be installed with: + + swupd bundle-add containers-virt + + Alternative bundle options are + + cloud-native-basic - Contains ClearLinux native software for Cloud + + .. note:: + + If your search does not produce results with a specific + term, shorten the search term. For example, use *kube* instead of + *kubernetes*. + +#. Add the bundle. + + .. code-block:: bash + + sudo swupd bundle-add containers-virt + + .. note:: + + To add multiple bundles simply add a space followed by the bundle name. + + The output of a successful installation should be similar to: + + .. code-block:: console + + Downloading packs... + + Extracting containers-virt pack for version 24430 + ...50% + Extracting kernel-container pack for version 24430 + ...100% + Starting download of remaining update content. This may take a while... + ...100% + Finishing download of update content... + Installing bundle(s) files... + ...100% + Calling post-update helper scripts. + Successfully installed 1 bundle + +Example 3: Verify and correct system file mismatch +================================================== + +:command:`swupd` can determine whether system directories and files have +been added to, overwritten, removed, or modified (e.g., permissions). + +.. code-block:: bash + + sudo swupd verify + +All directories that are watched by :command:`swupd` are verified according +to the manifest data and hash mismatches are flagged as follows: + +.. code-block:: console + + Verifying version 23300 + Verifying files + ...0% + Hash mismatch for file: /usr/bin/chardetect + ... + ... + Hash mismatch for file: /usr/lib/python3.6/site-packages/urllib3/util/wait.py + ...100% + Inspected 237180 files + 423 files did not match + Verify successful + +In this case, python packages that were installed on top of the default +install were flagged as mismatched. :command:`swupd` can be directed to +ignore or fix issues based on command line options. + +:command:`swupd` can correct any issues it detects. Additional directives +can be added including a white list of directories that will be ignored. + +The following command will repair issues, remove unknown items, and +ignore files or directories matching `/usr/lib/python`: + +.. code-block:: bash + + sudo swupd verify --fix --picky --picky-whitelist=/usr/lib/python + +Quick Reference +*************** + +swupd info + To see the currently installed version and update servers. + +swupd update + To update to a specific version or with no arguments to update to latest. + +swupd bundle-list [--all] + To list installed bundles. + +swupd bundle-add [-b] + To find a bundle that contains your search term. + +swupd bundle-add + To add a bundle. + +swupd bundle-remove + To remove a bundle. + +swupd --help + For additional :command:`swupd` commands. + +man swupd + To reference the :command:`swupd` man page, or see the + `source documentation`_ available on github. + +Related topics +************** + +* :ref:`autospec` +* :ref:`mixer` +* :ref:`bundles` + +.. _source documentation: https://github.com/clearlinux/swupd-client/blob/master/docs/swupd.1.rst + +.. _Kata Containers: https://clearlinux.org/downloads/containers + +.. _one bundle: https://github.com/clearlinux/clr-bundles/blob/master/bundles/containers-virt + +.. _Bundle Definition Files: https://github.com/clearlinux/clr-bundles + +.. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles \ No newline at end of file diff --git a/source/reference/bundle-commands.rst b/source/clear-linux/reference/bundle-commands.rst similarity index 100% rename from source/reference/bundle-commands.rst rename to source/clear-linux/reference/bundle-commands.rst diff --git a/source/reference/bundles/bundles.html.txt b/source/clear-linux/reference/bundles/bundles.html.txt similarity index 100% rename from source/reference/bundles/bundles.html.txt rename to source/clear-linux/reference/bundles/bundles.html.txt diff --git a/source/reference/bundles/bundles.rst b/source/clear-linux/reference/bundles/bundles.rst similarity index 100% rename from source/reference/bundles/bundles.rst rename to source/clear-linux/reference/bundles/bundles.rst diff --git a/source/reference/bundles/openssh-server.rst b/source/clear-linux/reference/bundles/openssh-server.rst similarity index 100% rename from source/reference/bundles/openssh-server.rst rename to source/clear-linux/reference/bundles/openssh-server.rst diff --git a/source/reference/collaboration/collaboration.rst b/source/clear-linux/reference/collaboration/collaboration.rst similarity index 100% rename from source/reference/collaboration/collaboration.rst rename to source/clear-linux/reference/collaboration/collaboration.rst diff --git a/source/reference/collaboration/structure-formatting.rst b/source/clear-linux/reference/collaboration/structure-formatting.rst similarity index 100% rename from source/reference/collaboration/structure-formatting.rst rename to source/clear-linux/reference/collaboration/structure-formatting.rst diff --git a/source/reference/collaboration/writing-guide.rst b/source/clear-linux/reference/collaboration/writing-guide.rst similarity index 100% rename from source/reference/collaboration/writing-guide.rst rename to source/clear-linux/reference/collaboration/writing-guide.rst diff --git a/source/reference/compatible-hardware.rst b/source/clear-linux/reference/compatible-hardware.rst similarity index 100% rename from source/reference/compatible-hardware.rst rename to source/clear-linux/reference/compatible-hardware.rst diff --git a/source/clear-linux/reference/compatible-kernels.rst b/source/clear-linux/reference/compatible-kernels.rst new file mode 100644 index 00000000..cc76e524 --- /dev/null +++ b/source/clear-linux/reference/compatible-kernels.rst @@ -0,0 +1,91 @@ +.. _compatible-kernels: + +Compatible kernels +################## + +The |CL-ATTR| provides the following Linux kernels with a respective bundle. +This document describes the specific use cases these `bundles`_ serve +and provides links to their source code. + +Kernel native +============= + +The *kernel-native* bundle focuses on the bare metal platforms. It is +optimized for fast booting and performs best on the Intel® architectures +described on the :ref:`supported hardware list`. The +optimization patches are found in our `Linux`_ GitHub\* repo. + +Kernel Container +================ + +The *kernel-container* bundle contains the kernel used by the +Intel® Clear Containers project. This kernel is optimized for +fast booting and performs best on |CC| running on the Intel® architectures +described on the :ref:`supported hardware list`. +The optimization patches are found in our `Linux-Container`_ GitHub repo. + +.. _vm-kernels: + +Kernel LTS +========== + +The *kernel-lts* bundle focuses on the bare metal platforms but uses the +latest :abbr:`LTS (Long Term Support)` Linux kernel. It is optimized for fast +booting and performs best on the Intel® architectures described on the +:ref:`supported hardware list`. Additionally, this +kernel includes the VirtualBox\* kernel modules, see our +:ref:`instructions on using Virtualbox` for more information. +The optimization patches are found in our `Linux-LTS`_ GitHub repo. + +Kernel KVM +========== + +The *kernel-kvm* bundle focuses on the Linux +:abbr:`KVM (Kernel-based Virtual Machine)`. It is optimized for fast booting +and performs best on Virtual Machines running on the Intel® architectures +described on the :ref:`supported hardware list`. +Use this kernel when running |CL| as the guest OS on top of *qemu/kvm*. Use +this kernel with **cloud orchestrators** using *qemu/kvm* internally as +their **hypervisor**. This kernel can be used as a standalone |CL| VM, see +our :ref:`instructions on using KVM` for more information. The +optimization patches are found in our `Linux-KVM`_ GitHub repo. + +Kernel Hyper-V\* +================ + +The *kernel-hyperv* bundle focuses on running Linux on Microsoft\* +Hyper-V. It is optimized for fast booting and performs best on Virtual +Machines running on the Intel® architectures described on the +:ref:`supported hardware list`. +Use this kernel when running |CL| as the guest OS of **Cloud Instances** in +projects such as Microsoft `Azure`_\*. This kernel can be used in a +standalone |CL| VM, see our :ref:`instructions on using Hyper-V` for +more information. The optimization patches are found in our `Linux-HyperV`_ +GitHub repo. + +Kernel Hyper-V LTS +================== + +The *kernel-hyperv-lts* bundle focuses on running Linux on Microsoft +Hyper-V but uses the latest :abbr:`LTS (Long Term Support)` Linux kernel. It +is optimized for fast booting and performs best on Virtual +Machines running on the Intel® architectures described on the +:ref:`supported hardware list`. +Use this kernel when running |CL| as the guest OS of **Cloud Instances** in +projects such as Microsoft `Azure`_. This kernel can be used in a standalone +|CL| VM, see our :ref:`instructions on using Hyper-V` for +more information. The optimization patches are found in our +`Linux-HyperV-LTS`_ GitHub repo. + + +.. _Linux: https://github.com/clearlinux-pkgs/linux +.. _Linux-LTS: https://github.com/clearlinux-pkgs/linux-lts +.. _Linux-KVM: https://github.com/clearlinux-pkgs/linux-kvm +.. _Linux-HyperV: https://github.com/clearlinux-pkgs/linux-hyperv +.. _Linux-HyperV-LTS: https://github.com/clearlinux-pkgs/linux-hyperv-lts +.. _Linux-Container: https://github.com/clearlinux-pkgs/linux-container +.. _bundles: https://github.com/clearlinux/clr-bundles +.. _CIAO: https://github.com/01org/ciao +.. _Azure: + https://azuremarketplace.microsoft.com/en-us/marketplace/apps/clear-linux-project.clear-linux-os + diff --git a/source/reference/how-to-clear-overview.rst b/source/clear-linux/reference/how-to-clear-overview.rst similarity index 100% rename from source/reference/how-to-clear-overview.rst rename to source/clear-linux/reference/how-to-clear-overview.rst diff --git a/source/reference/image-types.rst b/source/clear-linux/reference/image-types.rst similarity index 68% rename from source/reference/image-types.rst rename to source/clear-linux/reference/image-types.rst index cc5d1325..a87fbd56 100644 --- a/source/reference/image-types.rst +++ b/source/clear-linux/reference/image-types.rst @@ -35,11 +35,14 @@ Table 2 lists the currently available images that are platform specific. * - Image Type - Description - * - live-desktop.img or live-desktop.iso - - Image for booting to GNOME\* desktop to preview or install the OS. + * - installer.img + - Preferred image of |CL| with interactive installer. - * - live-server.img or live-server.iso - - Image for booting to server command prompt to preview or install the OS. + * - installer.iso + - 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. .. list-table:: Table 2: Types of platform-specific |CL| images :widths: 15, 85 @@ -48,23 +51,20 @@ Table 2 lists the currently available images that are platform specific. * - Image Type - Description - * - aws.img - - Image suitable for use with Amazon\* AWS\*. - * - azure.vhd - - Virtual Hard Disk for use on Microsoft\* Azure\* cloud platform. + - Virtual Hard Disk for use on Microsoft\* Azure\* cloud platform * - azure-docker.vhd - - Virtual Hard Disk for use on Microsoft Azure cloud platform with Docker\* pre-installed. + - Virtual Hard Disk for use on Microsoft Azure cloud platform with Docker\* pre-installed * - azure-machine-learning.vhd - - Virtual Hard Disk for use on Microsoft Azure cloud platform with the `machine-learning-basic` bundle installed. + - Virtual Hard Disk for use on Microsoft Azure cloud platform with the `machine-learning-basic` bundle installed - * - cloudguest.img - - Image with generic cloud guest virtual machine (VM) requirements installed. + * - cloud.img + - Image for use by cloud deployments such as OpenStack\* - * - gce.tar - - Image with the Google Compute Engine (GCE) specific kernel. + * - containers.img + - Image for use by Clear Containers runtime. Includes `optimized kernel`_ for Clear Containers. * - hyperv.vhdx - Virtual Hard Disk for use with Microsoft Hyper-V\* hypervisor. Includes `optimized kernel`_ for Hyper-V. @@ -73,15 +73,9 @@ Table 2 lists the currently available images that are platform specific. - Image for booting in a simple VM with start_qemu.sh. Includes `optimized kernel`_ for KVM. - * - kvm-legacy.img - - Image for booting in a simple VM using legacy BIOS, if using start_qemu.sh make sure to remove -bios parameter. - - * - pxe.tar - - Image suitable for use with PXE server. - * - vmware.vmdk - Virtual Machine Disk for VMware\* platforms inclduing Player, Workstation, and ESXi. -.. _images: https://clearlinux.org/downloads +.. _images: https://cdn.download.clearlinux.org/image .. _`optimized kernel`: https://clearlinux.org/documentation/clear-linux/reference/compatible-kernels diff --git a/source/reference/reference.rst b/source/clear-linux/reference/reference.rst similarity index 73% rename from source/reference/reference.rst rename to source/clear-linux/reference/reference.rst index 8a680960..b9f7a8ea 100644 --- a/source/reference/reference.rst +++ b/source/clear-linux/reference/reference.rst @@ -15,17 +15,6 @@ features. bundles/openssh-server how-to-clear-overview collaboration/collaboration + compatible-kernels system-requirements image-types - -.. _concepts: - -Clear Linux concepts -******************** - -.. toctree:: - :maxdepth: 1 - :glob: - - ../concepts/* - diff --git a/source/reference/system-requirements.rst b/source/clear-linux/reference/system-requirements.rst similarity index 100% rename from source/reference/system-requirements.rst rename to source/clear-linux/reference/system-requirements.rst diff --git a/source/tutorials/aws-web/aws-web.rst b/source/clear-linux/tutorials/aws-web/aws-web.rst similarity index 100% rename from source/tutorials/aws-web/aws-web.rst rename to source/clear-linux/tutorials/aws-web/aws-web.rst diff --git a/source/tutorials/aws-web/figures/aws-web-1.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-1.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-1.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-1.png diff --git a/source/tutorials/aws-web/figures/aws-web-10.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-10.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-10.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-10.png diff --git a/source/tutorials/aws-web/figures/aws-web-11.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-11.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-11.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-11.png diff --git a/source/tutorials/aws-web/figures/aws-web-12.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-12.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-12.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-12.png diff --git a/source/tutorials/aws-web/figures/aws-web-13.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-13.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-13.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-13.png diff --git a/source/tutorials/aws-web/figures/aws-web-14.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-14.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-14.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-14.png diff --git a/source/tutorials/aws-web/figures/aws-web-2.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-2.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-2.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-2.png diff --git a/source/tutorials/aws-web/figures/aws-web-3.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-3.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-3.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-3.png diff --git a/source/tutorials/aws-web/figures/aws-web-4.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-4.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-4.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-4.png diff --git a/source/tutorials/aws-web/figures/aws-web-5.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-5.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-5.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-5.png diff --git a/source/tutorials/aws-web/figures/aws-web-6.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-6.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-6.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-6.png diff --git a/source/tutorials/aws-web/figures/aws-web-7.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-7.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-7.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-7.png diff --git a/source/tutorials/aws-web/figures/aws-web-8.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-8.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-8.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-8.png diff --git a/source/tutorials/aws-web/figures/aws-web-9.png b/source/clear-linux/tutorials/aws-web/figures/aws-web-9.png similarity index 100% rename from source/tutorials/aws-web/figures/aws-web-9.png rename to source/clear-linux/tutorials/aws-web/figures/aws-web-9.png diff --git a/source/tutorials/azure.rst b/source/clear-linux/tutorials/azure.rst similarity index 100% rename from source/tutorials/azure.rst rename to source/clear-linux/tutorials/azure.rst diff --git a/source/tutorials/azure/figures/azure-1.png b/source/clear-linux/tutorials/azure/figures/azure-1.png similarity index 100% rename from source/tutorials/azure/figures/azure-1.png rename to source/clear-linux/tutorials/azure/figures/azure-1.png diff --git a/source/tutorials/azure/figures/azure-2.png b/source/clear-linux/tutorials/azure/figures/azure-2.png similarity index 100% rename from source/tutorials/azure/figures/azure-2.png rename to source/clear-linux/tutorials/azure/figures/azure-2.png diff --git a/source/tutorials/azure/figures/azure-3.png b/source/clear-linux/tutorials/azure/figures/azure-3.png similarity index 100% rename from source/tutorials/azure/figures/azure-3.png rename to source/clear-linux/tutorials/azure/figures/azure-3.png diff --git a/source/tutorials/dars.rst b/source/clear-linux/tutorials/dars.rst similarity index 100% rename from source/tutorials/dars.rst rename to source/clear-linux/tutorials/dars.rst diff --git a/source/tutorials/dlrs/dlrs.rst b/source/clear-linux/tutorials/dlrs/dlrs.rst similarity index 70% rename from source/tutorials/dlrs/dlrs.rst rename to source/clear-linux/tutorials/dlrs/dlrs.rst index 49dd3930..7af186c9 100644 --- a/source/tutorials/dlrs/dlrs.rst +++ b/source/clear-linux/tutorials/dlrs/dlrs.rst @@ -6,6 +6,7 @@ Deep Learning Reference Stack This tutorial describes how to run benchmarking workloads for TensorFlow\*, PyTorch\*, and Kubeflow in |CL-ATTR| using the Deep Learning Reference Stack. + .. contents:: :local: :depth: 1 @@ -25,14 +26,14 @@ The Deep Learning Reference Stack is available in the following versions: for Deep Neural Networks (Intel® MKL-DNN) primitives and introduces support for Intel® AVX-512 Vector Neural Network Instructions (VNNI). * `Intel MKL-DNN`_, which includes the TensorFlow framework optimized using - Intel® Math Kernel Library for Deep Neural Networks (Intel® MKL-DNN) - primitives. + Intel® Math Kernel Library for Deep Neural Networks (Intel® MKL-DNN) primitives. * `Eigen`_, which includes `TensorFlow`_ optimized for Intel® architecture. * `PyTorch with OpenBLAS`_, which includes PyTorch with OpenBlas. * `PyTorch with Intel MKL-DNN`_, which includes PyTorch optimized using Intel® Math Kernel Library (Intel® MKL) and Intel MKL-DNN. -.. important:: + +.. note:: To take advantage of the Intel® AVX-512 and VNNI functionality with the Deep Learning Reference Stack, you must use the following hardware: @@ -40,41 +41,36 @@ The Deep Learning Reference Stack is available in the following versions: * Intel® AVX-512 images require an Intel® Xeon® Scalable Platform * VNNI requires a 2nd generation Intel® Xeon® Scalable Platform + Stack features ============== * Deep Learning Reference Stack `V3.0 release announcement`_. -* Deep Learning Reference Stack v2.0 including current - `PyTorch benchmark results`_. -* Deep Learning Reference Stack v1.0 including current - `TensorFlow benchmark results`_. -* `Release notes on Github\*`_ for the latest release of Deep Learning Reference - Stack. +* Deep Learning Reference Stack v2.0 including current `PyTorch benchmark results`_. +* Deep Learning Reference Stack v1.0 including current `TensorFlow benchmark results`_. +* `Release notes on Github\*`_ for the latest release of Deep Learning Reference Stack. .. note:: - The Deep Learning Reference Stack is a collective work, and each piece of software within the work has its own license. Please see the `terms of use`_ for more details about licensing and usage of the Deep Learning Reference Stack. - - + Performance test results for the Deep Learning Reference Stack were + obtained using `runc` as the runtime. Prerequisites ============= -* :ref:`Install ` |CL| on your host system +* :ref:`Install ` |CL| on your host system. * :command:`containers-basic` bundle * :command:`cloud-native-basic` bundle In |CL|, :command:`containers-basic` includes Docker\*, which is required for TensorFlow and PyTorch benchmarking. Use the :command:`swupd` utility to -check if :command:`containers-basic` and :command:`cloud-native-basic` are -present: +check if :command:`containers-basic` and :command:`cloud-native-basic` are present: .. code-block:: bash sudo swupd bundle-list -To install the :command:`containers-basic` or :command:`cloud-native-basic` -bundles, enter: +To install the :command:`containers-basic` or :command:`cloud-native-basic` bundles, enter: .. code-block:: bash @@ -95,16 +91,11 @@ Version compatibility We validated these steps against the following software package versions: -* |CL| 26240 (Minimum supported version) +* |CL| 26240 (Lower version not supported.) * Docker 18.06.1 * Kubernetes 1.11.3 * Go 1.11.12 - -.. note:: - - The Deep Learning Reference Stack was developed to provide the best user experience when executed on a |CL| host. However, as the stack runs in a container environment, you should be able to complete the following sections of this tutorial on other Linux* distributions, provided they comply with the Docker*, Kubernetes* and Go* package versions listed above. Look for your distribution documentation on how to update packages and manage Docker services. - TensorFlow single and multi-node benchmarks ******************************************* @@ -113,12 +104,6 @@ For multi-node testing, replicate these steps for each node. These steps provide a template to run other benchmarks, provided that they can invoke TensorFlow. -.. note:: - - Performance test results for the Deep Learning Reference Stack and for this tutorial were - obtained using `runc` as the runtime. - - #. Download either the `Eigen`_ or the `Intel MKL-DNN`_ Docker image from `Docker Hub`_. @@ -152,9 +137,6 @@ TensorFlow. You can replace the model with one of your choice supported by the TensorFlow benchmarks. - If you are using an FP32 based model, it can be converted to an int8 model - using `Intel® quantization tools`_. - PyTorch single and multi-node benchmarks **************************************** @@ -197,11 +179,6 @@ Kubeflow multi-node benchmarks The benchmark workload runs in a Kubernetes cluster. The tutorial uses `Kubeflow`_ for the Machine Learning workload deployment on three nodes. -.. warning:: - - If you choose the Intel® MKL-DNN or Intel® MKL-DNN-VNNI image, your platform must support the Intel® AVX-512 instruction set. Otherwise, an *illegal instruction* error may appear, and you won’t be able to complete this tutorial. - - Kubernetes setup ================ @@ -216,48 +193,12 @@ We used `flannel`_ as the network provider for these tests. If you prefer a different network layer, refer to the Kubernetes `networking documentation`_ for setup. -Kubectl -======= - -You can use kubectl to run commands against your Kubernetes cluster. Refer to -the `kubectl overview`_ for details on syntax and operations. Once you have a -working cluster on Kubernetes, use the following YAML script to start a pod with -a simple shell script, and keep the pod open. - -#. Copy this example.yaml script to your system: - - .. code-block:: console - - apiVersion: v1 - kind: Pod - metadata: - name: example-pod - labels: - app: ex-pod - spec: - containers: - - name: ex-pod-container - image: clearlinux/stacks-dlrs-mkl:latest - command: ['/bin/bash', '-c', '--'] - args: [ "while true; do sleep 30; done" ] - -#. Execute the script with kubectl: - - .. code-block:: bash - - kubectl apply –f /example.yaml - -This script opens a single pod. More robust solutions would create a deployment -or inject a python script or larger shell script into the container. - Images ====== -You must add `launcher.py`_ to the Docker image to include the Deep +You must add `launcher.py` to the Docker image to include the Deep Learning Reference Stack and put the benchmarks repo in the correct -location. Note that this tutorial uses Kubeflow v0.4.0, and cannot guarantee results if you use a different version. - -From the Docker image, run the following: +location. From the Docker image, run the following: .. code-block:: bash @@ -266,7 +207,7 @@ From the Docker image, run the following: cp launcher.py /opt chmod u+x /opt/* -Your entry point becomes: :file:`/opt/launcher.py`. +Your entry point becomes: :file:`/opt/launcher.py` This builds an image that can be consumed directly by TFJob from Kubeflow. @@ -276,9 +217,9 @@ ksonnet\* Kubeflow uses ksonnet\* to manage deployments, so you must install it before setting up Kubeflow. -ksonnet was added to the :command:`cloud-native-basic` bundle in |CL| version -27550. If you are using an older |CL| version (not recommended), you must -manually install ksonnet as described below. +ksonnet was added to the :command:`cloud-native-basic` bundle in |CL| version 27550. If +you are using an older |CL| version (not recommended), you must manually +install ksonnet as described below. On |CL|, follow these steps: @@ -350,8 +291,7 @@ Run a TFJob Replace with the image name you specified in previous steps. -#. Generate Kubernetes manifests for the workloads and apply them using these - commands: +#. Generate Kubernetes manifests for the workloads and apply them using these commands: .. code-block:: bash @@ -429,8 +369,7 @@ A new, blank notebook is displayed, with a cell ready for input. :alt: New blank notebook -To verify that PyTorch is working, copy the following snippet into the blank -cell, and run the cell. +To verify that PyTorch is working, copy the following snippet into the blank cell, and run the cell. .. code-block:: console @@ -453,79 +392,6 @@ You can continue working in this notebook, or you can download existing notebooks to take advantage of the Deep Learning Reference Stack's optimized deep learning frameworks. Refer to `Jupyter Notebook`_ for details. -Uninstallation -************** - -To uninstall the Deep Learning Reference Stack, you can choose to stop the container so that it is not using system resources, or you can stop the container and delete it to free storage space. - -To stop the container, execute the following from your host system: - -#. Find the container's ID - - .. code-block:: bash - - docker container ls - - This will result in output similar to the following: - - .. code-block:: console - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - e131dc71d339 clearlinux/stacks-dlrs-oss "/bin/sh -c 'bash'" 23 seconds ago Up 21 seconds oss - -#. You can then use the ID or container name to stop the container. This example uses the name "oss": - - .. code-block:: bash - - docker container stop oss - - -#. Verify that the container is not running - - .. code-block:: bash - - docker container ls - - -#. To delete the container from your system you need to know the Image ID: - - .. code-block:: bash - - docker images - - This command results in output similar to the following: - - .. code-block:: console - - REPOSITORY TAG IMAGE ID CREATED SIZE - clearlinux/stacks-dlrs-oss latest 82757ec1648a 4 weeks ago 3.43GB - clearlinux/stacks-dlrs-mkl latest 61c178102228 4 weeks ago 2.76GB - -#. To remove an image use the image ID: - - .. code-block:: bash - - docker rmi 82757ec1648a - - .. code-block:: console - - # docker rmi 827 - Untagged: clearlinux/stacks-dlrs-oss:latest - Untagged: clearlinux/stacks-dlrs-oss@sha256:381f4b604537b2cb7fb5b583a8a847a50c4ed776f8e677e2354932eb82f18898 - Deleted: sha256:82757ec1648a906c504e50e43df74ad5fc333deee043dbfe6559c86908fac15e - Deleted: sha256:e47ecc039d48409b1c62e5ba874921d7f640243a4c3115bb41b3e1009ecb48e4 - Deleted: sha256:50c212235d3c33a3c035e586ff14359d03895c7bc701bb5dfd62dbe0e91fb486 - - - Note that you can execute the :command:`docker rmi` command using only the first few characters of the image ID, provided they are unique on the system. - -#. Once you have removed the image, you can verify it has been deleted with: - - .. code-block:: bash - - docker images - - Related topics ************** @@ -536,6 +402,7 @@ Related topics * :ref:`kubernetes` tutorial * `Jupyter Notebook`_ + .. _TensorFlow: https://www.tensorflow.org/ .. _Kubeflow: https://www.kubeflow.org/ @@ -576,12 +443,4 @@ Related topics .. _Jupyter Notebook: https://jupyter.org/ -.. _kubectl overview: https://kubernetes.io/docs/reference/kubectl/overview/ - -.. _launcher.py: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow - -.. _terms of use: https://clearlinux.org/stacks/deep-learning/terms-of-use - .. _Release notes on Github\*: https://github.com/clearlinux/dockerfiles/blob/master/stacks/dlrs/releasenote.md - -.. _Intel® quantization tools: https://github.com/IntelAI/tools/blob/master/tensorflow_quantization/README.md#quantization-tools diff --git a/source/tutorials/dlrs/figures/dlrs-fig-1.png b/source/clear-linux/tutorials/dlrs/figures/dlrs-fig-1.png similarity index 100% rename from source/tutorials/dlrs/figures/dlrs-fig-1.png rename to source/clear-linux/tutorials/dlrs/figures/dlrs-fig-1.png diff --git a/source/tutorials/dlrs/figures/dlrs-fig-2.png b/source/clear-linux/tutorials/dlrs/figures/dlrs-fig-2.png similarity index 100% rename from source/tutorials/dlrs/figures/dlrs-fig-2.png rename to source/clear-linux/tutorials/dlrs/figures/dlrs-fig-2.png diff --git a/source/tutorials/dlrs/figures/dlrs-fig-3.png b/source/clear-linux/tutorials/dlrs/figures/dlrs-fig-3.png similarity index 100% rename from source/tutorials/dlrs/figures/dlrs-fig-3.png rename to source/clear-linux/tutorials/dlrs/figures/dlrs-fig-3.png diff --git a/source/tutorials/dlrs/figures/dlrs-fig-4.png b/source/clear-linux/tutorials/dlrs/figures/dlrs-fig-4.png similarity index 100% rename from source/tutorials/dlrs/figures/dlrs-fig-4.png rename to source/clear-linux/tutorials/dlrs/figures/dlrs-fig-4.png diff --git a/source/tutorials/dlrs/figures/dlrs-fig-5.png b/source/clear-linux/tutorials/dlrs/figures/dlrs-fig-5.png similarity index 100% rename from source/tutorials/dlrs/figures/dlrs-fig-5.png rename to source/clear-linux/tutorials/dlrs/figures/dlrs-fig-5.png diff --git a/source/tutorials/docker/docker.rst b/source/clear-linux/tutorials/docker/docker.rst similarity index 100% rename from source/tutorials/docker/docker.rst rename to source/clear-linux/tutorials/docker/docker.rst diff --git a/source/tutorials/flatpak/figures/01-install-libreoffice.gif b/source/clear-linux/tutorials/flatpak/figures/01-install-libreoffice.gif similarity index 100% rename from source/tutorials/flatpak/figures/01-install-libreoffice.gif rename to source/clear-linux/tutorials/flatpak/figures/01-install-libreoffice.gif diff --git a/source/tutorials/flatpak/figures/02-openlibreoffice.gif b/source/clear-linux/tutorials/flatpak/figures/02-openlibreoffice.gif similarity index 100% rename from source/tutorials/flatpak/figures/02-openlibreoffice.gif rename to source/clear-linux/tutorials/flatpak/figures/02-openlibreoffice.gif diff --git a/source/tutorials/flatpak/flatpak.rst b/source/clear-linux/tutorials/flatpak/flatpak.rst similarity index 100% rename from source/tutorials/flatpak/flatpak.rst rename to source/clear-linux/tutorials/flatpak/flatpak.rst diff --git a/source/tutorials/fmv.rst b/source/clear-linux/tutorials/fmv.rst similarity index 100% rename from source/tutorials/fmv.rst rename to source/clear-linux/tutorials/fmv.rst diff --git a/source/tutorials/greengrass.rst b/source/clear-linux/tutorials/greengrass.rst similarity index 100% rename from source/tutorials/greengrass.rst rename to source/clear-linux/tutorials/greengrass.rst diff --git a/source/tutorials/hadoop.rst b/source/clear-linux/tutorials/hadoop.rst similarity index 100% rename from source/tutorials/hadoop.rst rename to source/clear-linux/tutorials/hadoop.rst diff --git a/source/tutorials/kata.rst b/source/clear-linux/tutorials/kata.rst similarity index 99% rename from source/tutorials/kata.rst rename to source/clear-linux/tutorials/kata.rst index cecd365e..1fb1fd4f 100644 --- a/source/tutorials/kata.rst +++ b/source/clear-linux/tutorials/kata.rst @@ -110,7 +110,7 @@ Troubleshooting .. code-block:: bash - sudo swupd info + sudo swupd verify .. _Kata Containers: https://katacontainers.io/ diff --git a/source/tutorials/kata_migration.rst b/source/clear-linux/tutorials/kata_migration.rst similarity index 100% rename from source/tutorials/kata_migration.rst rename to source/clear-linux/tutorials/kata_migration.rst diff --git a/source/tutorials/kubernetes/kubernetes-bp.rst b/source/clear-linux/tutorials/kubernetes/kubernetes-bp.rst similarity index 100% rename from source/tutorials/kubernetes/kubernetes-bp.rst rename to source/clear-linux/tutorials/kubernetes/kubernetes-bp.rst diff --git a/source/tutorials/kubernetes/kubernetes.rst b/source/clear-linux/tutorials/kubernetes/kubernetes.rst similarity index 92% rename from source/tutorials/kubernetes/kubernetes.rst rename to source/clear-linux/tutorials/kubernetes/kubernetes.rst index 0dedc22f..153d7aa8 100644 --- a/source/tutorials/kubernetes/kubernetes.rst +++ b/source/clear-linux/tutorials/kubernetes/kubernetes.rst @@ -150,30 +150,12 @@ Configure and run CRI-O + kata-runtime sudo systemctl daemon-reload sudo systemctl restart crio -#. Initialize the master control plane with the command below and follow the displayed instructions to set up `kubectl`: +#. Initialize the master control plane with the command: .. code-block:: bash sudo kubeadm init --cri-socket=/run/crio/crio.sock -#. Register kata-runtime as a RuntimeClass handler: - - .. code-block:: bash - - cat << EOF | kubectl apply -f - - kind: RuntimeClass - apiVersion: node.k8s.io/v1beta1 - metadata: - name: native - handler: runc - --- - kind: RuntimeClass - apiVersion: node.k8s.io/v1beta1 - metadata: - name: kata-containers - handler: kata - EOF - Install pod network add-on ************************** @@ -181,6 +163,32 @@ You must choose and install a `pod network add-on`_ to allow your pods to communicate. Check whether or not your add-on requires special flags when you initialize the master control plane. +The CRI-O default plugin_dir is :file:`/opt/cni/bin`. This must be a +writable directory because third-party networking add-ons will install +themselves there. + +.. note:: + + CNI plugins provided by |CL| are installed as part of *cloud-native-basic* + in :file:`/usr/libexec/cni/` and are currently *not* found by CRI-O by + default. These separate directories are required because `swupd` controls + the content of :file:`/usr` and leaves :file:`/opt` unchanged. + +When using third-party network add-ons that rely on those plugins, such as +Weave or Flannel do, make them available by creating symlinks: + +.. code-block:: bash + + sudo mkdir -p /opt/cni/bin + +.. code-block:: bash + + for i in /usr/libexec/cni/*; do sudo ln -sf $i /opt/cni/bin; done + +**Notes about Weave Net add-on** + +The Weave Net add-on works by default when the above configuration is done. + **Notes about flannel add-on** If you choose the `flannel` add-on, then you must add the following to the @@ -190,7 +198,7 @@ If you choose the `flannel` add-on, then you must add the following to the --pod-network-cidr 10.244.0.0/16 -Furthermore, if you are using CRI-O and `flannel` and you want to use Kata Containers, +If you are using CRI-O and `flannel` and you want to use Kata Containers, edit the :file:`/etc/crio/crio.conf` file to add: .. code-block:: bash diff --git a/source/tutorials/machine-learning/figures/machine-learning-1.png b/source/clear-linux/tutorials/machine-learning/figures/machine-learning-1.png similarity index 100% rename from source/tutorials/machine-learning/figures/machine-learning-1.png rename to source/clear-linux/tutorials/machine-learning/figures/machine-learning-1.png diff --git a/source/tutorials/machine-learning/figures/machine-learning-2.png b/source/clear-linux/tutorials/machine-learning/figures/machine-learning-2.png similarity index 100% rename from source/tutorials/machine-learning/figures/machine-learning-2.png rename to source/clear-linux/tutorials/machine-learning/figures/machine-learning-2.png diff --git a/source/tutorials/machine-learning/figures/machine-learning-3.png b/source/clear-linux/tutorials/machine-learning/figures/machine-learning-3.png similarity index 100% rename from source/tutorials/machine-learning/figures/machine-learning-3.png rename to source/clear-linux/tutorials/machine-learning/figures/machine-learning-3.png diff --git a/source/tutorials/machine-learning/figures/machine-learning-4.png b/source/clear-linux/tutorials/machine-learning/figures/machine-learning-4.png similarity index 100% rename from source/tutorials/machine-learning/figures/machine-learning-4.png rename to source/clear-linux/tutorials/machine-learning/figures/machine-learning-4.png diff --git a/source/tutorials/machine-learning/figures/machine-learning-5.png b/source/clear-linux/tutorials/machine-learning/figures/machine-learning-5.png similarity index 100% rename from source/tutorials/machine-learning/figures/machine-learning-5.png rename to source/clear-linux/tutorials/machine-learning/figures/machine-learning-5.png diff --git a/source/tutorials/machine-learning/figures/machine-learning-6.png b/source/clear-linux/tutorials/machine-learning/figures/machine-learning-6.png similarity index 100% rename from source/tutorials/machine-learning/figures/machine-learning-6.png rename to source/clear-linux/tutorials/machine-learning/figures/machine-learning-6.png diff --git a/source/tutorials/machine-learning/figures/machine-learning-7.png b/source/clear-linux/tutorials/machine-learning/figures/machine-learning-7.png similarity index 100% rename from source/tutorials/machine-learning/figures/machine-learning-7.png rename to source/clear-linux/tutorials/machine-learning/figures/machine-learning-7.png diff --git a/source/tutorials/machine-learning/figures/machine-learning-8.png b/source/clear-linux/tutorials/machine-learning/figures/machine-learning-8.png similarity index 100% rename from source/tutorials/machine-learning/figures/machine-learning-8.png rename to source/clear-linux/tutorials/machine-learning/figures/machine-learning-8.png diff --git a/source/tutorials/machine-learning/figures/run-cell-button.png b/source/clear-linux/tutorials/machine-learning/figures/run-cell-button.png similarity index 100% rename from source/tutorials/machine-learning/figures/run-cell-button.png rename to source/clear-linux/tutorials/machine-learning/figures/run-cell-button.png diff --git a/source/tutorials/machine-learning/machine-learning.rst b/source/clear-linux/tutorials/machine-learning/machine-learning.rst similarity index 100% rename from source/tutorials/machine-learning/machine-learning.rst rename to source/clear-linux/tutorials/machine-learning/machine-learning.rst diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-01.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-01.png new file mode 100644 index 00000000..8f7b669e Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-01.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-02.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-02.png new file mode 100644 index 00000000..f6dbc17b Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-02.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-03.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-03.png new file mode 100644 index 00000000..b8fbe4c5 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-03.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-04.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-04.png new file mode 100644 index 00000000..93753eb6 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-04.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-05.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-05.png new file mode 100644 index 00000000..97377cad Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-05.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-06.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-06.png new file mode 100644 index 00000000..c8a9984e Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-06.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-07.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-07.png new file mode 100644 index 00000000..32af7048 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-07.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-08.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-08.png new file mode 100644 index 00000000..e11eeacf Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-08.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-09.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-09.png new file mode 100644 index 00000000..eaf180db Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-09.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-10.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-10.png new file mode 100644 index 00000000..f269aa75 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-10.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-11.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-11.png new file mode 100644 index 00000000..9813e5b8 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-11.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-12.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-12.png new file mode 100644 index 00000000..f7db1648 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-12.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-1.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-1.png new file mode 100644 index 00000000..818c0837 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-1.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-2.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-2.png new file mode 100644 index 00000000..934bcfb6 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-2.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-3.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-3.png new file mode 100644 index 00000000..5ec22be6 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-3.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-4.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-4.png new file mode 100644 index 00000000..880a3708 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-4.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-5.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-5.png new file mode 100644 index 00000000..5301b7f0 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-mint-5.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-restore-bl-1.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-restore-bl-1.png new file mode 100644 index 00000000..6e48fcc7 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-restore-bl-1.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-restore-bl-2.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-restore-bl-2.png new file mode 100644 index 00000000..f8c0952d Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-restore-bl-2.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-1.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-1.png new file mode 100644 index 00000000..4bbe5943 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-1.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-2.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-2.png new file mode 100644 index 00000000..a75b4329 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-2.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-3.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-3.png new file mode 100644 index 00000000..f8f0b4d0 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-3.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-4.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-4.png new file mode 100644 index 00000000..082599e4 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-4.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-5.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-5.png new file mode 100644 index 00000000..0970a7e3 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-5.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-6.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-6.png new file mode 100644 index 00000000..0e322d11 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-6.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-7.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-7.png new file mode 100644 index 00000000..2c8aca82 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-rhel-7.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-sles-1.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-sles-1.png new file mode 100644 index 00000000..ab0d6798 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-sles-1.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-sles-2.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-sles-2.png new file mode 100644 index 00000000..1d221335 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-sles-2.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-sles-3.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-sles-3.png new file mode 100644 index 00000000..abf0bf2a Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-sles-3.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-sles-4.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-sles-4.png new file mode 100644 index 00000000..3d08938c Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-sles-4.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-1.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-1.png new file mode 100644 index 00000000..0ed0ff2f Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-1.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-2.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-2.png new file mode 100644 index 00000000..663818ee Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-2.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-3.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-3.png new file mode 100644 index 00000000..f4ef4fcd Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-3.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-4.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-4.png new file mode 100644 index 00000000..bf368d41 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-4.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-5.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-5.png new file mode 100644 index 00000000..891a8560 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-ubuntu-5.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-win-1.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-win-1.png new file mode 100644 index 00000000..fe6a006c Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-win-1.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-win-2.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-win-2.png new file mode 100644 index 00000000..424c8fc0 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-win-2.png differ diff --git a/source/clear-linux/tutorials/multi-boot/figures/multi-boot-win-3.png b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-win-3.png new file mode 100644 index 00000000..2b902316 Binary files /dev/null and b/source/clear-linux/tutorials/multi-boot/figures/multi-boot-win-3.png differ diff --git a/source/clear-linux/tutorials/multi-boot/multi-boot-mint.rst b/source/clear-linux/tutorials/multi-boot/multi-boot-mint.rst new file mode 100644 index 00000000..3835815e --- /dev/null +++ b/source/clear-linux/tutorials/multi-boot/multi-boot-mint.rst @@ -0,0 +1,140 @@ +.. _multi-boot-mint: + +Install Linux Mint\* 18.1 *Serena* MATE +####################################### + +This guide describes Linux Mint-specific details of the :ref:`multi-boot` +tutorial. + +#. Start the Mint installer and follow the prompts. + +#. At the :guilabel:`Installation type` screen, choose + :guilabel:`Something else`. See Figure 1. + + .. figure:: figures/multi-boot-mint-1.png + + Figure 1: Mint: Installation type. + +#. Create a new root partition. + + #. Under the :guilabel:`Device` column, select :guilabel:`free space`. See + Figure 2. + + .. figure:: figures/multi-boot-mint-2.png + + Figure 2: Mint: Add partition. + + #. Click the :guilabel:`+` button. + + #. In the :guilabel:`Size` field, enter a value for the new partition + size. For this example, we used *40000 MB*, as shown in Figure 3. + + .. figure:: figures/multi-boot-mint-3.png + + Figure 3: Mint: Configure new partition settings. + + #. Set :guilabel:`Use as` to :guilabel:`Ext4 journaling file system`. + + #. Set the :guilabel:`Mount point` to :guilabel:`/`. + + #. Click :guilabel:`OK`. + +#. Share the swap partition created by |CL|. + + #. Under the :guilabel:`Device` column, select :file:`/dev/sda2`. + + #. Click :guilabel:`Change`. + + #. Confirm :guilabel:`Use as` is set to :guilabel:`Swap area`. See Figure 4. + + .. figure:: figures/multi-boot-mint-4.png + + Figure 4: Mint: Set swap partition. + +#. Follow the remaining prompts to complete the Mint installation. + +#. At this point, you cannot boot |CL| because `Grub` + is the default boot loader. Follow these steps to make the |CL| + Systemd-Boot the default boot loader and add Mint as a boot option. + + #. Boot into Mint. + + #. Log in. + + #. Locate the Mint :file:`grub.cfg` file in the :file:`/boot/grub/` + directory and look for the :guilabel:`menuentry` section. In Figure 5, the + highlighted lines identify the kernel, the :file:`initrd` files, the root + partition UUID, and the additional parameters used. Use this information + to create a new Systemd-Boot entry for Mint. + + .. figure:: figures/multi-boot-mint-5.png + + Figure 5: Mint: grub.cfg file. + + #. Copy the kernel and :file:`initrd` file to the EFI partition. + + .. code-block:: bash + + sudo cp /boot/vmlinuz-4.4.0-53-generic /boot/efi + + sudo cp /boot/initrd.img-4.4.0-53-generic /boot/efi + + #. Create a boot entry for Mint. At a minimum, the file must contain + these settings: + + +---------+------------------------------------+ + | Setting | Description | + +=========+====================================+ + | title | Text to show in the boot menu | + +---------+------------------------------------+ + | linux | Linux kernel image | + +---------+------------------------------------+ + | initrd | initramfs image | + +---------+------------------------------------+ + | options | Options to pass to the EFI program | + | | or kernel boot parameters | + +---------+------------------------------------+ + + See the `systemd boot loader documentation`_ for additional + details. + + The *options* parameters must specify the root partition UUID and + any additional parameters that Mint requires. + + .. note:: The root partition UUID used below is unique to this example. + + .. code-block:: bash + + sudoedit /boot/efi/loader/entries/mint.conf + + Add the following lines to the :file:`mint.conf` file: + + .. code-block:: console + + title Mint 18.1 Serena MATE + + linux /vmlinuz-4.4.0-53-generic + + initrd /initrd.img-4.4.0-53-generic + + options root=UUID=af4901e1-6238-470a-8c14-bc0f0f7715ec ro + +#. Re-install Systemd-Boot to make it the default boot loader. + + .. code-block:: bash + + sudo bootctl install --path /boot/efi + + .. note:: + If an older version of Mint does not have the `bootctl` command, + skip this step and see :ref:`multi-boot-restore-bl` to restore + Systemd-Boot. + +#. Reboot. + +If you want to install other :abbr:`OSes (operating systems)`, refer to +:ref:`multi-boot` for details. + + +.. _systemd boot loader documentation: + https://wiki.archlinux.org/index.php/Systemd-boot diff --git a/source/clear-linux/tutorials/multi-boot/multi-boot-restore-bl.rst b/source/clear-linux/tutorials/multi-boot/multi-boot-restore-bl.rst new file mode 100644 index 00000000..2b71ffd5 --- /dev/null +++ b/source/clear-linux/tutorials/multi-boot/multi-boot-restore-bl.rst @@ -0,0 +1,58 @@ +.. _multi-boot-restore-bl: + +Restore the |CL-ATTR| boot loader +################################### + +This guide is part of the :ref:`multi-boot` tutorial. If you install a new +:abbr:`OS (operating system)` or upgrade an existing OS, the default boot +loader may change from |CL| Systemd-Boot. This guide describes how to restore +Systemd-Boot. + +#. Boot the |CL| installer from a USB thumb drive. See :ref:`bootable-usb`. + +#. At the introduction screen, press :kbd:`Control+Alt+F2` to bring up the + |CL| console. See Figure 1. + + .. figure:: figures/multi-boot-restore-bl-1.png + + Figure 1: |CL|: Console. + +#. Log in as *root*. + + .. note:: + When you log in for the first time as *root* through the console, you must + set a new password. + +#. Find the location of the |CL| EFI partition. In this example, it is + :file:`/dev/sda3`. See Figure 2. + + .. code-block:: bash + + fdisk -l + + .. figure:: figures/multi-boot-restore-bl-2.png + + Figure 2: |CL|: fdisk -l command. + +#. Mount the EFI partition. + + .. code-block:: bash + + mount /dev/sda3 /mnt + +#. Re-install Systemd-Boot to make it the default boot loader. + + .. code-block:: bash + + bootctl install --path /mnt + +#. Unmount the EFI partition. + + .. code-block:: bash + + umount /mnt + +#. Reboot. + +If you want to install other :abbr:`OSes (operating systems)`, refer to +:ref:`multi-boot` for details. diff --git a/source/clear-linux/tutorials/multi-boot/multi-boot-rhel.rst b/source/clear-linux/tutorials/multi-boot/multi-boot-rhel.rst new file mode 100644 index 00000000..7a836863 --- /dev/null +++ b/source/clear-linux/tutorials/multi-boot/multi-boot-rhel.rst @@ -0,0 +1,165 @@ +.. _multi-boot-rhel: + +Install Red Hat\* Enterprise Linux 7.4 Beta +########################################### + +This guide describes Red Hat-specific details of the :ref:`multi-boot` +tutorial. + +#. Start the Red Hat installer and follow the prompts. + +#. At the :guilabel:`INSTALLATION SUMMARY` screen, choose + :guilabel:`INSTALLATION DESTINATION`. See Figure 1. + + .. figure:: figures/multi-boot-rhel-1.png + + Figure 1: Red Hat: Installation summary. + +#. In the :guilabel:`Device Selection` section, select a drive on which to + install the OS. See Figure 2. + + .. figure:: figures/multi-boot-rhel-2.png + + Figure 2: Red Hat: Installation destination. + +#. Under the :guilabel:`Other Storage Options` section, choose + :guilabel:`I will configure partitioning`. See Figure 2. + +#. Click :guilabel:`Done`. + +#. Under the :menuselection:`New Red Hat Enterprise Linux 7.4 Installation + --> New mount points will use the following partitioning scheme` section, + select :menuselection:`Standard Partition` from the drop down list. See + Figure 3. + + .. figure:: figures/multi-boot-rhel-3.png + + Figure 3: Red Hat: New partition scheme. + +#. Create a new root partition. + + #. Click the :menuselection:`+` button on the lower left corner. + + #. Enter `/` and the new partition size. For this example, we specified 45 + GB. See Figure 4. + + .. figure:: figures/multi-boot-rhel-4.png + + Figure 4: Red Hat: Create new root partition. + + #. Click :guilabel:`Add mount point`. + +#. Share the swap partition that was created by |CL|. See Figure 5. + + #. Expand :guilabel:`Unknown`. + + #. Select :guilabel:`swap / sda2`. + + #. Select :guilabel:`Reformat`. + + #. Click :guilabel:`Update Settings`. + + .. figure:: figures/multi-boot-rhel-5.png + + Figure 5: Red Hat: Configure swap partition. + +#. Share the EFI partition that was created by |CL|. See Figure 6. + + #. Expand :guilabel:`Unknown.` + + #. Select :guilabel:`EFI System Partition / sda3`. + + #. Under :guilabel:`Mount Point`, enter `/boot/efi`. + + #. Click :guilabel:`Update Settings`. + + .. figure:: figures/multi-boot-rhel-6.png + + Figure 6: Red Hat: Configure EFI partition. + +#. Click :guilabel:`Done`. + +#. Follow the remaining prompts to complete the Red Hat installation. + +#. At this point, you cannot boot |CL| because `Grub` is the default boot + loader. Follow these steps to make the |CL| Systemd-Boot the default boot + loader and add Red Hat as a boot option: + + #. Boot into Red Hat. + + #. Log in. + + #. Locate the Red Hat :file:`grub.cfg` file in the + :file:`/boot/efi/EFI/redhat/` directory and look for the primary Red + Hat :guilabel:`menuentry` section. In Figure 7, the highlighted lines + identify the kernel and `initrd` filenames, root partition UUID, and + additional parameters used. Use this information to create a + new Systemd-Boot entry for Red Hat. + + .. figure:: figures/multi-boot-rhel-7.png + + Figure 7: Red Hat: grub.cfg file. + + #. Copy the kernel and :file:`initrd` file to the EFI partition. + + .. code-block:: bash + + sudo cp /boot/vmlinuz-3.10.0-663.el7.x86_64 /boot/efi + + sudo cp /boot/initramfs-3.10.0-663.el7.x86_64.img /boot/efi + + #. Create a boot entry for Red Hat. At a minimum, the file must contain + these settings: + + +---------+---------------------------------------------------+ + | Setting | Description | + +=========+===================================================+ + | title | Text to show in the boot menu | + +---------+---------------------------------------------------+ + | linux | Linux kernel image | + +---------+---------------------------------------------------+ + | initrd | initramfs image | + +---------+---------------------------------------------------+ + | options | Options to pass to the EFI program or kernel boot | + | | parameters | + +---------+---------------------------------------------------+ + + See the `systemd boot loader documentation`_ for additional + details. + + The *options* parameters must specify the root partition UUID and any + additional parameters that Red Hat requires. + + .. note:: The root partition UUID used below is unique to this example. + + .. code-block:: bash + + sudoedit /boot/efi/loader/entries/redhat.conf + + Add the following lines to the :file:`redhat.conf` file: + + .. code-block:: console + + title Red Hat Enterprise Linux 7.4 Beta + + linux /vmlinuz-3.10.0-663.el7.x86_64 + + initrd /initramfs-3.10.0-663.el7.x86_64.img + + options root=UUID=30655c74-6cc1-4c55-8fcc-ac8bddcea4db ro + crashkernel=auto rhgb LANG=en_US.UTF-8 + + #. Re-install Systemd-Boot to make it the default boot loader. + + .. note:: + This version of Red Hat does not support `bootctl install`. Perform + the steps in :ref:`multi-boot-restore-bl` instead. + + #. Reboot. + +If you want to install other :abbr:`OSes (operating systems)`, refer to +:ref:`multi-boot` for details. + + +.. _systemd boot loader documentation: + https://wiki.archlinux.org/index.php/Systemd-boot diff --git a/source/clear-linux/tutorials/multi-boot/multi-boot-sles.rst b/source/clear-linux/tutorials/multi-boot/multi-boot-sles.rst new file mode 100644 index 00000000..43e53fe4 --- /dev/null +++ b/source/clear-linux/tutorials/multi-boot/multi-boot-sles.rst @@ -0,0 +1,124 @@ +.. _multi-boot-sles: + +Install SUSE\* Linux Enterprise Server 12 SP2 +############################################# + +This guide describes SUSE-specific details of the :ref:`multi-boot` +tutorial. + +#. Start the SUSE installer and follow the prompts. + +#. At the :guilabel:`Suggested Partitioning` screen, choose + :guilabel:`Expert Partitioner`. See Figure 1. + + .. figure:: figures/multi-boot-sles-1.png + + Figure 1: SUSE: Suggested partitioning. + + **Optional:** Under :guilabel:`Available Storage on Linux` section, + right-click the SUSE :file:`/home` partition and delete it. In this example, it is :file:`/dev/sda8`. See Figure 2. + + .. figure:: figures/multi-boot-sles-2.png + + Figure 2: SUSE: Delete /home partition. + +#. Under :guilabel:`Available Storage on Linux` section, right-click the SUSE + root partition and resize it. In this example, :file:`/dev/sda7` is + resized to 45 GB. See Figure 3. + + .. figure:: figures/multi-boot-sles-3.png + + Figure 3: SUSE: Resize root partition. + +#. Click :guilabel:`Accept`. + +#. Follow the remaining prompts to complete the SUSE installation. + +#. At this point, you cannot boot |CL| because `Grub` + is the default boot loader. Follow these steps to make the |CL| + Systemd-Boot the default boot loader and add SUSE as a boot option: + + #. Boot into SUSE. + + #. Log in. + + #. Locate the SUSE :file:`grub.cfg` file in the :file:`/boot/grub2/` directory + and look for the primary SUSE :guilabel:`menuentry` section. In Figure 4, the + highlighted lines identify the kernel, the :file:`initrd` filenames, the + root partition UUID, and the additional parameters used. Use this information + to create a new Systemd-Boot entry for SUSE. + + .. figure:: figures/multi-boot-sles-4.png + + Figure 4: SUSE: grub.cfg file. + + #. Copy the kernel and the :file:`initrd` file to the EFI partition. + + .. code-block:: bash + + sudo cp /boot/vmlinuz-4.4.21-69-default /boot/efi + + sudo cp /boot/initrd-4.4.21-69-default /boot/efi + + #. Create a boot entry for SUSE. At a minimum, the file must contain + these settings: + + +---------+---------------------------------------+ + | Setting | Description | + +=========+=======================================+ + | title | Text to show in the boot menu | + +---------+---------------------------------------+ + | linux | Linux kernel image | + +---------+---------------------------------------+ + | initrd | initramfs image | + +---------+---------------------------------------+ + | options | Options to pass to the EFI program or | + | | kernel boot parameters | + +---------+---------------------------------------+ + + See the `systemd boot loader documentation`_ for additional + details. + + The *options* parameter must specify the root partition UUID and + any additional parameters SUSE requires. + + .. note:: The root partition UUID used below is unique to this example. + + .. code-block:: bash + + sudoedit /boot/efi/loader/entries/suse.conf + + Add the following lines to the :file:`suse.conf` file: + + .. code-block:: console + + title SUSE Linux Enterprise 12 SP2 + + linux /vmlinuz-4.4.21-69-default + + initrd /initrd-4.4.21-69-default + + options root=UUID=b9e25e98-a644-4ac3-b955-ae32800ee350 ro + resume=/dev/disk/by-uuid/6a50c032-1c1e-4b4a-b799-ca365bb10dc7 + splash=silent showopts crashkernel=109M,high + crashkernel=72M,low + +#. Re-install Systemd-Boot to make it the default boot loader. + + .. code-block:: bash + + sudo bootctl install --path /boot/efi + + .. note:: + If an older version of SUSE does not have the `bootctl` command, + skip this step and see :ref:`multi-boot-restore-bl` to restore + Systemd-Boot. + +#. Reboot. + +If you want to install other :abbr:`OSes (operating systems)`, refer to +:ref:`multi-boot` for details. + + +.. _systemd boot loader documentation: + https://wiki.archlinux.org/index.php/Systemd-boot diff --git a/source/clear-linux/tutorials/multi-boot/multi-boot-ubuntu.rst b/source/clear-linux/tutorials/multi-boot/multi-boot-ubuntu.rst new file mode 100644 index 00000000..dc42a85e --- /dev/null +++ b/source/clear-linux/tutorials/multi-boot/multi-boot-ubuntu.rst @@ -0,0 +1,142 @@ +.. _multi-boot-ubuntu: + +Install Ubuntu\* 16.04 LTS Desktop +################################## + +This guide describes Ubuntu-specific details of the :ref:`multi-boot` +tutorial. + +#. Start the Ubuntu installer and follow the prompts. + +#. At the :guilabel:`Installation type` screen, choose + :guilabel:`Something else`. See Figure 1. + + .. figure:: figures/multi-boot-ubuntu-1.png + + Figure 1: Ubuntu: Installation type. + +#. Create a new root partition. + + #. Under the :guilabel:`Device` column, select :guilabel:`free space`. See + Figure 2. + + .. figure:: figures/multi-boot-ubuntu-2.png + + Figure 2: Ubuntu: Add partition. + + #. Click the :guilabel:`+` button on the lower left corner. + + #. Enter the new partition size. For this example, we used *40000 MB*, as + shown in Figure 3. + + .. figure:: figures/multi-boot-ubuntu-3.png + + Figure 3: Ubuntu: Configure new root partition. + + #. Set :guilabel:`Use as` to :guilabel:`Ext4 journaling file system`. + + #. Set the :guilabel:`Mount point` to `/`. + + #. Click :guilabel:`OK`. + + #. Under the :guilabel:`Format?` column, select the new partition to be + formatted, in this example :file:`/dev/sda8`. + +#. Share the swap partition that was created by |CL|. + + #. Under the :guilabel:`Device` column, select :file:`/dev/sda2`. + + #. Click :guilabel:`Change`. + + #. Confirm :guilabel:`Use as` is set to :guilabel:`swap area`. See Figure 4. + + .. figure:: figures/multi-boot-ubuntu-4.png + + Figure 4: Ubuntu: Set swap partition. + +#. Follow the remaining prompts to complete the Ubuntu installation. + +#. At this point, you cannot boot |CL| because `Grub` + is the default boot loader. Follow these steps to make the |CL| + Systemd-Boot the default boot loader and add Ubuntu as a boot option: + + #. Boot into Ubuntu. + + #. Log in. + + #. Locate the Ubuntu :file:`grub.cfg` file in the :file:`/boot/grub/` + directory and look for the :guilabel:`menuentry` section. In Figure 5, the + highlighted lines identify the kernel, the :file:`initrd` files, the + root partition UUID, and the additional parameters used. Use this + information to create a new Systemd-Boot entry for Ubuntu. + + .. figure:: figures/multi-boot-ubuntu-5.png + + Figure 5: Ubuntu: grub.cfg file. + + #. Copy the kernel and the :file:`initrd` file to the EFI partition. + + .. code-block:: bash + + sudo cp /boot/vmlinuz-4.8.0-36-generic.efi.signed /boot/efi + + sudo cp /boot/initrd.img-4.8.0-36-generic /boot/efi + + #. Create a boot entry for Ubuntu. At a minimum, the file must contain + these settings: + + +---------+------------------------------------+ + | Setting | Description | + +=========+====================================+ + | title | Text to show in the boot menu | + +---------+------------------------------------+ + | linux | Linux kernel image | + +---------+------------------------------------+ + | initrd | initramfs image | + +---------+------------------------------------+ + | options | Options to pass to the EFI program | + | | or kernel boot parameters | + +---------+------------------------------------+ + + See the `systemd boot loader documentation`_ for additional + details. + + The *options* parameters must specify the root partition UUID and + any additional parameters that Ubuntu requires. + + .. note:: The root partition UUID used below is unique to this example. + + .. code-block:: bash + + sudoedit /boot/efi/loader/entries/ubuntu.conf + + Add the following lines to the :file:`ubuntu.conf` file: + + .. code-block:: console + + title Ubuntu 16.04 LTS Desktop + + linux /vmlinuz-4.8.0-36-generic.efi.signed + + initrd /initrd.img-4.8.0-36-generic + + options root=UUID=17f0aa66-3467-4f99-b92c-8b2cea1045aa ro + +#. Re-install Systemd-Boot to make it the default boot loader. + + .. code-block:: bash + + sudo bootctl install --path /boot/efi + + .. note:: + If an older version of Ubuntu does not have the `bootctl` command, + skip this step and see :ref:`multi-boot-restore-bl` to restore + Systemd-Boot. + +#. Reboot. + +If you want to install other :abbr:`OSes (operating systems)`, refer to +:ref:`multi-boot` for details. + +.. _systemd boot loader documentation: + https://wiki.archlinux.org/index.php/Systemd-boot diff --git a/source/clear-linux/tutorials/multi-boot/multi-boot-win.rst b/source/clear-linux/tutorials/multi-boot/multi-boot-win.rst new file mode 100644 index 00000000..52900c53 --- /dev/null +++ b/source/clear-linux/tutorials/multi-boot/multi-boot-win.rst @@ -0,0 +1,46 @@ +.. _multi-boot-win: + +Install Windows\* Server 2016 +############################# + +This guide describes Windows-specific details of the :ref:`multi-boot` +tutorial. + +#. Start the Windows installer and follow the prompts. + +#. At the :guilabel:`Type of installation` screen, choose + :guilabel:`Custom: Install Windows only (advanced)`. See Figure 1. + + .. figure:: figures/multi-boot-win-1.png + + Figure 1: Windows: Choose installation type. + +#. Select :guilabel:`Unallocated Space` and create a new partition of the + desired size. In this example, we specified 50000 MB. See Figure 2. + + .. figure:: figures/multi-boot-win-2.png + + Figure 2: Windows: Create new partition. + + .. note:: + Windows creates its own 100 MB EFI partition if none exists. + In this example, Windows sees the EFI partition created during the + |CL| installation and does not create one. + +#. Select the newly created partition and follow the remaining prompts + to complete the Windows installation. See Figure 3. + + .. figure:: figures/multi-boot-win-3.png + + Figure 3: Windows: Install on newly created partition. + +#. Finish the Windows out-of-box-experience process. + +#. At this point, you cannot boot |CL| because Windows is the + default boot loader. See :ref:`multi-boot-restore-bl` to restore + Systemd-Boot and add Windows to its boot menu. + + +If you want to install other :abbr:`OSes (operating systems)`, refer to +:ref:`multi-boot` for details. + diff --git a/source/clear-linux/tutorials/multi-boot/multi-boot.rst b/source/clear-linux/tutorials/multi-boot/multi-boot.rst new file mode 100644 index 00000000..8a8c8f80 --- /dev/null +++ b/source/clear-linux/tutorials/multi-boot/multi-boot.rst @@ -0,0 +1,266 @@ +.. _multi-boot: + +Multi-boot |CL-ATTR| with other operating systems +################################################# + +|CL-ATTR| uses the Systemd-Boot boot loader, which does not support multi- +booting without manual manipulation. This tutorial shows how to configure the +|CL| boot loader to work with other :abbr:`OSes (operating systems)`. + +Process overview +**************** + +The process to install other operating systems for a multi-booting computer is +described below. Install |CL| first, then install other operating systems in +any order. + +#. Install |CL| first with a EFI partition large enough to store the kernels + of other operating systems and their initrds, in the case of Linux + distributions. + +#. Install the next operating system without creating its own EFI + partition. + +#. Boot into the newly installed operating system. + +#. For Linux distributions, copy its kernel and `initrd` to the |CL| EFI + partition. This step is not needed for Windows\*. + +#. Add an entry for the newly installed operating system in the + Systemd-Boot menu. + +#. Make Systemd-Boot the default boot loader. + +#. Repeat the previous steps to install each additional operating system. + +If you update any installed operating systems, be aware that: + +* The default boot loader may change from |CL| Systemd-Boot. Perform the + steps in :ref:`multi-boot-restore-bl`. + +* Linux kernels or `initrd` images may change. Keep their corresponding Systemd-Boot + :file:`/boot/efi/loader/entries/*.conf` files up-to-date. + +This process is not guaranteed to work with all Linux distributions and all +their versions. The next section lists the OSes that we tested. + + +Tested operating systems +************************ + +The following operating systems were tested on an Intel® NUC6i7KYK with 32GB +RAM and a 360GB SSD. Table 1 lists the information specific to the +installation of the tested operating systems. + +.. csv-table:: Table 1: OS specific installation information + :header: # , OS, Version, Partition Size [#]_, Swap Size [#]_, EFI Partition Size [#]_, Download Link + + 1,Clear Linux,16140,50 GB,8 GB,1 GB,https://cdn.download.clearlinux.org/releases/16140/clear/ + 2,Windows,Server 2016,50 GB,N/A,Shared with #1,https://www.microsoft.com/en-us/cloud-platform/windows-server + 3,Red Hat\*,Server 7.4 Beta,45 GB,Shared with #1,Shared with #1,https://access.redhat.com/downloads/ + 4,SUSE\*,Server 12 SP2,45 GB,Shared with #1,Shared with #1,https://www.suse.com/download-linux/ + 5,Ubuntu\*,16.04.02 LTS Desktop,40 GB,Shared with #1,Shared with #1,https://www.ubuntu.com/download/desktop + 6,Linux Mint\*,18.1 *Serena* MATE,40 GB,Shared with #1,Shared with #1,https://linuxmint.com/edition.php?id=228 + +Table notes: + +.. [#] Configure the partition size as desired. + + +.. [#] To save disk space, share a single swap partition between + multiple Linux installations. Swap size was determined using these + `recommended swap partition sizes`_. + + +.. [#] The EFI partition holds the kernel and boot information for |CL| and + other operating systems. The partition size is dependent on the number + of operating systems to be installed. In general, allocate about 100 MB + per operating system. For this tutorial, we used 1 GB. + + + +.. _multi-boot-detail-proc: + +Detailed procedures +******************* + +* :ref:`multi-boot-cl` (below) + +.. toctree:: + :maxdepth: 2 + + multi-boot-win + multi-boot-rhel + multi-boot-sles + multi-boot-ubuntu + multi-boot-mint + multi-boot-restore-bl + + +.. _multi-boot-cl: + +Install |CL| +************ + +Navigation tips for text-based installation interfaces: + +* Use the :kbd:`Up Arrow` and :kbd:`Down Arrow` keys to move between + the options on the screen. + +* Use the :kbd:`Space` to select or highlight an option. + +* Press :kbd:`Enter` to activate the selected option and to move ahead. + +Installation details +==================== + +#. Create a bootable USB drive of the |CL| installer using one of the methods + below. + + * :ref:`bootable-usb-linux` + * :ref:`bootable-usb-mac` + * :ref:`bootable-usb-windows` + +#. Start the |CL| installer and follow the prompts. + +#. On the :guilabel:`Choose Installation Type` screen, choose + :guilabel:`Manual (Advanced)`, as shown in Figure 1. + + .. figure:: figures/multi-boot-01.png + + Figure 1: |CL| installer: Choose installation type screen. + +#. On the :guilabel:`Choose partitioning method` screen, choose + :guilabel:`Manually configure mounts and partitions`, as shown in + Figure 2. + + .. figure:: figures/multi-boot-02.png + + Figure 2: |CL|: Choose partitioning method. + +#. Select the drive, in this case :file:`/dev/sda`, and press :kbd:`Enter` to + go into the `cgdisk` partitioning tool. See Figure 3. + + .. figure:: figures/multi-boot-03.png + + Figure 3: |CL|: Choose drive to partition. + +#. Create a new root partition. + + #. Select :guilabel:`New`, as shown in Figure 4. + + .. _multi-boot-04: + + .. figure:: figures/multi-boot-04.png + + Figure 4: |CL|: Create new partition. + + #. Accept the default first sector. + + #. Specify the desired size of the partition. For this example, we + specified *50 GB*. See Figure 5. + + .. figure:: figures/multi-boot-05.png + + Figure 5: |CL|: New partition size. + + #. Set the partition type to :guilabel:`8300 (Linux filesystem)`, as shown + in Figure 6. + + .. figure:: figures/multi-boot-06.png + + Figure 6: |CL|: Set partition type. + + #. Name the partition :file:`CL-root`. This name makes it easier to + identify later. See Figure 7. + + .. figure:: figures/multi-boot-07.png + + Figure 7: |CL|: Name partition. + +#. Create a new swap partition as shown in Figure 8. + + .. figure:: figures/multi-boot-08.png + + Figure 8: |CL|: Create swap partition. + + #. Select the *free space* partition located at the bottom of the column. + + #. Select :guilabel:`New`. See :ref:`Figure 4`. + + #. Accept the default first sector. + + #. Specify the desired size of the swap partition. For this example, we + used 8 GB. See the `recommended swap partition sizes`_ for guidance. + + #. Set the partition type to :guilabel:`8200 (Linux swap)`. + + #. Name the partition :file:`CL-swap`. + +#. Create a new EFI partition as shown in Figure 9. + + .. figure:: figures/multi-boot-09.png + + Figure 9: |CL|: Create EFI partition. + + #. In the :guilabel:`Partition Type` column, select :guilabel:`free space` + located at the bottom of the column. + + #. Select :guilabel:`New`. See :ref:`Figure 4`. + + #. Accept the default first sector. + + #. Specify the desired size of the partition. For this example, we used + 1024 MB. This partition will hold |CL|, the kernels of the other + operating systems, and their boot information. Its size depends on the + number of installed operating systems. In general, allocate about 100 MB + per operating system. For this example, we used 1024 MB. + + #. Set the partition type to :guilabel:`ef00 (EFI partition)`. + + #. Name the partition :file:`CL-EFI`. + +#. Select :guilabel:`Write` to apply the new partition table. + +#. Select :guilabel:`Quit` to exit the `cgdisk` tool. + +#. On the :guilabel:`Set mount points` screen, specify the mount points and + format settings as shown in Figure 10. + + .. figure:: figures/multi-boot-10.png + + Figure 10: |CL|: Set mount points. + +#. On the :guilabel:`User configuration` screen, select + :guilabel:`Create an administrative user`, as shown in Figure 11. + + .. figure:: figures/multi-boot-11.png + + Figure 11: |CL|: User configuration. + +#. Select :guilabel:`Add user to sudoers?`, as shown in Figure 12. + + .. figure:: figures/multi-boot-12.png + + Figure 12: |CL|: Add user as sudoer. + +#. Follow the remaining prompts to complete the installation and finish + the out-of-box-experience for |CL|. + +#. Log in. + +#. Add a Systemd-Boot timeout period or Systemd-Boot will not present the + boot menu of available OSes to choose from and will always boot |CL|. + + .. code-block:: bash + + sudo clr-boot-manager set-timeout 20 + + sudo clr-boot-manager update + +#. Reboot. + +If you want to install other OSes, refer to :ref:`multi-boot-detail-proc`. + +.. _recommended swap partition sizes: + https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/5/html/Deployment_Guide/ch-swapspace.html diff --git a/source/tutorials/nvidia.rst b/source/clear-linux/tutorials/nvidia.rst similarity index 67% rename from source/tutorials/nvidia.rst rename to source/clear-linux/tutorials/nvidia.rst index 94a2fe34..55c84a88 100644 --- a/source/tutorials/nvidia.rst +++ b/source/clear-linux/tutorials/nvidia.rst @@ -1,29 +1,23 @@ .. _nvidia: -Install NVIDIA\* Drivers -######################## +Install NVIDIA Drivers +###################### -NVIDIA manufactures graphics processing units (GPU), also known as +NVIDIA is a manufacture of graphics processing units (GPU), also known as graphics cards. -NVIDIA devices on Linux\* have two popular device driver options: the -opensource drivers from the `nouveau project`_ or the proprietary drivers -published by NVIDIA. The nouveau drivers are built into the |CL-ATTR| -kernel and are loaded automatically at system boot if a compatible card -is detected. +NVIDIA devices on Linux have two popular device driver options: the opensource +drivers from the `nouveau project`_ or the proprietary drivers published by +NVIDIA. The nouveau drivers are built into the |CL-ATTR| kernel and are loaded +automatically at system boot if a compatible card is detected. -These instructions show how to use the proprietary NVIDIA drivers, which +These instructions show how to use the proprietary NVIDIA drivers which require a manual installation. -.. warning:: +.. note:: - Software installed outside of :ref:`swupd ` is not updated - with |CL| updates and must be updated and maintained manually. - - For example, the file :file:`/usr/lib/libGL.so` conflicts between the one - provided by the mesa package in |CL| and the one NVIDIA provides. If a |CL| - update overwrites these files, a reinstallation of the NVIDIA driver might - be required. + Software installed outside of :ref:`swupd ` is not updated with |CL| + updates and must be updated and maintained manually. @@ -36,7 +30,7 @@ Prerequisites ************* * A |CL| system with a desktop installed -* An NVIDIA device installed +* A NVIDIA device installed Install DKMS @@ -53,7 +47,7 @@ Install the appropriate DKMS bundle using the instructions below: compatible between updates with NVIDIA drivers. -.. include:: /guides/kernel/kernel-modules-dkms.rst +.. include:: ../guides/maintenance/kernel-modules-dkms.rst :start-after: kernel-modules-dkms-install-begin: :end-before: kernel-modules-dkms-install-end: @@ -96,7 +90,7 @@ Disable the nouveau Driver ========================== The proprietary NVIDIA driver is incompatible with the nouveau driver and -must be disabled before installation can continue. +needs to be disabled before installation can continue. #. Disable the nouveau driver by creating a blacklist file under :file:`/etc/modprobe.d` and reboot. @@ -109,24 +103,21 @@ must be disabled before installation can continue. #. Reboot the system and log back in. It is normal for the graphical - environment not to start without the NVIDIA driver loaded. + environment to not start with no NVIDIA driver loaded. - -Configure Alternative Software Paths -==================================== +Configure the Dynamic Linker +============================ The NVIDIA installer will be directed to install files under :file:`/opt/nvidia` as much as possible to keep its contents isolated from the -rest of the |CL| system files under :file:`/usr`. The dynamic linker and X -server must be configured to use the content under -:file:`/opt/nvidia`. +rest of the |CL| system files under :file:`/usr`. The dynamic linker will +need to be configured to use the NVIDIA-provided libraries. -#. Configure the dynamic linker to look for and to cache shared libraries under - :file:`/opt/nvidia/lib` and :file:`/opt/nvidia/lib32` in addition to the - default paths. +#. Configure the dynamic linker to look for and cache shared libraries under + :file:`/opt/nvidia/lib` and :file:`/opt/nvidia/lib32`. .. code-block:: bash @@ -134,26 +125,7 @@ server must be configured to use the content under sudo mkdir /etc/ld.so.conf.d printf "/opt/nvidia/lib \n/opt/nvidia/lib32 \n" | sudo tee --append /etc/ld.so.conf.d/nvidia.conf - -#. Reload the dynamic linker run-time bindings and library cache. - - .. code-block:: bash - - sudo ldconfig - -#. Create a Xorg configuration file to search for modules under - :file:`/opt/nvidia` in addition to the default path. - - .. code-block:: bash - - sudo mkdir -p /etc/X11/xorg.conf.d/ - sudo tee /etc/X11/xorg.conf.d/nvidia-files-opt.conf > /dev/null <<'EOF' - Section "Files" - ModulePath "/usr/lib64/xorg/modules" - ModulePath "/opt/nvidia/lib64/xorg/modules" - EndSection - EOF Install the NVIDIA Drivers @@ -180,31 +152,26 @@ Install the NVIDIA Drivers --utility-prefix=/opt/nvidia \ --opengl-prefix=/opt/nvidia \ --compat32-prefix=/opt/nvidia \ - --compat32-libdir=lib32 \ + --compat32-libdir=lib32 \ --x-prefix=/opt/nvidia \ - --x-module-path=/opt/nvidia/lib64/xorg/modules \ - --x-library-path=/opt/nvidia/lib64 \ - --x-sysconfig-path=/etc/X11/xorg.conf.d \ --documentation-prefix=/opt/nvidia \ - --application-profile-path=/etc/nvidia \ --no-precompiled-interface \ --no-nvidia-modprobe \ --no-distro-scripts \ --force-libglx-indirect \ - --glvnd-egl-config-path=/etc/glvnd/egl_vendor.d \ - --egl-external-platform-config-path=/etc/egl/egl_external_platform.d \ --dkms \ --silent + #. The graphical interface may automatically start after the NVIDIA driver is loaded. Return to the working terminal and log back in if necessary. -#. Confirm that the NVIDIA kernel modules are loaded. +#. Validate the nvidia kernel modules are loaded. .. code-block:: bash - lsmod | grep ^nvidia + lsmod | grep ^nvidia #. Run a |CL| system verification to restore files that the NVIDIA installer @@ -212,16 +179,17 @@ Install the NVIDIA Drivers .. code-block:: bash - sudo swupd repair --quick --bundles=lib-opengl + sudo swupd verify --quick --fix --bundles=lib-opengl .. note:: The NVIDIA software places some files under the :file:`/usr` subdirectory which are not managed by |CL| and conflict with the |CL| stateless design. - - Although a limited version of :command:`swupd repair` is run above, - other uses of the :command:`swupd repair` command should be avoided + Although a limited version of :command:`swupd verify --fix` is ran above, + other uses of the :command:`swupd verify --fix` command should be avoided with the proprietary NVIDIA drivers installed. + + Updating the NVIDIA Drivers @@ -234,10 +202,10 @@ Updating the NVIDIA drivers follows the same steps as initial installation, however the desktop environment must first be stopped so that the drivers are not in use. -#. Follow the steps in the `Download the NVIDIA Drivers for Linux`_ section - to get the latest NVIDIA drivers. +#. Follow the steps in `Download the NVIDIA Drivers for Linux`_ section to get + the latest NVIDIA drivers. -#. Temporarily set the default boot target to the *multi-user*, which is +#. Temporarily set the default boot target to the *multi-user* which is a non-graphical runtime. .. code-block:: bash @@ -246,9 +214,9 @@ not in use. #. Reboot the system and log back in. It is normal for the graphical - environment not to start. + environment to not start. -#. Follow the steps in the `Install the NVIDIA Drivers`_ section to update +#. Follow the steps in `Install the NVIDIA Drivers`_ section to update the NVIDIA drivers. This installation will overwrite the previous NVIDIA drivers and files. @@ -262,7 +230,7 @@ not in use. #. Reboot the system and log back in. #. Trigger a flatpak update which will download the runtime corresponding - with the new NVIDIA drivers for the flatpak apps that require it. + with the new NVIDIA drivers for flatpak apps requiring it. .. code-block:: bash @@ -273,21 +241,16 @@ Uninstalling the NVIDIA Drivers ******************************* The NVIDIA drivers and associated software can be uninstalled and nouveau -driver restored with the instructions in this section. +driver restored by: -#. Remove the :file:`modprobe.d` file that prevents nouveau from loading. +#. Remove the previously created file :file:`/etc/modprobe.d` that + prevents nouveau from loading. .. code-block:: bash sudo rm /etc/modprobe.d/disable-nouveau.conf -#. Remove the :file:`xorg.conf.d` file that adds a search path for X modules. - - .. code:: bash - - sudo rm /etc/X11/xorg.conf.d/nvidia-files-opt.conf - #. Run the :command:`sudo /opt/nvidia/bin/nvidia-uninstall` #. Follow the prompts on the screen and reboot the system. diff --git a/source/tutorials/smb/figures/smb-1.png b/source/clear-linux/tutorials/smb/figures/smb-1.png similarity index 100% rename from source/tutorials/smb/figures/smb-1.png rename to source/clear-linux/tutorials/smb/figures/smb-1.png diff --git a/source/tutorials/smb/figures/smb-2.png b/source/clear-linux/tutorials/smb/figures/smb-2.png similarity index 100% rename from source/tutorials/smb/figures/smb-2.png rename to source/clear-linux/tutorials/smb/figures/smb-2.png diff --git a/source/tutorials/smb/figures/smb-desktop-1.png b/source/clear-linux/tutorials/smb/figures/smb-desktop-1.png similarity index 100% rename from source/tutorials/smb/figures/smb-desktop-1.png rename to source/clear-linux/tutorials/smb/figures/smb-desktop-1.png diff --git a/source/tutorials/smb/figures/smb-desktop-2.png b/source/clear-linux/tutorials/smb/figures/smb-desktop-2.png similarity index 100% rename from source/tutorials/smb/figures/smb-desktop-2.png rename to source/clear-linux/tutorials/smb/figures/smb-desktop-2.png diff --git a/source/tutorials/smb/figures/smb-desktop-3.png b/source/clear-linux/tutorials/smb/figures/smb-desktop-3.png similarity index 100% rename from source/tutorials/smb/figures/smb-desktop-3.png rename to source/clear-linux/tutorials/smb/figures/smb-desktop-3.png diff --git a/source/tutorials/smb/smb-desktop.rst b/source/clear-linux/tutorials/smb/smb-desktop.rst similarity index 100% rename from source/tutorials/smb/smb-desktop.rst rename to source/clear-linux/tutorials/smb/smb-desktop.rst diff --git a/source/tutorials/smb/smb.rst b/source/clear-linux/tutorials/smb/smb.rst similarity index 100% rename from source/tutorials/smb/smb.rst rename to source/clear-linux/tutorials/smb/smb.rst diff --git a/source/tutorials/spark.rst b/source/clear-linux/tutorials/spark.rst similarity index 100% rename from source/tutorials/spark.rst rename to source/clear-linux/tutorials/spark.rst diff --git a/source/tutorials/tutorials.rst b/source/clear-linux/tutorials/tutorials.rst similarity index 93% rename from source/tutorials/tutorials.rst rename to source/clear-linux/tutorials/tutorials.rst index 0d5300e9..2e102f10 100644 --- a/source/tutorials/tutorials.rst +++ b/source/clear-linux/tutorials/tutorials.rst @@ -14,6 +14,7 @@ Explore our tutorials to discover what you can do with |CL|! machine-learning/machine-learning docker/docker azure + multi-boot/multi-boot hadoop fmv aws-web/aws-web @@ -27,5 +28,3 @@ Explore our tutorials to discover what you can do with |CL|! yubikey-u2f nvidia dars - redis - tutorial-proxy diff --git a/source/tutorials/wordpress/figures/web-server-install-1.png b/source/clear-linux/tutorials/wordpress/figures/web-server-install-1.png similarity index 100% rename from source/tutorials/wordpress/figures/web-server-install-1.png rename to source/clear-linux/tutorials/wordpress/figures/web-server-install-1.png diff --git a/source/tutorials/wordpress/figures/web-server-install-2.png b/source/clear-linux/tutorials/wordpress/figures/web-server-install-2.png similarity index 100% rename from source/tutorials/wordpress/figures/web-server-install-2.png rename to source/clear-linux/tutorials/wordpress/figures/web-server-install-2.png diff --git a/source/tutorials/wordpress/figures/web-server-install-3.png b/source/clear-linux/tutorials/wordpress/figures/web-server-install-3.png similarity index 100% rename from source/tutorials/wordpress/figures/web-server-install-3.png rename to source/clear-linux/tutorials/wordpress/figures/web-server-install-3.png diff --git a/source/tutorials/wordpress/figures/web-server-install-4.png b/source/clear-linux/tutorials/wordpress/figures/web-server-install-4.png similarity index 100% rename from source/tutorials/wordpress/figures/web-server-install-4.png rename to source/clear-linux/tutorials/wordpress/figures/web-server-install-4.png diff --git a/source/tutorials/wordpress/figures/web-server-install-5.png b/source/clear-linux/tutorials/wordpress/figures/web-server-install-5.png similarity index 100% rename from source/tutorials/wordpress/figures/web-server-install-5.png rename to source/clear-linux/tutorials/wordpress/figures/web-server-install-5.png diff --git a/source/tutorials/wordpress/figures/web-server-install-6.png b/source/clear-linux/tutorials/wordpress/figures/web-server-install-6.png similarity index 100% rename from source/tutorials/wordpress/figures/web-server-install-6.png rename to source/clear-linux/tutorials/wordpress/figures/web-server-install-6.png diff --git a/source/tutorials/wordpress/figures/web-server-install-7.png b/source/clear-linux/tutorials/wordpress/figures/web-server-install-7.png similarity index 100% rename from source/tutorials/wordpress/figures/web-server-install-7.png rename to source/clear-linux/tutorials/wordpress/figures/web-server-install-7.png diff --git a/source/tutorials/wordpress/figures/web-server-install-8.png b/source/clear-linux/tutorials/wordpress/figures/web-server-install-8.png similarity index 100% rename from source/tutorials/wordpress/figures/web-server-install-8.png rename to source/clear-linux/tutorials/wordpress/figures/web-server-install-8.png diff --git a/source/tutorials/wordpress/figures/wp-install-1.png b/source/clear-linux/tutorials/wordpress/figures/wp-install-1.png similarity index 100% rename from source/tutorials/wordpress/figures/wp-install-1.png rename to source/clear-linux/tutorials/wordpress/figures/wp-install-1.png diff --git a/source/tutorials/wordpress/figures/wp-install-2.png b/source/clear-linux/tutorials/wordpress/figures/wp-install-2.png similarity index 100% rename from source/tutorials/wordpress/figures/wp-install-2.png rename to source/clear-linux/tutorials/wordpress/figures/wp-install-2.png diff --git a/source/tutorials/wordpress/figures/wp-install-3.png b/source/clear-linux/tutorials/wordpress/figures/wp-install-3.png similarity index 100% rename from source/tutorials/wordpress/figures/wp-install-3.png rename to source/clear-linux/tutorials/wordpress/figures/wp-install-3.png diff --git a/source/tutorials/wordpress/figures/wp-install-4.png b/source/clear-linux/tutorials/wordpress/figures/wp-install-4.png similarity index 100% rename from source/tutorials/wordpress/figures/wp-install-4.png rename to source/clear-linux/tutorials/wordpress/figures/wp-install-4.png diff --git a/source/tutorials/wordpress/figures/wp-install-5.png b/source/clear-linux/tutorials/wordpress/figures/wp-install-5.png similarity index 100% rename from source/tutorials/wordpress/figures/wp-install-5.png rename to source/clear-linux/tutorials/wordpress/figures/wp-install-5.png diff --git a/source/tutorials/wordpress/figures/wp-install-6.png b/source/clear-linux/tutorials/wordpress/figures/wp-install-6.png similarity index 100% rename from source/tutorials/wordpress/figures/wp-install-6.png rename to source/clear-linux/tutorials/wordpress/figures/wp-install-6.png diff --git a/source/tutorials/wordpress/figures/wp-install-7.png b/source/clear-linux/tutorials/wordpress/figures/wp-install-7.png similarity index 100% rename from source/tutorials/wordpress/figures/wp-install-7.png rename to source/clear-linux/tutorials/wordpress/figures/wp-install-7.png diff --git a/source/tutorials/wordpress/figures/wp-install-8.png b/source/clear-linux/tutorials/wordpress/figures/wp-install-8.png similarity index 100% rename from source/tutorials/wordpress/figures/wp-install-8.png rename to source/clear-linux/tutorials/wordpress/figures/wp-install-8.png diff --git a/source/tutorials/wordpress/web-server-install.rst b/source/clear-linux/tutorials/wordpress/web-server-install.rst similarity index 100% rename from source/tutorials/wordpress/web-server-install.rst rename to source/clear-linux/tutorials/wordpress/web-server-install.rst diff --git a/source/tutorials/wordpress/wordpress.rst b/source/clear-linux/tutorials/wordpress/wordpress.rst similarity index 100% rename from source/tutorials/wordpress/wordpress.rst rename to source/clear-linux/tutorials/wordpress/wordpress.rst diff --git a/source/tutorials/wordpress/wp-install.rst b/source/clear-linux/tutorials/wordpress/wp-install.rst similarity index 100% rename from source/tutorials/wordpress/wp-install.rst rename to source/clear-linux/tutorials/wordpress/wp-install.rst diff --git a/source/tutorials/yubikey-u2f.rst b/source/clear-linux/tutorials/yubikey-u2f.rst similarity index 100% rename from source/tutorials/yubikey-u2f.rst rename to source/clear-linux/tutorials/yubikey-u2f.rst diff --git a/source/concepts/figures/stateless-1.png b/source/concepts/figures/stateless-1.png deleted file mode 100644 index 550f37ce..00000000 Binary files a/source/concepts/figures/stateless-1.png and /dev/null differ diff --git a/source/concepts/figures/stateless-2.png b/source/concepts/figures/stateless-2.png deleted file mode 100644 index 94e8af22..00000000 Binary files a/source/concepts/figures/stateless-2.png and /dev/null differ diff --git a/source/concepts/stateless.rst b/source/concepts/stateless.rst deleted file mode 100644 index 3252d22a..00000000 --- a/source/concepts/stateless.rst +++ /dev/null @@ -1,145 +0,0 @@ -.. _stateless: - -Stateless -######### - -In most operating systems, files can become intermingled with user and system -data and configurations. - -.. figure:: figures/stateless-1.png - :scale: 45% - :align: center - :alt: Stateless: User and system files mixed - - Figure 1: Without stateless, user and system files become mixed on the filesystem over time. - -|CL-ATTR| has a stateless design philosophy of which the goal is to provide an -:abbr:`OS (operating system)` that functions without excessive user -configuration or customization. Stateless in this context does *not* mean -ephemeral or non-persistent. - -.. contents:: :local: - :depth: 2 - - -File-level separation -********************* - -To accomplish a stateless design the Linux Filesystem Hierarchy is separated -between user-owned areas and |CL|-owned areas. - -.. figure:: figures/stateless-2.png - :scale: 45% - :align: center - :alt: Stateless: User and system files separation - - Figure 2: With stateless, user and system files are separated on the filesystem. - -System areas -============ -File under the :file:`/usr` directory are managed by |CL| as system files. -Files written under the :file:`/usr` directory by users can get removed -through system updates with :ref:`swupd `.This operating -assumption allows |CL| to verify and maintain integrity of system files. - -User areas -========== -Files under the :file:`/etc/`, :file:`/home`, and :file:`/var` directories are -owned and managed by the user. A freshly installed |CL| system will only have -a minimal set of files in the :file:`/etc/` directory and software installed -by |CL| does not write to :file:`/etc`. This operating assumption allows |CL| -users to clearly identify the configuration that makes their system unique. - - -Software Configuration -********************** - -With stateless separation, default software configurations are read in order -from predefined source code, |CL| provided defaults, and user-provided -configuration. - -Default configurations -====================== - -Software in |CL| provides default configuration values so that it is -immediately functional, whenever it is appropriate to do so. - -|CL| distributed software packages may be directly modified to include default -configuration values or default configuration files may be provided by |CL| -under :file:`/usr/share/defaults`. These files can be referenced as templates -for customization. - -For example, the default configuration that Apache uses when installed can be -found at :file:`/usr/share/defaults/httpd/httpd.conf` directory. - - -Overriding configurations -========================= - -If a configuration needs to be changed, the appropriate file should be -modified by the user under :file:`/etc/`. If the configuration file does not -already exist, it can be created in the appropriate location. - -User defined configuration files should contain the minimal set of desired -changes and rely on default configuration for the rest. - -For example, a customized Apache configuration can be used instead by: - -#. Create the destination directory for the configuration: - - .. code :: bash - - sudo mkdir /etc/httpd - -#. Copy the default configuration as a reference template: - - .. code :: bash - - sudo cp /usr/share/defaults/httpd/httpd.conf /etc/httpd/ - -#. Make any desired modifications to the configurations: - - .. code :: bash - - sudoedit /etc/httpd/httpd.conf - -#. Reload the service or reboot the system to pickup any changes: - - .. code :: bash - - systemctl daemon-reload httpd && systemctl restart httpd - - -This pattern can be used to modify the configurations of other programs too. -The `stateless man page`_ has application-specific examples. - - -System reset -************ - -Once advantage of the stateless design is that the system defaults can be -easily restored by simply deleting everything under :file:`/etc/` and -:file:`/var`. - -Running the commands below effectively performs a system reset as if it was -just installed: - -.. code:: - - sudo rm -rf /etc - sudo rm -rf /var - -In other Linux distributions, this can be a catastrophic action that renders a -system unable to boot. - -Additional information -********************** - -* `stateless man page`_ - -* `Where is /etc/fstab in Clear Linux? `_ - - -.. _`stateless man page`: https://github.com/clearlinux/clr-man-pages/blob/master/stateless.7.rst - - diff --git a/source/conf.py b/source/conf.py index 07a1394f..18ab0719 100644 --- a/source/conf.py +++ b/source/conf.py @@ -49,7 +49,7 @@ source_suffix = '.rst' #source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'index' +master_doc = 'clear-linux/clear-linux' # General information about the project. #project = u'Clear Linux* project' @@ -133,8 +133,7 @@ html_context = { # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - 'style_nav_header_background': '#8e6db6', - 'navigation_depth': 4 + 'style_nav_header_background': '#8e6db6' } # Add any paths that contain custom themes here, relative to this directory. diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-12.png b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-12.png deleted file mode 100644 index 98edfbb7..00000000 Binary files a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-12.png and /dev/null differ diff --git a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-16.png b/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-16.png deleted file mode 100644 index 72974308..00000000 Binary files a/source/get-started/bare-metal-install-server/figures/bare-metal-install-server-16.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/00-sign-in.png b/source/get-started/virtual-machine-install/figures/gce/00-sign-in.png deleted file mode 100644 index 4b9840ee..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/00-sign-in.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/01-cloud-storage.png b/source/get-started/virtual-machine-install/figures/gce/01-cloud-storage.png deleted file mode 100644 index 0888723d..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/01-cloud-storage.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/02-storage-browser.png b/source/get-started/virtual-machine-install/figures/gce/02-storage-browser.png deleted file mode 100644 index 704f94b8..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/02-storage-browser.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/03-create-bucket.png b/source/get-started/virtual-machine-install/figures/gce/03-create-bucket.png deleted file mode 100644 index 36a1da38..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/03-create-bucket.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/04-bucket-created.png b/source/get-started/virtual-machine-install/figures/gce/04-bucket-created.png deleted file mode 100644 index 064719cb..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/04-bucket-created.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/10-image-upload.png b/source/get-started/virtual-machine-install/figures/gce/10-image-upload.png deleted file mode 100644 index babaf2d1..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/10-image-upload.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/11-bucket-uploaded.png b/source/get-started/virtual-machine-install/figures/gce/11-bucket-uploaded.png deleted file mode 100644 index ce368e44..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/11-bucket-uploaded.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/20-gce-image.png b/source/get-started/virtual-machine-install/figures/gce/20-gce-image.png deleted file mode 100644 index 7b8a2ccb..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/20-gce-image.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/20-image-library.png b/source/get-started/virtual-machine-install/figures/gce/20-image-library.png deleted file mode 100644 index a70cceee..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/20-image-library.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/21-create-image.png b/source/get-started/virtual-machine-install/figures/gce/21-create-image.png deleted file mode 100644 index 4ef4d43b..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/21-create-image.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/22-image-list.png b/source/get-started/virtual-machine-install/figures/gce/22-image-list.png deleted file mode 100644 index 4347e462..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/22-image-list.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/30-create-vm.png b/source/get-started/virtual-machine-install/figures/gce/30-create-vm.png deleted file mode 100644 index 528a461e..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/30-create-vm.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/30-vm-catalog.png b/source/get-started/virtual-machine-install/figures/gce/30-vm-catalog.png deleted file mode 100644 index 06071cf6..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/30-vm-catalog.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/30-vm-instances.png b/source/get-started/virtual-machine-install/figures/gce/30-vm-instances.png deleted file mode 100644 index 3c38bd8d..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/30-vm-instances.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/30-vm-none.png b/source/get-started/virtual-machine-install/figures/gce/30-vm-none.png deleted file mode 100644 index e043ef03..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/30-vm-none.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/31-select-boot-disk.png b/source/get-started/virtual-machine-install/figures/gce/31-select-boot-disk.png deleted file mode 100644 index b0b44cdf..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/31-select-boot-disk.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/40-clear-vm-security.png b/source/get-started/virtual-machine-install/figures/gce/40-clear-vm-security.png deleted file mode 100644 index 8d45b4a4..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/40-clear-vm-security.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/40-ssh-key.png b/source/get-started/virtual-machine-install/figures/gce/40-ssh-key.png deleted file mode 100644 index e18a390c..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/40-ssh-key.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/41-vm-created.png b/source/get-started/virtual-machine-install/figures/gce/41-vm-created.png deleted file mode 100644 index ec4f3a20..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/41-vm-created.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/gce/42-ssh-vm.png b/source/get-started/virtual-machine-install/figures/gce/42-ssh-vm.png deleted file mode 100644 index 92badb80..00000000 Binary files a/source/get-started/virtual-machine-install/figures/gce/42-ssh-vm.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-01.png b/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-01.png deleted file mode 100644 index 7722a886..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-01.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-02.png b/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-02.png deleted file mode 100644 index 365f8545..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-02.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-03.png b/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-03.png deleted file mode 100644 index 496f270a..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-03.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-04.png b/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-04.png deleted file mode 100644 index 31662623..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-04.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-05.png b/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-05.png deleted file mode 100644 index c250776d..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-05.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-06.png b/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-06.png deleted file mode 100644 index 9926af81..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-06.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-07.png b/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-07.png deleted file mode 100644 index 8f2c2b34..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-07.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-08.png b/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-08.png deleted file mode 100644 index 7b23c454..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-08.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-09.png b/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-09.png deleted file mode 100644 index f6feabfa..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-09.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-10.png b/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-10.png deleted file mode 100644 index 0ffd96e8..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-10.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-11.png b/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-11.png deleted file mode 100644 index b0ca6d35..00000000 Binary files a/source/get-started/virtual-machine-install/figures/vbox/virtualbox-cl-installer-11.png and /dev/null differ diff --git a/source/get-started/virtual-machine-install/gce.rst b/source/get-started/virtual-machine-install/gce.rst deleted file mode 100644 index 0579648b..00000000 --- a/source/get-started/virtual-machine-install/gce.rst +++ /dev/null @@ -1,266 +0,0 @@ -.. _gce: - -Launch |CL-ATTR| Compute Engine on Google Cloud Platform\* -########################################################## - -This tutorial walks you through the steps to create a virtual machine -instance of |CL-ATTR| on `Google Cloud Platform`_ (:abbr:`GCP (Google Cloud Platform)`). - -.. contents:: :local: - :depth: 1 - -Prerequisites -************* - -* Set up a Google account and a GCP billing account. - -* Generate and install a user SSH key in the Linux PCs that will connect to - the VMs in GCP. - - -Process -******* - -#. Sign in to your Google\* account on the - `Google Cloud Console `_: - - .. figure:: figures/gce/00-sign-in.png - :scale: 50 % - :alt: Sign in to Google services - - Figure 1: Google sign in screen - -#. Google Cloud Platform uses **Projects** to manage resources. - Select or create a new project for hosting the |CL| VM. - - .. note:: - - Refer to the - `Quickstart Using a Linux VM `_ - guide to learn about the process of creating VM instances on GCP. - -#. Navigate to the latest |CL| - `release folder `_ - to view the currently released :abbr:`GCE (Google Compute Engine\*)` - image, and download the :file:`clear--gce.tar.gz` - image archive. - - You don't need to uncompress the image archive, the intact file will - be uploaded to the Google Cloud Storage later. - -#. Create a *Storage Bucket* for hosting the |CL| image source archive - downloaded in the previous step: - - * Click the *Navigation menu* icon on the upper left screen menu. - - * Select the *Storage* item from the side bar on the left. You will - be sent to the Storage Browser tool or the Cloud Storage overview page. - - .. figure:: figures/gce/01-cloud-storage.png - :scale: 50 % - :alt: Browse Google Cloud Storage - - Figure 2: Browse Google Cloud Storage - - .. note:: - You may need to create a billing account and link to this project - before you create a bucket. - - .. figure:: figures/gce/02-storage-browser.png - :scale: 50 % - :alt: Cloud Storage Browser tool - - Figure 3: Cloud Storage Browser tool - - * Click the ``CREATE BUCKET`` button to enter the bucket creation tool. - The bucket name must be unique because buckets in the Cloud Storage share - a single global namespace. - - Leave the remaining options set to the defaults, and select the - ``Create`` button at the bottom to create a *Bucket*. - - .. figure:: figures/gce/03-create-bucket.png - :scale: 50 % - :alt: Set a unique bucket name - - Figure 4: Set bucket name - -#. Once the bucket is created, click the ``Upload files`` button - on the Bucket details page to upload the |CL| GCE image archive - to the named bucket: - - .. figure:: figures/gce/04-bucket-created.png - :scale: 50 % - :alt: Cloud Storage bucket is available for storing objects - - Figure 5: Cloud Storage bucket - - .. figure:: figures/gce/10-image-upload.png - :scale: 50 % - :alt: Uploading the image source archive file - - Figure 6: Uploading the image source archive file - - .. figure:: figures/gce/11-bucket-uploaded.png - :scale: 50 % - :alt: Image archive imported complete - - Figure 7: Importing complete - -#. Browse the Compute Engine Image library page: - - * Click the *Navigation menu* icon on the upper left screen menu. - - * Hover your mouse over the *Compute Engine* menu and select *Images*. - - .. figure:: figures/gce/20-gce-image.png - :scale: 50 % - :alt: Go to Google Compute Engine Image library - - Figure 8: Image library - -#. On the Compute Engine Image library page, click the ``[+] CREATE IMAGE`` - menu item to create a custom image: - - .. figure:: figures/gce/20-image-library.png - :scale: 50 % - :alt: Create a Google Compute Engine image - - Figure 9: Create image - -#. In the VM image creation page, change the image source type to - *Cloud Storage file*. - -#. Under :guilabel:`Cloud Storage file`, select :guilabel:`Browse`. - -#. Locate the :file:`clear--gce.tar.gz` file, - and click :guilabel:`Select`. - - .. figure:: figures/gce/21-create-image.png - :scale: 50 % - :alt: Create the image using the imported image archive object - - Figure 10: Create image using imported object - - Accept all default options, and click the ``Create`` button - at the bottom to import the Clear Linux GCE image to the image library. - - .. figure:: figures/gce/22-image-list.png - :scale: 50 % - :alt: Clear Linux Compute Engine image is created - - Figure 11: Image is created - -#. After the |CL| image is imported, you can launch a VM instance running - |CL|: - - * Click the *Navigation menu* icon on the upper left screen menu. - - * Hover your mouse over the *Compute Engine* menu group and select - the *VM instances* item. - - .. figure:: figures/gce/30-vm-instances.png - :scale: 50 % - :alt: Go to VM instances catalog - - Figure 12: VM instances catalog - -#. If no VM instance was created in this project, you will be prompted to - create one. - -#. Alternatively, click the ``CREATE INSTANCE`` button on the VM - instances page to create a VM instance. - - .. figure:: figures/gce/30-vm-none.png - :scale: 50 % - :alt: Prompt for VM creation - - Figure 13: VM creation - - .. figure:: figures/gce/30-vm-catalog.png - :scale: 50 % - :alt: List of VM instances - - Figure 14: VM instances list - - * In :guilabel:`Region`, choose a region based on the - `Best practices for Compute Engine regions selection`_. - - * Under *Boot disk*, click the ``Change`` button. - - .. figure:: figures/gce/30-create-vm.png - :scale: 50 % - :alt: Use custom image while creating Clear Linux VM instance - - Figure 15: Use custom image - - * Select the *Custom images* tab for using Clear Linux OS GCE image. - - .. figure:: figures/gce/31-select-boot-disk.png - :scale: 50 % - :alt: Select Clear Linux boot disk to create a VM instance - - Figure 16: Select Clear Linux boot disk to create a VM instance - - * Scroll down to the bottom of the VM instance creation page, - expand the *Management, security, disks, networking, sole tenancy* group. - - .. figure:: figures/gce/40-clear-vm-security.png - :scale: 50 % - :alt: Clear Linux requires setting up SSH keys - - Figure 17: Set up SSH keys - - .. note:: - |CL| does not allow SSH login with a root account by default. - As a result, you must configure the VM instance with your - SSH public key, so that you are able to access it remotely. - - Refer to :ref:`security` for more details. - - * Click the *Security* tab, copy and paste your SSH public key: - - .. figure:: figures/gce/40-ssh-key.png - :scale: 50 % - :alt: Set SSH key for remote login - - Figure 18: Set SSH key for remote login - - .. warning:: - - The username is assigned from characters preceding ``@`` in the email - address, included in the SSH key. The dot symbol "." is not allowed, - because it is an invalid character while creating user accounts in - |CL|. - - * Click the ``Create`` button to create the |CL| VM. - -#. The Clear Linux VM instance is created and assigned a public IP address: - - .. figure:: figures/gce/41-vm-created.png - :scale: 50 % - :alt: Clear Linux VM instance is created and started - - Figure 19: Clear Linux VM instance is created and started - -#. You can now SSH login to the VM using the IP address obtained in the - previous step, and the username associated with the SSH public key: - - .. figure:: figures/gce/42-ssh-vm.png - :scale: 50 % - :alt: SSH login to the Clear Linux VM - - Figure 20: SSH login to Clear Linux VM - -Related topics -************** - -The following tutorials describe a similar process and may be useful references: - -* :ref:`azure` -* :ref:`aws-web` - - -.. _Google Cloud Platform: https://cloud.google.com/ - -.. _Best practices for Compute Engine regions selection: https://cloud.google.com/solutions/best-practices-compute-engine-region-selection diff --git a/source/get-started/virtual-machine-install/virtualbox-cl-installer.rst b/source/get-started/virtual-machine-install/virtualbox-cl-installer.rst deleted file mode 100644 index f919cff1..00000000 --- a/source/get-started/virtual-machine-install/virtualbox-cl-installer.rst +++ /dev/null @@ -1,407 +0,0 @@ -.. _virtualbox-cl-installer: - -Install a |CL-ATTR| VM in VirtualBox\* -###################################### - -Oracle\* VirtualBox\* is a type 2 hypervisor. This document explains how to -create a virtual machine on the `VirtualBox hypervisor`_ with |CL-ATTR| as -the guest operating system. These instructions support use of the |CL| -live-server installer to create |CL| virtual machine (VM). - -.. contents:: :local: - :depth: 1 - -Prerequisites -************* - -Before continuing, assure you have: - -#. Enabled virtualization, such as Intel® - `Virtualization Technology`_ (Intel® VT), on the host system from - EFI/BIOS. - -#. Downloaded and installed |VB| **version 6.0 or greater** from - the `official VirtualBox website`_ per the `appropriate instructions`_ - for your platform. - -Download and extract the |CL| installer ISO -******************************************* - -#. Download the :file:`clear--live-server.iso.xz` of - |CL| on the `downloads page`_. - -#. Validate the integrity of the downloaded image by checking the file hash - and signatures. Refer :ref:`validate-signatures` for detailed steps. - -#. Decompress the downloaded image. - - - On Windows you can use `7zip`_ to extract the file by right-clicking the - file to *Extract Here* (in the same directory) - - .. figure:: figures/vbox/virtualbox-cl-installer-01.png - :scale: 100% - :alt: 7zip extract here command - - Figure 1: 7zip extract here command - - - On Linux : - - .. code-block:: bash - - xz -d clear--live-server.iso.xz - -#. Delete the originally downloaded compressed file. - -Create a new |VB| virtual machine -********************************* - -A new :abbr:`VM (Virtual Machine)` needs to be created in |VBM| where |CL| -will be installed. General instructions for creating a virtual machine and -details about using different settings are available on the -`VirtualBox manual section on Creating a VM`_. - -#. Launch the |VBM| from your host system. - -#. Click the *New* button to create a new VM. - -#. Choose :guilabel:`Expert mode`. - -#. In :guilabel:`Create Virtual Machine`, enter the following settings: - - - **Name**: Choose name (e.g. ClearLinuxOS-VM). - - **Type**: Linux - - **Version**: **Linux 2.6 / 3.x / 4.x (64-bit)** - - **Hard disk**: `Create a virtual hard disk now` - - **Memory size default**: 2048 MB (Adjust appropriately.) - - .. note:: - Later, if you want to change the amount of RAM allocated, power down your VM. Return to :file:`Settings > System` and change - :guilabel:`Base Memory` to the desired size. - - .. figure:: figures/vbox/virtualbox-cl-installer-02.png - :scale: 100% - :alt: Create Virtual Machine - - Figure 2: Create Virtual Machine - -#. Select :guilabel:`Create`. - -#. In :guilabel:`Create Virtual Hard Disk`, select: - - - **File location** - - **File size**: **32.00 GB**. Adjust size to your needs. - - **Hard disk file type**: `VDI (VirtualBox Disk Image)` - - **Storage on physical hard disk**:`Dynamically allocated` - - .. figure:: figures/vbox/virtualbox-cl-installer-03.png - :scale: 100% - :alt: Create Virtual Hard Disk - - Figure 3: Create Virtual Hard Disk - -#. Click *Create*. - - A new virtual machine will be created and appear in the |VBM|. - -#. Click *Settings* to configure the |CL| VM. - -#. In the left-hand menu, navigate to the :guilabel:`System` menu. - -#. In the :guilabel:`Motherboard` tab, select the `Chipset` pulldown menu, - and then select :guilabel:`ICH9`. See Figure 4. - - .. note:: - - You can select which chipset will be presented to the virtual machine. - Consult the `VM VirtualBox User Manual`_ for more details. - -#. In :guilabel:`Enabled Features`, check these boxes: - - - **Enable I/O APIC** - - **Enable EFI (special OSes only)** - - .. figure:: figures/vbox/virtualbox-cl-installer-04.png - :scale: 100% - :alt: Settings > System - - Figure 4: Settings > System - - .. note:: - - By default, only 1 virtual CPU is allocated to the new VM. Consider - increasing the number of virtual processors allocated to the virtual - machine under Settings > System > Processor for increased - performance. - -#. Select :guilabel:`OK`. - -Install |CL| on the |VB| VM -*************************** - -|CL| is ready to be installed. - -Mount the installation ISO -========================== - -The |CL| installer ISO needs to be mounted as a virtual CD-ROM on the VM -before powering the VM on. - -#. From the *ClearLinux-OS* :guilabel:`Settings` at left, select - :guilabel:`Storage`. - -#. From :guilabel:`Storage Devices`, middle column, click the blue - disk labeled *Empty*. - -#. From the :guilabel:`Attributes` menu, click the blue CD disk next to - the *Optical Drive* drop down menu and click *Choose Virtual Optical - Disk File...* - - .. figure:: figures/vbox/virtualbox-cl-installer-05.png - :scale: 100% - :alt: Choose Virtual Optical Disk Drive - - Figure 5: Choose Virtual Optical Disk Drive - -#. Where there appears :guilabel:`Please choose a virtual optical disk file`, - select the ISO file and click *Open*. - - .. figure:: figures/vbox/virtualbox-cl-installer-06.png - :scale: 100% - :alt: Mounting an ISO - - Figure 6: Mounting an ISO - -#. Select :guilabel:`OK` to exit and return to the main |VBM|. - -Install |CL| with live-server installer -======================================= - -#. In the |VBM|, select virtual machine you created and click *Start*. - - .. figure:: figures/vbox/virtualbox-cl-installer-07.png - :scale: 100% - :alt: Start the installer - - Figure 7: Start the installer - - .. note:: - - To release the mouse cursor from the VM console window, press the right - :kbd:`Ctrl` key on the keyboard. - -#. When :guilabel:`Clear Linux Installer` in boot manager appears, - select :kbd:`Enter`. Do not install the bundle `desktop-autostart`. - -#. Follow the steps in :ref:`bare-metal-install-server` to - install |CL| onto the VM virtual disk. Note: - - #. In :guilabel:`Configure Installation Media`, navigate top - VBOX HARDDISK, and then select :guilabel:`Confirm`. - - #. In :guilabel:`Advanced options` > :guilabel:`Manage User`, create an - administrative user. - - #. Do not install the bundle `desktop-autostart`. - -#. When |CL| installation is complete, select :guilabel:`Exit`. - -#. At the prompt, enter: - - .. code-block:: bash - - shutdown now - -Unmount the ISO -=============== - -The |CL| installer ISO needs to be unmounted to allow the VM to boot from the -virtual hard disk. - -#. Return to the |VBM|. - -#. Click *Settings* to configure the |CL| VM. - -#. From the *VM - Settings* window, navigate to the *Storage* pane from the - left-hand side. - -#. From the middle *Storage Devices* column, click the blue CD disk labeled - *clear--live-server.iso* under the *Controller: IDE* from. - -#. From the *Attributes* column at right, in *Optical Drive*, select the - blue CD icon beside and click *Remove Disk from Virtual Drive*. - - .. figure:: figures/vbox/virtualbox-cl-installer-08.png - :scale: 100% - :alt: Remove Disk from Virtual Drive - - Figure 8: Remove Disk from Virtual Drive - -#. Click *OK* to exit the *VM Settings* menu and return to the main - |VBM|. - -Install |VB| Linux Guest Additions -================================== - -|CL| provides Linux Guest Additions drivers for full compatibility using an -install script in the **kernel-lts** (Long Term Support) bundle by |CL|. - -#. From the |VBM| select the |CL| VM, and select :guilabel:`Start`. - -#. In the VM Console, log in as the administrative user previously created. - - .. note:: - A message may appear: "A kernel update is available: you may wish - to reboot the system." - - To update the kernel, enter: - - .. code-block:: bash - - sudo reboot - - At initial login, enter the administrative user's password and continue. - -#. Validate the installed kernel is **kernel-lts** by checking the output - of the :command:`uname -r` command. It should end in **.lts** or **.lts2018**. - - .. code-block:: bash - - uname -r - .lts - - If the running kernel is not **lts**: install the LTS kernel manually, - update the bootloader, and check again: - - .. code-block:: bash - - sudo swupd bundle-add kernel-lts - clr-boot-manager set-kernel $(basename $(realpath /usr/lib/kernel/default-lts)) - clr-boot-manager update - reboot - -#. Remove any kernel bundles that do not end in *-lts* or *kernel-install* - to simplify and avoid conflicts: - - .. code-block:: bash - - sudo swupd bundle-list | grep kernel - sudo swupd bundle-remove - -#. In the VM Console top menu, click *Devices*, and select - *Insert Guest Additions CD image...* to mount the |VB| driver installation to the |CL| VM. - - .. figure:: figures/vbox/virtualbox-cl-installer-09.png - :scale: 100% - :alt: Insert Guest Additions CD image - - Figure 9: Insert Guest Additions CD image - -#. If a dialogue appears, "VBx_GAs_6.0.8... Would you like to run it?", - select :guilabel:`Cancel`. - - Instead, we provide a script to patch and install |VB| drivers on |CL|. - -#. Open a Terminal and enter the script: - - .. code-block:: bash - - sudo install-vbox-lga - - .. note:: - - Successful installation shows: "Guest Additions installation complete". - If drivers are already installed, don't re-install them. - -#. Shut down the system. Select :guilabel:`Machine>ACPI Shutdown`. - - .. figure:: figures/vbox/virtualbox-cl-installer-10.png - :scale: 100% - :alt: Powering off a VirtualBox VM - - Figure 10: Powering off a VirtualBox VM - -#. Select :guilabel:`Settings`, :guilabel:`Display`. - -#. In :guilabel:`Graphics Controller`, select :guilabel:`VBoxSVGA` - to adjust screen size dynamically. - - .. figure:: figures/vbox/virtualbox-cl-installer-11.png - :scale: 100% - :alt: Remove Disk from Virtual Drive - - Figure 11: VirtualBox hardware acceleration error - -#. In the |VBM|, select :guilabel:`Start`. - -#. In the VM console, login and verify the |VB| drivers are loaded: - - .. code-block:: bash - - lsmod | grep ^vbox - - You should see drivers loaded with names beginning with **vbox**: - (e.g., vboxvideo, vboxguest). - -#. Add `desktop-autostart` for a full desktop experience. - - .. code-block:: bash - - sudo swupd bundle-add desktop-autostart - -#. Reboot the VM and log in with the administrative user. - - .. code-block:: bash - - sudo reboot - -The |CL| VM running on |VB| is ready to develop and explore. - -Troubleshooting -*************** - -#. **Problem:** On a Microsoft\* Windows\* OS, |VB| encounters an error when - trying to start a VM indicating *VT-X/AMD-v hardware acceleration is not - available on your system.* - - .. figure:: figures/vbox/virtualbox-cl-installer-12.png - :scale: 100% - :alt: Remove Disk from Virtual Drive - - Figure 12: VirtualBox hardware acceleration error - - **Solution:** First, double check the `Prerequisites`_ section to make - sure *Hardware accelerated virtualization* extensions have been enabled - in the host system's EFI/BIOS. - - *Hardware accelerated virtualization*, may get disabled for |VB| when - another hypervisor, such as *Hyper-V* is enabled. - - To disable *Hyper-V* execute this command in an - **Administrator: Command Prompt or Powershell**, and reboot the system: - - .. code-block:: bash - - bcdedit /set {current} hypervisorlaunchtype off - - To enable Hyper-V again, execute this command in an - **Administrator: Command Prompt or Powershell**, and reboot the system: - - .. code-block:: bash - - bcdedit /set {current} hypervisorlaunchtype Auto - -.. _appropriate instructions: https://www.virtualbox.org/manual/ch02.html - -.. _official VirtualBox website: https://www.virtualbox.org/wiki/Downloads - -.. _VirtualBox hypervisor: https://www.virtualbox.org/ - -.. _downloads page: https://clearlinux.org/downloads - -.. _`VirtualBox manual section on Creating a VM`: https://www.virtualbox.org/manual/UserManual.html#gui-createvm - -.. _7zip: http://www.7-zip.org/ - -.. _Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html - -.. _VM VirtualBox User Manual: https://docs.oracle.com/cd/E97728_01/E97727/html/settings-system.html \ No newline at end of file diff --git a/source/guides/maintenance/assign-static-ip.rst b/source/guides/maintenance/assign-static-ip.rst deleted file mode 100644 index 9028fbfc..00000000 --- a/source/guides/maintenance/assign-static-ip.rst +++ /dev/null @@ -1,184 +0,0 @@ -.. _assign-static-ip: - -Assign a static IP address -########################## - -By default, your |CL-ATTR| system automatically gets an IP address from your -network via DHCP. If you do not have a DHCP server on your network or simply -want to use a static IP address, follow the steps in this guide. - -.. contents:: - :local: - :depth: 1 - -Identify which program is managing the interface -************************************************ - -New installations of |CL| use NetworkManager as the default network interface -manager for all network connections. - -.. note:: - - * The *cloud* |CL| images continue to use systemd-networkd to manage - network connections. - - * In earlier |CL| versions, systemd-network was used to manage Ethernet - interfaces and NetworkManager was used for wireless interfaces. - - -Before defining a configuration for assigning a static IP address, you should -verify which program is managing the network interface. - -#. Check the output of :command:`nmcli device` to see if NetworkManager is - managing the device. - - .. code-block:: bash - - nmcli device status - - If the STATE column for the device shows *connected* or *disconnected*, the - network configuration is being managed by NetworkManager and the instructions - for :ref:`using NetworkManager ` should be used. - - If the STATE column for the device shows *unmanaged*, check to see if the - device is being managed by systemd-networkd - - -#. Check the output of :command:`networkctl list` to see if - systemd-networkd is managing the device. - - .. code-block:: bash - - networkctl list - - If the SETUP column for the device shows *configured*, the network - configuration is being managed by systemd-networkd and the instructions for - :ref:`using systemd-networkd ` should be used. - - -.. _nm-static-ip: - -Using NetworkManager -******************** - -Network connections managed by NetworkManager are stored as files with the -:file:`.nmconnection` file extension in the -:file:`/etc/NetworkManager/system-connections/` directory. - -A few tools exists to aid to manipulate network connections managed by -NetworkManager: - -* nmcli - a command-line tool - -* nmtui - a text user interface that provides a pseudo graphical menu in the - terminal - -* nm-connection-editor - a graphical user interface - -The method below uses the command line tool *nmcli* to modify network -connection. - - -#. Identify the existing connection name: - - .. code:: bash - - nmcli connection show - - The output will look like this: - - .. code:: bash - - NAME UUID TYPE DEVICE - Wired connection 1 00000000-0000-0000-0000-000000000000 802-3-etherneten01 - - If a connection does not exist, it will need to be created with - :command:`nmcli connection add`. - - -#. Modify the connection to use a static IP address. Replace the variables in - brackets with the appropriate values. *[CONNECTION_NAME]* should be - replaced with the NAME from the command above. - - .. code:: - - sudo nmcli connection modify "[CONNECTION_NAME]" \ - ipv4.method "manual" \ - ipv4.addresses "[IP_ADDRESS]/[CIDR_NETMASK]" \ - ipv4.gateway "[GATEWAY_IP_ADDRESS]" \ - ipv4.dns "[PRIMARY_DNS_IP],[SECONDARY_DNS_IP]" - - - See the `nmcli developer page `_ for more - configuration options. For advanced configurations, the - :file:`/etc/NetworkManager/system-connections/*.nmconnection`. can be edited - directly. - - -#. Restart the NetworkManager server to reload the DNS servers: - - .. code-block:: bash - - sudo systemctl restart NetworkManager - - -#. Verify your static IP address details have been set: - - .. code-block:: bash - - nmcli - - - -.. _networkd-static-ip: - -Using systemd-networkd -********************** - -Network connections managed by systemd-networkd are stored as files with the -:file:`.network` file extension the :file:`/etc/systemd/network/` directory. - -Files to manipulate network connections managed by systemd-networkd must be -created manually. - -#. Create the :file:`/etc/systemd/network` directory if it doesn't exist already: - - .. code-block:: bash - - sudo mkdir -p /etc/systemd/network - -#. Create a :file:`.network` file and add the following content. Replace the - variables in brackets with the appropriate values. *[INTERFACE_NAME]* - should be replaced with LINK from the output of :command:`networkctl list` - ran previously. - - .. code-block:: bash - - sudo $EDITOR /etc/systemd/network/70-static.network - - [Match] - Name=[INTERFACE_NAME] - - [Network] - Address=[IP_ADDRESS]/[CIDR_NETMASK] - Gateway=[GATEWAY_IP_ADDRESS] - DNS=[PRIMARY_DNS_IP] - DNS=[SECONDARY_DNS_IP] - - See the `systemd-network man page - `_ - for more configuration options. - -#. Restart the systemd-networkd service: - - .. code-block:: bash - - sudo systemctl restart systemd-networkd - - -#. Verify your static IP address details have been set: - - .. code-block:: bash - - networkctl status - diff --git a/source/guides/maintenance/cpu-performance.rst b/source/guides/maintenance/cpu-performance.rst deleted file mode 100644 index 10eedb6e..00000000 --- a/source/guides/maintenance/cpu-performance.rst +++ /dev/null @@ -1,196 +0,0 @@ -.. _cpu-performance: - -CPU Power and Performance -######################### - -Modern x86 :abbr:`CPUs (central processing units)` employ a number of features -and technologies to balance performance, energy, and thermal efficiencies. - -By default, |CL| prioritizes maximum CPU performance with the philosophy that -the faster the program finishes execution, the faster the CPU can return to a -low energy idle state. It is important to understand and evaluate all of these -technologies when troubleshooting or considering changing the defaults. - -.. contents:: :local: - :depth: 1 - -CPU power saving mechanisms -=========================== - -C-states and P-states are both CPU power saving mechanisms that are entered -under different operating conditions. The tradeoff is a slightly longer time -to exit these states when the CPU is needed once again. - -.. _c-states-section: - -C-states (idle states) ----------------------- - -C-states are hardware sleep states that are entered when it is determined that -the CPU is idle and not executing instructions. - -C-states aim to reduce power utilization by increasingly reducing clock -frequency, voltages, and features in each state. - -Although C-states can typically be limited or disabled in a system's UEFI or -BIOS configuration, these settings are overridden when the `intel_idle -driver`_ is in use. - -To view the current cpuidle driver run this command in a terminal: - -.. code:: bash - - cat /sys/devices/system/cpu/cpuidle/current_driver - -For troubleshooting, C-states can be limited with a kernel command line boot -parameter by adding :command:`processor.max_cstate=N intel_idle.max_cstate=N` -or completely disabled with :command:`idle=poll`. - -.. note:: - - * :command:`processor.max_cstate=0` is changed to :command:`processor.max_cstate=1` by the kernel to be a valid value. - - * :command:`intel_idle.max_cstate=0` disables the Intel Idle driver, not set - it to C-state 0. - -.. _p-states-section: - -P-states (performance states) ------------------------------ - -P-states, also known as *SpeedStep* on Intel processors or *Cool'n'Quiet* on -AMD processors, are states entered while the CPU is active and executing -instructions. - -P-states aim to reduce power utilization by adjusting CPU clock frequency and -voltages based on CPU demand. - -P-states can typically be limited or disabled in a system's firmware (UEFI/BIOS). - -Turbo boost -~~~~~~~~~~~ - -`Turbo Boost technology`_, found on some modern Intel CPUs, allows core(s) on -a processor to temporarily operate at a higher than rated CPU clock frequency -to accommodate demanding workloads if the CPU is under defined power and -thermal thresholds. - -Turbo boost is an extension of P-states. As such, changing or limiting -C-states or P-states impact the ability of a process to enter Turbo boost. - -Turbo boost can be disabled in a system's UEFI or BIOS. Turbo boost can also -be disabled within |CL| with the command: - -.. code:: bash - - echo 1 | sudo tee /sys/devices/system/cpu/intel_pstate/no_turbo - -Linux CPU clock frequency scaling -================================= - -The CPUFreq subsystem in Linux allows the OS to control :ref:`C-states -` and :ref:`P-states ` -via CPU drivers and governors that provide algorithms that define how and when -to enter these states. - -Scaling driver --------------- - -Linux uses the `Intel P-state driver`_, *intel_pstate*, for modern Intel -processors from the Sandy Bridge generation or newer. Other processors may -default to the *acpi-cpufreq* driver which reads values from the systems UEFI -or BIOS. - -To view the current CPU frequency scaling driver run this command in a terminal: - -.. code:: bash - - cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_driver - -Scaling governor ----------------- - -|CL| sets the CPU governor to *performance* which calls for the CPU to operate -at maximum clock frequency. In other words, P-state P0. While this may sound -wasteful at first, it is important to remember that power utilization does not -increase significantly simply because of a locked clock frequency without a -workload. - -To view the current CPU frequency scaling governor run this command in a terminal: - -.. code:: bash - - cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor - -To change the CPU frequency scaling governor: - -#. Disable |CL| enforcement of certain power and performance settings: - - .. code:: bash - - sudo systemctl mask clr-power.timer - -#. Change the governor. In the example below, the governor is set to - *performance*: - - .. code:: bash - - echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor - -The list of all governors can be found in the `Linux kernel documentation on -CPUFreq Governors`_. - -.. note:: - - The intel_pstate driver only supports *performance* and *powersave* governors. - -Thermal management -================== - -`thermald`_ is a Linux thermal management daemon used to prevent the -overheating of platforms. When temperature thresholds are exceeded, thermald -forces a C-state by inserting CPU sleep cycles and adjusts available cooling -methods. This can be especially desirable for laptops. - -By default, thermald is disabled in |CL| and starts automatically if battery -power is detected. thermald can be manually enabled using the systemd service -by running the command: - -.. code:: bash - - sudo systemctl enable thermald - sudo systemctl start thermald - -For more information, see the thermald man page: - -.. code:: bash - - man thermald - -`ThermalMonitor`_ is a GUI application that can visually graph and log -temperatures from thermald. To use ThermalMonitor, add the desktop-apps-extras -bundle and add your user account to the power group: - -.. code:: bash - - sudo swupd bundle-add desktop-apps-extras - sudo usermod -a -G power - ThermalMonitor - -.. note:: - - After adding a new group you must log out and log back in for the new group - to take affect. - - -.. _`Intel P-state driver`: https://www.kernel.org/doc/Documentation/cpu-freq/intel-pstate.txt - -.. _`Linux kernel documentation on CPUFreq Governors`: https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt - -.. _thermald: https://01.org/linux-thermal-daemon - -.. _`intel_idle driver`: https://github.com/torvalds/linux/blob/master/drivers/idle/intel_idle.c - -.. _`ThermalMonitor`: https://github.com/intel/thermal_daemon/tree/master/tools/thermal_monitor - -.. _`Turbo Boost technology`: https://www.intel.com/content/www/us/en/architecture-and-technology/turbo-boost/turbo-boost-technology.html diff --git a/source/includes/get-started.txt b/source/includes/get-started.txt deleted file mode 100644 index d9c0fb92..00000000 --- a/source/includes/get-started.txt +++ /dev/null @@ -1,2 +0,0 @@ -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. \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index bbb22b64..8752775b 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,46 +1,18 @@ -.. _clear-linux: +.. Clear Technologies documentation master file. -|CL-PRJ| -############################################# +:orphan: -Welcome to the |CL-ATTR| documentation pages, the source for |CL| documentation. - -.. raw:: html - - - -Our documentation is divided into the following sections: - -:ref:`get-started` - .. include:: /includes/get-started.txt - -:ref:`tooling` - Clear Linux is a little different from other distros. Here are some - important tools and concept for managing your install. - -:ref:`guides` - 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. - -:ref:`faq` - Refer to our FAQ section to read commonly asked questions and answers. +Clear Linux - Documentation +########################### .. toctree:: - :maxdepth: 2 - :hidden: + :maxdepth: 1 - get-started/get-started - tooling/tooling - guides/guides - tutorials/tutorials - reference/reference - FAQ/faq \ No newline at end of file + clear-linux/clear-linux + sitemap + +License and disclaimers +======================= + +.. include:: documentation_license.rst + :start-line: 2 diff --git a/source/main-site-content/get-started.yml b/source/main-site-content/get-started.yml deleted file mode 100644 index cf0a59df..00000000 --- a/source/main-site-content/get-started.yml +++ /dev/null @@ -1,4 +0,0 @@ -title: 'Getting Started' -type: 'documentation card' -content: /includes/get-started.txt -github_url: 'https://clearlinux.org/documentation/clear-linux/get-started' \ No newline at end of file diff --git a/source/sitemap.rst b/source/sitemap.rst new file mode 100644 index 00000000..7e747da5 --- /dev/null +++ b/source/sitemap.rst @@ -0,0 +1,13 @@ +.. _clear-linux-sitemap: + +Clear Linux - Documentation Sitemap +################################### + +.. toctree:: + :includehidden: + + clear-linux/concepts/concepts + clear-linux/get-started/get-started + clear-linux/guides/guides + clear-linux/reference/reference + clear-linux/tutorials/tutorials diff --git a/source/substitutions.txt b/source/substitutions.txt index 1f1d049d..20c6b780 100644 --- a/source/substitutions.txt +++ b/source/substitutions.txt @@ -14,7 +14,3 @@ Not fully unmounting the USB drive before burning an image could cause file system checksum errors in it. If this happens, burn the image again ensuring all the USB drive partitions are unmounted first. - -.. |VB| replace:: VirtualBox - -.. |VBM| replace:: VirtualBox Manager diff --git a/source/tooling/compatible-kernels.rst b/source/tooling/compatible-kernels.rst deleted file mode 100644 index 9640be50..00000000 --- a/source/tooling/compatible-kernels.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. _compatible-kernels: - -Kernels -####### - -The |CL-ATTR| provides the following Linux kernels with a respective bundle. -This document describes the specific use cases these `bundles`_ serve -and provides links to their source code. - -Bare metal only -*************** - -Kernel native - The *kernel-native* bundle focuses on the bare metal platforms. It is - optimized for fast booting and performs best on the Intel® architectures - described on the :ref:`supported hardware list`. The - optimization patches are found in our `Linux`_ GitHub\* repo. - -Kernel Container - The *kernel-container* bundle contains the kernel used by the - Intel® Clear Containers project. This kernel is optimized for - fast booting and performs best on |CC| running on the Intel® architectures - described on the :ref:`supported hardware list`. - The optimization patches are found in our `Linux-Container`_ GitHub repo. - -.. _vm-kernels: - -Also compatible with VMs -************************ - -Kernel LTS - The *kernel-lts* bundle focuses on the bare metal platforms but uses the - latest :abbr:`LTS (Long Term Support)` Linux kernel. It is optimized for - fast booting and performs best on the Intel® architectures described on the - :ref:`supported hardware list`. Additionally, this - kernel includes the VirtualBox\* kernel modules, see our - :ref:`instructions on using Virtualbox` for more - information. The optimization patches are found in our `Linux-LTS`_ GitHub - repo. - -VM only -******* - -Kernel KVM - The *kernel-kvm* bundle focuses on the Linux - :abbr:`KVM (Kernel-based Virtual Machine)`. It is optimized for fast - booting and performs best on Virtual Machines running on the Intel® - architectures described on the - :ref:`supported hardware list`. Use this kernel when - running |CL| as the guest OS on top of *qemu/kvm*. Use this kernel with - **cloud orchestrators** using *qemu/kvm* internally as their **hypervisor** - . This kernel can be used as a standalone |CL| VM, see our - :ref:`instructions on using KVM` for more information. The - optimization patches are found in our `Linux-KVM`_ GitHub repo. - -Kernel Hyper-V\* - The *kernel-hyperv* bundle focuses on running Linux on Microsoft\* - Hyper-V. It is optimized for fast booting and performs best on Virtual - Machines running on the Intel® architectures described on the - :ref:`supported hardware list`. - Use this kernel when running |CL| as the guest OS of **Cloud Instances** in - projects such as Microsoft `Azure`_\*. This kernel can be used in a - standalone |CL| VM, see our :ref:`instructions on using Hyper-V` - for more information. The optimization patches are found in our - `Linux-HyperV`_ GitHub repo. - -Kernel Hyper-V LTS - The *kernel-hyperv-lts* bundle focuses on running Linux on Microsoft - Hyper-V but uses the latest :abbr:`LTS (Long Term Support)` Linux kernel. - It is optimized for fast booting and performs best on Virtual - Machines running on the Intel® architectures described on the - :ref:`supported hardware list`. - Use this kernel when running |CL| as the guest OS of **Cloud Instances** in - projects such as Microsoft `Azure`_. This kernel can be used in a - standalone |CL| VM, see our :ref:`instructions on using Hyper-V` - for more information. The optimization patches are found in our - `Linux-HyperV-LTS`_ GitHub repo. - - -.. _Linux: https://github.com/clearlinux-pkgs/linux -.. _Linux-LTS: https://github.com/clearlinux-pkgs/linux-lts -.. _Linux-KVM: https://github.com/clearlinux-pkgs/linux-kvm -.. _Linux-HyperV: https://github.com/clearlinux-pkgs/linux-hyperv -.. _Linux-HyperV-LTS: https://github.com/clearlinux-pkgs/linux-hyperv-lts -.. _Linux-Container: https://github.com/clearlinux-pkgs/linux-container -.. _bundles: https://github.com/clearlinux/clr-bundles -.. _CIAO: https://github.com/01org/ciao -.. _Azure: - https://azuremarketplace.microsoft.com/en-us/marketplace/apps/clear-linux-project.clear-linux-os - diff --git a/source/tooling/debug.rst b/source/tooling/debug.rst deleted file mode 100644 index 0dadc690..00000000 --- a/source/tooling/debug.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. _debug: - -Debug System -############ - -|CL-ATTR| introduces a novel approach to system software debugging using -*clr-debug-info*. On the client side, the |CL| debug system obtains any -necessary debug information on-the-fly over a network during a debugging -session. On the server side, the system curates and compresses debug -information into small pieces for efficient downloading. - -For developers, this avoids the interruption during debugging that usually -happens when debug information is missing. This can be especially useful on -systems where storage is limited. - - -.. contents:: :local: - :depth: 2 - - -Background ----------- - -Software that is compiled and packaged for general usage in an operating -system typically only contains components that are used to execute the -program, such as binaries and libraries. Extra developer data, such as the -actual source code and symbol information, are separated and excluded for -efficiency. - -The debug information helps relate binary code to human readable source code -lines and variables. Most of the time, this auxiliary information -is not needed; -however without it, debugging a program results in limited visibility. - - -Usage ------ - -The clr-debug-info system is integrated into |CL| and seamlessly engages once -installed. - -#. Install the *dev-utils* bundle. - - .. code:: bash - - sudo swupd bundle-add dev-utils - - .. note:: - - The *telemetrics* and *performance-tools* bundles also include - clr-debug-info. - - -#. Start a debugging session against a program using a debugger, such as GDB. - For example, to debug *gnome-control-center* execute the following - command: - - .. code:: bash - - gdb /usr/bin/gnome-control-center - -As you step through the program and debug information is needed, the -clr_debug_daemon obtains it in the background. - - -Implementation --------------- - -The implementation of the |CL| debug system is open source and available on -GitHub at: https://github.com/clearlinux/clr-debug-info/ - -.. figure:: figures/debug-diagram.png - :width: 400px - :alt: Debug system communication flow - - Figure 1: The communication flow of the |CL| debug system - -The |CL| debug system implements a :abbr:`FUSE (filesystem in userspace)` -filesystem mounted at :file:`/usr/lib/debug` and :file:`/usr/src/debug`. The -FUSE filesystem starts automatically. You can verify its status by executing -:command:`systemctl status clr_debug_fuse.service`. - -The *clr_debug_daemon* is responsible for fetching the appropriate package -debug content from the server and making it available for any debugging -programs that need it. It is socket activated whenever a request to the local -FUSE filesystem occurs. You can verify its status with :command:`systemctl -status clr_debug_daemon.service`. - - -|CL| hosts debuginfo content packaged for consumption by |CL| debug clients at -https://download.clearlinux.org/debuginfo/ diff --git a/source/tooling/figures/debug-diagram.png b/source/tooling/figures/debug-diagram.png deleted file mode 100644 index d85a4045..00000000 Binary files a/source/tooling/figures/debug-diagram.png and /dev/null differ diff --git a/source/tooling/swupd-guide.rst b/source/tooling/swupd-guide.rst deleted file mode 100644 index 95ee8c36..00000000 --- a/source/tooling/swupd-guide.rst +++ /dev/null @@ -1,346 +0,0 @@ -.. _swupd-guide: - -swupd -##### - -:command:`swupd` links a |CL-ATTR| installation with upstream updates and -software. - -.. contents:: - :local: - :depth: 1 - -Description -*********** - -:command:`swupd` has two main functions: - -#. Manage software and replace APT or YUM, by installing bundles - rather than packages. -#. Check for system updates and install them. - -:command:`swupd` manages overlapping dependencies behind the scenes, ensuring -that all software is compatible across the system. It can be used to verify -the OS, clean cached files, and fix issues. - -:ref:`Bundles ` contain everything needed to deliver a software -capability. They are the smallest granularity component that is -managed by |CL|. A bundle comes with all of its dependencies rather than -downloading a cascade of package dependencies when installing a piece of -software. - -Versioning -========== - -Using package managers to monitor software version compatibility or -compare multiple systems on many Linux distributions can be cumbersome. - -With |CL| :command:`swupd`, versioning happens at the individual file level. -This means |CL| generates an entirely new OS version with any set of software -changes to the system, including software downgrades or removals. This -rolling release versioning model is similar to :command:`git` internal version -tracking, where any of the individual file commits are tracked and move the -pointer forward when changed. - -A number that represents the **current** release of the OS describes 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. On a daily basis, -this matters to system administrators who need to determine which of their -systems do not have the latest security fixes, or which combinations of -software have been tested. Every release of the same number is guaranteed to -contain the same versions of software, so there's no ambiguity between two -systems running the same version of |CL|. - -Updating -======== - -|CL| enforces regular updating of the OS by default and automatically -checks for updates against a version server. The content server provides the -file and metadata content for all versions and can be the same as the -version server. The content url server provides metadata in the form of -*manifests*, which list and describe file contents, symlinks, -and directories. Additionally, the actual content is provided to clients -in the form of archive files. - -Software updates with |CL| are also efficient. Unlike package-based -distributions, :command:`swupd` only updates files that have changed, rather -than entire packages. For example, it is quite common for an OS security -patch to be as small as 15 KB. Using binary deltas, |CL| is able to -apply only what is needed. - -For details on how to generate update content for |CL|, see the -:ref:`mixer ` tool. - -How it works -************ - -Prerequisites -============= - -* The device is on a well-connected network. -* The device is able to connect to an update server. The default server is: - http://update.clearlinux.org - -Updates -======= - -|CL| updates are automatic by default, but can be set to occur only on -demand. :command:`swupd` makes sure that regular updates are simple and -secure. It can also check the validity of currently installed files and -software, and can correct any problems. - -Manifests ---------- - -The |CL| software update content consists of data and metadata. The data is -the files that end up in the OS. The metadata contains relevant information to -properly provision the data to the OS file system, as well as update the -system and add or remove additional content to the OS. - -The manifests are mostly long lists of hashes that describe content. -Each bundle gets its own manifest file. There is a master manifest -file that describes all manifests to tie it all together. - -Fullfiles, packs, and delta packs ---------------------------------- - -To speed up updates and optimize content delivery, update data provisioned to -a system is obtained by one of the following methods: - -* *Fullfiles* are always generated for every file in every release. This - allows any |CL| to obtain the exact copy of the content - for each version directly. This is used if the OS verification - needs to replace a single file, for instance. - -* *Packs* are available for some releases. They combine many files to speed - up the creation of installation media and large updates. - -* *Delta packs* are an optimized version of packs that only contain updates - (binary diffs). They cannot be used without having the original file content. - -Bundle search -============= - -:command:`swupd` searches download manifest data for -bundles that match the term. Enter only one term, or hyphenated term, per -search. Use the command :command:`man swupd` to learn more. - -Only the base bundle is returned. Bundles can contain other bundles via -includes. For more details, see `Bundle Definition Files`_ and its -subdirectory bundles. - -Bundles that are already installed are marked **(installed)** in search -results. - -Optionally, you can review our `bundles`_ on GitHub\*. - -Examples -******** - -Example 1: Disable and enable automatic updates -=============================================== - -|CL| updates are automatic by default, but can be set to occur only -on demand. - -#. Verify your current auto-update setting. - - .. code-block:: bash - - sudo swupd autoupdate - - .. code-block:: console - - Enabled - -#. Disable automatic updates. - - .. code-block:: bash - - sudo swupd autoupdate --disable - - .. code-block:: console - - Warning: disabling automatic updates may take you out of compliance with your IT policy - - Running systemctl to disable updates - Created symlink /etc/systemd/system/swupd-update.service → /dev/null. - Created symlink /etc/systemd/system/swupd-update.timer → /dev/null. - -#. Check manually for updates. - - .. code-block:: bash - - sudo swupd check-update - -#. Install an update after identifying one that you need. - - .. code-block:: bash - - sudo swupd update --version - -#. Re-enable automatic installs. - - .. code-block:: bash - - sudo swupd autoupdate --enable - -.. _swupd-guide-example-install-bundle: - -Example 2: Find and install Kata Containers\* -============================================= - -Kata Containers is a popular container implementation. Unlike other -container implementations, each Kata Container has its own -kernel instance and runs on its own :abbr:`VM (Virtual Machine)` for -improved security. - -|CL| makes it very easy to install, since you only need to add -`one bundle`_ to use `Kata Containers`_: `containers-virt`, despite a -number of dependencies. Also, check out our tutorial: :ref:`kata`. - -#. Find the correct bundle. - - To return all possible matches for the search string, enter - :command:`swupd search`, followed by 'kata': - - .. code-block:: bash - - sudo swupd search kata - - The output should be similar to: - - .. code-block:: console - - Bundle with the best search result: - - containers-virt - Run container applications from Dockerhub in lightweight virtual machines - - This bundle can be installed with: - - swupd bundle-add containers-virt - - Alternative bundle options are - - cloud-native-basic - Contains ClearLinux native software for Cloud - - .. note:: - - If your search does not produce results with a specific term, shorten - the search term. For example, use *kube* instead of *kubernetes*. - -#. Add the bundle. - - .. code-block:: bash - - sudo swupd bundle-add containers-virt - - .. note:: - - To add multiple bundles, add a space followed by the bundle name. - - The output of a successful installation should be similar to: - - .. code-block:: console - - Downloading packs... - - Extracting containers-virt pack for version 24430 - ...50% - Extracting kernel-container pack for version 24430 - ...100% - Starting download of remaining update content. This may take a while... - ...100% - Finishing download of update content... - Installing bundle(s) files... - ...100% - Calling post-update helper scripts. - Successfully installed 1 bundle - -Example 3: Verify and correct system file mismatch -================================================== - -:command:`swupd` can determine whether system directories and files have -been added to, overwritten, removed, or modified (e.g., permissions). - -.. code-block:: bash - - sudo swupd diagnose - -All directories that are watched by :command:`swupd` are verified according -to the manifest data. Hash mismatches are flagged as follows: - -.. code-block:: console - - Verifying version 23300 - Verifying files - ...0% - Hash mismatch for file: /usr/bin/chardetect - ... - ... - Hash mismatch for file: /usr/lib/python3.6/site-packages/urllib3/util/wait.py - ...100% - Inspected 237180 files - 423 files did not match - Verify successful - -In this case, Python\* packages that were installed on top of the default -install were flagged as mismatched. :command:`swupd` can be directed to -ignore or fix issues based on command line options. - -:command:`swupd` can correct any issues it detects. Additional directives -can be added including a white list of directories to be ignored. - -The following command repairs issues, removes unknown items, and -ignores files or directories matching :file:`/usr/lib/python`: - -.. code-block:: bash - - sudo swupd repair --picky --picky-whitelist=/usr/lib/python - -Quick reference -*************** - -swupd info - Returns the currently installed version and update servers. - -swupd update - Updates to a specific version or updates to latest version if no - arguments are used. - -swupd bundle-list [--all] - Lists installed bundles. - -swupd bundle-add [-b] - Finds a bundle that contains your search term. - -swupd bundle-add - Adds a bundle. - -swupd bundle-remove - Removes a bundle. - -swupd --help - Lists additional :command:`swupd` commands. - -man swupd - Opens the :command:`swupd` man page. - -Refer to :command:`swupd` `source documentation`_ on GitHub for more details. - -Related topics -************** - -* :ref:`autospec` -* :ref:`mixer` -* :ref:`bundles` - -.. _source documentation: https://github.com/clearlinux/swupd-client/blob/master/docs/swupd.1.rst - -.. _Kata Containers: https://clearlinux.org/downloads/containers - -.. _one bundle: https://github.com/clearlinux/clr-bundles/blob/master/bundles/containers-virt - -.. _Bundle Definition Files: https://github.com/clearlinux/clr-bundles - -.. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles \ No newline at end of file diff --git a/source/tooling/tooling.rst b/source/tooling/tooling.rst deleted file mode 100644 index 8cac79a9..00000000 --- a/source/tooling/tooling.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _tooling: - -Tooling -####### - -Clear Linux is a little different from other distros. Here are some important tools and concepts for managing your install. - -.. toctree:: - :maxdepth: 1 - :glob: - - * - ../guides/telemetrics/telem-guide \ No newline at end of file diff --git a/source/tutorials/redis.rst b/source/tutorials/redis.rst deleted file mode 100644 index 1d86e4c9..00000000 --- a/source/tutorials/redis.rst +++ /dev/null @@ -1,215 +0,0 @@ -.. _redis: - -Run Redis on |CL-ATTR| -###################### - -Redis is an in-memory key:value store designed for quick lookups, accessible -over the network. In this tutorial, you'll install redis and launch a -redis-server on |CL|, plus learn a few basic redis commands. We also invite -you to pull our `Clear Linux Redis instance`_ on dockerhub\* for application -or infrastructure development. - -While the `redis data structure store`_ can serve as a NoSQL database for a Web application, it's also easy to integrate in an existing stack. For example, you could use the Redis caching layer for real-time responses on a leaderboard in a gaming app. Redis offers many client libraries with language-specific bindings for Python, Perl, Ruby, and more. - -.. contents:: - :local: - :depth: 1 - -Prerequisites -************* -* Install the `redis-native` bundle in |CL| -* Install the `containers-basic` bundle in |CL| (only required in Example 2) - -Install the redis bundle -************************ - -In |CL|, find redis in the `redis-native` bundle. - -#. Open a Terminal and login as an administrative user. - -#. Add :file:`redis-native`. - -.. code-block:: bash - - sudo swupd bundle-add redis-native - -.. note:: - - If the bundle already exists, no action is required. - -Start the redis-server -********************** - -A `systemd` service unit is available to control the redis server. -By default, redis runs on port 6379. - -#. Start the service. - - .. code-block:: bash - - systemctl start redis - - .. note:: - - To stop redis run :command:`systemctl stop redis`. - -#. Assure the service is running. - - .. code-block:: bash - - systemctl status redis - -#. Verify the redis-server sends a reply. - - .. code-block:: bash - - redis-cli ping - - .. note:: - - Expected output: `PONG`. - -#. Optional: If you wish to apply advanced configuration, copy the - `redis.conf` into /etc/ directory. - - .. code-block:: bash - - sudo cp /usr/share/defaults/etc/redis.conf /etc/ - -The redis-server is now ready to use on |CL|. Try some examples below. - -Example 1: Use the redis-cli and try commands -********************************************* - -One advantage of redis over other NoSQL databases is that developers can -easily access data structures like lists, sets, sorted sets, strings, and -hashes using collection operations commands similar to those found in many -programming languages. These exercises are inspired by `try redis io`_. - -After your `redis-server` is running, try some basic commands. - -#. Enter the `redis-cli`. It provides syntax suggestions as you type. - - .. code-block:: bash - - redis-cli - -#. SET key to hold string value. In the set create connections and increment. - - .. code-block:: bash - - SET server:name "clearlinux" - - .. code-block:: bash - - MGET server:name - - .. note:: - If the key does not exist or hold a key value, `nil` is returned. - - .. code-block:: bash - - SET connections 100 - - .. code-block:: bash - - INCR connections - - .. code-block:: bash - - INCR connections - - .. code-block:: bash - - DEL connections - -#. Create a `friends` list and insert new values at the end of the list. - - .. code-block:: bash - - RPUSH friends "Deb" - - .. code-block:: bash - - RPUSH friends "David" - - .. code-block:: bash - - RPUSH friends "Mary" - -#. Modify `friends` list, using a common slice method with a 0-index. - - .. code-block:: bash - - LRANGE friends 0 1 - - .. code-block:: bash - - LLEN friends - - .. code-block:: bash - - LPOP friends - - .. code-block:: bash - - RPOP friends - - .. code-block:: bash - - LLEN friends - -#. Consider using a hash, a very useful data type, which maps string fields - and string values, offering multiple lookup methods. - - Enter many user key:values with `HMSET`. Then try `HGET` and `HGETALL`. - - .. code-block:: bash - - HMSET user:1000 name "Robert Noyce" password "SuperEngi9eer" email "robert.noyce@intel.com" - - .. code-block:: bash - - HGET user:1000 name - - .. code-block:: bash - - HGET user:1000 email - - .. code-block:: bash - - HGETALL user:1000 - - -Example 2: Run the |CL| redis docker image -****************************************** - -We also provide a `Clear Linux Redis instance`_, which is -updated continuously and maintained by |CL| development. - -.. code-block:: bash - - sudo swupd bundle-add containers-basic - -.. code-block:: bash - - sudo systemctl start docker - -.. code-block:: bash - - sudo -E docker pull clearlinux/redis - -Next Steps -********** - -* Follow the `redis quickstart tutorial`_ to expand potential uses. - -* Learn to :ref:`docker`. - -.. _try redis io: https://try.redis.io/ - -.. _Clear Linux Redis instance: https://hub.docker.com/r/clearlinux/redis - -.. _redis data structure store: https://redis.io/ - -.. _redis quickstart tutorial: https://redis.io/topics/quickstart diff --git a/source/tutorials/tutorial-proxy.rst b/source/tutorials/tutorial-proxy.rst deleted file mode 100644 index eab5ca47..00000000 --- a/source/tutorials/tutorial-proxy.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. _tutorial-proxy: - -Setting up proxy -################ - -This tutorial shows you how to configure your system for use behind an -outbound proxy to access the Internet. - -|CL| :ref:`tooling` applications already benefit from the :ref:`autoproxy` -feature. - -.. contents:: - :local: - :depth: 1 - -Prerequisites -************* - -This tutorial assumes you have installed |CL| on your host system. -For detailed instructions on installing |CL| on a bare metal system, visit -the :ref:`bare metal installation guide `. - -Shells and programs in a desktop session -**************************************** - -Terminal -======== - -Add the following to your ~/.bashrc: - -.. code-block:: bash - - export http_proxy=http://your.http-proxy.url:port - export https_proxy=http://your.https-proxy.url:port - export ftp_proxy=http://your.ftp-proxy.url:port - export socks_proxy=http://your.socks-proxy.url:port - export no_proxy=".your-company-domain.com,localhost" - export HTTP_PROXY=$http_proxy - export HTTPS_PROXY=$https_proxy - export FTP_PROXY=$ftp_proxy - export SOCKS_PROXY=$socks_proxy - export NO_PROXY=$no_proxy - -wget -**** - -Run this command to enable downloading from websites from the terminal: - -.. code-block:: bash - - echo >> ~/.wgetrc <