{"id":19871926,"url":"https://github.com/saltstack-formulas/openssh-formula","last_synced_at":"2026-01-26T18:54:39.373Z","repository":{"id":8924603,"uuid":"10653604","full_name":"saltstack-formulas/openssh-formula","owner":"saltstack-formulas","description":null,"archived":false,"fork":false,"pushed_at":"2025-01-06T23:09:45.000Z","size":593,"stargazers_count":89,"open_issues_count":22,"forks_count":295,"subscribers_count":44,"default_branch":"master","last_synced_at":"2025-01-11T16:38:05.266Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saltstack-formulas.png","metadata":{"files":{"readme":"docs/README.rst","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-06-12T22:16:16.000Z","updated_at":"2024-12-14T15:58:51.000Z","dependencies_parsed_at":"2023-10-03T14:38:51.629Z","dependency_job_id":"8115ea7f-b783-4c75-a437-6c7899e748d3","html_url":"https://github.com/saltstack-formulas/openssh-formula","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saltstack-formulas%2Fopenssh-formula","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saltstack-formulas%2Fopenssh-formula/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saltstack-formulas%2Fopenssh-formula/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saltstack-formulas%2Fopenssh-formula/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saltstack-formulas","download_url":"https://codeload.github.com/saltstack-formulas/openssh-formula/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241296646,"owners_count":19940073,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T16:13:59.858Z","updated_at":"2026-01-26T18:54:34.342Z","avatar_url":"https://github.com/saltstack-formulas.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"openssh-formula\n===============\n\n|img_travis| |img_sr|\n\n.. |img_travis| image:: https://travis-ci.com/saltstack-formulas/openssh-formula.svg?branch=master\n   :alt: Travis CI Build Status\n   :scale: 100%\n   :target: https://travis-ci.com/saltstack-formulas/openssh-formula\n.. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg\n   :alt: Semantic Release\n   :scale: 100%\n   :target: https://github.com/semantic-release/semantic-release\n\nInstall and configure an openssh server.\n\n.. contents:: **Table of Contents**\n\nGeneral notes\n-------------\n\nSee the full `SaltStack Formulas installation and usage instructions\n\u003chttps://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html\u003e`_.\n\nIf you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section\n\u003chttps://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas\u003e`_.\n\nIf you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``,\nwhich contains the currently released version. This formula is versioned according to `Semantic Versioning \u003chttp://semver.org/\u003e`_.\n\nSee `Formula Versioning Section \u003chttps://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning\u003e`_ for more details.\n\nIf you need (non-default) configuration, please refer to:\n\n- `how to configure the formula with map.jinja \u003cmap.jinja.rst\u003e`_\n- the ``pillar.example`` file\n\n\nContributing to this repo\n-------------------------\n\n**Commit message formatting is significant!!**\n\nPlease see `How to contribute \u003chttps://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst\u003e`_ for more details.\n\nAvailable states\n----------------\n\n.. contents::\n   :local:\n\n``openssh``\n^^^^^^^^^^^\n\nInstalls the ``openssh`` server package and service.\n\n``openssh.auth``\n^^^^^^^^^^^^^^^^\n\nManages SSH certificates for users.\n\n``openssh.auth_map``\n^^^^^^^^^^^^^^^^^^^^\n\nSame functionality as openssh.auth but with a simplified Pillar syntax.\nPlays nicely with `Pillarstack\n\u003chttps://docs.saltstack.com/en/latest/ref/pillar/all/salt.pillar.stack.html\u003e`_.\n\n``openssh.banner``\n^^^^^^^^^^^^^^^^^^\n\nInstalls a banner that users see when SSH-ing in.\n\n``openssh.client``\n^^^^^^^^^^^^^^^^^^\n\nInstalls the openssh client package.\n\n``openssh.config``\n^^^^^^^^^^^^^^^^^^\n\nInstalls the ssh daemon configuration file included in this formula\n(under \"openssh/files\"). This configuration file is populated\nby values from pillar. ``pillar.example`` results in the generation\nof the default ``sshd_config`` file on Debian Wheezy.\n\nIt is highly recommended ``PermitRootLogin`` is added to pillar\nso root login will be disabled.\n\n``openssh.config_ini``\n^^^^^^^^^^^^^^^^^^^^^^\n\nVersion of managing ``sshd_config`` that uses the\n`ini_managed.option_present \u003chttps://docs.saltstack.com/en/latest/ref/states/all/salt.states.ini_manage.html\u003e`_\nstate module, so it enables to override only one or\nmultiple values and keeping the defaults shipped by your\ndistribution.\n\n\n``openssh.known_hosts``\n^^^^^^^^^^^^^^^^^^^^^^^\n\nManages ``/etc/ssh/ssh_known_hosts`` and fills it with the\npublic SSH host keys of your minions (collected via the Salt mine)\nand of hosts listed in you pillar data. It's possible to include\nminions managed via ``salt-ssh`` by using the ``known_hosts_salt_ssh`` renderer.\n\nYou can restrict the set of minions\nwhose keys are listed by using the pillar data ``openssh:known_hosts:target``\nand ``openssh:known_hosts:tgt_type`` (those fields map directly to the\ncorresponding attributes of the ``mine.get`` function).\n\nThe **Salt mine** is used to share the public SSH host keys, you must thus\nconfigure it accordingly on all hosts that must export their keys. Two\nmine functions are required, one that exports the keys (one key per line,\nas they are stored in ``/etc/ssh/ssh_host_*_key.pub``) and one that defines\nthe public hostname that the keys are associated to. Here's the way to\nsetup those functions through pillar::\n\n    # Required for openssh.known_hosts\n    mine_functions:\n      public_ssh_host_keys:\n        mine_function: cmd.run\n        cmd: cat /etc/ssh/ssh_host_*_key.pub\n        python_shell: true\n      public_ssh_hostname:\n        mine_function: grains.get\n        key: id\n\nThe above example assumes that the minion identifier is a valid DNS name\nthat can be used to connect to the host. If that's not the case, you might\nwant to use the ``fqdn`` grain instead of the ``id`` one. The above example\nalso uses the default mine function names used by this formula. If you have to\nuse other names, then you should indicate the names to use in pillar keys\n``openssh:known_hosts:mine_keys_function`` and\n``openssh:known_hosts:mine_hostname_function``.\n\nYou can also integrate alternate DNS names of the various hosts in\n``/etc/ssh/ssh_known_hosts``. You just have to specify all the alternate DNS names as a\nlist in the ``openssh:known_hosts:aliases`` pillar key. Whenever the IPv4 or\nIPv6 behind one of those DNS entries matches an IPv4 or IPv6 behind the\nofficial hostname of a minion, the alternate DNS name will be associated to the\nminion's public SSH host key.\n\nTo **include minions managed via salt-ssh** install the ``known_hosts_salt_ssh`` renderer::\n\n    # in pillar.top:\n    '*':\n      - openssh.known_hosts_salt_ssh\n\n    # In your salt/ directory:\n    # Link the pillar file:\n    mkdir pillar/openssh\n    ln -s ../../formulas/openssh-formula/_pillar/known_hosts_salt_ssh.sls pillar/openssh/known_hosts_salt_ssh.sls\n\nYou'll find the cached pubkeys in Pillar ``openssh:known_hosts:salt_ssh``.\n\nIt's possible to define aliases for certain hosts::\n\n    openssh:\n      known_hosts:\n        cache:\n          public_ssh_host_names:\n            minion.id:\n              - minion.id\n              - alias.of.minion.id\n\nThe cache is populated by applying ``openssh.gather_host_keys``\nto the salt master::\n\n    salt 'salt-master.example.test' state.apply openssh.gather_host_keys\n\nThe state tries to fetch the SSH host keys via ``salt-ssh``. It calls the command as user\n``salt-master`` by default. The username can be changed via Pillar::\n\n    openssh:\n      known_hosts:\n        cache:\n          user: salt-master\n\nUse a cronjob to populate a host key cache::\n\n    # crontab -e -u salt-master\n    0 1 * * * salt 'salt-master.example.test' state.apply openssh.gather_host_keys\n\nIf you must have the latest pubkeys, run the state before all others::\n\n    # states/top.sls:\n    base:\n      salt:\n        # slooooow!\n        - openssh.gather_host_keys\n\nYou can also use a \"golden\" known hosts file. It overrides the keys fetched by the cronjob.\nThis lets you re-use the trust estabished in the salt-ssh user's known_hosts file::\n\n    # In your salt/ directory: (Pillar expects the file here.)\n    ln -s /home/salt-master/.ssh/known_hosts ./known_hosts\n\n    # Test it:\n    salt-ssh 'minion' pillar.get 'openssh:known_hosts:salt_ssh'\n\nTo add **public keys of hosts not among your minions** list them under the\npillar key ``openssh:known_hosts:static``::\n\n    openssh:\n      known_hosts:\n        static:\n          github.com: 'ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq[...]'\n          gitlab.com: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABA[...]'\n\nPillar ``openssh:known_hosts:static`` overrides ``openssh:known_hosts:salt_ssh``.\n\nTo **include localhost** and local IP addresses (``127.0.0.1`` and ``::1``) use this Pillar::\n\n    openssh:\n      known_hosts:\n        include_localhost: true\n\nTo prevent ever-changing IP addresses from being added to a host, use this::\n\n    openssh:\n      known_hosts:\n        omit_ip_address:\n          - my.host.tld\n\nTo completely disable adding IP addresses::\n\n    openssh:\n      known_hosts:\n        omit_ip_address: true\n\n``openssh.moduli``\n^^^^^^^^^^^^^^^^^^\n\nManages the system wide ``/etc/ssh/moduli`` file.\n\n``openssh._mapdata``\n^^^^^^^^^^^^^^^^^^^^\n\nTesting state which dumps the ``map.jinja`` values in ``/tmp/salt_mapdata_dump.yaml``.\nThis state is not called by any include but is mostly used by kitchen and Inspec infrastructure to validate ``map.jinja``.\n\n\nTesting\n-------\n\nLinux testing is done with ``kitchen-salt``.\n\nRequirements\n^^^^^^^^^^^^\n\n* Ruby\n* Docker\n\n.. code-block:: bash\n\n   $ gem install bundler\n   $ bundle install\n   $ bin/kitchen test [platform]\n\nWhere ``[platform]`` is the platform name defined in ``kitchen.yml``,\ne.g. ``debian-9-2019-2-py3``.\n\n``bin/kitchen converge``\n^^^^^^^^^^^^^^^^^^^^^^^^\n\nCreates the docker instance and runs the ``openssh`` main states, ready for testing.\n\n``bin/kitchen verify``\n^^^^^^^^^^^^^^^^^^^^^^\n\nRuns the ``inspec`` tests on the actual instance.\n\n``bin/kitchen destroy``\n^^^^^^^^^^^^^^^^^^^^^^^\n\nRemoves the docker instance.\n\n``bin/kitchen test``\n^^^^^^^^^^^^^^^^^^^^\n\nRuns all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.\n\n``bin/kitchen login``\n^^^^^^^^^^^^^^^^^^^^^\n\nGives you SSH access to the instance for manual testing.\n\nTesting with Vagrant\n--------------------\n\nWindows/FreeBSD/OpenBSD testing is done with ``kitchen-salt``.\n\nRequirements\n^^^^^^^^^^^^\n\n* Ruby\n* Virtualbox\n* Vagrant\n\nSetup\n^^^^^\n\n.. code-block:: bash\n\n   $ gem install bundler\n   $ bundle install --with=vagrant\n   $ bin/kitchen test [platform]\n\nWhere ``[platform]`` is the platform name defined in ``kitchen.vagrant.yml``,\ne.g. ``windows-81-latest-py3``.\n\nNote\n^^^^\n\nWhen testing using Vagrant you must set the environment variable ``KITCHEN_LOCAL_YAML`` to ``kitchen.vagrant.yml``.  For example:\n\n.. code-block:: bash\n\n   $ KITCHEN_LOCAL_YAML=kitchen.vagrant.yml bin/kitchen test      # Alternatively,\n   $ export KITCHEN_LOCAL_YAML=kitchen.vagrant.yml\n   $ bin/kitchen test\n\nThen run the following commands as needed.\n\n``bin/kitchen converge``\n^^^^^^^^^^^^^^^^^^^^^^^^\n\nCreates the Vagrant instance and runs the ``openssh`` main states, ready for testing.\n\n``bin/kitchen verify``\n^^^^^^^^^^^^^^^^^^^^^^\n\nRuns the ``inspec`` tests on the actual instance.\n\n``bin/kitchen destroy``\n^^^^^^^^^^^^^^^^^^^^^^^\n\nRemoves the Vagrant instance.\n\n``bin/kitchen test``\n^^^^^^^^^^^^^^^^^^^^\n\nRuns all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.\n\n``bin/kitchen login``\n^^^^^^^^^^^^^^^^^^^^^\n\nGives you RDP/SSH access to the instance for manual testing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaltstack-formulas%2Fopenssh-formula","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaltstack-formulas%2Fopenssh-formula","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaltstack-formulas%2Fopenssh-formula/lists"}