.. -*- mode: 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 dsa, rsa, or v1 key,
  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
  ``<repo>/SSHbase/<key filename>.H_<hostname>``

* Pre-seeding can also be performed using ``bcfg2-admin pull
  ConfigFile /name/of/ssh/key``

* Revoking existing keys -- deleting
  ``<repo>/SSHbase/\*.H_<hostname>`` will remove keys for an existing
  client.

Aliases
=======

SSHbase has support for Aliases listed in :ref:`clients.xml
<server-plugins-grouping-metadata-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``)

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/<key
filename>.Gxx_<group name>``.  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_<hostname>`` or
``SSHbase/ssh_known_hosts.Gxx_<group name>``.  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 <server-info>` file to
control the permissions and other metadata for the keys and
``ssh_known_hosts`` file.  You can use the ``<Path>`` directive in
``info.xml`` to change the metadata for different keys, e.g.::

    <FileInfo>
      <Path name="/etc/ssh/ssh_host_dsa_key">
        <Info owner="root" group="wheel" mode="0660"/>
      </Path>
      <Path name="/etc/ssh/ssh_host_dsa_key.pub">
        <Info owner="root" group="wheel" mode="0664"/>
      </Path>
    </FileInfo>

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]_key     | root  | root  | 0600 | false     | false    | None     |
+----------------------------------+-------+-------+------+-----------+----------+----------+
| ssh_host_[rsa|dsa|ecdsa]_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
<server-admin-pull>`.  You should almost certainly set ``sensitive``
to "true" in ``info.xml``.

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`.