Register Clients With a Bootstrap Script

1. Introduction

Registering clients with a bootstrap script gives you control over parameters, and can help if you have to register a large number of clients at once.

To register clients using a bootstrap script, we recommend you create a template bootstrap script to begin, which can then be copied and modified. The bootstrap script you create is executed on the client when it is registered, and ensures all the necessary packages are deployed to the client. Some parameters in the bootstrap script ensure the client system can be assigned to its base channel, using activation key and GPG key.

It is important that you check the repository information carefully, to ensure it matches the base channel repository. If the repository information does not match exactly, the bootstrap script cannot download the correct packages.

Additional considerations:

  • All clients need a bootstrap repository. It is automatically created and regenerated on the Uyuni Server when products are synchronized. A bootstrap repository includes packages for installing Salt on clients, and for registering clients. For more information about creating a bootstrap repository, see Bootstrap Repository.

  • openSUSE Leap 15 and SLE 15 use Python 3 by default. Bootstrap scripts based on Python 2 must be re-created for openSUSE Leap 15 and SLE 15 systems. If you register openSUSE Leap 15 or SLE 15 systems using Python 2, the bootstrap script fails.

GPG Keys and Uyuni Client Tools

The GPG key used by Uyuni Client Tools is not trusted by default. When you create your bootstrap script, add a path to the file containing the public key fingerprint with the ORG_GPG_KEY parameter.

2. Create a Bootstrap Script with mgr-bootstrap

The mgr-bootstrap command generates custom bootstrap scripts. A bootstrap script is used by Uyuni client systems for simplifying their initial registration and configuration.

The arguments --activation-keys and --script, are the only mandatory arguments. On the Uyuni Server, as root at the command line execute it with the mandatory arguments. Replace <ACTIVATION_KEY and <EDITED_NAME> with your values:

mgr-bootstrap --activation-keys=<ACTIVATION_KEY> --script=bootstrap-<EDITED_NAME>.sh

The mgr-bootstrap command offers several other options, including the ability to set a specific hostname, set specific GPG keys, and set the registration method (salt-minion or salt-bundle).

For more information, see the mgr-bootstrap man page, or run mgr-bootstrap --help.

3. Create a Bootstrap Script from Web UI

You can use the Uyuni Web UI to create an editable bootstrap script.

Procedure: Creating a Bootstrap Script

  1. In the Uyuni Web UI, navigate to Admin  Manager Configuration  Bootstrap Script.

  2. The required fields are pre-populated with values derived from previous installation steps. For details on each setting, see Bootstrap Script.

  3. Click Update to create the script.

  4. The bootstrap script is generated and stored on the server in the /srv/www/htdocs/pub/bootstrap directory. Alternatively, you can access the bootstrap script over HTTPS. Replace <example.com> with the host name of your Uyuni Server:

    https://<example.com>/pub/bootstrap/bootstrap.sh

Do not disable SSL in your bootstrap script. Ensure that Enable SSL is checked in the Web UI, or that the setting USING_SSL=1 exists in the bootstrap script. If you disable SSL, the registration process requires custom SSL certificates.

For more information about custom certificates, see SSL Certificates.

4. Edit a Bootstrap Script

You can copy and modify the template bootstrap script you created to customize it. A minimal requirement when modifying a bootstrap script for use with Uyuni is the inclusion of an activation key. Most packages are signed with GPG, so you also need to have trusted GPG keys on your system to install them.

In this procedure, you need to know the exact name of your activation keys. Navigate to Home  Overview and, in the Tasks box, click Manage Activation Keys. All keys created for channels are listed on this page. You must enter the full name of the key you wish to use in the bootstrap script exactly as presented in the key field. For more information about activation keys, see Activation Keys.

Procedure: Modifying a Bootstrap Script

  1. On your Uyuni Server, as root at the command line change to the bootstrap directory with:

    cd /srv/www/htdocs/pub/bootstrap/

  2. Create and rename two copies of the template bootstrap script for use with each of your clients.

    cp bootstrap.sh bootstrap-sles12.sh
cp bootstrap.sh bootstrap-sles15.sh

  3. Open bootstrap-sles15.sh for modification. Scroll down until you can see the text shown below. If exit 1 exists in the file, comment it out by typing a hash or pound sign (#) at the beginning of the line. This activates the script. Enter the name of the key for this script in the ACTIVATION_KEYS= field:

    echo "Enable this script: comment (with #'s) this block (or, at least just"
echo "the exit below)"
echo
#exit 1

# can be edited, but probably correct (unless created during initial install):
# NOTE: ACTIVATION_KEYS *must* be used to bootstrap a client machine.
ACTIVATION_KEYS=1-sles15
ORG_GPG_KEY=

  4. When you have finished, save the file, and repeat this procedure for the second bootstrap script.

By default, bootstrap script will try to install venv-salt-minion if it is available in the bootstrap repository and salt-minion if there is no Salt bundle in the bootstrap repository. It is possible to avoid installing Salt bundle and keep using salt-minion if you need it for some reason.

For more information, see Salt Bundle.

5. Register Clients Running the Bootstrap Script

When you have finished creating your script, you can use it to register clients.

Procedure: Running the Bootstrap Script

  1. On the Uyuni Server, log in as root. At the command prompt, and change to the bootstrap directory:

    cd /srv/www/htdocs/pub/bootstrap/

  2. Run this command to execute the bootstrap script on the client; replace EXAMPLE.COM with the host name of your client:

    cat bootstrap-sles15.sh | ssh root@EXAMPLE.COM /bin/bash

  3. Alternatively, on the client, run this command:

    curl -Sks https://server_hostname/pub/bootstrap/bootstrap-sles15.sh | /bin/bash

    To avoid problems, make sure the bootstrap script is executed using bash.

    This script downloads the required dependencies located in the repositories directory you created earlier.

  4. When the script has finished running, you can check that the client is registered correctly. Open the Uyuni Web UI and navigate to Systems  Overview to ensure the new client is listed. If the client is not listed, in the Uyuni Web UI navigate to Salt  Keys and check whether the client key is accepted.

When new packages or updates are installed on the client using Uyuni, any end user license agreements (EULAs) are automatically accepted. To review a package EULA, open the package detail page in the Web UI.