mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-09-03 12:21:41 +00:00
Update unattended installation doc and deprecate ister doc. (#1079)
Closes #1052 Signed-off-by: Bun K Tan <bun.k.tan@intel.com>
This commit is contained in:
bktan8
@@ -3,10 +3,11 @@
|
||||
Install using clr-installer and a configuration file
|
||||
####################################################
|
||||
|
||||
This page explains how to install |CL-ATTR| using the clr-installer tool
|
||||
with a configuration file. The configuration file (:file:`clr-installer.yaml`)
|
||||
can be reused to duplicate the same installation configuration on additional
|
||||
machines.
|
||||
In addition to the interactive GUI and text-based modes,
|
||||
:command:`clr-installer` also supports an unattended mode where you
|
||||
simply provide it a YAML configuration file.
|
||||
|
||||
This guide shows you two examples of how to use its unattended mode.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
@@ -15,67 +16,63 @@ machines.
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
Ensure that your target system supports the installation:
|
||||
For installation onto bare metal, ensure that your target system
|
||||
supports these requirements:
|
||||
|
||||
* :ref:`system-requirements`
|
||||
* :ref:`compatibility-check`
|
||||
|
||||
Process
|
||||
*******
|
||||
Download and make bootable USB of the live server image
|
||||
*******************************************************
|
||||
|
||||
This guide describes two methods for using a configuration file with the
|
||||
clr-installer tool. You can use either method to achieve the same goal. Choose
|
||||
the method that works best for your setup.
|
||||
See :ref:`bootable-usb`.
|
||||
|
||||
If you are installing |CL| for the first time, we recommend Example 1.
|
||||
Example 1: Fresh installation onto bare metal
|
||||
*********************************************
|
||||
|
||||
To clone an existing |CL| setup on another system, we recommend Example 2.
|
||||
This example uses a YAML configuration file to perform a new installation.
|
||||
|
||||
Example 1
|
||||
=========
|
||||
#. Boot up the |CL| Live Server USB thumb drive.
|
||||
|
||||
This method uses a configuration file template to perform a new installation.
|
||||
|
||||
Perform the following steps:
|
||||
|
||||
#. Go to `Downloads`_ and download the latest Clear Linux OS Server image.
|
||||
|
||||
For example:
|
||||
https://download.clearlinux.org/releases/30010/clear/clear-30010-live-server.iso.xz
|
||||
|
||||
#. Follow the instructions to :ref:`bootable-usb` based on your OS.
|
||||
|
||||
#. Boot up the USB thumb drive.
|
||||
#. Select :guilabel:`Clear Linux OS` from the menu.
|
||||
#. In the console window, log in as root and set a password.
|
||||
|
||||
#. In the console window, log in as `root` and set a password.
|
||||
|
||||
#. Verify you have a network connection to the Internet and configure proxy
|
||||
settings if you're working behind a firewall.
|
||||
#. Download a :file:`live-server.yaml` template.
|
||||
|
||||
For example:
|
||||
#. Download a sample YAML configuration file. For example, if you want to
|
||||
install |CL| with a desktop GUI, you might want to use :file:`live-desktop.yaml`.
|
||||
Or you can use the :file:`live-server.yaml` if you want to install a non-GUI version
|
||||
of |CL|.
|
||||
|
||||
.. code-block:: bash
|
||||
* *Desktop:*
|
||||
|
||||
curl -O https://download.clearlinux.org/releases/30010/clear/config/image/live-server.yaml
|
||||
.. code-block:: bash
|
||||
|
||||
#. Edit the template and change the settings as needed.
|
||||
curl -O https://cdn.download.clearlinux.org/current/config/image/live-desktop.yaml
|
||||
|
||||
Commonly-changed settings include:
|
||||
* *Server:*
|
||||
|
||||
.. _install-configfile-yaml-begin:
|
||||
.. code-block:: bash
|
||||
|
||||
#. Under *block-devices*, set “file: "/dev/sda"” or enter your preferred device.
|
||||
#. Under *targetMedia*, set the third partition size to “0” to use the entire disk space.
|
||||
#. Under *bundles*, add additional bundles as needed.
|
||||
curl -O https://cdn.download.clearlinux.org/current/config/image/live-server.yaml
|
||||
|
||||
#. Edit the YAML configuration file and change the settings as needed.
|
||||
|
||||
Commonly-changed settings include (refer to the example below):
|
||||
|
||||
a. Under *block-devices* (line 15), set your target media. For example: ``file: "/dev/sda"``.
|
||||
#. Under *targetMedia* (line 34), set the third partition size to “0” to use the entire disk space.
|
||||
#. Under *bundles* (line 37), add additional bundles as needed.
|
||||
#. Delete the *post-install* section unless you have post-installation scripts.
|
||||
#. Under *Version*, set a version number. To use the latest version, set to “0”.
|
||||
#. Under *Version* (line 50), set a version number. To use the latest version, set to “0”.
|
||||
|
||||
Commonly-changed settings are shown in lines 15, 34, 37, and 51 below.
|
||||
See `Installer YAML Syntax`_ for more details.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
:linenos:
|
||||
:emphasize-lines: 14,15,34,37,51
|
||||
:emphasize-lines: 14,15,34,37,50
|
||||
|
||||
#clear-linux-config
|
||||
|
||||
@@ -121,7 +118,6 @@ Perform the following steps:
|
||||
telemetry: false
|
||||
iso: true
|
||||
keepImage: true
|
||||
autoUpdate: false
|
||||
|
||||
keyboard: us
|
||||
language: en_US.UTF-8
|
||||
@@ -129,56 +125,67 @@ Perform the following steps:
|
||||
|
||||
version: 30010
|
||||
|
||||
.. _install-configfile-yaml-end:
|
||||
|
||||
Start the installation with the command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
clr-installer --config live-server.yaml
|
||||
|
||||
Example 2
|
||||
=========
|
||||
|
||||
This method uses a saved configuration file from a previous installation,
|
||||
which you can use to easily duplicate the installation on additional machines.
|
||||
|
||||
Perform the following steps:
|
||||
|
||||
#. Open a console window on a system where |CL| was installed to retrieve a
|
||||
copy of the configuration file.
|
||||
|
||||
#. In the console window, log in as root and enter your password.
|
||||
|
||||
#. Change directory to :file:`/root` and copy the :file:`clr-installer.yaml`
|
||||
file to a USB thumb drive.
|
||||
#. Start the unattended installation using the `--config` option.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd /root
|
||||
cp clr-installer.yaml <USB-thumb-drive>
|
||||
clr-installer --config live-server.yaml
|
||||
|
||||
Start the installation on the target with the following steps:
|
||||
#. Reboot your system after installation is completed.
|
||||
|
||||
#. Go to `Downloads`_ and download the latest Clear Linux OS Server image.
|
||||
Example 2: Replicate a previous installation
|
||||
********************************************
|
||||
|
||||
For example:
|
||||
https://download.clearlinux.org/releases/30010/clear/clear-30010-live-server.iso.xz
|
||||
This example uses a saved configuration file from a previous installation,
|
||||
which you can use to easily clone the installation on additional machines
|
||||
, ideally with the same hardware configuration.
|
||||
|
||||
#. Follow the instructions to :ref:`bootable-usb` based on your OS.
|
||||
.. warning::
|
||||
|
||||
Be aware of the following when applying a saved configuration on a new machine:
|
||||
|
||||
* Make sure the target media on the new machine matches up
|
||||
|
||||
* The users' credentials will be replicated as well
|
||||
|
||||
#. Boot up the USB thumb drive.
|
||||
#. Select :guilabel:`Clear Linux OS` from the menu.
|
||||
#. In the console window, log in as root and set a password.
|
||||
#. Verify you have a network connection to the Internet and configure proxy
|
||||
settings if you're working behind a firewall.
|
||||
#. Plug in and mount the USB thumb drive containing the retrieved
|
||||
:file:`clr-installer.yaml` configuration file.
|
||||
#. Start the installation with the command:
|
||||
#. On a system where |CL| was installed, open a terminal window.
|
||||
|
||||
#. Get root privilege.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
clr-installer --config clr-installer.yaml
|
||||
sudo su
|
||||
|
||||
#. Copy the :file:`clr-installer.yaml` from :file:`/root` to a USB thumb drive.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cp /root/clr-installer.yaml <USB-thumb-drive>
|
||||
|
||||
#. Install on target system.
|
||||
|
||||
a. Boot up the |CL| Live Server USB thumb drive.
|
||||
|
||||
#. Select :guilabel:`Clear Linux OS` from the menu.
|
||||
|
||||
#. In the console window, log in as `root` and set a password.
|
||||
|
||||
#. Verify you have a network connection to the Internet and configure proxy
|
||||
settings if you're working behind a firewall.
|
||||
|
||||
#. Plug in and mount the USB thumb drive containing the retrieved
|
||||
:file:`clr-installer.yaml` configuration file.
|
||||
|
||||
#. Doublecheck to make sure the target media in the saved configuration file
|
||||
matches with the target system's.
|
||||
|
||||
#. Start the installation.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
clr-installer --config clr-installer.yaml
|
||||
|
||||
#. Reboot your system after installation is completed.
|
||||
|
||||
References
|
||||
**********
|
||||
@@ -186,7 +193,5 @@ References
|
||||
* `Clear Linux Installer`_
|
||||
* `Installer YAML Syntax`_
|
||||
|
||||
.. _Downloads: https://clearlinux.org/downloads
|
||||
.. _Clear Linux Installer: https://github.com/clearlinux/clr-installer
|
||||
|
||||
.. _Installer YAML Syntax: https://github.com/clearlinux/clr-installer/blob/master/scripts/InstallerYAMLSyntax.md
|
||||
.. _Installer YAML Syntax: https://github.com/clearlinux/clr-installer/blob/master/scripts/InstallerYAMLSyntax.md
|
||||
|
||||
@@ -1,92 +0,0 @@
|
||||
.. _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 an average of 10 releases per week using the
|
||||
ister tool. With each release, we produce multiple
|
||||
:ref:`image types for different environments <image-types>` and use cases such
|
||||
as installers, Hyper-V, KVM, or VMWare.
|
||||
|
||||
Each image has a JSON configuration file that is used by ister to generate the
|
||||
image. These JSON configuration files describe the image type, partitions, version,
|
||||
and bundles that will be preinstalled by default with the image. For each image
|
||||
type we produce, the corresponding JSON configuration file for the image also is
|
||||
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 instructions 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. Here are some examples:
|
||||
|
||||
* 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 :ref:`swupd-guide` for
|
||||
more information on installing bundles.
|
||||
|
||||
#. Download the `ister.py`_ tool and grant it sudo privileges.
|
||||
|
||||
#. Download the JSON configuration file for the desired image (located in
|
||||
:file:`config/image/`):
|
||||
|
||||
* `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 the “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`
|
||||
|
||||
.. _ister.py: https://github.com/bryteise/ister
|
||||
.. _Current release: https://cdn.download.clearlinux.org/current/
|
||||
.. _Previous releases: https://cdn.download.clearlinux.org/releases/
|
||||
@@ -160,7 +160,7 @@ A mix is created with the following steps:
|
||||
#. Create image.
|
||||
|
||||
mixer creates a bootable image from your updated content using
|
||||
the :ref:`ister` tool. In this step you can specify which bundles you want
|
||||
the `clr-installer`_ tool. In this step you can specify which bundles you want
|
||||
*preinstalled* in the image. Users can later install other bundles available
|
||||
in your mix.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user