Deployment to remote hosts

Method A: The deployment system

samhain includes a system to facilitate deployment of the client to remote hosts. This system enables you to: build and store binary packages for different operating systems, install them, create baseline databases upon installation, update the server configuration, and maintain the client database required by the beltane web-based console.

The system comprises a shell script deploy.sh that will be installed in the same directory as the samhain/yule (by default, /usr/local/sbin), and a directory tree that will be installed below the samhain/yule data directory (see the Section called Layout of the deployment system>). The script and the directory tree can be relocated freely. There is a configuration file ~/.deploy.conf that is created in the home directory of the user when deploy.sh is run for the first time, where you can specify the default for the top level directory of the system.

NoteNote
 

In the following, an architecture is just a label for some group of hosts, typically a particular operating system (or some particular installation thereof). As long as you know what the label means, you can choose it freely (alphanumeric + underscore).

The architecture for a build/install host (i.e. the association between a host and the architecture-specific configuration data) is currently specified via a command-line option.

The system allows to use per-architecture customized build options, as well as per-host customized runtime configuration files.

By default, the system will search for a sufficiently advanced incarnation of dialog to provide a nice user interface. You can switch this off in favour of a plain console interface, if you prefer (or if you want to run the script non-interactively).

To use this system, you must first install it with the command:

sh$ make install-deploy

TipInstallation tip
 

This system is somewhat tied to the server (yule). While you can safely install it later, installing it together with the server will take care that the defaults are already correct. Upon first invocation a configuration file ~/.deploy.conf will be written, where you can modify the defaults settings.

WarningBackward compatibility
 

The deployment system has been completely revised in version 2.0 of samhain. It will not work with samhain versions below 2.0 (i.e. you cannot install them using this system). However, the default location and format of the client database (used by the beltane web-based console) has not changed.

Installing the new version of the deploy system will not overwrite the old version (deploy.sh will be installed as deploy2.sh, if an old version is detected).

Requirements

  1. You must have compiled and installed the server (yule) on the local host where you use the deploy system.

  2. You must have installed the deployment system by using make deploy-install. This will install the script deploy.sh into the sbindir (default /usr/local/sbin, but depends on your configure options), and the deployment system into localstatedir/install_name/profiles (default /var/lib/yule/profiles, but depends on your configure options).

    If you already have installed the deprecated version 1 deployment system, the script will be installed as deploy2.sh.

  3. For each architecture that you define, there must be (at least) one build host where development tools (C compiler, make, strip) are available to build the client executable.

  4. On each remote where you want to build or install, you should be able to login as root with ssh using RSA authentication, such that ssh-agent can be used.

TipTIP
 

To use RSA-based authentication in a secure way, you may proceed as follows:

Use ssh-keygen to create a public/private key pair. Don't forget to set a passphrase for the private key (ssh-keygen will ask for it).

Copy the public key (HOME/.ssh/identity.pub for the ssh protocol version 1, HOME/.ssh/id_rsa.pub for ssh protocol version 2) to HOME/.ssh/authorized_keys on any remote host where you want to log in. Do not copy the private key HOME/.ssh/identity (ssh protocol version 1) or HOME/.ssh/id_rsa (ssh protocol version 2) to any untrusted host !

On your central host, execute the commands (use "ssh-agent -c" if you are using a csh-style shell):

bash$eval `ssh-agent -s`
bash$ssh-add

You can then ssh/scp without typing the passphrase again, until you exit the current shell.

Layout of the deployment system

(localstatedir)/(install_name)/profiles/
                      |
                      |
                      |-- source ------------> (tarballs)
                      |
                      |-- configs -----------> (default configs)
                      |
                      |-- archpkg
                      |    | 
                      |    |-- architecture -> (compiled package, setup script)
                      |
                      |-- hosts
                      |    |
                      |    |-- hostname -----> (optional host-specific config)
                      |
                      |-- libexec -----------> (scripts)
                      |
                      |-- private -----------> (gpg key)
                      |
                      |-- tmp

