## Chapter 5. Using Bootstrap¶

SUSE Manager provides a tool that automates much of the manual reconfiguration described in previous chapters: mgr-bootstrap. This tool plays an integral role in the SUSE Manager Server Installation Program, enabling generation of the bootstrap script during installation.

SUSE Manager Proxy Server customers and customers with updated SUSE Manager Server setting require a bootstrap tool that can be used independently. SUSE Manager Bootstrap, invoked with the command /usr/bin/mgr-bootstrap, serves that purpose and comes installed by default on both SUSE Manager Server and SUSE Manager Proxy Server.

If used correctly, the script this tool generates can be run from any client system to conduct the following tasks:

- Redirect client applications to the SUSE Manager Proxy or SUSE Manager

- Import custom GPG keys

- Install SSL certificates

- Register the system to SUSE Manager and particular system groups and channels with the help of activation keys

- Perform miscellaneous post-configuration activities, including updating packages, performing reboots, and altering SUSE Manager configuration

Customers should note, however, the inherent risks of using a script to conduct configuration. Security tools such as SSL certificates are installed by the script itself. Therefore they do not yet exist on the systems and cannot be used to process transactions. This allows for the possibility of someone impersonating the SUSE Manager Server and transmitting bad data. This is mitigated by the fact that virtually all SUSE Manager Servers and client systems operate behind customer firewalls and are restricted from outside traffic. Registration is conducted via SSL and is therefore protected.

The bootstrap script `bootstrap.sh` is automatically placed in the `/srv/www/htdocs/pub/bootstrap/` directory of the SUSE Manager Server. From there it can be downloaded and run on all client systems. Note that some preparation and post-generation editing is required, as identified in the following sections. Refer to Section 5.4, “Bootstrap Options” for the tool's complete list of options. Finally, refer to the Appendix A, Sample Bootstrap Script for an example script.

## 5.1. Preparation¶

Since Bootstrap (`mgr-bootstrap`) depends on other components of the SUSE Manager infrastructure to properly configure client systems, those components must be prepared before script generation. The following list identifies suggested initial measures:

- Generate activation keys to be called by the script(s). Activation keys can be used to register client systems, entitle them to a SUSE Manager service level, and subscribe them to specific channels and system groups, all in one action. Note that you must have Management entitlements available to use an activation key, while inclusion of multiple activation keys at once requires Provisioning entitlements. Generate activation keys through the Activation Keys page within the Systems category of the SUSE Manager website. Refer to the SUSE Manager Reference Guide for instructions on creation and use.

- We recommend your RPMs be signed by a custom GNU Privacy Guard (GPG) key. Make the key available so you may refer to it from the script. Generate the key as described in the Channel Management Guide and place the key in the `/srv/www/htdocs/pub/` directory of the SUSE Manager Server, per Chapter 4, Importing Custom GPG Keys.

- If you wish to use the script to deploy your CA SSL public certificate, have the certificate or the package (RPM) containing that certificate available on that SUSE Manager Server and include it during script generation with the `--ssl-cert` option. Refer to Chapter 3, SSL Infrastructure for details.

- Have the values ready to develop one or many bootstrap scripts, depending on the variety of systems to be reconfigured. Since mgr-bootstrap provides a full set of reconfiguration options, you may use it to generate different bootstrap scripts to accommodate each type of system. For instance, `bootstrap-web-servers.sh` might be used to reconfigure your Web servers, while `bootstrap-app-servers.sh` can handle the application servers. Consult Section 5.4, “Bootstrap Options” for the complete list.

## 5.2. Generation¶

Now that all of the necessary components are in place, you may use mgr-bootstrap to generate the required scripts. Log into your SUSE Manager Server or SUSE Manager Proxy Server as root and issue the mgr-bootstrap command followed by the desired options and values. If no options are included, a `bootstrap.sh` file is created in the `bootstrap/` subdirectory that contains the essential values derived from the server, including hostname, the SSL certificate, it if exists, SSL and GPG settings, and a call for the `client-config-overrides.txt` file.

At a minimum, we strongly recommend your scripts also accommodate activation keys, GPG keys, and advanced configuration options in the following manner:

- Use the `--activation-keys` option to include keys, taking into account the Entitlement requirements identified in Section 5.1, “Preparation”.

- Use the `--gpg-key` option to identify the key path and filename during script generation. Otherwise, use the `--no-gpg` option to turn off this verification on client systems. We recommend retaining this security measure.

