mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-08-26 10:28:24 +00:00
Merge branch 'master' into kd-autospec-apply-guide-template
This commit is contained in:
michael vincerra
+46
-19
@@ -5,8 +5,11 @@ Install |CL-ATTR| from the live desktop beta image
|
||||
|
||||
The live desktop beta image allows you to boot |CL-ATTR| into a GNOME
|
||||
desktop without modifying the host system. Using the live image, you can
|
||||
explore the possibilities of developing with |CL|. You can also launch the
|
||||
new installer and install |CL| on your target system.
|
||||
explore the possibilities of developing with |CL|.
|
||||
|
||||
You can also launch the installer to install |CL| on your target system.
|
||||
If you proceed with installation, this document assumes you follow the
|
||||
`Recommended options`_.
|
||||
|
||||
.. contents:: :local:
|
||||
:depth: 1
|
||||
@@ -32,9 +35,7 @@ Preliminary steps
|
||||
|
||||
#. Follow your OS instructions to create a bootable USB drive.
|
||||
|
||||
* :ref:`bootable-usb-linux-all`
|
||||
* :ref:`bootable-usb-mac-all`
|
||||
* :ref:`bootable-usb-windows-all`
|
||||
* :ref:`bootable-usb`
|
||||
|
||||
Install from live image
|
||||
***********************
|
||||
@@ -86,18 +87,18 @@ Minimum installation requirements
|
||||
*********************************
|
||||
|
||||
To fulfill minimum installation requirements, complete the
|
||||
`Required options`_. `Advanced options`_ are optional.
|
||||
`Required options`_. We also encourage you to install `Recommended options`_ for a full desktop experience. `Advanced options`_ are optional.
|
||||
|
||||
.. note::
|
||||
|
||||
* The :kbd:`Install` button is only highlighted **after** you complete the
|
||||
`Required options`_, and after you enter required values in submenus.
|
||||
* The :kbd:`Install` button is **only highlighted after** you complete
|
||||
`Required options`_.
|
||||
|
||||
* You must choose whether or not to participate in :ref:`telemetrics`
|
||||
before you can finish installation.
|
||||
|
||||
* You may wish to `Test Network Settings`_ before you
|
||||
`Configure Network Interfaces`_. Assure that a ``Success`` message is received before installation.
|
||||
* You may `Test Network Settings`_ before installation
|
||||
`Configure Network Interfaces`_. Assure a *Success* message appears before installation.
|
||||
|
||||
Main Menu
|
||||
*********
|
||||
@@ -242,7 +243,7 @@ Configure Media
|
||||
|
||||
#. Select :kbd:`Enter` to :kbd:`Confirm`.
|
||||
|
||||
#. Choose one partitioning method and continue below:
|
||||
#. Select one partitioning method and continue:
|
||||
|
||||
* `Auto Partition`_
|
||||
* `Add Partition`_
|
||||
@@ -455,6 +456,22 @@ For more detailed information, visit our :ref:`telemetry-about` page.
|
||||
|
||||
Figure 14: Enable Telemetry
|
||||
|
||||
Recommended options
|
||||
*******************
|
||||
|
||||
After you complete the `Required options`_, we highly recommend completing
|
||||
a few `Advanced options`_ at minimum:
|
||||
|
||||
* `Bundle Selection`_ Add basic utlities and tools:
|
||||
|
||||
* :file:`desktop-autostart`
|
||||
* :file:`user-basic`
|
||||
|
||||
* `User Manager`_ Assign a new user with administrative rights
|
||||
* `Assign Hostname`_ Simplify your development environment
|
||||
|
||||
This document assumes you follow these additional steps.
|
||||
|
||||
Skip to finish installation
|
||||
===========================
|
||||
|
||||
@@ -462,10 +479,9 @@ After selecting values for all :guilabel:`Required options`, you may skip
|
||||
to `Finish installation`_.
|
||||
|
||||
Otherwise, continue below. In the Main Menu, select
|
||||
:guilabel:`Advanced options` to configure network interfaces or proxy
|
||||
settings, add bundles, add/manage users, add kernel arguments, and more.
|
||||
:guilabel:`Advanced options` for additional configuration.
|
||||
|
||||
Advanced Options
|
||||
Advanced options
|
||||
****************
|
||||
|
||||
Configure Network Interfaces
|
||||
@@ -588,12 +604,20 @@ Bundle Selection
|
||||
|
||||
#. Select :kbd:`Spacebar` to select the checkbox for each desired bundle.
|
||||
|
||||
#. We recommend adding :file:`desktop-autostart` and :file:`user-basic`.
|
||||
|
||||
.. figure:: figures/bare-metal-install-beta-19.png
|
||||
:scale: 100%
|
||||
:alt: Bundle Selection
|
||||
|
||||
Figure 19: Bundle Selection
|
||||
|
||||
.. note::
|
||||
|
||||
The default bundle choices and selections differ between the
|
||||
:file:`clear-<XXXXX>.live-desktop-beta.img` and the
|
||||
:file:`clear-<XXXXX>.installer.img`.
|
||||
|
||||
#. Select :kbd:`Confirm` or :kbd:`Cancel`.
|
||||
|
||||
You are returned to the :guilabel:`Advanced options` menu.
|
||||
@@ -815,17 +839,20 @@ Finish installation
|
||||
#. When you are satisfied with your installation configuration, navigate to
|
||||
:guilabel:`Install` and select :kbd:`Enter`.
|
||||
|
||||
#. Select :guilabel:`reboot`.
|
||||
|
||||
.. note::
|
||||
|
||||
When installation is finished, a ``reboot`` button appears.
|
||||
|
||||
#. Select ``reboot``.
|
||||
If you do not perform `Recommended options`_, upon rebooting, a
|
||||
:file:`login:` prompt will appear. At the prompt, enter `root` and change your password immediately.
|
||||
|
||||
#. When the system reboots, remove any installation media present.
|
||||
|
||||
**Congratulations!**
|
||||
.. note::
|
||||
|
||||
You have successfully installed |CL| on bare metal using the new installer.
|
||||
Allow time for the graphical login to appear. This shows the administrative user that you created in `Recommended options`_.
|
||||
|
||||
#. Log in as the adminstrative user.
|
||||
|
||||
Next steps
|
||||
**********
|
||||
|
||||
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 170 KiB After Width: | Height: | Size: 147 KiB |
@@ -38,7 +38,7 @@ Optionally, you can use this command:
|
||||
|
||||
#. Follow your OS instructions to create a bootable USB drive.
|
||||
|
||||
* :ref:`bootable-usb-beta-all`
|
||||
* :ref:`bootable-usb`
|
||||
|
||||
#. After downloading the image, verify and decompress the file per your OS.
|
||||
|
||||
|
||||
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 170 KiB After Width: | Height: | Size: 147 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 96 KiB After Width: | Height: | Size: 96 KiB |
@@ -1,203 +0,0 @@
|
||||
.. _bootable-usb-beta-all:
|
||||
|
||||
Create a bootable USB on your OS
|
||||
################################
|
||||
|
||||
Follow these instructions to create a bootable |CL-ATTR| USB drive based on
|
||||
your OS.
|
||||
|
||||
* :ref:`bootable-usb-linux-all`
|
||||
* :ref:`bootable-usb-mac-all`
|
||||
* :ref:`bootable-usb-windows-all`
|
||||
|
||||
Return to :ref:`get-started`
|
||||
|
||||
Requirements:
|
||||
*************
|
||||
|
||||
* Use a **16GB** or larger USB drive.
|
||||
|
||||
.. _bootable-usb-linux-all:
|
||||
|
||||
Create a bootable USB drive on Linux
|
||||
************************************
|
||||
|
||||
.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst
|
||||
:Start-after: verify-linux:
|
||||
|
||||
|
||||
Burn the |CL| image onto a USB drive
|
||||
====================================
|
||||
|
||||
.. caution::
|
||||
|
||||
|CAUTION-BACKUP-USB|
|
||||
|
||||
#. Open a terminal emulator and get root privilege.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo -s
|
||||
|
||||
#. Go to the directory with the decompressed image.
|
||||
#. Plug in the USB drive.
|
||||
#. Identify the USB drive using the :command:`lsblk` command. This shows all
|
||||
drives attached to the system, including the primary hard disk. In the
|
||||
example output below, there are 4 drives
|
||||
(`/dev/sda`, `/dev/sdb`, `/dev/sdc`, and `/dev/sdd`) attached, where
|
||||
`/dev/sda` is primary drive in this case. The remaining are 3 USB drives.
|
||||
The output also shows the mounted partitions (under the `MOUNTPOINT`
|
||||
column) for each drive.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
lsblk
|
||||
|
||||
Example output:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
|
||||
sdd 8:48 1 15G 0 disk
|
||||
├─sdd2 8:50 1 5G 0 part /run/media/user1/960c184f-3bb7-42b7-bcaf-0c1282
|
||||
├─sdd3 8:51 1 8G 0 part /run/media/user1/704f3382-b26d-4f34-af1b-cb9aab
|
||||
└─sdd1 8:49 1 2G 0 part
|
||||
sdb 8:16 1 14.8G 0 disk
|
||||
└─sdb1 8:17 1 14.8G 0 part /run/media/user1/PATRIOT_USB
|
||||
sdc 8:32 1 7.3G 0 disk
|
||||
└─sdc1 8:33 1 7.3G 0 part /run/media/user1/LINUX MINT
|
||||
sda 8:0 0 335.4G 0 disk
|
||||
├─sda4 8:4 0 28G 0 part
|
||||
├─sda2 8:2 0 3.7G 0 part [SWAP]
|
||||
├─sda7 8:7 0 6G 0 part /home
|
||||
├─sda5 8:5 0 1G 0 part /boot
|
||||
├─sda3 8:3 0 954M 0 part /boot/efi
|
||||
├─sda1 8:1 0 28G 0 part
|
||||
├─sda8 8:8 0 30G 0 part /
|
||||
└─sda6 8:6 0 7.9G 0 part [SWAP]
|
||||
|
||||
#. Before an image can be burned onto a USB drive, it should be un-mounted.
|
||||
Some Linux* distros may automatically mount a USB drive when it is plugged
|
||||
in. To unmount, use the :command:`umount` command followed by the device
|
||||
identifier/partition. For example: From the above :command:`lsblk` output,
|
||||
`/dev/sdd` has 2 mounted partitions. To unmount them, enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
umount /dev/sdd2
|
||||
umount /dev/sdd3
|
||||
|
||||
#. Burn the image onto the USB drive. The command-line example below burns an
|
||||
uncompressed image onto `/dev/sdd`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
dd if=./clear-[version number]-[image type] of=/dev/sdd bs=4M status=progress
|
||||
|
||||
.. _bootable-usb-mac-all:
|
||||
|
||||
Create a bootable USB drive on macOS*
|
||||
*************************************
|
||||
|
||||
.. include:: ../../guides/maintenance/download-verify-decompress-mac.rst
|
||||
:start-after: verify-mac:
|
||||
|
||||
|
||||
Burn the |CL| image onto a USB drive
|
||||
====================================
|
||||
|
||||
.. caution::
|
||||
|
||||
|CAUTION-BACKUP-USB|
|
||||
|
||||
#. Launch the Terminal app.
|
||||
#. Go to the directory with the decompressed image.
|
||||
#. Plug in a USB drive and get its identifier by entering the command
|
||||
:command:`diskutil list`. See Figure 1.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
diskutil list
|
||||
|
||||
.. figure:: figures/bootable-usb-mac-1.png
|
||||
:scale: 100 %
|
||||
:alt: Get USB drive identifier
|
||||
|
||||
Figure 1: macOS* - Get USB drive identifier
|
||||
|
||||
#. Unmount the USB drive identified in the previous step. The command-line
|
||||
example below umounts `/dev/disk2`:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
diskutil umountDisk /dev/disk2
|
||||
|
||||
#. Burn the image onto the drive using the :command:`dd` command. The
|
||||
command-line example below burns an uncompressed image onto `/dev/disk2`:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo dd if=./clear-[version number]-[image type] of=/dev/rdisk2 bs=4m
|
||||
|
||||
|
||||
Adding an ‘r’ in front of the disk identifier should help speed up the
|
||||
imaging process.
|
||||
|
||||
You can press :kbd:`<CTL>-T` to check imaging progress.
|
||||
|
||||
#. Eject the USB drive.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
diskutil eject /dev/disk2
|
||||
|
||||
.. _bootable-usb-windows-all:
|
||||
|
||||
Create a bootable USB drive on Windows\*
|
||||
****************************************
|
||||
|
||||
.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst
|
||||
:Start-after: verify-windows:
|
||||
|
||||
Burn the |CL| image onto a USB drive
|
||||
====================================
|
||||
|
||||
.. caution::
|
||||
|
||||
|CAUTION-BACKUP-USB|
|
||||
|
||||
#. Download the `Rufus`_ utility to burn the image onto a USB drive.
|
||||
|
||||
#. Plug in the USB drive and open Rufus.
|
||||
|
||||
#. Click the :guilabel:`SELECT` button. See Figure 1.
|
||||
|
||||
.. figure:: figures/bootable-usb-windows-1.png
|
||||
:scale: 80 %
|
||||
:alt: Rufus utility - Click the SELECT button
|
||||
|
||||
Figure 1: Rufus utility - Click the SELECT button
|
||||
|
||||
#. Find and select the previously extracted |CL| image file.
|
||||
Then, click the :guilabel:`Open` button. See Figure 2.
|
||||
|
||||
.. figure:: figures/bootable-usb-windows-2.png
|
||||
:scale: 80 %
|
||||
:alt: Rufus utility - Show and select |CL| image file
|
||||
|
||||
Figure 2: Rufus utility - Show and select |CL| image file
|
||||
|
||||
#. Click the :guilabel:`START` button. See Figure 3.
|
||||
|
||||
.. figure:: figures/bootable-usb-windows-3.png
|
||||
:scale: 80 %
|
||||
:alt: Rufus utility - Click the START button
|
||||
|
||||
Figure 3: Rufus utility - Click START button
|
||||
|
||||
Return to install from live image
|
||||
*********************************
|
||||
|
||||
Return to :ref:`get-started`
|
||||
|
||||
.. _Rufus: https://rufus.ie/
|
||||
@@ -1,105 +0,0 @@
|
||||
.. _bootable-usb-linux:
|
||||
|
||||
Create a bootable USB drive on Linux\*
|
||||
######################################
|
||||
|
||||
Follow these instructions to create a bootable |CL-ATTR| USB drive.
|
||||
Use an **8GB** or larger USB drive. Download either a live image,
|
||||
``clear-<version>-live.img.xz`` or an installer image,
|
||||
``clear-<version>-installer.img.xz``, from our `image`_ download page.
|
||||
|
||||
Instructions are also available for other operating systems:
|
||||
|
||||
* :ref:`bootable-usb-mac`
|
||||
* :ref:`bootable-usb-windows`
|
||||
|
||||
.. include:: ../../reference/image-types.rst
|
||||
:start-after: incl-image-filename:
|
||||
:end-before: incl-image-filename-end:
|
||||
|
||||
.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst
|
||||
:Start-after: verify-linux:
|
||||
|
||||
.. _copy-usb-linux:
|
||||
|
||||
Burn the |CL| image onto a USB drive
|
||||
************************************
|
||||
|
||||
.. caution::
|
||||
|
||||
|CAUTION-BACKUP-USB|
|
||||
|
||||
#. Open a terminal emulator and get root privilege.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo -s
|
||||
|
||||
#. Go to the directory with the decompressed image.
|
||||
#. Plug in the USB drive.
|
||||
#. Identify the USB drive using the :command:`lsblk` command. This shows all
|
||||
drives attached to the system, including the primary hard disk. In the
|
||||
example output below, there are 4 drives
|
||||
(`/dev/sda`, `/dev/sdb`, `/dev/sdc`, and `/dev/sdd`) attached, where
|
||||
`/dev/sda` is primary drive in this case. The remaining are 3 USB drives.
|
||||
The output also shows the mounted partitions (under the `MOUNTPOINT`
|
||||
column) for each drive.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
lsblk
|
||||
|
||||
Example output:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
|
||||
sdd 8:48 1 15G 0 disk
|
||||
├─sdd2 8:50 1 5G 0 part /run/media/user1/960c184f-3bb7-42b7-bcaf-0c1282
|
||||
├─sdd3 8:51 1 8G 0 part /run/media/user1/704f3382-b26d-4f34-af1b-cb9aab
|
||||
└─sdd1 8:49 1 2G 0 part
|
||||
sdb 8:16 1 14.8G 0 disk
|
||||
└─sdb1 8:17 1 14.8G 0 part /run/media/user1/PATRIOT_USB
|
||||
sdc 8:32 1 7.3G 0 disk
|
||||
└─sdc1 8:33 1 7.3G 0 part /run/media/user1/LINUX MINT
|
||||
sda 8:0 0 335.4G 0 disk
|
||||
├─sda4 8:4 0 28G 0 part
|
||||
├─sda2 8:2 0 3.7G 0 part [SWAP]
|
||||
├─sda7 8:7 0 6G 0 part /home
|
||||
├─sda5 8:5 0 1G 0 part /boot
|
||||
├─sda3 8:3 0 954M 0 part /boot/efi
|
||||
├─sda1 8:1 0 28G 0 part
|
||||
├─sda8 8:8 0 30G 0 part /
|
||||
└─sda6 8:6 0 7.9G 0 part [SWAP]
|
||||
|
||||
#. Before an image can be burned onto a USB drive, it should be un-mounted.
|
||||
Some Linux distros may automatically mount a USB drive when it is plugged
|
||||
in. To unmount, use the :command:`umount` command followed by the device
|
||||
identifier/partition. For example: From the above :command:`lsblk` output,
|
||||
`/dev/sdd` has 2 mounted partitions. To unmount them, enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
umount /dev/sdd2
|
||||
umount /dev/sdd3
|
||||
|
||||
#. Burn the image onto the USB drive. The command-line example below burns an
|
||||
uncompressed image onto `/dev/sdd`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
dd if=./clear-[version number]-[image type] of=/dev/sdd bs=4M status=progress
|
||||
|
||||
.. _usb-next:
|
||||
|
||||
Next steps
|
||||
**********
|
||||
|
||||
With a bootable |CL| USB drive, you can:
|
||||
|
||||
* :ref:`bare-metal-install`
|
||||
* :ref:`boot-live-image`
|
||||
* :ref:`multi-boot`
|
||||
|
||||
.. _image: https://download.clearlinux.org/image
|
||||
.. _releases: https://download.clearlinux.org/releases
|
||||
@@ -1,81 +0,0 @@
|
||||
.. _bootable-usb-mac:
|
||||
|
||||
Create a bootable USB drive on macOS
|
||||
####################################
|
||||
|
||||
Follow these instructions to create a bootable |CL-ATTR| USB drive.
|
||||
Use an **8GB** or larger USB drive. Download either a live image,
|
||||
``clear-<version>-live.img.xz`` or an installer image,
|
||||
``clear-<version>-installer.img.xz``, from our `image`_ download page.
|
||||
|
||||
Instructions are also available for other operating systems:
|
||||
|
||||
* :ref:`bootable-usb-linux`
|
||||
* :ref:`bootable-usb-windows`
|
||||
|
||||
.. include:: ../../reference/image-types.rst
|
||||
:start-after: incl-image-filename:
|
||||
:end-before: incl-image-filename-end:
|
||||
|
||||
.. include:: ../../guides/maintenance/download-verify-decompress-mac.rst
|
||||
:start-after: verify-mac:
|
||||
|
||||
|
||||
Burn the |CL| image onto a USB drive
|
||||
************************************
|
||||
|
||||
.. caution::
|
||||
|
||||
|CAUTION-BACKUP-USB|
|
||||
|
||||
#. Launch the Terminal app.
|
||||
#. Go to the directory with the decompressed image.
|
||||
#. Plug in a USB drive and get its identifier by entering the command
|
||||
:command:`diskutil list`. See Figure 1.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
diskutil list
|
||||
|
||||
.. figure:: figures/bootable-usb-mac-1.png
|
||||
:scale: 100 %
|
||||
:alt: Get USB drive identifier
|
||||
|
||||
Figure 1: macOS - Get USB drive identifier
|
||||
|
||||
#. Unmount the USB drive identified in the previous step. The command-line
|
||||
example below umounts `/dev/disk2`:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
diskutil umountDisk /dev/disk2
|
||||
|
||||
#. Burn the image onto the drive using the :command:`dd` command. The
|
||||
command-line example below burns an uncompressed image onto `/dev/disk2`:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo dd if=./clear-[version number]-[image type] of=/dev/rdisk2 bs=4m
|
||||
|
||||
|
||||
Adding an ‘r’ in front of the disk identifier should help speed up the
|
||||
imaging process.
|
||||
|
||||
You can press :kbd:`<CTL>-T` to check imaging progress.
|
||||
|
||||
#. Eject the USB drive.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
diskutil eject /dev/disk2
|
||||
|
||||
Next steps
|
||||
**********
|
||||
|
||||
With a bootable |CL| USB drive, you can:
|
||||
|
||||
* :ref:`bare-metal-install`
|
||||
* :ref:`boot-live-image`
|
||||
* :ref:`multi-boot`
|
||||
|
||||
.. _image: https://download.clearlinux.org/image
|
||||
@@ -1,69 +0,0 @@
|
||||
.. _bootable-usb-windows:
|
||||
|
||||
Create a bootable USB drive on Windows\*
|
||||
########################################
|
||||
|
||||
Follow these instructions to create a bootable |CL-ATTR| USB drive.
|
||||
Use an **8GB** or larger USB drive. Download either a live image,
|
||||
``clear-<version>-live.img.xz`` or an installer image,
|
||||
``clear-<version>-installer.img.xz``, from our `image`_ download page.
|
||||
|
||||
Instructions are also available for other operating systems:
|
||||
|
||||
* :ref:`bootable-usb-mac`
|
||||
* :ref:`bootable-usb-linux`
|
||||
|
||||
.. include:: ../../reference/image-types.rst
|
||||
:start-after: incl-image-filename:
|
||||
:end-before: incl-image-filename-end:
|
||||
|
||||
.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst
|
||||
:Start-after: verify-windows:
|
||||
|
||||
Burn the |CL| image onto a USB drive
|
||||
************************************
|
||||
|
||||
.. caution::
|
||||
|
||||
|CAUTION-BACKUP-USB|
|
||||
|
||||
#. Download the `Rufus`_ utility to burn the image onto a USB drive.
|
||||
|
||||
#. Plug in the USB drive and open Rufus.
|
||||
|
||||
#. Click the :guilabel:`SELECT` button. See Figure 1.
|
||||
|
||||
.. figure:: figures/bootable-usb-windows-1.png
|
||||
:scale: 80 %
|
||||
:alt: Rufus utility - Click the SELECT button
|
||||
|
||||
Figure 1: Rufus utility - Click the SELECT button
|
||||
|
||||
#. Find and select the previously extracted |CL| image file.
|
||||
Then, click the :guilabel:`Open` button. See Figure 2.
|
||||
|
||||
.. figure:: figures/bootable-usb-windows-2.png
|
||||
:scale: 80 %
|
||||
:alt: Rufus utility - Show and select |CL| image file
|
||||
|
||||
Figure 2: Rufus utility - Show and select |CL| image file
|
||||
|
||||
#. Click the :guilabel:`START` button. See Figure 3.
|
||||
|
||||
.. figure:: figures/bootable-usb-windows-3.png
|
||||
:scale: 80 %
|
||||
:alt: Rufus utility - Click the START button
|
||||
|
||||
Figure 3: Rufus utility - Click START button
|
||||
|
||||
Next steps
|
||||
**********
|
||||
|
||||
With a bootable |CL| USB drive, you can:
|
||||
|
||||
* :ref:`bare-metal-install`
|
||||
* :ref:`boot-live-image`
|
||||
* :ref:`multi-boot`
|
||||
|
||||
.. _Rufus: http://rufus.akeo.ie/
|
||||
.. _image: https://download.clearlinux.org/image
|
||||
@@ -1,32 +1,192 @@
|
||||
.. _bootable-usb:
|
||||
|
||||
Create a bootable |CL-ATTR| USB drive
|
||||
#####################################
|
||||
Create a bootable USB drive
|
||||
###########################
|
||||
|
||||
Instructions to create a |CL-ATTR| USB drive vary depending on your operating
|
||||
system.
|
||||
system. Follow the instructions applicable to your system:
|
||||
|
||||
.. _download-usb-image:
|
||||
* :ref:`bootable-usb-linux`
|
||||
* :ref:`bootable-usb-mac`
|
||||
* :ref:`bootable-usb-windows`
|
||||
|
||||
Download the latest |CL| image
|
||||
******************************
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
There are 2 types of |CL| images suitable for burning onto and running
|
||||
off a USB drive:
|
||||
* Use an **8GB** or larger USB drive.
|
||||
* `Download`_ the |CL| live boot image or interactive installer image.
|
||||
|
||||
* Live image: :file:`clear-[version number]-live.img.xz`
|
||||
* Installer image: :file:`clear-[version number]-installer.img.xz`
|
||||
.. _bootable-usb-linux:
|
||||
|
||||
Go to the |CL| `image`_ repository and download the desired type.
|
||||
Create a bootable USB drive on Linux\*
|
||||
**************************************
|
||||
|
||||
With the appropriate image downloaded, choose the step-by-step instructions
|
||||
applicable to your system:
|
||||
Make sure you have have completed all `Prerequisites`_.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
Before burning the image onto your USB drive,
|
||||
:ref:`verify and decompress your image <verify-linux>`.
|
||||
|
||||
bootable-usb-linux
|
||||
bootable-usb-windows
|
||||
bootable-usb-mac
|
||||
Burn the |CL| image onto a USB drive
|
||||
====================================
|
||||
|
||||
.. _image: https://download.clearlinux.org/image
|
||||
.. caution::
|
||||
|
||||
|CAUTION-BACKUP-USB|
|
||||
|
||||
#. Open a terminal emulator and get root privilege.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo -s
|
||||
|
||||
#. Go to the directory with the decompressed image.
|
||||
|
||||
#. Plug in the USB drive.
|
||||
|
||||
#. Identify the USB drive using the :command:`lsblk` command. This shows all
|
||||
drives attached to the system, including the primary hard disk. In the
|
||||
example output below, there are 4 drives
|
||||
(`/dev/sda`, `/dev/sdb`, `/dev/sdc`, and `/dev/sdd`) attached, where
|
||||
`/dev/sda` is primary drive. The remaining are three USB drives. The output
|
||||
also shows the mounted partitions (under the `MOUNTPOINT` column) for each
|
||||
drive.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
lsblk
|
||||
|
||||
Example output:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
|
||||
sdd 8:48 1 15G 0 disk
|
||||
├─sdd2 8:50 1 5G 0 part /run/media/user1/960c184f-3bb7-42b7-bcaf-0c1282
|
||||
├─sdd3 8:51 1 8G 0 part /run/media/user1/704f3382-b26d-4f34-af1b-cb9aab
|
||||
└─sdd1 8:49 1 2G 0 part
|
||||
sdb 8:16 1 14.8G 0 disk
|
||||
└─sdb1 8:17 1 14.8G 0 part /run/media/user1/PATRIOT_USB
|
||||
sdc 8:32 1 7.3G 0 disk
|
||||
└─sdc1 8:33 1 7.3G 0 part /run/media/user1/LINUX MINT
|
||||
sda 8:0 0 335.4G 0 disk
|
||||
├─sda4 8:4 0 28G 0 part
|
||||
├─sda2 8:2 0 3.7G 0 part [SWAP]
|
||||
├─sda7 8:7 0 6G 0 part /home
|
||||
├─sda5 8:5 0 1G 0 part /boot
|
||||
├─sda3 8:3 0 954M 0 part /boot/efi
|
||||
├─sda1 8:1 0 28G 0 part
|
||||
├─sda8 8:8 0 30G 0 part /
|
||||
└─sda6 8:6 0 7.9G 0 part [SWAP]
|
||||
|
||||
#. You must unmount a USB drive before you can burn an image onto it. Note that
|
||||
some Linux distros automatically mount a USB drive when it is plugged in.
|
||||
Unmount a USB drive with the :command:`umount` command followed by the device
|
||||
identifier/partition. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
umount /dev/sdd2
|
||||
umount /dev/sdd3
|
||||
|
||||
#. Burn the image onto the USB drive. The example below burns an uncompressed
|
||||
image onto `<your USB device>`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
dd if=./clear-[version number]-[image type] of=<your USB device> bs=4M status=progress
|
||||
|
||||
.. _bootable-usb-mac:
|
||||
|
||||
Create a bootable USB drive on macOS\*
|
||||
**************************************
|
||||
|
||||
Make sure you have have completed all `Prerequisites`_.
|
||||
|
||||
Before burning the image onto your USB drive,
|
||||
:ref:`verify and decompress your image <verify-mac>`.
|
||||
|
||||
Burn the |CL| image onto a USB drive
|
||||
====================================
|
||||
|
||||
.. caution::
|
||||
|
||||
|CAUTION-BACKUP-USB|
|
||||
|
||||
#. Launch the Terminal app.
|
||||
|
||||
#. Go to the directory with the decompressed image.
|
||||
|
||||
#. Plug in a USB drive and get its identifier:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
diskutil list
|
||||
|
||||
This will list available disks and their partitions, as shown in Figure 1.
|
||||
|
||||
.. figure:: figures/bootable-usb-mac-1.png
|
||||
:scale: 100 %
|
||||
:alt: Get USB drive identifier
|
||||
|
||||
Figure 1: macOS - Get USB drive identifier
|
||||
|
||||
#. Unmount the USB drive identified in the previous step. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
diskutil umountDisk /dev/disk2
|
||||
|
||||
#. Burn the image onto the drive using the :command:`dd` command. The example
|
||||
below burns an uncompressed image onto `<your USB device>`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo dd if=./clear-[version number]-[image type] of=<your USB device> bs=4m
|
||||
|
||||
To speed up the imaging process, add an ‘r’ in front of the disk identifier.
|
||||
For example `/dev/rdisk2`.
|
||||
|
||||
Press :kbd:`<CTL>-T` to check imaging progress.
|
||||
|
||||
#. Eject the USB drive.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
diskutil eject /dev/disk2
|
||||
|
||||
.. _bootable-usb-windows:
|
||||
|
||||
Create a bootable USB drive on Windows\*
|
||||
****************************************
|
||||
|
||||
Make sure you have have completed all `Prerequisites`_.
|
||||
|
||||
Before burning the image onto your USB drive,
|
||||
:ref:`verify and decompress your image <verify-windows>`.
|
||||
|
||||
Burn the |CL| image onto a USB drive
|
||||
====================================
|
||||
|
||||
.. caution::
|
||||
|
||||
|CAUTION-BACKUP-USB|
|
||||
|
||||
#. Download the `Rufus`_ utility to burn the image onto a USB drive.
|
||||
|
||||
#. Plug in the USB drive and open Rufus.
|
||||
|
||||
#. Under `Boot selection`, click the :guilabel:`SELECT` button.
|
||||
|
||||
#. Find and select the previously extracted |CL| image file.
|
||||
|
||||
#. Click the :guilabel:`START` button. See Figure 2.
|
||||
|
||||
.. figure:: figures/bootable-usb-windows-3.png
|
||||
:scale: 80 %
|
||||
:alt: Rufus utility
|
||||
|
||||
Figure 2: Rufus utility
|
||||
|
||||
|
||||
.. _Rufus: https://rufus.ie/
|
||||
.. _Download: https://clearlinux.org/downloads
|
||||
|
||||
@@ -17,7 +17,6 @@ Pre-install
|
||||
|
||||
compatibility-check
|
||||
bootable-usb/bootable-usb
|
||||
bootable-usb/bootable-usb-beta-all
|
||||
|
||||
Install |CL|
|
||||
************
|
||||
|
||||
@@ -38,7 +38,9 @@ Create a virtual machine in VirtualBox
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
curl -O https://download.clearlinux.org/image/$(curl https://download.clearlinux.org/image/latest-images | grep live)
|
||||
curl -O https://download.clearlinux.org/image/$(curl https://download.clearlinux.org/image/latest-images | grep 'live\.')
|
||||
|
||||
.. note:: `grep` functionality may differ depending on your CLI.
|
||||
|
||||
#. Decompress the downloaded image. Uncompressed image size is ~ **5GB**.
|
||||
|
||||
|
||||
@@ -6,22 +6,15 @@ Create and enable a new user space
|
||||
This section provides steps to complete the following basic setup tasks for
|
||||
a newly installed |CL-ATTR| system:
|
||||
|
||||
* Create a new user.
|
||||
* Update the OS to its most current version using `swupd`.
|
||||
* Install the most common applications for system administrators and
|
||||
developers using bundles.
|
||||
* Set up a new user and add the new user to the `wheel` group.
|
||||
* Install a GUI to test `sudo` privileges.
|
||||
|
||||
.. note::
|
||||
Log in as the root user to complete the tasks in this
|
||||
section.
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Create a new user
|
||||
******************
|
||||
*****************
|
||||
|
||||
To create a new user and set a password for that user, enter the following
|
||||
commands as a root user:
|
||||
commands as a `root` user:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -33,29 +26,8 @@ including the password for that user. The :command:`passwd` command prompts
|
||||
you to enter a new password. Retype the new password for the new user
|
||||
account just created.
|
||||
|
||||
Install and update the OS software to its current version
|
||||
*********************************************************
|
||||
|
||||
|CL| has a unique application and architecture to add and update applications
|
||||
and to perform system updates called software update utility or
|
||||
:command:`swupd`. Software applications are installed as bundles using the
|
||||
sub-command :command:`bundle-add`.
|
||||
|
||||
The `sysadmin-basic` bundle installs the vast majority of
|
||||
applications useful to a system administrator.
|
||||
Install the `sysadmin-basic` bundle:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
swupd bundle-add sysadmin-basic
|
||||
|
||||
We provide the full list of bundles and packages installed with the
|
||||
`sysadmin-basic`_ bundle. Additionally, we have listed
|
||||
`all bundles`_ for |CL|, active or deprecated. Click any bundle on the
|
||||
list to view the manifest of the bundle.
|
||||
|
||||
Set up a new user and add the new user to the `wheel` group
|
||||
***********************************************************
|
||||
Add the new user to the `wheel` group
|
||||
*************************************
|
||||
|
||||
Before logging off as root and logging into your new user account,
|
||||
enable the :command:`sudo` command for your new `<userid>`.
|
||||
@@ -73,65 +45,50 @@ To be able to execute all applications with root privileges, add the
|
||||
|
||||
To log off as root, enter :command:`exit`.
|
||||
|
||||
The command will bring you back to the `login:` prompt.
|
||||
|
||||
#. Enter the new `<userid>` and the password created earlier.
|
||||
|
||||
You will now be in the home directory of `<userid>`. The bundle
|
||||
`sysadmin-basic`_ contains the majority of applications that a system
|
||||
administrator would want, but it does not include a graphical user
|
||||
interface. The `desktop` bundle includes the GNOME\* Display Manager and
|
||||
additional supporting applications.
|
||||
You will now be in the home directory of `<userid>`.
|
||||
|
||||
Install a GUI to test `sudo` privileges
|
||||
========================================
|
||||
.. note::
|
||||
Install and update the OS software to its current version
|
||||
*********************************************************
|
||||
|
||||
If you are following this sequence after just setting up the
|
||||
pre-configured VMware\* virtual machine from the repo, you must
|
||||
:ref:`increase virtual disk size<increase-virtual-disk-size>` or the
|
||||
following step will fail.
|
||||
The |CL| software utility :ref:`swupd <swupd-guide>` allows you to perform system updates while reaping the benefits of upstream development.
|
||||
|
||||
To test the :command:`sudo` command and ensure it is set up correctly,
|
||||
install the GNOME Display Manager (gdm) and start it.
|
||||
To update your newly installed OS, run:
|
||||
|
||||
#. To install the the GNOME Display Manager using :command:`swupd`, enter
|
||||
the following command:
|
||||
.. code-block:: bash
|
||||
|
||||
.. code-block:: bash
|
||||
sudo swupd update
|
||||
|
||||
sudo swupd bundle-add desktop
|
||||
Add a bundle
|
||||
************
|
||||
|
||||
#. To start the GNOME Display Manager, enter the following command:
|
||||
Software applications are installed as bundles using the command
|
||||
:command:`swupd bundle-add`. Experienced Linux* users might compare `swupd`
|
||||
to running :command:`apt-get` or :command:`yum install` for package
|
||||
management. Yet |CL| manages packages at the level of bundles, which
|
||||
are integrated stacks of packages.
|
||||
|
||||
.. code-block:: bash
|
||||
For example, the `sysadmin-basic` bundle installs the majority of applications useful to a system administrator. To install it, enter:
|
||||
|
||||
systemctl start gdm
|
||||
.. code-block:: bash
|
||||
|
||||
#. The system prompts you to authenticate the user. Enter the password for
|
||||
`<userid>`, and the GNOME Display Manager starts as shown in Figure
|
||||
1:
|
||||
swupd bundle-add sysadmin-basic
|
||||
|
||||
.. figure:: figures/gnomedt.png
|
||||
:scale: 50 %
|
||||
:alt: Gnome Desktop
|
||||
View a full list of bundles and packages installed with the `sysadmin-basic`_ bundle. You can also view `all bundles`_ for |CL|, active or deprecated.
|
||||
|
||||
Figure 1: :guilabel:`Gnome Desktop`
|
||||
Expand your knowledge of :command:`swupd` and check out our developer resources:
|
||||
|
||||
#. To start the GNOME Display Manager each time you start your system, enter
|
||||
the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
systemctl enable gdm
|
||||
* :ref:`swupd-guide`
|
||||
* :ref:`developer-workstation`
|
||||
|
||||
Next steps
|
||||
***********
|
||||
**********
|
||||
|
||||
With your system now running |CL|, many opportunities exist.
|
||||
Check out our guides and tutorials.
|
||||
|
||||
Visit the :ref:`tutorials <tutorials>` page for examples on using your |CL|
|
||||
system.
|
||||
* :ref:`guides`
|
||||
* :ref:`tutorials`
|
||||
|
||||
.. _`sysadmin-basic`:
|
||||
https://github.com/clearlinux/clr-bundles/blob/master/bundles/sysadmin-basic
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
.. _ister:
|
||||
|
||||
ister.py image builder
|
||||
######################
|
||||
|
||||
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.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Description
|
||||
***********
|
||||
|
||||
|CL| is a rolling release and produces on average 10 releases per week using the
|
||||
ister tool. With each release we produce multiple
|
||||
`image types for different environments`_ and use cases such as installers,
|
||||
Hyper-V, KVM, or VMWare.
|
||||
|
||||
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<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<mixer>` guide
|
||||
for instruction on using ister to build an image for a custom mix.
|
||||
|
||||
Examples
|
||||
********
|
||||
|
||||
Recreate an upstream image
|
||||
==========================
|
||||
|
||||
The published configuration files for upstream images may be used to recreate an
|
||||
image, for example when you want to:
|
||||
|
||||
* Use an older version of |CL| and the image is no longer available (only after
|
||||
March 2017).
|
||||
* Customize the partitions of an image.
|
||||
* Customize the bundles preinstalled in an image.
|
||||
* Run your own post installation script.
|
||||
|
||||
|
||||
Follow these steps to recreate an upstream image based on the image's JSON
|
||||
configuration file:
|
||||
|
||||
#. Install the :command:`os-installer` bundle. Refer to `Install a bundle`_ for
|
||||
more details.
|
||||
|
||||
#. Download the `ister.py tool`_ and grant it sudo privileges.
|
||||
|
||||
#. Download the JSON configuration file for the desired image:
|
||||
|
||||
* `Configuration files for the current release`_
|
||||
* `Previous releases`_ (only after March 2017)
|
||||
|
||||
For a previous release, navigate to `Previous releases`_, select the version
|
||||
you want, and find the JSON configuration file under
|
||||
:file:`/clear/config/image`. For example:
|
||||
``https://cdn.download.clearlinux.org/releases/15700/clear/config/image/``
|
||||
|
||||
#. 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
|
||||
process. If it does, download the script and make it executable.
|
||||
|
||||
#. Edit the JSON configuration file as needed.
|
||||
|
||||
#. If your configuration file has an accompanying "PostNonChroot" script, change
|
||||
the default path of the script to match your path.
|
||||
|
||||
#. Generate the new image with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo ister.py -t [JSON configuration]
|
||||
|
||||
Related topics
|
||||
**************
|
||||
|
||||
* :ref:`mixer`
|
||||
* :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
|
||||
@@ -0,0 +1,447 @@
|
||||
.. _kernel-development:
|
||||
|
||||
Kernel development
|
||||
##################
|
||||
|
||||
This document shows how to obtain and compile a Linux* kernel source
|
||||
using |CL-ATTR| development tooling.
|
||||
|
||||
The `kernels available`_ in |CL| aim to be performant and practical. In some
|
||||
cases, it may be necessary to modify the kernel to suit your specific needs
|
||||
or test new kernel code as a developer.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
:backlinks: top
|
||||
|
||||
Source RPM files (SRPM) are also available for all |CL| kernels, and can be
|
||||
used for development instead. Select this link to view the latest `source RPM files`_.
|
||||
|
||||
Request changes be included with the |CL| kernel
|
||||
************************************************
|
||||
|
||||
If the kernel modification you need is already open source and likely to be
|
||||
useful to others, consider submitting a request to include it in the
|
||||
|CL| kernels.If your change request is accepted, you do not need to maintain your own modified kernel.
|
||||
|
||||
Make enhancement requests to the |CL| `distribution on GitHub`_ .
|
||||
|
||||
Set up kernel development environment
|
||||
*************************************
|
||||
|
||||
In some cases, it may be necessary to modify the kernel to suit your specific
|
||||
needs or to test new kernel code.
|
||||
|
||||
You can build and install a custom kernel; however you must:
|
||||
|
||||
* Disable Secure Boot
|
||||
* Maintain any updates to the kernel going forward
|
||||
|
||||
To create a custom kernel, start with the |CL| development environment.
|
||||
Then make changes to the kernel, build it, and install it.
|
||||
|
||||
|
||||
Install the |CL| development tooling framework
|
||||
==============================================
|
||||
|
||||
.. include:: autospec.rst
|
||||
:start-after: install-tooling-after-header:
|
||||
:end-before: install-tooling-end:
|
||||
|
||||
Clone the kernel package
|
||||
========================
|
||||
Clone the existing kernel package repository from |CL| as a starting point.
|
||||
|
||||
#. Clone the Linux kernel package from |CL|. Using the
|
||||
:command:`make clone_<PACKAGENAME>` command in the
|
||||
:file:`clearlinux/` directory clones the package from the
|
||||
`clearlinux-pkgs GitHub`_.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/clearlinux
|
||||
make clone_linux
|
||||
|
||||
#. Navigate into the cloned package directory.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/clearlinux/packages/linux
|
||||
|
||||
|
||||
The "linux" package is the kernel that comes with |CL| in the `kernel-native`
|
||||
bundle. Alternatively, you can use a different kernel variant as the base for
|
||||
modification. For a list of kernel package names which you can clone instead,
|
||||
see the `clearlinux-pkgs GitHub`_.
|
||||
|
||||
.. note::
|
||||
|
||||
The latest version of the |CL| kernel package is pulled as a starting
|
||||
point. An older version can pulled by switching to different git tag by using :command:`git checkout tag/<TAG_NAME>`.
|
||||
|
||||
Change the kernel version
|
||||
=========================
|
||||
|
||||
|CL| tends to use the latest kernel available from `kernel.org`_, the Linux
|
||||
upstream. The kernel version that will be built can be changed in the
|
||||
RPM SPEC file. While most packages in Clear Linux are typically packaged
|
||||
using :ref:`autospec-about`, the kernel is not. This means control files
|
||||
provided by autospec are not available and changes must be made manually.
|
||||
|
||||
#. Open the Linux kernel package RPM SPEC file in an editor.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$EDITOR linux.spec
|
||||
|
||||
#. Modify the Version, Release, and Source0 URL entries at the top of the
|
||||
file to change the version of Linux kernel that will be compiled.
|
||||
|
||||
A list of current and available kernel release can be found on
|
||||
`kernel.org`_.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Name: linux
|
||||
Version: 4.20.8
|
||||
Release: 696
|
||||
License: GPL-2.0
|
||||
Summary: The Linux kernel
|
||||
Url: http://www.kernel.org/
|
||||
Group: kernel
|
||||
Source0: https://cdn.kernel.org/pub/linux/kernel/v4.x/linux-4.20.8.tar.xz
|
||||
Source1: config
|
||||
Source2: cmdline
|
||||
|
||||
%define ktarget native
|
||||
|
||||
.. note::
|
||||
- Consider changing the Name from *linux* in the RPM spec file to easily identify a modified kernel.
|
||||
|
||||
- Consider changing the ktarget from *native* in the RPM spec file to easily identify a modified kernel.
|
||||
|
||||
#. Commit and save the changes to the file.
|
||||
|
||||
Pull a copy of the Linux kernel source code
|
||||
===========================================
|
||||
|
||||
Obtain a local copy of the source code to make modifications against.
|
||||
|
||||
#. Run make sources to pull the kernel source code specified in the RPM
|
||||
SPEC file. In the example, it downloads the :file:`linux-4.20.8.tar.xz` file.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make sources
|
||||
|
||||
|
||||
#. Extract the kernel source code archive. This will create a working copy
|
||||
of the Linux source that you can modify.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
tar -xvf linux-4.20.8.tar.xz
|
||||
|
||||
#. Navigate to the extracted directory. In this example, it has been
|
||||
extracted into a :file:`linux-4.20.8` directory.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd linux-4.20.8/
|
||||
|
||||
|
||||
Customize the Linux kernel source
|
||||
*********************************
|
||||
|
||||
After the kernel sources have been obtained, customizations to the kernel
|
||||
configuration or source code can be made for inclusion with the kernel
|
||||
build. These customizations are optional.
|
||||
|
||||
Modify kernel configuration
|
||||
===========================
|
||||
|
||||
The kernel source has many configuration options available to pick support for different hardware and software features.
|
||||
|
||||
These configuration values must be provided in the :file:`.config` file at
|
||||
compile time. You will need to make modifications to the :file:`.config`
|
||||
file, and include it in the kernel package.
|
||||
|
||||
|
||||
#. Make sure you have followed the steps to
|
||||
`Pull a copy of the Linux kernel source code`_ and are in the kernel
|
||||
source working directory.
|
||||
|
||||
|
||||
#. If you have an existing :file:`.config` file from an old kernel, copy it
|
||||
into the working directory as :file:`.config` for comparison.
|
||||
Otherwise, use the |CL| kernel configuration file as template
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cp ~/clearlinux/packages/linux/config .config
|
||||
|
||||
|
||||
#. Make any desired changes to the :file:`.config` using a kernel
|
||||
configuration tool. Below are some popular options:
|
||||
|
||||
- :command:`$EDITOR .config` - the .config file can be directly edited
|
||||
for simple changes with names that are already known.
|
||||
|
||||
- :command:`make config` - a text-based tool that asks questions
|
||||
one-by-one to decide configuration options.
|
||||
|
||||
- :command:`make menuconfig` - a terminal user interface that provides
|
||||
menus to decide configuration options.
|
||||
|
||||
- :command:`make xconfig` - a graphical user interface that provides
|
||||
tree views to decide configuration options.
|
||||
|
||||
|
||||
More configuration tools can be found by looking at the make help:
|
||||
:command:`make help | grep config`
|
||||
|
||||
#. Commit and save the changes to the :file:`.config` file.
|
||||
|
||||
#. Copy the :file:`.config` file from the kernel source directory into
|
||||
the kernel package directory as :file:`config` for inclusion in the build.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cp .config ../config
|
||||
|
||||
Modify kernel source code
|
||||
=========================
|
||||
|
||||
Changes to kernel code are applied with patch files. Patch files are
|
||||
formatted git commits that can be applied to the main source code.
|
||||
|
||||
You will need to obtain a copy of the source code,
|
||||
make modifications, generate patch file(s), and add them to the RPM SPEC
|
||||
file for inclusion during the kernel build.
|
||||
|
||||
If you have a large number of patches or a more complex workflow,
|
||||
consider using a patch management tool in addition to Git such as
|
||||
`Quilt`_.
|
||||
|
||||
|
||||
#. Make sure you have followed the steps to
|
||||
`Pull a copy of the Linux kernel source code`_ and are in the kernel
|
||||
source working directory.
|
||||
|
||||
|
||||
#. Initialize the kernel source directory as a new git repo and create a
|
||||
commit with all the existing source files to begin tracking changes.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git init
|
||||
git add -A
|
||||
git commit -m "Initial commit of Linux kernel source"
|
||||
|
||||
|
||||
#. Apply patches provided by the |CL| kernel package to the kernel source
|
||||
in the working directory.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git am ../*.patch
|
||||
|
||||
|
||||
#. Make any of your desired code changes to the Linux source code files.
|
||||
|
||||
|
||||
#. Track and commit your changes to the local git repo.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git add <FILENAME>
|
||||
git commit -m "My patch for driver A" <FILENAME>
|
||||
|
||||
|
||||
#. Generate a patch file based on your git commits.
|
||||
<n> represents the number of local commits to create patch file.
|
||||
See the `git-format-patch Documentation`_ for detailed information
|
||||
on using :command:`git format-patch`
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git format-patch -<n>
|
||||
|
||||
#. Copy the patch files from the patches directory in the linux
|
||||
source tree to the RPM build directory.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cp *.patch ~/clearlinux/packages/linux/
|
||||
|
||||
|
||||
#. Navigate back to the RPM build directory.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/clearlinux/packages/linux/
|
||||
|
||||
#. Open the Linux kernel package RPM SPEC file in an editor.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$EDITOR linux.spec
|
||||
|
||||
#. Locate the section of the SPEC file that contains existing patch
|
||||
variable definitions and append your patch file name. Ensure the
|
||||
patch number does not collide with an existing patch.
|
||||
In this example, the patch file is called
|
||||
:file:`2001-my-patch-for-driver-A.patch`
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
#
|
||||
# Small Clear Linux Tweaks
|
||||
#
|
||||
Patch0501: 0501-zero-extra-registers.patch
|
||||
Patch0502: 0502-locking-rwsem-spin-faster.patch
|
||||
|
||||
#Serie1.name WireGuard
|
||||
#Serie1.git https://git.zx2c4.com/WireGuard
|
||||
#Serie1.tag 00bf4f8c8c0ec006633a48fd9ee746b30bb9df17
|
||||
Patch1001: 1001-WireGuard-fast-modern-secure-kernel-VPN-tunnel.patch
|
||||
#Serie1.end
|
||||
|
||||
Patch2001: 2001-my-patch-for-driver-A.patch
|
||||
|
||||
|
||||
#. Locate the section of the SPEC file further down that contains
|
||||
patch application and append your patch file number used in the step above.
|
||||
In this example, patch2001 is added.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
#
|
||||
# Small tweaks
|
||||
#
|
||||
%patch0501 -p1
|
||||
%patch0502 -p1
|
||||
|
||||
#Serie1.patch.start
|
||||
%patch1001 -p1
|
||||
#Serie1.patch.end
|
||||
|
||||
%patch2001 -p1
|
||||
|
||||
|
||||
#. Commit and save the changes to the RPM SPEC file.
|
||||
|
||||
Modify kernel boot parameters
|
||||
=============================
|
||||
The kernel boot options are passed from the bootloader to the kernel with
|
||||
command-line parameters.
|
||||
|
||||
While temporary changes can be made to kernel parameters on a running
|
||||
system or on a during boot, you can also modify the default parameters that
|
||||
are persistent and distributed with a customized kernel.
|
||||
|
||||
|
||||
#. Open the kernel :file:`cmdline` file in an editor.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$EDITOR cmdline
|
||||
|
||||
|
||||
#. Make any desired change to the kernel parameters.
|
||||
For example, you can remove the :command:`quiet` parameter to see more
|
||||
verbose output of kernel log messages during the boot process.
|
||||
|
||||
#. Commit and save the changes to the :file:`cmdline` file.
|
||||
|
||||
See the `Kernel parameters documentation`_ for a list of available
|
||||
parameters.
|
||||
|
||||
Build and install the kernel
|
||||
****************************
|
||||
After changes have been made to the kernel source and RPM SPEC file,
|
||||
the kernel is ready to be compiled and packaged into an RPM.
|
||||
|
||||
The |CL| development tooling makes use of :command:`mock` environments to
|
||||
isolate building of packages in a sanitized workspace.
|
||||
|
||||
#. Start the compilation process by issuing the :command:`make build`
|
||||
command. This process is typically resource intensive and will take a while.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make build
|
||||
|
||||
.. note::
|
||||
The `ccache plugin for mock`_ can be enabled to help speed up any future rebuilds of the kernel package by caching compiler outputs and reusing them.
|
||||
|
||||
|
||||
#. The result will be multiple :file:`.rpm` files in the :file:`rpms`
|
||||
directory as output.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ls rpms/
|
||||
|
||||
The kernel RPM will be named
|
||||
:file:`linux<NAME>-<VERSION>-<RELEASE>.x86_64.rpm`
|
||||
|
||||
|
||||
#. The kernel RPM file can be input to the :ref:`mixer` to create a
|
||||
custom bundle and mix of |CL|.
|
||||
|
||||
Alternatively, the kernel RPM bundle can be installed manually on a local
|
||||
machine for testing. This approach works well for individual development or
|
||||
testing. For a more scalable and customizable approach, consider using the
|
||||
:ref:`mixer` to provide a custom kernel with updates.
|
||||
|
||||
1. Install the kernel onto the local system by extracting the RPM with the
|
||||
:command:`rpm2cpio` command.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
rpm2cpio linux<NAME>-<VERSION>-<RELEASE>.x86_64.rpm | (cd /; sudo cpio -i -d -u -v);
|
||||
|
||||
|
||||
#. Update the |CL| boot manager using :command:`clr-boot-manager` and reboot.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo clr-boot-manager list-kernels
|
||||
sudo clr-boot-manager set-kernel org.clearlinux.<TARGET>.<VERSION>-<RELEASE>
|
||||
|
||||
sudo reboot
|
||||
|
||||
|
||||
#. After a reboot, verify the customized kernel is running.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
uname -a
|
||||
|
||||
Related topics
|
||||
**************
|
||||
|
||||
* :ref:`kernel-modules`
|
||||
* :ref:`mixer`
|
||||
|
||||
.. _kernels available: https://clearlinux.org/documentation/clear-linux/reference/compatible-kernels
|
||||
|
||||
.. _distribution on GitHub: https://github.com/clearlinux/distribution/issues/new/choose
|
||||
|
||||
.. _source RPM files: https://download.clearlinux.org/current/source/SRPMS/
|
||||
|
||||
.. _Quilt: http://savannah.nongnu.org/projects/quilt
|
||||
|
||||
.. _clearlinux-pkgs GitHub: https://github.com/clearlinux-pkgs
|
||||
|
||||
.. _kernel.org: https://www.kernel.org/
|
||||
|
||||
.. _Kernel parameters documentation: https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt
|
||||
|
||||
.. _ccache plugin for mock: https://fedoraproject.org/wiki/Mock/Plugin/CCache?rd=Subprojects/Mock/Plugin/CCache
|
||||
|
||||
.. _git-format-patch Documentation: https://git-scm.com/docs/git-format-patch
|
||||
|
||||
.. _user-setup script: https://github.com/clearlinux/common/blob/master/user-setup.sh
|
||||
@@ -16,6 +16,7 @@ completed.
|
||||
enable-user-space
|
||||
swupd-guide
|
||||
bulk-provision
|
||||
kernel-development
|
||||
kernel-modules
|
||||
mixer
|
||||
mixin
|
||||
@@ -28,3 +29,4 @@ completed.
|
||||
download-verify-decompress-windows
|
||||
autospec
|
||||
assign-static-ip
|
||||
ister
|
||||
|
||||
@@ -1,167 +1,191 @@
|
||||
.. _mixin:
|
||||
|
||||
Create and add custom bundles to your upstream Clear Linux system
|
||||
#################################################################
|
||||
mixin
|
||||
#####
|
||||
|
||||
|CL-ATTR| offers many curated bundles that you can install on your system to
|
||||
create your desired capabilities. If the available upstream bundles do not
|
||||
meet your needs, you can create and add your own custom bundles to your
|
||||
system using one of two methods. Note: Upstream refers to the official
|
||||
version of |CL|.
|
||||
mixin is a tool provided in the |CL-ATTR| that allows users to add custom
|
||||
content to their client systems and still receive updates from their upstream OS
|
||||
vendor.
|
||||
|
||||
The first method is to use the :ref:`mixer tool<mixer>` to create your own
|
||||
|CL| image and add your bundles to it. Mixing your own |CL| image can
|
||||
give you great control and flexibility; however, you must act as an
|
||||
:abbr:`OSV (Operating System Vendor)` and maintain your releases and
|
||||
updates because you have forked from upstream.
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
The second method is to use the :command:`mixin` tool, which also
|
||||
makes use of mixer to create custom bundles that you can add to your
|
||||
upstream |CL| system. This simpler method provides a “light” forking from
|
||||
upstream, which means you can continue to get upstream bundles and updates.
|
||||
If needed, you can easily revert your system back to the upstream version.
|
||||
Description
|
||||
***********
|
||||
|
||||
This guide shows you how to accomplish the second method by following these
|
||||
steps:
|
||||
mixin uses the mixer tool to generate a local update for client systems. With
|
||||
the mixin tool, a user can add remote RPM repositories or local RPMs and mix
|
||||
them into their update stream, while continuing to get upstream bundles and
|
||||
updates. The metadata generated from the mixin tool is merged with the upstream
|
||||
metadata to provide a single source of update content, which swupd uses to
|
||||
perform updates.
|
||||
|
||||
#. Set up the workspace.
|
||||
#. Copy your custom RPM package to the workspace.
|
||||
#. Create a bundle with your custom RPM package.
|
||||
#. Migrate your |CL| system to your custom mix.
|
||||
#. Add your custom bundle to your system.
|
||||
#. Optional: Revert your system back to 100% upstream.
|
||||
The mixin tool is included in the :command:`mixer` bundle.
|
||||
|
||||
Set up the workspace
|
||||
********************
|
||||
How to use
|
||||
**********
|
||||
|
||||
#. Install the mixer bundle to enable mixer.
|
||||
Learn the mixin tool set up and workflow.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
Install the :command:`mixer` bundle to add the mixin tool. Refer to
|
||||
`Install a bundle`_ for more details.
|
||||
|
||||
Workflow
|
||||
========
|
||||
|
||||
The following steps show how to create and add a custom bundle with the mixin
|
||||
tool:
|
||||
|
||||
#. Add or create a new repo(s)
|
||||
|
||||
mixin pulls packages to build your custom bundle from locations referred to
|
||||
as repos. There are two default repos for mixin:
|
||||
|
||||
* upstream
|
||||
* local
|
||||
|
||||
Additional repos can be added, such as other locations on your local system
|
||||
or remote repos.
|
||||
|
||||
RPMs must be built specifically for |CL| in order for them to work properly.
|
||||
Refer to :ref:`autospec` for instruction on creating RPMs for |CL|.
|
||||
|
||||
#. Create a custom bundle with desired RPMs
|
||||
|
||||
Add the desired packages to your new bundle and build the bundle. By default,
|
||||
the bundle will be named after its parent repo.
|
||||
|
||||
The first time you build the bundle, mixer will create a new OS version by
|
||||
taking your current upstream |CL| version and multiplying it by 1000. For
|
||||
example, if your upstream version is 27650, your custom version will be
|
||||
27650000. For each subsequent call to mixin, mixer will increment the version
|
||||
by 10.
|
||||
|
||||
View the `mixin man page`_ for more information on mixin commands.
|
||||
|
||||
#. Update system to make custom bundle available
|
||||
|
||||
Update your system using swupd to make your custom bundle accessible.
|
||||
|
||||
When you first create your mix, you will have to do a one-time migration to
|
||||
your custom mix as part of the update. After you migrate, the system version
|
||||
switches over to your last custom version number as noted in the previous
|
||||
step. As long as you remain on your custom version of |CL| you can continue
|
||||
to create and add new bundles to your mix with no extra migration step.
|
||||
|
||||
#. Install custom bundles
|
||||
|
||||
Install your custom bundle using the normal swupd :command:`bundle-add`
|
||||
command.
|
||||
|
||||
View the `swupd man page`_ for more information on swupd commands.
|
||||
|
||||
Examples
|
||||
********
|
||||
|
||||
Complete all `Prerequisites`_ before using these examples.
|
||||
|
||||
Example 1: Add custom helloclear bundle
|
||||
=======================================
|
||||
|
||||
This example shows the basic steps of adding a custom bundle from a local repo.
|
||||
|
||||
#. Check that :command:`helloclear` does not exist on your system:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
helloclear
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo swupd bundle-add mixer
|
||||
helloclear: command not found
|
||||
|
||||
#. Create the workspace.
|
||||
#. Follow the "Build a new RPM" example from :ref:`autospec` to create a new
|
||||
`helloclear` RPM.
|
||||
|
||||
The resulting RPMs are in `~/clearlinux/packages/helloclear/rpms`.
|
||||
|
||||
#. Create a new repo.
|
||||
|
||||
#. Create a local repo folder and copy the new `helloclear` RPM files into
|
||||
the repo:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mkdir ~/mixin-repo
|
||||
cp ~/clearlinux/packages/helloclear/rpms/helloclear-v1.0-1.x86_64.rpm ~/mixin-repo
|
||||
cp ~/clearlinux/packages/helloclear/rpms/helloclear-bin-v1.0-1.x86_64.rpm ~/mixin-repo
|
||||
|
||||
#. Create the repo data:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/mixin-repo
|
||||
createrepo_c .
|
||||
|
||||
#. Add the repo name:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixin repo add mylocalrepo file://$HOME/mixin-repo/
|
||||
|
||||
#. Create custom bundle with the new `helloclear` RPM. Add `helloclear` to the
|
||||
:command:`helloclear-bundle` bundle and build the bundle:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixin package add helloclear --bundle helloclear-bundle
|
||||
sudo mixin build
|
||||
|
||||
#. Migrate your |CL| to your custom mix. Check your version before and after the
|
||||
update to see the switch to your custom mix:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd check-update
|
||||
sudo swupd update --migrate
|
||||
sudo swupd check-update
|
||||
|
||||
#. Install your custom bundle. Check that the `helloclear-bundle` is now
|
||||
available and install it to your system:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle-list -a | grep helloclear-bundle
|
||||
sudo swupd bundle-add helloclear-bundle
|
||||
|
||||
#. Test for `helloclear` again to see that it is installed:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
helloclear
|
||||
|
||||
#. Revert your system back to upstream (optional). This example reverts back to
|
||||
upstream version 27650:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo mkdir -p /usr/share/mix/local-rpms
|
||||
sudo swupd verify --fix --picky --force -m 27650 -C /usr/share/clear/update-ca/Swupd_Root.pem
|
||||
sudo swupd clean --all
|
||||
sudo swupd check-update
|
||||
|
||||
Copy your custom RPM package to the workspace
|
||||
*********************************************
|
||||
Related topics
|
||||
**************
|
||||
|
||||
.. note::
|
||||
* :ref:`About mixer <mixer-about>`
|
||||
* :ref:`mixer`
|
||||
* :ref:`autospec-about`
|
||||
* :ref:`bundles-about`
|
||||
* :ref:`swupd-about`
|
||||
|
||||
You cannot simply use RPMs from other Linux distros on |CL|. You must
|
||||
build RPMs specifically for |CL| in order for them to work properly.
|
||||
Follow the instructions on how to build RPMs found at the
|
||||
`Developer tooling framework for Clear Linux`_.
|
||||
|
||||
If you have a local RPM you want to add to your mix you can do so by copying
|
||||
your RPM package to the workspace.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo cp [RPM] /usr/share/mix/local-rpms
|
||||
|
||||
Alternatively, you can add a remote RPM repository by running the following
|
||||
command.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo mixin repo add [repo-name] [repo-url]
|
||||
|
||||
Create a bundle with your custom RPM package
|
||||
********************************************
|
||||
|
||||
Use the :command:`mixin` command to create a bundle with the RPM
|
||||
package.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo mixin package add [package-name] [--bundle bundle-name] [--build]
|
||||
|
||||
This command will add package-name to a bundle that is named after its parent
|
||||
repository. For example, if the RPM was provided locally, it will be added to
|
||||
the 'local' bundle. If it came from a repo that was added with
|
||||
:command:`mixin repo add`, it will be added to a bundle named after the
|
||||
repo-name. If the `--bundle bundle-name` flag is provided, the package will
|
||||
be added to `bundle-name` instead. The `--build` flag tells :command:`mixin`
|
||||
to run a `mixer` build after adding the package.
|
||||
|
||||
To add more than one RPM to your previously-created bundle, repeat
|
||||
the :command:`mixin package add` command and change the package name. Do not
|
||||
add the `--build` flag until all packages have been added. Once done adding
|
||||
packages, run the following to create your local mix.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo mixin build
|
||||
|
||||
.. note::
|
||||
|
||||
* The first time you run the :command:`mixin build` command, mixer
|
||||
creates a new OS version by taking your current upstream |CL| version
|
||||
and multiplying it by 1000. For example, if your upstream version is
|
||||
21530, your custom version will be 21530000. For each subsequent call
|
||||
to mixin, mixer will increment the version by 10. For example,
|
||||
21530010, 21530020, etc.
|
||||
|
||||
Migrate your Clear Linux system to your custom mix
|
||||
**************************************************
|
||||
|
||||
Before you can use your custom bundle, you must migrate your |CL| system
|
||||
to your custom mix to make the bundle accessible.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo swupd update --migrate
|
||||
|
||||
After you migrate, the version of your |CL| system switches over to your
|
||||
last custom version number as noted in the previous section.
|
||||
|
||||
You can continue to create new bundles with :command:`mixin`
|
||||
while you are in your custom version of |CL|. You do not need to migrate
|
||||
again. However, you must run :command:`swupd update` again to update your
|
||||
system in order to make those bundles visible.
|
||||
|
||||
Add your custom bundle to your system
|
||||
*************************************
|
||||
|
||||
#. Get a listing of your newly-created bundle.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo swupd bundle-list -a
|
||||
|
||||
The listing includes all upstream bundles.
|
||||
|
||||
#. Add your bundle.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo swupd bundle-add [bundle-name]
|
||||
|
||||
.. note::
|
||||
|
||||
You can also update your system to the latest upstream version using
|
||||
this command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo swupd update
|
||||
|
||||
Optional: Revert your system back to 100% upstream
|
||||
**************************************************
|
||||
|
||||
If you want to revert your |CL| system back to the official upstream
|
||||
version, use this command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo swupd verify --fix --force --picky -m [upstream-version-number] -C /usr/share/clear/update-ca/Swupd_Root.pem
|
||||
|
||||
After the command completes, all custom RPMs and bundles are unavailable
|
||||
because :file:`/usr/share/mix` is deleted as part of the reversion process.
|
||||
|
||||
.. _Developer tooling framework for Clear Linux:
|
||||
https://github.com/clearlinux/common
|
||||
.. _mixin man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixin.1.rst
|
||||
.. _swupd man page: https://github.com/clearlinux/swupd-client/blob/master/docs/swupd.1.rst
|
||||
.. _Install a bundle: https://clearlinux.org/documentation/clear-linux/guides/maintenance/swupd-guide#adding-a-bundle
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,169 @@
|
||||
.. _openssh-server:
|
||||
|
||||
openssh-server
|
||||
##############
|
||||
|
||||
The **openssh-server** bundle provides the OpenSSH\* package needed to enable
|
||||
an SSH service in |CL-ATTR|. Remote users require an SSH service to be able
|
||||
to use an encrypted login shell.
|
||||
|
||||
|CL| enables the `sshd.socket` unit, which will listen on port 22 by default
|
||||
and start the OpenSSH service as required. The first time OpenSSH starts, it
|
||||
generates the server SSH keys needed for the service.
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
Assure the bundle :file:`openssh-server` is installed.
|
||||
|
||||
To check it it's on your host, enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle-list
|
||||
|
||||
To add it, enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle-add openssh-server
|
||||
|
||||
Change default port
|
||||
*******************
|
||||
|
||||
Perform the following steps to change the default listening port for the
|
||||
OpenSSH service:
|
||||
|
||||
#. Open the sshd.socket file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl edit sshd.socket
|
||||
|
||||
#. Add the `[Socket]` section and `ListenStream` option to the sshd.socket
|
||||
file as shown below. The first `ListenStream` entry removes the |CL|
|
||||
default listen port value. The second `ListenStream` entry sets the new
|
||||
default listen port value. In this example, we set the new default port
|
||||
to 4200:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
[Socket]
|
||||
ListenStream=
|
||||
ListenStream=4200
|
||||
|
||||
|
||||
Make sure to include a new line after the last line of text in the sshd.socket file.
|
||||
|
||||
#. Verify your changes:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cat /etc/systemd/system/sshd.socket.d/override.conf
|
||||
|
||||
You should see the following output:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
[Socket]
|
||||
ListenStream=
|
||||
ListenStream=4200
|
||||
|
||||
#. Reload the systemd daemon configurations:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
#. Restart the sshd.socket unit:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl restart sshd.socket
|
||||
|
||||
#. Confirm the the sshd.socket unit is listening on your new port:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl status sshd.socket
|
||||
|
||||
.. note::
|
||||
|
||||
Output should show :guilabel:`Active:` as `active(listening)`.
|
||||
|
||||
Enable SFTP
|
||||
***********
|
||||
|
||||
|CL| *disables* the :abbr:`SFTP (SSH File Transfer Protocol)` subsystem by
|
||||
default due to security considerations. To enable the SFTP subsystem, perform
|
||||
the following configuration of the :abbr:`SSHD (SSH Daemon)` service file:
|
||||
|
||||
#. Create a systemd drop-in directory for the SSHD service:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkdir -p /etc/systemd/system/sshd@.service.d
|
||||
|
||||
#. Create the following file:
|
||||
:file:`/etc/systemd/system/sshd@.service.d/sftp.conf`
|
||||
|
||||
#. Add the OPTIONS environment variable to the sftp.conf file.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
[Service]
|
||||
Environment="OPTIONS=-o Subsystem=\"sftp /usr/libexec/sftp-server\""
|
||||
|
||||
#. Reload systemd configuration:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
Congratulations! The SFTP subsystem is enabled.
|
||||
|
||||
Enable root login
|
||||
*****************
|
||||
|
||||
To enable root login via SSH, perform the following steps:
|
||||
|
||||
#. Create a *ssh* directory in :file:`/etc`, if it does not already exist.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mkdir /etc/ssh
|
||||
|
||||
#. Create the following file, if it does not already exist:
|
||||
:file:`/etc/ssh/sshd_config`
|
||||
|
||||
#. Set the configuration variable in /etc/ssh/sshd_config
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
PermitRootLogin yes
|
||||
|
||||
Enable X11-forwarding
|
||||
*********************
|
||||
|
||||
X11 forwarding allows you to securely run graphical applications
|
||||
(i.e., X clients) over the ssh conection. This will alow for remote gui apps
|
||||
without the need for full VNC/remotedesktop. To enable X11-forwarding via
|
||||
SSH, perform the following steps:
|
||||
|
||||
#. Create a *ssh* directory in :file:`/etc`, if it does not already exist.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mkdir /etc/ssh
|
||||
|
||||
#. Create the following file, if it does not already exist:
|
||||
:file:`/etc/ssh/sshd_config`
|
||||
|
||||
#. Set the configuration variables.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
AllowTcpForwarding yes
|
||||
X11UseLocalhost yes
|
||||
X11DisplayOffset 10
|
||||
X11Forwarding yes
|
||||
@@ -12,6 +12,7 @@ features.
|
||||
compatible-hardware
|
||||
bundle-commands
|
||||
bundles/bundles
|
||||
bundles/openssh-server
|
||||
how-to-clear-overview
|
||||
collaboration/collaboration
|
||||
compatible-kernels
|
||||
|
||||
@@ -1,40 +1,48 @@
|
||||
.. _greengrass:
|
||||
|
||||
Enable AWS Greengrass* and OpenVINO™ on |CL-ATTR|
|
||||
#################################################
|
||||
Enable AWS Greengrass\* and OpenVINO™ toolkit
|
||||
#############################################
|
||||
|
||||
Hardware accelerated Function-as-a-Service (FaaS) enables cloud developers
|
||||
to deploy inference functionalities [1] on Intel® IoT edge devices with
|
||||
accelerators (CPU, Integrated GPU, Intel® FPGA, and Intel® Movidius™). These
|
||||
functions provide a great developer experience and seamless migration of
|
||||
visual analytics from cloud to edge in a secure manner using a containerized
|
||||
environment. Hardware-accelerated FaaS provides the best-in-class
|
||||
Hardware accelerated Function-as-a-Service (FaaS) enables cloud developers to
|
||||
deploy inference functionalities [1] on Intel® IoT edge devices with
|
||||
accelerators (CPU, Integrated GPU, Intel® FPGA, and Intel® Movidius™
|
||||
technology). These functions provide a great developer experience and seamless
|
||||
migration of visual analytics from cloud to edge in a secure manner using a
|
||||
containerized environment. Hardware-accelerated FaaS provides the best-in-class
|
||||
performance by accessing optimized deep learning libraries on Intel® IoT
|
||||
edge devices with accelerators.
|
||||
|
||||
This tutorial will demonstrate how to:
|
||||
This tutorial demonstrates how to:
|
||||
|
||||
* Set up the Intel® edge device with |CL-ATTR|
|
||||
* Install the OpenVINO™ and AWS Greengrass* software stacks
|
||||
* Use AWS Greengrass and lambdas to deploy the FaaS samples from the cloud
|
||||
* Install the OpenVINO™ toolkit and Amazon Web Services\* (AWS\*)
|
||||
Greengrass\* software stacks
|
||||
* Use AWS Greengrass\* and AWS Lambda\* to deploy the FaaS samples from the cloud
|
||||
|
||||
Supported Platforms
|
||||
Refer to the following topics:
|
||||
|
||||
.. contents:: :local:
|
||||
:depth: 1
|
||||
|
||||
|
||||
Supported platforms
|
||||
*******************
|
||||
|
||||
* Operating System: |CL| latest release
|
||||
* Hardware: Intel® core platforms (Tutorial supports inference on CPU only)
|
||||
* Hardware: Intel® core platforms (This tutorial supports inference on CPU only.)
|
||||
|
||||
Description of Samples
|
||||
**********************
|
||||
Sample description
|
||||
==================
|
||||
|
||||
The AWS Greengrass samples are located at the `Edge-Analytics-FaaS`_. For this tutorial we will use the 1.0 version of the source code.
|
||||
The AWS Greengrass samples are located at `Edge-Analytics-FaaS`_. This
|
||||
tutorial uses the 1.0 version of the source code.
|
||||
|
||||
We provide the following AWS Greengrass samples:
|
||||
|CL| provides the following AWS Greengrass samples:
|
||||
|
||||
* `greengrass_classification_sample.py`_
|
||||
|
||||
This AWS Greengrass sample classifies a video stream using classification
|
||||
networks such as AlexNet and GoogLeNet and publishes top-10 results on AWS*
|
||||
networks such as AlexNet and GoogLeNet and publishes top-10 results on AWS\*
|
||||
IoT Cloud every second.
|
||||
|
||||
* `greengrass_object_detection_sample_ssd.py`_
|
||||
@@ -46,8 +54,8 @@ We provide the following AWS Greengrass samples:
|
||||
coordinates on AWS IoT Cloud every second.
|
||||
|
||||
|
||||
Installing |CL| on the edge device
|
||||
**********************************
|
||||
Install the OS on the edge device
|
||||
*********************************
|
||||
|
||||
Start with a clean installation of |CL| on a new system, using the
|
||||
:ref:`bare-metal-install`, found in :ref:`get-started`.
|
||||
@@ -56,8 +64,8 @@ Create user accounts
|
||||
====================
|
||||
|
||||
After |CL| is installed, create two user accounts. Create an administrative
|
||||
user in |CL|. You will also create a user account for the Greengrass
|
||||
services to use (see Greengrass user below).
|
||||
user in |CL| and create a user account for the Greengrass services to use (see
|
||||
Greengrass user below).
|
||||
|
||||
#. Create a new user and set a password for that user. Enter the following
|
||||
commands as ``root``:
|
||||
@@ -68,7 +76,7 @@ services to use (see Greengrass user below).
|
||||
passwd <userid>
|
||||
|
||||
#. Next, enable the :command:`sudo` command for your new ``<userid>``. Add
|
||||
``<userid>`` to the ``wheel`` group:
|
||||
``<userid>`` to the *wheel* group:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -82,14 +90,13 @@ services to use (see Greengrass user below).
|
||||
|
||||
.. note::
|
||||
|
||||
By default |CL| does not create an :file:`/etc/fstab` file.
|
||||
The Greengrass service needs to have the file created before
|
||||
it will run.
|
||||
By default, |CL| does not create an :file:`/etc/fstab` file.
|
||||
You must create this file before the Greengrass service runs.
|
||||
|
||||
Add required bundles
|
||||
====================
|
||||
|
||||
Use the ``swupd`` software updater utility to add the prerequisite bundles
|
||||
Use the :command:`swupd` software updater utility to add the prerequisite bundles
|
||||
for the OpenVINO software stack:
|
||||
|
||||
.. code-block:: bash
|
||||
@@ -100,20 +107,20 @@ for the OpenVINO software stack:
|
||||
|
||||
Learn more about how to :ref:`swupd-guide`.
|
||||
|
||||
The ``computer-vision-basic`` bundle will install the OpenVINO software,
|
||||
along with the edge device models needed.
|
||||
The :command:`computer-vision-basic` bundle installs the OpenVINO™ toolkit,
|
||||
and the sample models optimized for Intel® edge platforms.
|
||||
|
||||
Converting Deep Learning Models
|
||||
===============================
|
||||
Convert deep learning models
|
||||
============================
|
||||
|
||||
Locate Sample Models
|
||||
Locate sample models
|
||||
--------------------
|
||||
|
||||
There are two types of provided models that can be used in conjunction with AWS Greengrass
|
||||
for this tutorial: classification or object detection.
|
||||
There are two types of provided models that can be used in conjunction with
|
||||
AWS Greengrass for this tutorial: classification or object detection.
|
||||
|
||||
To complete this tutorial using an image classification model,
|
||||
download the BVLC Alexnet model files `bvlc_alexnet.caffemodel`_ and `deploy.prototxt`_
|
||||
download the BVLC AlexNet model files `bvlc_alexnet.caffemodel`_ and `deploy.prototxt`_
|
||||
to the default model_location at :file:`/usr/share/openvino/models`.
|
||||
Any custom pre-trained classification models can be used with the
|
||||
classification sample.
|
||||
@@ -123,12 +130,12 @@ are included with the computer-vision-basic bundle installation at :file:`/usr/s
|
||||
These models are provided as an example; however, you may also use a custom SSD model
|
||||
with the Greengrass object detection sample.
|
||||
|
||||
Running Model Optimizer
|
||||
-----------------------
|
||||
Run model optimizer
|
||||
-------------------
|
||||
|
||||
Follow these instructions for `converting deep learning models to Intermediate Representation using Model Optimizer`_. To optimize either of the afformentioned sample models, run one of the following commands.
|
||||
Follow these instructions for `converting deep learning models to Intermediate Representation using Model Optimizer`_. To optimize either of the sample models described above, run one of the following commands.
|
||||
|
||||
For classification using BVLC Alexnet model:
|
||||
For classification using BVLC AlexNet model:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -148,40 +155,40 @@ For object detection using SqueezeNetSSD-5Class model:
|
||||
|
||||
In these examples:
|
||||
|
||||
* ``<model_location>`` is :file:`/usr/share/openvino/models`
|
||||
* ``<model_location>`` is :file:`/usr/share/openvino/models`.
|
||||
|
||||
* ``<data_type>`` is FP32 or FP16, depending on target device.
|
||||
|
||||
* ``<output_dir>`` is the directory where the user wants to store the
|
||||
Intermediate Representation (IR). IR contains .xml format corresponding
|
||||
to the network structure and .bin format corresponding to weights. This
|
||||
.xml file should be passed to <PARAM_MODEL_XML>.
|
||||
* ``<output_dir>`` is the directory where the Intermediate Representation
|
||||
(IR) is stored. IR contains .xml format corresponding to the network
|
||||
structure and .bin format corresponding to weights. This .xml file should be
|
||||
passed to :command:`<PARAM_MODEL_XML>`.
|
||||
|
||||
* In the BVLC Alexnet model, the prototxt defines the input shape with
|
||||
* In the BVLC AlexNet model, the prototxt defines the input shape with
|
||||
batch size 10 by default. In order to use any other batch size, the
|
||||
entire input shape needs to be provided as an argument to the model
|
||||
optimizer. For example, to use batch size 1, you can provide
|
||||
“--input_shape [1,3,227,227]”.
|
||||
entire input shape must be provided as an argument to the model
|
||||
optimizer. For example, to use batch size 1, you must provide:
|
||||
``--input_shape [1,3,227,227]``
|
||||
|
||||
|
||||
Configuring an AWS Greengrass group
|
||||
===================================
|
||||
Configure AWS Greengrass group
|
||||
******************************
|
||||
|
||||
For each Intel® edge platform, we need to create a new AWS Greengrass group
|
||||
For each Intel® edge platform, you must create a new AWS Greengrass group
|
||||
and install AWS Greengrass core software to establish the connection between
|
||||
cloud and edge.
|
||||
|
||||
#. To create an AWS Greengrass group, follow the
|
||||
`AWS Greengrass developer guide`_
|
||||
#. To create an AWS Greengrass group, follow the instructions in
|
||||
`Configure AWS IoT Greengrass on AWS IoT`_.
|
||||
|
||||
#. To install and configure AWS Greengrass core on edge platform, follow
|
||||
the instructions at `Start AWS Greengrass on the Core Device`_. In
|
||||
step 8(b), download the x86_64 Ubuntu configuration of the AWS Greengrass
|
||||
the instructions in `Start AWS Greengrass on the Core Device`_. In
|
||||
step 8(b), download the x86_64 Ubuntu\* configuration of the AWS Greengrass
|
||||
core software.
|
||||
|
||||
.. note::
|
||||
|
||||
You will not need to run the ``cgroupfs-mount.sh`` script in step #6
|
||||
You do not need to run the :file:`cgroupfs-mount.sh` script in step #6
|
||||
of Module 1 of the `AWS Greengrass developer guide`_ because this is
|
||||
enabled already in |CL|.
|
||||
|
||||
@@ -190,13 +197,13 @@ cloud and edge.
|
||||
|
||||
.. note::
|
||||
|
||||
Security certificates are linked to your AWS* account.
|
||||
Security certificates are linked to your AWS account.
|
||||
|
||||
|
||||
Creating and Packaging Lambda Functions
|
||||
=======================================
|
||||
Create and package Lambda function
|
||||
**********************************
|
||||
|
||||
#. Complete steps 1-4 of the tutorial at `Create and Package Lambda Function`_ .
|
||||
#. Complete steps 1-4 of the AWS Greengrass tutorial at `Create and Package a Lambda Function`_.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -204,7 +211,7 @@ Creating and Packaging Lambda Functions
|
||||
environment on the edge device.
|
||||
|
||||
|
||||
#. In step 5, replace greengrassHelloWorld.py with the classification or object detection
|
||||
#. In step 5, replace :file:`greengrassHelloWorld.py` with the classification or object detection
|
||||
Greengrass sample from `Edge-Analytics-Faas`_:
|
||||
|
||||
* Classification: `greengrass_classification_sample.py`_
|
||||
@@ -227,36 +234,35 @@ Creating and Packaging Lambda Functions
|
||||
zip -r greengrass_lambda.zip greengrasssdk
|
||||
greengrass_object_detection_sample_ssd.py
|
||||
|
||||
#. Return to the AWS Documentation and follow steps 6-11 to `complete creating lambdas`_.
|
||||
#. Return to the AWS documentation section called `Create and Package a Lambda Function`_
|
||||
and complete the procedure.
|
||||
|
||||
.. note::
|
||||
|
||||
In step 9(a) of the AWS documentation, while uploading the zip file,
|
||||
make sure to name the handler as below depending on the AWS Greengrass
|
||||
sample you are using:
|
||||
make sure to name the handler to one of the following, depending on the
|
||||
AWS Greengrass sample you are using:
|
||||
|
||||
* greengrass_object_detection_sample_ssd.function_handler (or)
|
||||
* greengrass_object_detection_sample_ssd.function_handler
|
||||
* greengrass_classification_sample.function_handler
|
||||
|
||||
Deploying Lambdas
|
||||
=================
|
||||
|
||||
Configuring the Lambda function
|
||||
-------------------------------
|
||||
Configure Lambda function
|
||||
*************************
|
||||
|
||||
After creating the Greengrass group and the lambda function, start
|
||||
configuring the lambda function for AWS Greengrass.
|
||||
After creating the Greengrass group and the Lambda function, start
|
||||
configuring the Lambda function for AWS Greengrass.
|
||||
|
||||
#. Follow steps 1-8 in `Configure the Lambda Function`_ of the AWS
|
||||
#. Follow steps 1-8 in `Configure the Lambda Function for AWS IoT Greengrass`_ in the AWS
|
||||
documentation.
|
||||
|
||||
#. In addition to the details mentioned in step 8, change the Memory limit
|
||||
to 2048MB to accommodate large input video streams.
|
||||
to 2048 MB to accommodate large input video streams.
|
||||
|
||||
#. Add the following environment variables as key-value pairs when editing
|
||||
the lambda configuration and click on update:
|
||||
the Lambda configuration and click on update:
|
||||
|
||||
.. list-table:: **Table 1. Environment Variables: Lambda Configuration**
|
||||
.. list-table:: **Table 1. Environment variables: Lambda configuration**
|
||||
:widths: 20 80
|
||||
:header-rows: 1
|
||||
|
||||
@@ -282,94 +288,100 @@ configuring the lambda function for AWS Greengrass.
|
||||
(e.g. 1 for top-1 result, 5 for top-5 results)
|
||||
|
||||
#. Add subscription to subscribe, or publish messages from AWS Greengrass
|
||||
lambda function by following the steps 10-14 in `Configure the Lambda Function`_
|
||||
Lambda function by completing the procedure in `Configure the Lambda Function for AWS IoT Greengrass`_.
|
||||
|
||||
.. note::
|
||||
|
||||
The “Optional topic filter” field should be the topic
|
||||
mentioned inside the lambda function.
|
||||
The optional topic filter field is the topic mentioned inside the Lambda
|
||||
function. In this tutorial, sample topics include the following:
|
||||
:command:`openvino/ssd` or :command:`openvino/classification`
|
||||
|
||||
For example, openvino/ssd or openvino/classification
|
||||
Add local resources
|
||||
===================
|
||||
|
||||
Local Resources
|
||||
---------------
|
||||
#. Select `this link to add local resources and access privileges`_.
|
||||
Refer to the AWS documentation for details about `local resources and access privileges`_.
|
||||
|
||||
Following are the local resources needed for the CPU:
|
||||
The following table describes the local resources needed for the CPU:
|
||||
|
||||
.. list-table:: **Local Resources**
|
||||
:widths: 20, 20, 20, 20
|
||||
:header-rows: 1
|
||||
.. list-table:: **Local resources**
|
||||
:widths: 20, 20, 20, 20
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Resource type
|
||||
- Local path
|
||||
- Access
|
||||
* - Name
|
||||
- Resource type
|
||||
- Local path
|
||||
- Access
|
||||
|
||||
* - ModelDir
|
||||
- Volume
|
||||
- <MODEL_DIR> to be specified by user
|
||||
- Read-Only
|
||||
* - ModelDir
|
||||
- Volume
|
||||
- <MODEL_DIR> to be specified by user
|
||||
- Read-Only
|
||||
|
||||
* - Webcam
|
||||
- Device
|
||||
- /dev/video0
|
||||
- Read-Only
|
||||
* - Webcam
|
||||
- Device
|
||||
- /dev/video0
|
||||
- Read-Only
|
||||
|
||||
* - DataDir
|
||||
- Volume
|
||||
- <DATA_DIR> to be specified by user. Holds both input and output
|
||||
data.
|
||||
- Read and Write
|
||||
* - DataDir
|
||||
- Volume
|
||||
- <DATA_DIR> to be specified by user. Holds both input and output
|
||||
data.
|
||||
- Read and Write
|
||||
|
||||
Deploy
|
||||
------
|
||||
Deploy Lambda function
|
||||
**********************
|
||||
|
||||
To `deploy the lambda function to AWS Greengrass core device`_, select
|
||||
“Deployments” on group page and follow the instructions.
|
||||
Refer to the AWS documentation for instructions on how to
|
||||
`deploy the lambda function to AWS Greengrass core device`_. Select
|
||||
*Deployments* on the group page and follow the instructions.
|
||||
|
||||
Output Consumption
|
||||
------------------
|
||||
Output consumption
|
||||
==================
|
||||
|
||||
There are four options available for output consumption. These options are
|
||||
used to report, stream, upload, or store inference output at an interval
|
||||
defined by the variable ``reporting_interval`` in the AWS Greengrass samples.
|
||||
defined by the variable :command:`reporting_interval` in the AWS Greengrass samples.
|
||||
|
||||
a. IoT Cloud Output:
|
||||
This option is enabled by default in the AWS Greengrass samples using a
|
||||
variable ``enable_iot_cloud_output``. We can use it to verify the lambda
|
||||
a. IoT cloud output:
|
||||
|
||||
This option is enabled by default in the AWS Greengrass samples using the
|
||||
:command:`enable_iot_cloud_output` variable. You can use it to verify the lambda
|
||||
running on the edge device. It enables publishing messages to IoT cloud
|
||||
using the subscription topic specified in the lambda (For example,
|
||||
‘openvino/classification’ for classification and ‘openvino/ssd’ for
|
||||
object detection samples). For classification, top-1 result with class
|
||||
using the subscription topic specified in the lambda. (For example, topics
|
||||
may include :command:`openvino/classification` for classification and :command:`openvino/ssd`
|
||||
for object detection samples.) For classification, top-1 result with class
|
||||
label are published to IoT cloud. For SSD object detection, detection
|
||||
results such as bounding box co-ordinates of objects, class label, and
|
||||
results such as bounding box coordinates of objects, class label, and
|
||||
class confidence are published.
|
||||
|
||||
Follow the instructions here to `view the output on IoT cloud`_
|
||||
Follow the instructions here to `view the output on IoT cloud`_.
|
||||
|
||||
b. Kinesis Streaming:
|
||||
b. Kinesis streaming:
|
||||
|
||||
This option enables inference output to be streamed from the edge device
|
||||
to cloud using Kinesis [3] streams when ‘enable_kinesis_output’ is set
|
||||
to cloud using Kinesis [3] streams when :command:`enable_kinesis_output` is set
|
||||
to True. The edge devices act as data producers and continually push
|
||||
processed data to the cloud. The users need to set up and specify
|
||||
processed data to the cloud. You must set up and specify
|
||||
Kinesis stream name, Kinesis shard, and AWS region in the AWS Greengrass
|
||||
samples.
|
||||
|
||||
c. Cloud Storage using AWS S3 Bucket:
|
||||
c. Cloud storage using AWS S3 bucket:
|
||||
|
||||
When the ‘enable_s3_jpeg_output’ variable is set to True, it enables uploading and storing processed frames (in JPEG format) in an AWS S3 bucket. The users need to set up and specify the S3 bucket name in the
|
||||
AWS Greengrass samples to store the JPEG images. The images are named using the timestamp and uploaded to S3.
|
||||
When the :command:`enable_s3_jpeg_output` variable is set to True, it enables
|
||||
uploading and storing processed frames (in jpeg format) in an AWS S3
|
||||
bucket. You must set up and specify the S3 bucket name in the AWS
|
||||
Greengrass samples to store the JPEG images. The images are named using the
|
||||
timestamp and uploaded to S3.
|
||||
|
||||
d. Local Storage:
|
||||
d. Local storage:
|
||||
|
||||
When the ‘enable_s3_jpeg_output’ variable is set to True, it enables storing processed frames (in JPEG format) on the edge device. The
|
||||
images are named using the timestamp and stored in a directory specified
|
||||
by ‘PARAM_OUTPUT_DIRECTORY’.
|
||||
When the :command:`enable_s3_jpeg_output` variable is set to True, it enables
|
||||
storing processed frames (in jpeg format) on the edge device. The images
|
||||
are named using the timestamp and stored in a directory specified by
|
||||
:command:`PARAM_OUTPUT_DIRECTORY`.
|
||||
|
||||
References
|
||||
-----------
|
||||
**********
|
||||
|
||||
1. AWS Greengrass: https://aws.amazon.com/greengrass/
|
||||
2. AWS Lambda: https://aws.amazon.com/lambda/
|
||||
@@ -387,17 +399,15 @@ References
|
||||
|
||||
.. _converting deep learning models to Intermediate Representation using Model Optimizer: https://software.intel.com/en-us/articles/OpenVINO-ModelOptimizer
|
||||
|
||||
.. _AWS Greengrass developer guide: https://docs.aws.amazon.com/greengrass/latest/developerguide/gg-config.html
|
||||
.. _AWS Greengrass Developer Guide: https://docs.aws.amazon.com/greengrass/latest/developerguide/what-is-gg.html
|
||||
|
||||
.. _Configure AWS IoT Greengrass on AWS IoT: https://docs.aws.amazon.com/greengrass/latest/developerguide/gg-config.html
|
||||
|
||||
.. _Start AWS Greengrass on the Core Device: https://docs.aws.amazon.com/greengrass/latest/developerguide/gg-device-start.html
|
||||
|
||||
.. _AWS Greengrass Core SDK: https://docs.aws.amazon.com/greengrass/latest/developerguide/create-lambda.html
|
||||
.. _Configure the Lambda Function for AWS IoT Greengrass: https://docs.aws.amazon.com/greengrass/latest/developerguide/config-lambda.html
|
||||
|
||||
.. _complete creating lambdas: https://docs.aws.amazon.com/greengrass/latest/developerguide/create-lambda.html
|
||||
|
||||
.. _Configure the Lambda Function: https://docs.aws.amazon.com/greengrass/latest/developerguide/config-lambda.html
|
||||
|
||||
.. _Add local resources and access privileges: https://docs.aws.amazon.com/greengrass/latest/developerguide/access-local-resources.html
|
||||
.. _local resources and access privileges: https://docs.aws.amazon.com/greengrass/latest/developerguide/access-local-resources.html
|
||||
|
||||
.. _deploy the lambda function to AWS Greengrass core device: https://docs.aws.amazon.com/greengrass/latest/developerguide/configs-core.html
|
||||
|
||||
@@ -407,4 +417,4 @@ References
|
||||
|
||||
.. _this link to add local resources and access privileges: https://docs.aws.amazon.com/greengrass/latest/developerguide/access-local-resources.html
|
||||
|
||||
.. _Create and Package Lambda Function: https://docs.aws.amazon.com/greengrass/latest/developerguide/create-lambda.html
|
||||
.. _Create and Package a Lambda Function: https://docs.aws.amazon.com/greengrass/latest/developerguide/create-lambda.html
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
.. _kubernetes-bp:
|
||||
|
||||
Kubernetes Best Practices on |CL|
|
||||
#################################
|
||||
|
||||
Use swupd to update clusters
|
||||
****************************
|
||||
|
||||
This tutorial shows you how to manage your Kubernetes cluster while using
|
||||
:command:`swupd` to update |CL-ATTR|.
|
||||
|
||||
In our tutorial :ref:`kubernetes`, we explain how to set up a Kubernetes
|
||||
cluster on |CL| using `kubeadm`. `Kubeadm documentation`_ often builds on the
|
||||
assumption that the distribution uses a traditional package manager (e.g.,
|
||||
RPM/DEB).
|
||||
|
||||
In contrast, |CL| uses `swupd` to update the OS, which in this case updates
|
||||
all of the kubernetes node and client binaries simultaneously, as part of
|
||||
the `cloud-native-basic` bundle (e.g., kubectl, kubeadm, kubelet). Running
|
||||
:command:`sudo swupd update` requires special care to ensure the OS
|
||||
incorporates the latest Kubernetes upgrades.
|
||||
|
||||
This document describes best practices to manage cluster upgrades with
|
||||
`kubeadm` on a |CL|-based cluster.
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
Assure that you:
|
||||
|
||||
* Completed :ref:`kubernetes`
|
||||
* Installed the bundle `cloud-native-basic`
|
||||
|
||||
.. note::
|
||||
|
||||
Other Linux\* distros shown in Kubernetes upgrade documentation reflect
|
||||
`apt-get update`, `apt-mark hold kubeadm`, and similar commands; however, such commands **are not valid** on |CL|.
|
||||
|
||||
Update the control plane
|
||||
************************
|
||||
|
||||
#. Read kubernetes documentation `before you begin`_.
|
||||
|
||||
#. On your master node, run the command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd update
|
||||
|
||||
.. note::
|
||||
|
||||
If the minor version of Kubernetes changes, |CL| shows a message-of-the-day, or `motd`. When the `motd` appears, you **must postpone** a kubelet restart on master and nodes until the control plane is properly updated. :command:`swupd update` does not restart services automatically unless explicitly configured to do so.
|
||||
|
||||
#. Now follow these instructions in kubernetes documentation.
|
||||
|
||||
* `Upgrade control plane`_
|
||||
* `Drain control plane node`_
|
||||
* `Restart Kubelet and undrain node`_
|
||||
|
||||
Update worker nodes
|
||||
*******************
|
||||
|
||||
#. On each worker node, run the command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd update
|
||||
|
||||
#. Now follow these instructions in kubernetes documentation:
|
||||
|
||||
* `Drain node`_
|
||||
* `Update kubelet configuration`_
|
||||
* `Restart Kubelet and undrain node`_
|
||||
|
||||
.. _Kubeadm documentation: https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm-upgrade/
|
||||
|
||||
.. _Restart Kubelet and undrain node: https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-1-13/#restart-the-kubelet-for-all-nodes
|
||||
|
||||
.. _Update kubelet configuration: https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-1-13/#upgrade-the-kubelet-config-on-worker-nodes
|
||||
|
||||
.. _Drain node: https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-1-13/#drain-control-plane-and-worker-nodes
|
||||
|
||||
.. _Restart kubelet and undrain node: https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-1-13/#restart-the-kubelet-for-all-nodes
|
||||
|
||||
.. _Upgrade control plane: https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-1-13/#upgrade-the-control-plane-node
|
||||
|
||||
.. _Drain control plane node: https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-1-13/#drain-control-plane-and-worker-nodes
|
||||
|
||||
.. _Kubeadmn documentation: https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm/
|
||||
|
||||
.. _before you begin: https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-1-13/#before-you-begin
|
||||
|
||||
+44
-39
@@ -1,7 +1,7 @@
|
||||
.. _kubernetes:
|
||||
|
||||
Run Kubernetes\* on |CL-ATTR|
|
||||
#############################
|
||||
Run Kubernetes\*
|
||||
################
|
||||
|
||||
This tutorial describes how to install, configure, and run the
|
||||
`Kubernetes container orchestration system`_ on |CL-ATTR| using CRI+O and
|
||||
@@ -43,17 +43,16 @@ Kubernetes, a set of supported :abbr:`CRI (Container Runtime Interface)`
|
||||
runtimes, and networking plugins, are included in the `cloud-native-basic`_
|
||||
bundle.
|
||||
|
||||
.. note::
|
||||
|
||||
CRI-O’s default plugin_dir is :file:`/opt/bin/cni`.
|
||||
CNI plugins are installed as part of ``cloud-native-basic``.
|
||||
|
||||
To install this framework, enter the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle-add cloud-native-basic
|
||||
|
||||
.. note::
|
||||
|
||||
For more on networking plugins, see `Install pod network add-on`_.
|
||||
|
||||
Configure Kubernetes
|
||||
********************
|
||||
|
||||
@@ -150,7 +149,6 @@ Configure and run CRI-O + kata-runtime
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart crio
|
||||
sudo systemctl restart kubelet
|
||||
|
||||
#. Initialize the master control plane with the command:
|
||||
|
||||
@@ -158,7 +156,6 @@ Configure and run CRI-O + kata-runtime
|
||||
|
||||
sudo kubeadm init --cri-socket=/run/crio/crio.sock
|
||||
|
||||
|
||||
Install pod network add-on
|
||||
**************************
|
||||
|
||||
@@ -166,47 +163,49 @@ 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
|
||||
`kubeadm init` command:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
--pod-network-cidr 10.244.0.0/16
|
||||
--pod-network-cidr 10.244.0.0/16
|
||||
|
||||
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:
|
||||
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
|
||||
|
||||
[crio.runtime]
|
||||
manage_network_ns_lifecycle = true
|
||||
|
||||
Create a symlink for the network overlays:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo ln -s /usr/libexec/cni /opt/cni/bin
|
||||
|
||||
.. note::
|
||||
|
||||
|CL| installs CNI plugins that are part of the `cloud-native-basic`
|
||||
bundle to :file:`/usr/libexec/cni`. The directory is required because `
|
||||
swupd verify` may use it to repair a system to a known good state.
|
||||
|
||||
**Notes about Weave Net add-on**
|
||||
|
||||
If you choose the `Weave Net` add-on, you must make the following
|
||||
changes because it installs itself in the :file:`/opt/cni/bin` directory.
|
||||
|
||||
For using CRI-O and ``Weave Net``, complete the following step.
|
||||
|
||||
Add the `loopback` CNI plugin to the plugin path with the command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo ln -s /usr/libexec/cni/loopback /opt/bin/cni/loopback
|
||||
|
||||
Use your cluster
|
||||
****************
|
||||
|
||||
@@ -240,8 +239,8 @@ Read the Kubernetes documentation to learn more about:
|
||||
|
||||
* `Joining your nodes`_
|
||||
|
||||
Package configuration customization in |CL| (optional)
|
||||
******************************************************
|
||||
Package configuration customization (optional)
|
||||
**********************************************
|
||||
|
||||
|CL| is a stateless system that looks for user-defined package configuration
|
||||
files in the :file:`/etc/<package-name>` directory to be used as default. If
|
||||
@@ -289,6 +288,12 @@ commands as a shell script to configure all of these services in one step:
|
||||
EOF
|
||||
done
|
||||
|
||||
Next steps
|
||||
**********
|
||||
|
||||
:ref:`kubernetes-bp`
|
||||
|
||||
|
||||
Troubleshooting
|
||||
***************
|
||||
|
||||
@@ -14,6 +14,7 @@ Explore our tutorials to discover what you can do with |CL|!
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
wordpress/wordpress
|
||||
flatpak/flatpak
|
||||
@@ -30,6 +31,6 @@ Explore our tutorials to discover what you can do with |CL|!
|
||||
spark
|
||||
kata
|
||||
kata_migration
|
||||
kubernetes
|
||||
kubernetes/kubernetes*
|
||||
greengrass
|
||||
dlrs
|
||||
|
||||
@@ -6,7 +6,7 @@ import jinja2
|
||||
from jinja2 import Environment, FileSystemLoader, Template
|
||||
import git
|
||||
from operator import itemgetter
|
||||
from datetime import datetime
|
||||
from datetime import datetime
|
||||
|
||||
GITHUB_BASE = "https://github.com/clearlinux/clr-bundles/tree/master/bundles/"
|
||||
PUNDLES = "https://github.com/clearlinux/clr-bundles/blob/master/packages"
|
||||
@@ -15,16 +15,14 @@ PATTERN1 = re.compile(r"#\s?\[TITLE]:\w?(.*)")
|
||||
PATTERN2 = re.compile(r"#\s?\[DESCRIPTION]:\w?(.*)")
|
||||
PATTERN3 = re.compile(r"\(([^()]*|include)\)", re.MULTILINE)
|
||||
PATTERN4 = re.compile(r"^((?:(?!#)\w+[^-\s][-])\w+|\w+[^\s-])", re.MULTILINE)
|
||||
# ALT PATTERN4 = re.compile(r"^((?:(?!#)(\w+[^-\s])[-]\w+.)[^\s]{1,}[^\s]|\w+[^\s-])", re.MULTILINE)
|
||||
|
||||
PATTERN5 = re.compile(r"^(?!=a)\w.+\s[#]\s(\w+.*)?", re.MULTILINE)
|
||||
# Previous version: PATTERN5 = re.compile(r"^[^#].*(?<=\s\-\s)(\w+.*)?", re.MULTILINE)
|
||||
PATTERN5 = re.compile(r"^\w.+\s[#]\s(\w?.*)?", re.MULTILINE)
|
||||
|
||||
def extractor(lines):
|
||||
bundle_title = "title"
|
||||
data_desc = "description"
|
||||
url = "url"
|
||||
include_list = []
|
||||
include_unique = []
|
||||
|
||||
for i in lines:
|
||||
title = PATTERN1.match(i)
|
||||
@@ -37,26 +35,26 @@ def extractor(lines):
|
||||
data_desc = desc.groups(0)[0].strip()
|
||||
if url:
|
||||
url = os.path.join(GITHUB_BASE, bundle_title)
|
||||
|
||||
if includes:
|
||||
include_text = includes[0].strip("()")
|
||||
include_list.append(include_text)
|
||||
return {"title": bundle_title, "data_desc": data_desc, "include_list": include_list, "url": url}
|
||||
include_unique = set(include_list)
|
||||
return {"title": bundle_title, "data_desc": data_desc, "include_list": include_unique, "url": url}
|
||||
|
||||
def pundler():
|
||||
with io.open("./cloned_repo/clr-bundles/packages") as file_obj:
|
||||
lines = file_obj.readlines()
|
||||
pundle_title = "pundle_title"
|
||||
pundle_desc = "pundle_desc"
|
||||
purl = "purl"
|
||||
purl = "purl"
|
||||
pundle_list = []
|
||||
pun_desc = []
|
||||
pundle_master = []
|
||||
|
||||
|
||||
for i in lines:
|
||||
pundle = PATTERN4.findall(i)
|
||||
pundle_plus = PATTERN5.findall(i)
|
||||
|
||||
|
||||
if pundle:
|
||||
pundle_title = pundle[0]
|
||||
pundle_list.append(pundle_title)
|
||||
@@ -65,7 +63,7 @@ def pundler():
|
||||
pundle_desc = pundle_plus[0].strip("[]")
|
||||
pun_desc.append(pundle_desc)
|
||||
|
||||
for pun, desc in zip(pundle_list, pun_desc):
|
||||
for pun, desc in zip(pundle_list, pun_desc):
|
||||
pundle_master.append({"title": pun, "pun_desc": desc, "purl": PUNDLES})
|
||||
return pundle_master
|
||||
|
||||
@@ -82,7 +80,7 @@ def bundler():
|
||||
data.append(extractor(lines))
|
||||
|
||||
pundle_master = pundler()
|
||||
data = data + pundle_master
|
||||
data = data + pundle_master
|
||||
filtered = list(filter(lambda x: x.get('title'), data))
|
||||
sortedData = sorted(filtered, key=lambda x:x['title'].lower())
|
||||
#ALT sortedData2 = sorted(sortedData, key=itemgetter('title'))
|
||||
@@ -93,6 +91,6 @@ def bundler():
|
||||
|
||||
output = template.render(data=sortedData, now=datetime.utcnow())
|
||||
with io.open('bundles.html.txt', 'w') as file:
|
||||
file.write(output)
|
||||
|
||||
file.write(output)
|
||||
|
||||
bundler()
|
||||
|
||||
@@ -25,8 +25,8 @@
|
||||
<tbody>
|
||||
<tr>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr></tr>
|
||||
{% for d in data %}
|
||||
{% if d.url %}
|
||||
<tr id="bundle">
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
'''
|
||||
Usage: python code-blocks.py path/to/file.rst
|
||||
|
||||
Default output is to stdout
|
||||
|
||||
Parses all code found in blocks listed in blockTypes out of rst file for instruction testing.
|
||||
'''
|
||||
import sys
|
||||
|
||||
blockTypes = ["bash","console"]
|
||||
|
||||
def code_blocks(filename):
|
||||
with open(filename, 'r') as fd:
|
||||
c_indent = ''
|
||||
in_section = []
|
||||
for line in fd:
|
||||
blockFound = False
|
||||
indent = line[:len(line) - len(line.lstrip())]
|
||||
for blockType in blockTypes:
|
||||
if 'code-block:: ' + blockType in line:
|
||||
blockFound = True
|
||||
if blockFound:
|
||||
in_section = [line.strip()]
|
||||
c_indent = ''
|
||||
blockFound = False
|
||||
elif in_section:
|
||||
if not c_indent and line.strip():
|
||||
c_indent = indent
|
||||
if not (len(indent) >= len(c_indent)) and line.strip():
|
||||
yield in_section[2:]
|
||||
in_section = []
|
||||
else:
|
||||
in_section.append(line[len(c_indent):].rstrip())
|
||||
|
||||
def main():
|
||||
for code_block in code_blocks(sys.argv[1]):
|
||||
print('\n'.join(code_block) + '\n')
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
@@ -7,4 +7,5 @@
|
||||
.. |CC| replace:: Clear Containers
|
||||
|
||||
.. |CAUTION-BACKUP-USB| replace::
|
||||
Burning an image formats the USB drive, thus destroying all existing content. Backup your data before proceeding.
|
||||
Burning an image formats the USB drive, and will destroy all pre-existing
|
||||
content. Back up your data before proceeding.
|
||||
|
||||
Reference in New Issue
Block a user