Using the deploy.sh script

TipTip
 

When run for the first time, deploy.sh will create a configuration file ~/.deploy.conf with some default configuration options. You may want to review this file. Note that you can override all options there with command-line options; the configuration file is just for convenience, if you don't like the defaults and don't want to type the corresponding option on the command line every time.

deploy.sh can be invoked in three ways:

bash$deploy.sh --help
This will provide a general overview.
bash$deploy.sh --help command
This will provide help on a specific command (where command can be any of:
'clean', 'download', 'checksrc', 'build', or 'install'.
bash$deploy.sh [options] command
This will run 'command' with the specified options.

A log of the last run will be kept in tmp/logfile.lastrun

command can be any of the following:

deploy.sh download

This command will download a source tarball from the distribution website, verify its GnuPG signature, and install it into the source subdirectory. This command requires that either wget or lynx is in your PATH.

NoteManual installation of source
 

This note applies if you want to download source manually instead. Samhain distribution tarballs contain exactly two files: first, a source tarball with the source code, and second, its GnuPG signature. For installation into the source subdirectory, the distribution tarball must be unpacked, and both the source source tarball and its GnuPG signature moved into the source subdirectory.

deploy.sh build

This command will create a temporary directory on a remote build host, copy the selected version of the source there, build the selected format of the binary installer package, retrieve and store the package into the archpkg/<architecture> subdirectory, and remove the temporary build directory.

For each build, up to four files will be stored: (a) the binary installer package samhain-<version>.<format>, (b) the configure options used (configure-<version>.<format>), (c) the samhain-install.sh script generated during the build (install-<version>.<format>), and (only for packed executables) the client password set in the executable (PASSWD-<version>.<format>).

NotePackage formats
 

Note that the build host must provide the required tools if you want to build a package for the native package manager (i.e. deb, rpm, tbz2, or solaris pkg). On RPM-based Linux distributions and Gentoo Linux, building of RPMs and tbz2s, respectively, should just work. Debian requires additional packages for building debs.

The "run" binary package format does not require additional tools (it is a self-extracting tar package based on the makeself application, which is included in the samhain distribution). Use /bin/sh <package> --help for details.

deploy.sh install

This command will create a temporary directory on a remote host, copy the selected version of the installer package, its corresponding samhain-install.sh script, the runtime configuration file, and the preinstall, postinstall, initscripts scripts there. It will then:

(A) run the preinstall script on the client, which shuts down the running samhain daemon (if there is any).

(B) install the binary installer package on the client.

(C) run the postinstall script on the client, which sets the client password (unless the binary is packed), and replaces the default runtime configuration file with the proper one. The latter step is required, because deploy.sh build builds from the pristine source, so the runtime configuration file in the installer package is just the default one.

(D) copy the proper client runtime configuration file to the server data directory (as rc.<client_name>), fix the server configuration file, and restart the server (which will fail non-fatally if the server is not running).

(E) run the initscript script on the client, which initializes (or updates) the baseline database.

(F) retrieve the baseline database, copy it to the server data directory (as file.<client_name>), and remove the temporary directory on the client.

NoteThe runtime configuration file
 

If hosts/<hostname>/<arch>.samhainrc or hosts/<hostname>/samhainrc exists, this will be used (in this order of preference), otherwise configs/<arch>.samhainrc will be used. If the latter does not exist, the command will fail.

NoteTransparent handling of particular build options
 

The build options '--enable-stealth=..' is handled by determining the argument from the configure options that were used for the build, and preparing the runtime configuration file appropriately. I.e., you should provide a 'normal', plain-text configuration file.

The build option '--with-nocl=..' is handled by determining the argument (which is required for database initialization) from the configure options that were used for the build, and passing it to the initscript script.

Usage notes

WarningWarning
 

On Solaris, the PATH environment variable on the remote host (where you build or deploy) may get set according to /etc/default/su, which may be different from what you would expect (noted by S. Bailey).