- Include the `--allow-config-actions` flag to enable remote configuration management on all client systems touched by the script. This feature is useful in reconfiguring multiple systems simultaneously.

- Include the `--allow-remote-commands` flag to enable remote script use on all client systems. Like configuration management, this feature aids in reconfiguring multiple systems.

When you're done, your command will look something like this:

    mgr-bootstrap --activation-keys KEY1,KEY2 \
                    --gpg-key /srv/www/htdocs/pub/MY_CORPORATE_PUBLIC_KEY \
                    --allow-config-actions \
                    --allow-remote-commands

Obviously, include the actual key names. Refer to Section 5.4, “Bootstrap Options” for the complete list of options.

## 5.3. Script Use¶

Finally, when you're finished preparing the script for use, you are ready to run it. Log into the SUSE Manager Server or SUSE Manager Proxy Server, navigate to the `/srv/www/htdocs/pub/bootstrap/` directory and run the following command, altering the hostname and name of the script as needed to suit the system type:

    cat bootstrap-EDITED-NAME.sh | ssh root@CLIENT_MACHINE1 /bin/bash

A less secure alternative is to use either `wget` or `curl` to retrieve and run the script from every client system. Log into each client machine and issue the following command, altering script and hostname accordingly:

    wget -qO - \
    https://your-susemgr.example.com/pub/bootstrap/bootstrap-EDITED-NAME.sh \
    | /bin/bash

Or with, `curl`:

    curl -Sks \
    https://your-susemgr.example.com/pub/bootstrap/bootstrap-EDITED-NAME.sh \
    | /bin/bash

When this script has been run on each client system, all should be configured to use the SUSE Manager Server.

## 5.4. Bootstrap Options¶

The SUSE Manager Bootstrap offers many command line options for creating client boostrap scripts. Although descriptions of these options can be found within the following table, ensure that they are available in the version of the tool installed on your SUSE Manager Server by issuing the command mgr-bootstrap --help or reviewing its man page.

Table 5.1. Bootstrap Options

Option | Description
--- | ---
`-h`, `--help` | Display the help screen with a list of options specific to generating the bootstrap script.
`--activation-keys=`ACTIVATION_KEYS`` | activation key(s) as defined in the SUSE Manager website with multiple entries separated by a comma and no space
`--overrides=`OVERRIDES`` | Configuration overrides filename. The default is client-config-overrides.txt.
`--script=`SCRIPT`` | The bootstrap script filename. The default is bootstrap.sh.
`--hostname=`HOSTNAME`` | The fully qualified domain name (FQDN) of the server to which client systems will connect.
`--ssl-cert=`SSL_CERT`` | The path to your organization's public SSL certificate, either a package or a raw certificate. It will be copied to the `--pub-tree` option. A value of `""` will force a search of `--pub-tree`.
`--gpg-key=`GPG_KEY`` | The path to your organization's public GPG key, if used. It will be copied to the location specified by the `--pub-tree` option.
`--http-proxy=`HTTP_PROXY`` | The HTTP proxy setting for the client systems in the form `hostname:port`. A value of `""` disables this setting.
`--http-proxy-username=`HTTP_PROXY_USERNAME`` | If using an authenticating HTTP proxy, specify a username. A value of `""` disables this setting.
`--http-proxy-password=`HTTP_PROXY_PASSWORD`` | If using an authenticating HTTP proxy, specify a password.
`--allow-config-actions` | Boolean; including this option sets the system to allow all configuration actions via Novell Customer Center. This requires installing certain mgrcfg-* packages, possibly through an activation key.
`--allow-remote-commands` | Boolean; including this option sets the system to allow arbitrary remote commands via Novell Customer Center. This requires installing certain mgrcfg-* packages, possibly through an activation key.
`--no-ssl` | Not recommended - Boolean; including this option turns SSL off on the client system.
`--no-gpg` | Not recommended - Boolean; including this option turns GPG checking off on the client system.
`--no-up2date` | Not recommended - Boolean; including this option ensures zypper up will not run once the system has been bootstrapped.
`--pub-tree=`PUB_TREE`` | Change not recommended - The public directory tree where the CA SSL certificate and package will land; the bootstrap directory and scripts. The default is `/srv/www/htdocs/pub/`.
`--force` | Not recommended - Boolean; including this option forces bootstrap script generation despite warnings.
`-v`, `--verbose` | Display verbose messaging. Accumulative; `-vvv` causes extremely verbose messaging.