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 
      Section 1.2 ). 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.
| ![[Note]](stylesheet-images/note.png) | Note | 
|---|---|
| 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
      | ![[Tip]](stylesheet-images/tip.png) | Installation 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 
         | 
| ![[Warning]](stylesheet-images/warning.png) | Backward 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). | 
You must have compiled and installed the server ( yule ) on the local host where you use the deploy system.
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.
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.
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.
| ![[Tip]](stylesheet-images/tip.png) | Tip | 
|---|---|
| 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 (
           On your central host, execute the commands (use "ssh-agent -c" if you are using a csh-style shell): 
            You can then ssh/scp without typing the passphrase again, until you exit the current shell. | 
(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
	The 
          
          configs subdirectory holds for each
          architecture at least two files (example files will be
          placed there upon installation of the deployment
          system):
The configure options for this architecture; one option per line, each enclosed in single quotes.
If this file does not exist, it will be
                copied from 
                
                generic.configure, which is created upon
                installation, and holds (only) some minimum
                options.
The default runtime configuration file for a
                client running on this architecture. It is possible
                to override this on installation with a file 
                hosts/<hostname>/samhainrc.
The shell script to run before installing a client. Typically this script would shutdown the running client, if there is one.
Defaults to 
                
                libexec/preinstall.
The shell script to run after installing a client. This script receives the client password as first (and only) argument, and typically would set the password in the client binary.
Defaults to 
                
                libexec/postinstall.
The shell script to initialize/update the baseline database file installing a client.
Defaults to 
                
                libexec/initscript.
The 
          
          archpkg directory holds for each architecture a
          subdirectory 
          archpkg/<architecture>, where compiled binary
          installer packages are stored.
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>).
If you want to change the default options, you can
          set some of them via a configuration file 
          ~/.deploy.conf,
          which is created upon the first invocation of 
          deploy.sh .
To add support for another architecture <arch>, just create the two files 
          <arch>.configure(configure options) and 
          <arch>.samhainrc(runtime configuration) in the 
          configs directory of the deployment system (see
          
          Section 1.2 ).
Upon installation of the system, a template file 
          generic.configure is
          created, which contains the minimum options for a
          client.
The default scripts for preinstallation (shutting
          down the running client) and postinstallation (setting
          the client password, fixing the local configuration
          file), and the script for database initialization are
          located in the 
          
          libexec directory. You can override them for
          some (or all) architectures by storing
          architecture-specific files 
          <arch>.preinstall, 
          <arch>.postinstall, 
          <arch>.initscrip in the 
          
          configs directory.
| ![[Tip]](stylesheet-images/tip.png) | Tip | 
|---|---|
| When run for the first time, 
          deploy.sh will create a
          configuration file 
           | 
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:
Provides information on installed clients, or available installer packages.
Removes source tarballs from the 
              
              source subdirectory of the deploy system.
              Removes unused installer packages from the 
              
              archpkg/<arch> subdirectories of
              the deploy system.
Download a source tarball from the distribution
              site, verify the GnuPG signature (gpg must be
              installed), and install it into the 
              
              source subdirectory of the deploy system. 
              Requires one of: 
              wget , 
              curl , 
              links , 
              lynx , 
              fetch , or 
              
              lwp-request .
Check the GnuPG signatures of available source
              tarballs in the 
              
              source subdirectory of the deploy system
              (gpg must be installed). Optionally delete tarballs
              with no/invalid signature.
Build a binary installer package for the chosen
              architecture from one of the tarballs in the 
              
              source subdirectory, and store it in the 
              
              archpkg/<architecture> subdirectory
              (which will be created if it does not exist yet).
              Requires a file 
              <architecture>.configure and a file 
              <architecture>.samhainrc in the 
              
              configs subdirectory.
Copy a pre-built binary package (built with deploy.sh build ) to a remote host, stop the client running there (if any), install the (new) client, update the server configuration file and reload the server, initialize the file signature database and fetch it from the remote host.
Remove a samhain client that was previously installed with deploy.sh install .
-q | --quiet | --quiet=2 Produce output suitable for logging. Note that --quiet=2 implies --yes (see below).
-s | --simulate Print what would be done, but do not actually change the system.
-y | --yes Assume yes as answer to all prompts and run non-interactively.
-o <file> | --logfile=<file> Specify an output file for messages that would go to stdout otherwise. Has no effect on stderr (error messages).
-d <dialog> | --dialog=<dialog> Specify your preferred "dialog" clone (e.g. Xdialog). Use "no" to force plain text.
This command will show information for hosts in the client database (default), or for available binary installer packages.
This command will clean unused files: source tarballs
        in the 
        
        source subdirectory, and unused installer
        packages in the 
        archpkg/>arch> subdirectories.
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.
| ![[Note]](stylesheet-images/note.png) | Manual 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 
           | 
This command will check the GnuPG signatures of
        source tarballs in the 
        
        source subdirectory.
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>).
| ![[Note]](stylesheet-images/note.png) | Package 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, depot (HP-UX), 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. | 
--host=<hostname> The build host.
          --arch=<arch> 
	  The architecture to build for. This is used to
          get the "./configure" options from the file 
          configs/<arch>.configure, and to store the binary package
          into the directory 
          archpkg/<arch>.
          --version=<version> The version of samhain you want to build. Must
          be in the 
          
          source subdirectory.
