{"id":22700226,"url":"https://github.com/simp/pupmod-simp-ssh","last_synced_at":"2025-06-25T12:32:33.162Z","repository":{"id":32298727,"uuid":"35873688","full_name":"simp/pupmod-simp-ssh","owner":"simp","description":"The SIMP ssh Puppet Module","archived":false,"fork":false,"pushed_at":"2024-10-02T15:21:51.000Z","size":767,"stargazers_count":2,"open_issues_count":11,"forks_count":30,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-13T06:01:47.517Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/simp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-05-19T09:49:41.000Z","updated_at":"2024-10-22T20:42:14.000Z","dependencies_parsed_at":"2023-01-14T20:55:52.742Z","dependency_job_id":"d9fa9539-dd57-4d10-8546-be2d29c316f2","html_url":"https://github.com/simp/pupmod-simp-ssh","commit_stats":{"total_commits":143,"total_committers":30,"mean_commits":4.766666666666667,"dds":0.7552447552447552,"last_synced_commit":"b502599927deb07e42617e79f5c99f5d35aa4641"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simp%2Fpupmod-simp-ssh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simp%2Fpupmod-simp-ssh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simp%2Fpupmod-simp-ssh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simp%2Fpupmod-simp-ssh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simp","download_url":"https://codeload.github.com/simp/pupmod-simp-ssh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248670428,"owners_count":21142904,"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":["hacktoberfest"],"created_at":"2024-12-10T06:10:34.760Z","updated_at":"2025-04-13T06:01:57.039Z","avatar_url":"https://github.com/simp.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![License](https://img.shields.io/:license-apache-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)\n[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/73/badge)](https://bestpractices.coreinfrastructure.org/projects/73)\n[![Puppet Forge](https://img.shields.io/puppetforge/v/simp/ssh.svg)](https://forge.puppetlabs.com/simp/ssh)\n[![Puppet Forge Downloads](https://img.shields.io/puppetforge/dt/simp/ssh.svg)](https://forge.puppetlabs.com/simp/ssh)\n[![Build Status](https://travis-ci.org/simp/pupmod-simp-ssh.svg)](https://travis-ci.org/simp/pupmod-simp-ssh)\n\n# SSH\n\n#### Table of Contents\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [Module Description](#module-description)\n* [Setup](#setup)\n  * [What ssh affects](#what-ssh-affects)\n  * [Setup requirements](#setup-requirements)\n  * [Beginning with SSH](#beginning-with-ssh)\n* [Usage](#usage)\n  * [SSH client](#ssh-client)\n    * [Managing client settings](#managing-client-settings)\n    * [Managing client settings for specific hosts](#managing-client-settings-for-specific-hosts)\n    * [Managing additional client settings using ``ssh_config``](#managing-additional-client-settings-using-ssh_config)\n    * [Including the client by itself](#including-the-client-by-itself)\n  * [SSH server](#ssh-server)\n    * [Managing server settings](#managing-server-settings)\n    * [Managing additional server settings](#managing-additional-server-settings)\n      * [Using Hiera](#using-hiera)\n      * [Using ``sshd_config``](#using-sshd_config)\n    * [Including the server by itself](#including-the-server-by-itself)\n  * [Managing SSH ciphers](#managing-ssh-ciphers)\n    * [Server ciphers](#server-ciphers)\n    * [Client ciphers](#client-ciphers)\n  * [Managing ssh_authorized_keys](#managing-ssh_authorized_keys)\n* [Limitations](#limitations)\n* [Development](#development)\n* [Acceptance tests](#acceptance-tests)\n  * [Environment variables specific to pupmod-simp-ssh](#environment-variables-specific-to-pupmod-simp-ssh)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n## Module Description\n\nManages the SSH Client and Server\n\n\n## Setup\n\n### What ssh affects\n\nSSH installs the SSH package, runs the sshd service and manages files primarily\nin `/etc/ssh`\n\n### Setup requirements\n\nThe only requirement is including the ssh module in your modulepath\n\n### Beginning with SSH\n\n```puppet\ninclude 'ssh'\n```\n\n## Usage\n\nIncluding `ssh` will manage both the server and the client with reasonable\nsettings:\n\n```puppet\ninclude 'ssh'\n```\n\nThe `ssh` class automatically includes both the `ssh::client` and `ssh:server`\nclasses. To exclude one or both of these classes, set the appropriate parameter\nto false as shown:\n\n```puppet\nclass{ 'ssh':\n  enable_client =\u003e false,\n  enable_server =\u003e false,\n}\n```\n\n### SSH client\n\n#### Managing client settings\n\nIncluding `ssh::client` with no other options will automatically manage client\nsettings to be used with all hosts (`Host *`).\n\nIf you want to customize any of these settings, you must disable the creation\nof the default entry with `ssh::client::add_default_entry: false` and manage\n`Host *` manually with the defined type `ssh::client::host_config_entry`:\n\n\u003c!--\n  Maintainers: You can validate these examples with the acceptance test\n  \"with customized settings\" in `spec/acceptance/suites/default/ssh_spec.rb`.\n--\u003e\n\n\u003c!--\n  This example demonstrates the client side of SIMP-4440.\n\n  Acceptance test manifest = :client_manifest_w_custom_host_entries\n--\u003e\n\n```puppet\n\nclass{ 'ssh::client': add_default_entry =\u003e false }\n\nssh::client::host_config_entry{ '*':\n  gssapiauthentication      =\u003e true,\n  gssapikeyexchange         =\u003e true,\n  gssapidelegatecredentials =\u003e true,\n}\n```\n\n#### Managing client settings for specific hosts\n\nDifferent settings for particular hosts can be managed by using the defined\ntype `ssh::client::host_config_entry`:\n\n\u003c!--\n  Acceptance test manifest = :client_manifest_w_new_host\n--\u003e\n\n```puppet\n# `ancient.switch.fqdn` only understands old ciphers:\nssh::client::host_config_entry { 'ancient.switch.fqdn':\n  ciphers =\u003e [ 'aes128-cbc', '3des-cbc' ],\n}\n```\n\n#### Managing additional client settings using ``ssh_config``\n\nIf you need to customize a setting in `/etc/ssh/ssh_config` that\n`ssh::client::host_config_entry` doesn't manage, use the\n[`ssh_config`][aug_ssh__ssh_config] type, provided by augeasproviders_ssh:\n\n\u003c!--\n  Acceptance test manifest = :client_manifest_w_ssh_config\n--\u003e\n\n```puppet\n# RequestTTY isn't handled by ssh::client::host_config_entry\n# Note: RequestTTY is not a valid ssh_config setting on OpenSSH where version \u003c 5.9\nssh_config { 'Global RequestTTY':\n  ensure =\u003e present,\n  key    =\u003e 'RequestTTY',\n  value  =\u003e 'auto',\n}\n```\n\n#### Including the client by itself\n\n```puppet\ninclude `ssh::client`\n```\n\nYou can prevent all inclusions of `ssh` from inadvertently managing the SSH\nserver by specifying `ssh::enable_server: false`:\n\n```puppet\nclass{ 'ssh':\n  enable_client =\u003e true,\n  enable_server =\u003e false,\n}\n```\n\n\n### SSH server\n\n#### Managing server settings\n\nIncluding `ssh::server` with the default options will manage the server with\nreasonable settings for each host's environment.\n\n```puppet\ninclude 'ssh::server'\n\n# Alternative:\n# if `ssh::enable_server: true`, this will also work\ninclude 'ssh'\n```\n\nIf you want to customize any ``ssh::server`` settings, you must edit the\nparameters of `ssh::server::conf` using Hiera or ENC (Automatic Parameter\nLookup).  These customizations **_cannot be made directly_** using a\nresource-style class declaration; they _must_ be made via APL:\n\n```yaml\n---\n# Note: Hiera only!\nssh::server::conf::port: 2222\nssh::server::conf::ciphers:\n- 'chacha20-poly1305@openssh.com'\n- 'aes256-ctr'\n- 'aes256-gcm@openssh.com'\nssh::server::conf::ssh_loglevel: \"verbose\"\nssh::server::conf::gssapiauthentication: true\n```\n\n```puppet\ninclude 'ssh::server'\n\n# Alternative:\n# if `ssh::enable_server: true`, this will also work\ninclude 'ssh'\n```\n\n#### Managing additional server settings\n\n##### Using Hiera\n\nUsers may specify any undefined **global** ``sshd`` settings using the\n``ssh::server::conf::custom_entries`` parameter as follows:\n\n```yaml\n---\nssh::server::conf::custom_entries:\n  GSSAPIKeyExchange: \"yes\"\n  GSSAPICleanupCredentials: \"yes\"\n```\n\n\u003c!--\n  This example demonstrates the server side of SIMP-4440 and SIMP-4197.\n--\u003e\n\nNOTE: This is parameter is **not validated**.  Be careful to only specify\noptions that are allowed for your particular SSH daemon. Invalid options may\ncause the ssh service to fail on restart. Duplicate settings will result in\nduplicate Puppet resources (i.e., manifest compilation failures).\n\n##### Using ``sshd_config``\n\nPrior to version 6.7.0 of the `simp-ssh` module, undefined ``sshd`` settings\nwere managed with [`sshd_config`][aug_ssh__sshd_config]_ type, provided by\n[augeasproviders_ssh][aug_ssh]. Although this functionality has been\nincorporated into ``ssh::server::conf::custom_entries``, it is still available,\nand in some cases such as ``Match`` entries, necessary to call directly.\n\n\u003c!--\n  Maintainers: You can validate these examples with the acceptance test\n  \"should permit additional settings via the sshd_config type\" in\n  spec/acceptance/suites/default/default_spec.rb\n\n  Acceptance test hiera    = :server_hieradata_w_additions\n  Acceptance test manifest = :server_manifest_w_additions\n--\u003e\n\nThe following examples illustrate ``Match`` entries using `sshd_config`:\n\nPuppet:\n```puppet\ninclude 'ssh::server'\n\nsshd_config { \n  \"AllowAgentForwarding\":\n    ensure    =\u003e present,\n    condition =\u003e \"Host *.example.net\",\n    value     =\u003e \"yes\",\n}\n\n# Specify unique names to avoid duplicate declarations and compilation failures\nsshd_config { \n  \"X11Forwarding foo\":\n    ensure    =\u003e present,\n    keys      =\u003e \"X11Forwarding\",\n    condition =\u003e \"Host foo User root\",\n    value     =\u003e \"yes\",\n}\n```\n\nTo delete a `sshd_config` entry, simply set `ensure` to absent as shown:\n\n```puppet\nsshd_config {\n  \"X11Forwarding foo\":\n    ensure =\u003e absent,\n}\n```\n\n#### Including the server by itself\n\nYou can focus `ssh` on managing the SSH server by itself by specifying\n`ssh::enable_client: false`:\n\n```puppet\nclass{ 'ssh':\n  enable_client =\u003e false,\n  enable_server =\u003e true,\n}\n```\n\nNote: including `ssh::client` directly would still manage the SSH client\n\n\n### Managing SSH ciphers\n\nUnless instructed otherwise, the `ssh::` classes select ciphers based on the OS\nenvironment (the OS version, the version of the SSH server, whether [FIPS\nmode][fips_mode] is enabled, etc).\n\n#### Server ciphers\n\n\u003c!--\n   Maintainers: You can validate these examples by setting the environment\n   variable `SIMP_SSH_report_dir` to a valid directory path while running\n   the acceptance tests in spec/acceptance/suites/default/ssh_spec.rb.\n--\u003e\n\nAt the time of 6.4.0, the default ciphers for `ssh::server` on EL7 when FIPS\nmode is _disabled_ are:\n\n- `aes256-gcm@openssh.com`\n- `aes128-gcm@openssh.com`\n- `aes256-ctr`\n- `aes192-ctr`\n- `aes128-ctr`\n\nThere are also 'fallback' ciphers, which are required in order to communicate\nwith systems that are compliant with [FIPS-140-2][fips140_2].  These are\n_always_ included by default unless the parameter\n`ssh::server::conf::enable_fallback_ciphers` is set to `false`:\n\n- `aes256-ctr`\n- `aes192-ctr`\n- `aes128-ctr`\n\nAt the time of 6.4.0, the 'fallback' ciphers are the default ciphers for\n`ssh::server` on EL7 when FIPS mode is enabled and EL6 in either mode.\n\n\n#### Client ciphers\n\nBy default, the system client ciphers in `/etc/ssh/ssh_config` are configured\nto strong ciphers that are recommended for use.\n\nIf you need to connect to a system that does not support these ciphers but uses\nolder or weaker ciphers, you should either:\n  - Manage an entry for that specific host using an additional\n    `ssh::client::host_config_entry`, or:\n  - Connect to the client with custom ciphers specified by the command line\n    option, `ssh -c`\n    * You can see a list of ciphers that your ssh client supports with `ssh -Q\n      cipher`.\n    * See the [ssh man pages][ssh_man] for further information.\n\nEither of the choices above are preferable to weakening the system-wide\nclient settings unecessarily.\n\n\n### Managing ssh_authorized_keys\n\nYou can manage users authorized_keys file using the ``ssh::authorized_keys``\nclass and the ``ssh::authorized_keys::keys`` hiera value.\n\n```yaml\n---\nssh::authorized_keys::keys:\n  kelly: ssh-rsa skjfhslkdjfs...\n  nick:\n  - ssh-rsa sajhgfsaihd...\n  - ssh-rsa jrklsahsgfs...\n  mike:\n    key: dlfkjsahh...\n    type: ssh-rsa\n    user: mlast\n    target: /home/gitlab-runner/.ssh/authorized_keys\n```\n\n\n## Limitations\n\nSIMP Puppet modules are generally intended to be used on a Red Hat Enterprise\nLinux-compatible distribution.\n\n## Development\n\nPlease read our [Contribution Guide][simp_contrib].\n\nIf you find any issues, they can be submitted to our\n[JIRA](https://simp-project.atlassian.net).\n\nTo see a list of development tasks available for this module, run\n\n      bundle exec rake -T\n\n## Acceptance tests\n\nTo run the system tests, you need `Vagrant` installed.\n\nYou can then run the following to execute the acceptance tests:\n\n```shell\n   bundle exec rake beaker:suites\n```\n\nSome environment variables may be useful:\n\n```shell\n   BEAKER_debug=true\n   BEAKER_destroy=onpass\n   BEAKER_provision=no\n   BEAKER_fips=yes\n```\n\n*  ``BEAKER_debug``: show the commands being run on the SUT and their output.\n*  ``BEAKER_destroy=onpass`` prevent the machine destruction if the tests fail.\n*  ``BEAKER_provision=no``: prevent the machine from being recreated.  This can\n   save a lot of time while you're writing the tests.\n*  ``BEAKER_fips=yes``:  Provision the SUTs in [FIPS mode][fips_mode].\n\n### Environment variables specific to pupmod-simp-ssh\n\n```shell\n   SIMP_SSH_report_dir=/PATH/TO/DIRECTORY\n```\n\n* ``SIMP_SSH_report_dir``: If set to a valid directory, will record the Ciphers\n  / MACs / kexalgorithms for each SSH server during the test.  This can be used\n  to validate and update the information in the [Server\n  ciphers](#server-ciphers) section.\n\n[fips140_2]: https://csrc.nist.gov/publications/detail/fips/140/2/final\n[ssh_man]: https://man.openbsd.org/ssh\n[aug_ssh]: https://github.com/hercules-team/augeasproviders_ssh/\n[aug_ssh__ssh_config]: https://github.com/hercules-team/augeasproviders_ssh#ssh_config-provider\n[aug_ssh__sshd_config]: https://github.com/hercules-team/augeasproviders_ssh#sshd_config-provider\n[simp_contrib]: https://simp.readthedocs.io/en/stable/contributors_guide/\n[fips_mode]: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/chap-federal_standards_and_regulations#sec-Enabling-FIPS-Mode\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimp%2Fpupmod-simp-ssh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimp%2Fpupmod-simp-ssh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimp%2Fpupmod-simp-ssh/lists"}