From fff865e8f428f93c7718b9932552ea0261a95500 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Thu, 27 Oct 2011 08:49:09 -0400 Subject: Add a number of features to SSHbase: * Support for group-specific host keys * Support for fully static host- and group-specific ssh_known_hosts * (Support for totally generic host keys and ssh_known_hosts, too, but that's pretty useless.) * Support for info.xml, info, and :info files; only info.xml is likely to be useful, with the directive --- doc/server/info.txt | 25 ++++---- doc/server/plugins/generators/sshbase.txt | 99 +++++++++++++++++++++++++++---- doc/server/plugins/grouping/metadata.txt | 2 + 3 files changed, 100 insertions(+), 26 deletions(-) (limited to 'doc') diff --git a/doc/server/info.txt b/doc/server/info.txt index 97bb92a0d..ae2bf5cf6 100644 --- a/doc/server/info.txt +++ b/doc/server/info.txt @@ -3,19 +3,18 @@ .. NOTE: these are relative links (change when directory structure .. changes) -.. _Cfg: plugins/generators/cfg -.. _TGenshi: plugins/generators/tgenshi -.. _TCheetah: plugins/generators/tcheetah - .. _server-info: ==== Info ==== -Various file properties for entries served by the `Cfg`_, `TGenshi`_, -and `TCheetah`_ plugins are controlled through the use of ``:info``, -``info``, or ``info.xml`` files. +Various file properties for entries served by the :ref:`Cfg +`, :ref:`TGenshi +`, :ref:`TCheetah +`, and :ref:`SSHbase +` plugins are controlled through +the use of ``:info``, ``info``, or ``info.xml`` files. By default, these plugins are set to write files to the filesystem with owner **root**, group **root**, and mode **644** (read and write for @@ -82,6 +81,8 @@ specification. | | | execution | | +------------+-------------------+----------------------------------+---------+ +.. _server-info-info-xml: + info.xml files ============== @@ -94,9 +95,7 @@ files are XML, and work similarly to those used by :ref:`Rules The following specifies a different global set of permissions (root/sys/0651) than on clients in group webserver or named -"foo.example.com" (root/root/0652). - -.. code-block:: xml +"foo.example.com" (root/root/0652):: @@ -108,10 +107,10 @@ The following specifies a different global set of permissions -The following specifies a different set of permissions depending on -the path of the file. +.. versionadded:: 1.2.0 -.. code-block:: xml +You can also use the ```` directive to specify a different set +of permissions depending on the path of the file:: diff --git a/doc/server/plugins/generators/sshbase.txt b/doc/server/plugins/generators/sshbase.txt index 3697b62c4..5d679c7e5 100644 --- a/doc/server/plugins/generators/sshbase.txt +++ b/doc/server/plugins/generators/sshbase.txt @@ -8,7 +8,7 @@ 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 +building a proper ``ssh_known_hosts`` file, including a correct localhost record for the current system. It has two functions: @@ -26,32 +26,35 @@ 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_ + 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 ConfigFile - /name/of/ssh/key +* Pre-seeding can also be performed using ``bcfg2-admin pull + ConfigFile /name/of/ssh/key`` -* Revoking existing keys -- deleting /SSHbase/\*.H_ - will remove keys for an existing client. +* Revoking existing keys -- deleting + ``/SSHbase/\*.H_`` will remove keys for an existing + client. Aliases ======= -SSHbase has support for Aliases listed in clients.xml. The address for -the entries are specified either through DNS (e.g. a CNAME), or via the +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 + restart the server. This enables the SSHbase plugin on the Bcfg2 server. -#. Add Path entries for ``/etc/ssh/ssh_known_hosts``, and - ``/etc/ssh/ssh_host_dsa_key``, etc to a bundle or base. +#. 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. @@ -59,6 +62,30 @@ 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/.Gxx_``. For instance, +``ssh_host_dsa_key.pub.G65_foo-cluster``. + Adding public keys for unmanaged hosts ====================================== @@ -82,6 +109,52 @@ 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 | perms | sensitive | paranoid | encoding | ++==================================+=======+=======+=======+===========+==========+==========+ +| ssh_known_hosts | root | root | 0644 | false | false | None | ++----------------------------------+-------+-------+-------+-----------+----------+----------+ +| ssh_host_key | root | root | 0600 | true | false | base64 | ++----------------------------------+-------+-------+-------+-----------+----------+----------+ +| ssh_host_key.pub | root | root | 0644 | false | false | base64 | ++----------------------------------+-------+-------+-------+-----------+----------+----------+ +| ssh_host_[rsa|dsa|ecdsa]_key | root | root | 0600 | true | false | None | ++----------------------------------+-------+-------+-------+-----------+----------+----------+ +| ssh_host_[rsa|dsa|ecdsa]_key.pub | root | root | 0644 | false | false | None | ++----------------------------------+-------+-------+-------+-----------+----------+----------+ + Blog post ========= diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index fc8605115..c52ac7612 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -25,6 +25,8 @@ modified from clients through use of the ``-p`` flag to ``bcfg2``. Clients are associated with profile groups in ``Metadata/clients.xml`` as shown below. +.. _server-plugins-grouping-metadata-clients-xml: + Metadata/clients.xml ==================== -- cgit v1.2.3-1-g7c22