This is a short how-to in staging a SSH master which is the - text file - repository where the pristine sources of all SSH public keys, management scripts and configuration files will be held.

The requirements for a SSH master repository are almost negligible in terms of disk space and CPU resources. However, when triggering a key distribution process, a number of parallel SSH sessions will be spawned which will take up some system resources (see MAX_BACKGROUND_PROCS setting in the script). By default this is set to 30. In terms of network and firewall configurations: all SSH controls client hosts must be reachable through SSH (standard port 22) from the SSH master.

The basic steps to configure a SSH master are (as root user):

  1. Add a dedicated OS group & user - for example sshadmin - who will be the owner of the repository. The administrative account does not need a password (so lock it) but does require a valid shell:
[master]$ groupadd sshadmin
[master]$ useradd -g sshadmin sshadmin
  1. Create the repository:
[master]$ mkdir -p /etc/ssh_master
[master]$ chown -R sshadmin:sshadmin /etc/ssh_master
  1. Create a SSH key pair for the sshadmin user. This key pair will be used to authenticate on each of the SSH controls client systems when doing an update. If you opt to create a key with passphrase then you must:
    1. make sure you have a SSH agent process running on either SSH master server or your the machine you are originally connecting from (with agent forwarding enabled).
    2. add this key to the running SSH agent. Failing to do will block any remote update process to client hosts.
  1. Create the key repository with the keys that need to be distributed. You can choose to either store all keys in one big file or use a keys.d directory with separate key files. Make sure you add the keys in the required format! (see Master configuration files for more details):
[master]$ mkdir -p /etc/ssh_master/keys.d
[master]$ vi /etc/ssh_master/keys.d/newkey1
[master]$ vi /etc/ssh_master/keys.d/newkey2
[master]$ chown -R sshadmin:sshadmin /etc/ssh_master
  1. Create an initial version of the required master configuration files
[master]$ touch /etc/ssh_master/access
[master]$ touch /etc/ssh_master/alias
[master]$ touch /etc/ssh_master/targets
[master]$ chown -R sshadmin:sshadmin /etc/ssh_master

Build/edit the access, alias & targets files to fit your environment.

  1. Copy the management scripts into the repository:
[master]$ cp /etc/ssh_master/
[master]$ cp /etc/ssh_master/
[master]$ cp /etc/ssh_master/
[master]$ chown -R sshadmin:sshadmin /etc/ssh_master
[master]$ chmod ug+x /etc/ssh_master/
[master]$ chmod ug+x /etc/ssh_master/
[master]$ chmod ug+x /etc/ssh_master/

You may want to review the following settings in the manage_ssh.conf or manage_ssh.conf.local configuration files, especially if you are not using the default /etc/ssh_master & /etc/ssh_controls paths:

Note: the REMOTE_DIR & LOCAL_DIR settings can also be specified as command-line parameters to the script.

  1. Copy or configure the client configuration file:
[master]$ cp source:update_ssh.conf /etc/ssh_master/
[master]$ chown -R sshadmin:sshadmin /etc/ssh_master
  1. Perform a syntax check on the configuration files:
[master]$ cd /etc/ssh_masterer
[master:/etc/ssh_master]$ ./ --check-syntax

INFO: *** start of [--check-syntax] ***
INFO: logging takes places in /var/log/
INFO: runtime info: LOCAL_DIR is set to: /etc/ssh_controls
INFO: ACTION: syntax-checking the configuration files ...
INFO: finished syntax-checking the configuration files
INFO: performing cleanup ...
INFO: *** finish of [--check-syntax] ***

Note: the build-in syntax check has limited capabilities. It will not catch all possible errors so CAVEAT EMPTOR.

Example repository

Following is a listing of what a SSH master repository may look like:

[master]$ ls -lR /etc/ssh_master

-rw-r-----   1 sshadmin       sshadmin     27115 May  7 12:43 access
-rw-r-----   1 sshadmin       sshadmin     19684 May  7 12:45 alias
-rwxr-x---   1 sshadmin       sshadmin      5226 Jan 16 15:59
-rw-r--r--   1 sshadmin       sshadmin     10804 Apr 30 14:47 fingerprints
drwxr-s---   2 sshadmin       sshadmin      1024 May  1 10:54 keys.d
-rwxr-x---   1 sshadmin       sshadmin     40511 Apr 10 11:17
-rw-r-----   1 sshadmin       sshadmin      5269 May  7 12:46 targets
-rw-r-----   1 sshadmin       sshadmin       686 Dec 18 10:03 update_ssh.conf
-rwxr-x---   1 sshadmin       sshadmin     25833 Dec 23 08:42


-rw-rw----   1 sshadmin       sshadmin       394 Feb 23 14:41 user1.keys
-rw-rw----   1 sshadmin       sshadmin      8794 Dec  3 08:41 team1.keys
-rw-rw----   1 sshadmin       sshadmin      3394 Dec  3 08:39 team2.keys