.. -*- mode: rst -*- .. vim: ft=rst .. _server-plugins-generators-sshbase: ======= SSHbase ======= SSHbase is a purpose-built Bcfg2 plugin for managing ssh host keys. It is responsible for making ssh keys persist beyond a client rebuild and building a proper ``ssh_known_hosts`` file, including a correct localhost record for the current system. It has two functions: * Generating new ssh keys -- When a client requests a key (v1, rsa, ecdsa, etc.), and there is no existing key in the repository, one is generated. * Maintaining the ``ssh_known_hosts`` file -- all current known public keys (and extra public key stores) are integrated into a single ``ssh_known_hosts`` file, and a localhost record for the current client is added. The ``ssh_known_hosts`` file data is updated whenever any keys change, are added, or deleted. Interacting with SSHbase ======================== * Pre-seeding with existing keys -- Currently existing keys will be overwritten by new, sshbase-managed ones by default. Pre-existing keys can be added to the repository by putting them in ``/SSHbase/.H_`` * Pre-seeding can also be performed using ``bcfg2-admin pull Path /name/of/ssh/key`` * Revoking existing keys -- deleting ``/SSHbase/\*.H_`` will remove keys for an existing client. Aliases ======= SSHbase has support for Aliases listed in :ref:`clients.xml `. The address for the entries are specified either through DNS (e.g. a CNAME), or via the address attribute to the Alias. Getting started =============== #. Add SSHbase to the **plugins** line in ``/etc/bcfg2.conf`` and restart the server. This enables the SSHbase plugin on the Bcfg2 server. #. Add Path entries for ``/etc/ssh/ssh_known_hosts``, ``/etc/ssh/ssh_host_dsa_key``, ``/etc/ssh/ssh_host_dsa_key.pub``, etc., to a bundle. #. Enjoy. At this point, SSHbase will generate new keys for any client without a recorded key in the repository, and will generate an ``ssh_known_hosts`` file appropriately. Supported key formats ===================== SSHbase currently supports the following key formats: * RSA1 (``ssh_host_key``, ``ssh_host_key.pub``) * RSA2 (``ssh_host_rsa_key``, ``ssh_host_rsa_key.pub``) * DSA (``ssh_host_dsa_key``, ``ssh_host_dsa_key.pub``) * ECDSA (``ssh_host_ecdsa_key``, ``ssh_host_ecdsa_key.pub``) * Ed25519 (``ssh_host_ed25519_key``, ``ssh_host_ed25519_key.pub``) Group-specific keys =================== .. versionadded:: 1.2.0 In addition to host-specific keys, SSHbase also supports group-specific keys, e.g., for a high-availability cluster or similar application. Group-specific keys must be pre-seeded; SSHbase cannot create group-specific keys itself. To use group-specific keys, simply create ``SSHbase/.Gxx_``. For instance, ``ssh_host_dsa_key.pub.G65_foo-cluster``. Adding public keys for unmanaged hosts ====================================== If you have some hosts which are not managed by Bcfg2, but you would still like to have their public ssh keys available in ``ssh_known_hosts``, you can add their public keys to the ``SSHbase`` directory with a *.static* ending. Example: ``a.static``:: TEST1 ``b.static``:: TEST2 The generated ``ssh_known_hosts`` file:: TEST1 TEST2 Static ssh_known_hosts file =========================== .. versionadded:: 1.2.0 You can also distribute a fully static ``ssh_known_hosts`` file on a per-host or per-group basis by creating ``SSHbase/ssh_known_hosts.H_`` or ``SSHbase/ssh_known_hosts.Gxx_``. Those files will be entirely static; Bcfg2 will not add any host keys to them itself. Permissions and Metadata ======================== .. versionadded:: 1.2.0 SSHbase supports use of an :ref:`info.xml ` file to control the permissions and other metadata for the keys and ``ssh_known_hosts`` file. You can use the ```` directive in ``info.xml`` to change the metadata for different keys, e.g.:: Default permissions are as follows: +------------------------------------------+-------+-------+------+-----------+----------+----------+ | File | owner | group | mode | sensitive | paranoid | encoding | +==========================================+=======+=======+======+===========+==========+==========+ | ssh_known_hosts | root | root | 0644 | false | false | None | +------------------------------------------+-------+-------+------+-----------+----------+----------+ | ssh_host_key | root | root | 0600 | false | false | base64 | +------------------------------------------+-------+-------+------+-----------+----------+----------+ | ssh_host_key.pub | root | root | 0644 | false | false | base64 | +------------------------------------------+-------+-------+------+-----------+----------+----------+ | ssh_host_[rsa|dsa|ecdsa|ed25519]_key | root | root | 0600 | false | false | None | +------------------------------------------+-------+-------+------+-----------+----------+----------+ | ssh_host_[rsa|dsa|ecdsa|ed25519]_key.pub | root | root | 0644 | false | false | None | +------------------------------------------+-------+-------+------+-----------+----------+----------+ Note that the ``sensitive`` attribute is false, even for private keys, in order to permit :ref:`pulling with bcfg2-admin `. You should almost certainly set ``sensitive`` to "true" in ``info.xml``. .. _server-plugins-generators-sshbase-encryption: Encryption ========== SSHbase can optionally encrypt the private keys that it generates. To enable this feature, set the ``passphrase`` option in the ``[sshbase]`` section of ``bcfg2.conf`` to the name of the passphrase that should be used to encrypt all SSH keys. (The passphrases are enumerated in the ``[encryption]`` section.) See :ref:`server-encryption` for more details on Bcfg2 encryption in general. Blog post ========= http://www.ducea.com/2008/08/24/using-the-bcfg2-sshbase-plugin/ .. note:: The linked post uses deprecated ConfigFile entries. Path entries have since replaced these. See :ref:`server-configurationentries`.