--format=<run|rpm|deb|tbz2|depot|solaris-pkg> The format of the binary installer package. "run" is a portable (Unix) package based on makeself, "deb" is a Debian package, "tbz2" is a binary Gentoo Linux package, "rpm" is an RPM package, "depot" is an HP-UX binary package, and "solaris-pkg" for Sun Solaris.
--packed=<password> Build a packed executable, and set the client password before packing.
--user=<username> Login as <username> on the build host (defaults to root).
--add-path=<path> Append <path> to the PATH variable on the build host.
          --tmpdir=<path> Temporary directory to use on the build host
          (defaults to 
          
          /tmp).
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.
| ![[Note]](stylesheet-images/note.png) | The runtime configuration file | 
|---|---|
| If 
           | 
| ![[Note]](stylesheet-images/note.png) | Transparent 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 
           | 
--host=<hostname> The host on which to install.
--group=<foobar> The group to which you want to assign that client (default: none). This is used by the beltane web console to restrict access to users which are members of that group.
          --arch=<arch> The architecture to install. This is used to
          get the installer package from the directory 
          archpkg/<arch>/.
          --version=<version> The version of samhain you want to install. An
          installer package for this version must exist in the 
          archpkg/<arch>/ subdirectory.
--format=<run|rpm|deb|tbz2|depot|solaris-pkg> The format of the binary installer package. "run" is a portable (Unix) package based on makeself, "deb" is a Debian package, "tbz2" is a binary Gentoo Linux package, "rpm" is an RPM package, "depot" is an HP-UX binary package, and "solaris-pkg" for Sun Solaris.
--yule_exec=<path> Path to the yule executable.
--yule_conf=<path> Path to the yule configuration file.
--yule_data=<path> Path to the yule data directory.
          --no-init Do not
          initialize the file signature (baseline) database (and
          consequentially, do not replace the 
          file.<host> file on server.
          --no-rcfile Do not
          replace the 
          rc.<host> file on server.
--no-start Do not start up the client after installation.
--local=<command> An optional command executed locally (i.e. on the server) twice (with the last argument set to 'first' and 'second', respectively. First is after client config file installation (i.e. before baseline database initialisation on the client), second is just before client startup. The script will be called with the following five arguments:
hostname, i.e. the host on which to install,
arch, the architecture to install,
the directory where the deployment system is
              installed (default is 
              
              /var/lib/yule/profiles, but depends on
              your configure options),
the server data directory where client
              configuration files and baseline databases are stored
              (default is 
              
              /var/lib/yule, but depends on your
              configure options),
the literal word 'first' if the script is called the first time during client installation, the literal word 'second' otherwise.
          --tmpdir=<path> Temporary directory to use on the installation
          host (defaults to 
          
          /tmp).
This command will remove a samhain client that was previously installed by using deploy.sh install .