352 lines
10 KiB
ReStructuredText
352 lines
10 KiB
ReStructuredText
.. _readme:
|
|
|
|
openssh
|
|
=======
|
|
|img_travis| |img_sr|
|
|
|
|
.. |img_travis| image:: https://travis-ci.com/saltstack-formulas/openssh-formula.svg?branch=master
|
|
:alt: Travis CI Build Status
|
|
:scale: 100%
|
|
:target: https://travis-ci.com/saltstack-formulas/openssh-formula
|
|
.. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
|
|
:alt: Semantic Release
|
|
:scale: 100%
|
|
:target: https://github.com/semantic-release/semantic-release
|
|
|
|
Install and configure an openssh server.
|
|
|
|
.. contents:: **Table of Contents**
|
|
|
|
General notes
|
|
-------------
|
|
|
|
See the full `SaltStack Formulas installation and usage instructions
|
|
<https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
|
|
|
|
If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section
|
|
<https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas>`_.
|
|
|
|
If you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``,
|
|
which contains the currently released version. This formula is versioned according to `Semantic Versioning <http://semver.org/>`_.
|
|
|
|
See `Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>`_ for more details.
|
|
|
|
If you need (non-default) configuration, please refer to:
|
|
|
|
- `how to configure the formula with map.jinja <map.jinja.rst>`_
|
|
- the ``pillar.example`` file
|
|
|
|
|
|
Contributing to this repo
|
|
-------------------------
|
|
|
|
**Commit message formatting is significant!!**
|
|
|
|
Please see `How to contribute <https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst>`_ for more details.
|
|
|
|
Available states
|
|
----------------
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
``openssh``
|
|
^^^^^^^^^^^
|
|
|
|
Installs the ``openssh`` server package and service.
|
|
|
|
``openssh.auth``
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
Manages SSH certificates for users.
|
|
|
|
``openssh.auth_map``
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Same functionality as openssh.auth but with a simplified Pillar syntax.
|
|
Plays nicely with `Pillarstack
|
|
<https://docs.saltstack.com/en/latest/ref/pillar/all/salt.pillar.stack.html>`_.
|
|
|
|
``openssh.banner``
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs a banner that users see when SSH-ing in.
|
|
|
|
``openssh.client``
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs the openssh client package.
|
|
|
|
``openssh.config``
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
Installs the ssh daemon configuration file included in this formula
|
|
(under "openssh/files"). This configuration file is populated
|
|
by values from pillar. ``pillar.example`` results in the generation
|
|
of the default ``sshd_config`` file on Debian Wheezy.
|
|
|
|
It is highly recommended ``PermitRootLogin`` is added to pillar
|
|
so root login will be disabled.
|
|
|
|
``openssh.config_ini``
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Version of managing ``sshd_config`` that uses the
|
|
`ini_managed.option_present <https://docs.saltstack.com/en/latest/ref/states/all/salt.states.ini_manage.html>`_
|
|
state module, so it enables to override only one or
|
|
multiple values and keeping the defaults shipped by your
|
|
distribution.
|
|
|
|
|
|
``openssh.known_hosts``
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Manages ``/etc/ssh/ssh_known_hosts`` and fills it with the
|
|
public SSH host keys of your minions (collected via the Salt mine)
|
|
and of hosts listed in you pillar data. It's possible to include
|
|
minions managed via ``salt-ssh`` by using the ``known_hosts_salt_ssh`` renderer.
|
|
|
|
You can restrict the set of minions
|
|
whose keys are listed by using the pillar data ``openssh:known_hosts:target``
|
|
and ``openssh:known_hosts:tgt_type`` (those fields map directly to the
|
|
corresponding attributes of the ``mine.get`` function).
|
|
|
|
The **Salt mine** is used to share the public SSH host keys, you must thus
|
|
configure it accordingly on all hosts that must export their keys. Two
|
|
mine functions are required, one that exports the keys (one key per line,
|
|
as they are stored in ``/etc/ssh/ssh_host_*_key.pub``) and one that defines
|
|
the public hostname that the keys are associated to. Here's the way to
|
|
setup those functions through pillar::
|
|
|
|
# Required for openssh.known_hosts
|
|
mine_functions:
|
|
public_ssh_host_keys:
|
|
mine_function: cmd.run
|
|
cmd: cat /etc/ssh/ssh_host_*_key.pub
|
|
python_shell: true
|
|
public_ssh_hostname:
|
|
mine_function: grains.get
|
|
key: id
|
|
|
|
The above example assumes that the minion identifier is a valid DNS name
|
|
that can be used to connect to the host. If that's not the case, you might
|
|
want to use the ``fqdn`` grain instead of the ``id`` one. The above example
|
|
also uses the default mine function names used by this formula. If you have to
|
|
use other names, then you should indicate the names to use in pillar keys
|
|
``openssh:known_hosts:mine_keys_function`` and
|
|
``openssh:known_hosts:mine_hostname_function``.
|
|
|
|
You can also integrate alternate DNS names of the various hosts in
|
|
``/etc/ssh/ssh_known_hosts``. You just have to specify all the alternate DNS names as a
|
|
list in the ``openssh:known_hosts:aliases`` pillar key. Whenever the IPv4 or
|
|
IPv6 behind one of those DNS entries matches an IPv4 or IPv6 behind the
|
|
official hostname of a minion, the alternate DNS name will be associated to the
|
|
minion's public SSH host key.
|
|
|
|
To **include minions managed via salt-ssh** install the ``known_hosts_salt_ssh`` renderer::
|
|
|
|
# in pillar.top:
|
|
'*':
|
|
- openssh.known_hosts_salt_ssh
|
|
|
|
# In your salt/ directory:
|
|
# Link the pillar file:
|
|
mkdir pillar/openssh
|
|
ln -s ../../formulas/openssh-formula/_pillar/known_hosts_salt_ssh.sls pillar/openssh/known_hosts_salt_ssh.sls
|
|
|
|
You'll find the cached pubkeys in Pillar ``openssh:known_hosts:salt_ssh``.
|
|
|
|
It's possible to define aliases for certain hosts::
|
|
|
|
openssh:
|
|
known_hosts:
|
|
cache:
|
|
public_ssh_host_names:
|
|
minion.id:
|
|
- minion.id
|
|
- alias.of.minion.id
|
|
|
|
The cache is populated by applying ``openssh.gather_host_keys``
|
|
to the salt master::
|
|
|
|
salt 'salt-master.example.test' state.apply openssh.gather_host_keys
|
|
|
|
The state tries to fetch the SSH host keys via ``salt-ssh``. It calls the command as user
|
|
``salt-master`` by default. The username can be changed via Pillar::
|
|
|
|
openssh:
|
|
known_hosts:
|
|
cache:
|
|
user: salt-master
|
|
|
|
Use a cronjob to populate a host key cache::
|
|
|
|
# crontab -e -u salt-master
|
|
0 1 * * * salt 'salt-master.example.test' state.apply openssh.gather_host_keys
|
|
|
|
If you must have the latest pubkeys, run the state before all others::
|
|
|
|
# states/top.sls:
|
|
base:
|
|
salt:
|
|
# slooooow!
|
|
- openssh.gather_host_keys
|
|
|
|
You can also use a "golden" known hosts file. It overrides the keys fetched by the cronjob.
|
|
This lets you re-use the trust estabished in the salt-ssh user's known_hosts file::
|
|
|
|
# In your salt/ directory: (Pillar expects the file here.)
|
|
ln -s /home/salt-master/.ssh/known_hosts ./known_hosts
|
|
|
|
# Test it:
|
|
salt-ssh 'minion' pillar.get 'openssh:known_hosts:salt_ssh'
|
|
|
|
To add **public keys of hosts not among your minions** list them under the
|
|
pillar key ``openssh:known_hosts:static``::
|
|
|
|
openssh:
|
|
known_hosts:
|
|
static:
|
|
github.com: 'ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq[...]'
|
|
gitlab.com: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABA[...]'
|
|
|
|
Pillar ``openssh:known_hosts:static`` overrides ``openssh:known_hosts:salt_ssh``.
|
|
|
|
To **include localhost** and local IP addresses (``127.0.0.1`` and ``::1``) use this Pillar::
|
|
|
|
openssh:
|
|
known_hosts:
|
|
include_localhost: true
|
|
|
|
To prevent ever-changing IP addresses from being added to a host, use this::
|
|
|
|
openssh:
|
|
known_hosts:
|
|
omit_ip_address:
|
|
- my.host.tld
|
|
|
|
To completely disable adding IP addresses::
|
|
|
|
openssh:
|
|
known_hosts:
|
|
omit_ip_address: true
|
|
|
|
``openssh.moduli``
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
Manages the system wide ``/etc/ssh/moduli`` file.
|
|
|
|
``openssh._mapdata``
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
Testing state which dumps the ``map.jinja`` values in ``/tmp/salt_mapdata_dump.yaml``.
|
|
This state is not called by any include but is mostly used by kitchen and Inspec infrastructure to validate ``map.jinja``.
|
|
|
|
|
|
Testing
|
|
-------
|
|
|
|
Linux testing is done with ``kitchen-salt``.
|
|
|
|
Requirements
|
|
^^^^^^^^^^^^
|
|
|
|
* Ruby
|
|
* Docker
|
|
|
|
.. code-block:: bash
|
|
|
|
$ gem install bundler
|
|
$ bundle install
|
|
$ bin/kitchen test [platform]
|
|
|
|
Where ``[platform]`` is the platform name defined in ``kitchen.yml``,
|
|
e.g. ``debian-9-2019-2-py3``.
|
|
|
|
``bin/kitchen converge``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Creates the docker instance and runs the ``openssh`` main states, ready for testing.
|
|
|
|
``bin/kitchen verify``
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Runs the ``inspec`` tests on the actual instance.
|
|
|
|
``bin/kitchen destroy``
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Removes the docker instance.
|
|
|
|
``bin/kitchen test``
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
|
|
|
|
``bin/kitchen login``
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Gives you SSH access to the instance for manual testing.
|
|
|
|
Testing with Vagrant
|
|
--------------------
|
|
|
|
Windows/FreeBSD/OpenBSD testing is done with ``kitchen-salt``.
|
|
|
|
Requirements
|
|
^^^^^^^^^^^^
|
|
|
|
* Ruby
|
|
* Virtualbox
|
|
* Vagrant
|
|
|
|
Setup
|
|
^^^^^
|
|
|
|
.. code-block:: bash
|
|
|
|
$ gem install bundler
|
|
$ bundle install --with=vagrant
|
|
$ bin/kitchen test [platform]
|
|
|
|
Where ``[platform]`` is the platform name defined in ``kitchen.vagrant.yml``,
|
|
e.g. ``windows-81-latest-py3``.
|
|
|
|
Note
|
|
^^^^
|
|
|
|
When testing using Vagrant you must set the environment variable ``KITCHEN_LOCAL_YAML`` to ``kitchen.vagrant.yml``. For example:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ KITCHEN_LOCAL_YAML=kitchen.vagrant.yml bin/kitchen test # Alternatively,
|
|
$ export KITCHEN_LOCAL_YAML=kitchen.vagrant.yml
|
|
$ bin/kitchen test
|
|
|
|
Then run the following commands as needed.
|
|
|
|
``bin/kitchen converge``
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Creates the Vagrant instance and runs the ``openssh`` main states, ready for testing.
|
|
|
|
``bin/kitchen verify``
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Runs the ``inspec`` tests on the actual instance.
|
|
|
|
``bin/kitchen destroy``
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Removes the Vagrant instance.
|
|
|
|
``bin/kitchen test``
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
|
|
|
|
``bin/kitchen login``
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Gives you RDP/SSH access to the instance for manual testing.
|