openssh Cookbook

(opens in a new tab) (opens in a new tab) (opens in a new tab)

Installs and configures OpenSSH client and daemon.

Maintainers

This cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit sous-chefs.org (opens in a new tab) or come chat with us on the Chef Community Slack in #sous-chefs (opens in a new tab).

Requirements

Platforms

Debian/Ubuntu
RHEL/CentOS/Scientific/Oracle
Fedora
FreeBSD
Suse Enterprise Linux
openSUSE / openSUSE leap
AIX 7.1
Windows

Chef

Chef 12.1+

Cookbooks

iptables

Recipes

default

Installs openssh packages, manages the sshd config file, configure trusted ca keys, configure revoked keys, and starts/enables the sshd service.

iptables

Creates an iptables firewall rule to allow inbound SSH connections.

Usage

Apply the default recipe to the node's run_list to ensure that the openssh packages are installed, sshd is configured, and the service is started and enabled

Attributes List

The attributes list is dynamically generated, and lines up with the default openssh configs.

This means anything located in sshd_config (opens in a new tab) or ssh_config (opens in a new tab) can be used in your node attributes.

If the option can be entered more then once, use an Array, otherwise, use a String. If the option is host-specific use a Hash (please see below for more details).
Each attribute is stored as ruby case, and converted to camel case for the config file on the fly.
The current default attributes match the stock ssh_config and sshd_config provided by openssh.
The namespace for sshd_config is node['openssh']['server'].
Likewise, the namespace for ssh_config is node['openssh']['client'].
An attribute can be an Array, a Hash or a String.
If it is an Array, each item in the array will get it's own line in the config file.
Hash attributes are meant to used with ssh_config namespace to create host-specific configurations. The keys of the Hash will be used as the Host entries and their associated entries as the configuration values.
All the values in openssh are commented out in the attributes/default.rb file for a base starting point.
There is one special attribute name, which is match. This is not included in the default template like the others. node['openssh']['server']['match'] must be a Hash, where the key is the match pattern criteria and the value should be a Hash of normal keywords and values. The same transformations listed above apply to these keywords. To get improved sorting of match items, you can prefix the key with a number. See examples below.

Dynamic ListenAddress

Pass in a Hash of interface names, and IP address type(s) to bind sshd to. This will expand to a list of IP addresses which override the default node['openssh']['server']['listen_address'] value.

Examples and Common usage

These can be mixed and matched in roles and attributes. Please note, it is possible to get sshd into a state that it will not run. If this is the case, you will need to login via an alternate method and debug sshd like normal.

No Password logins

This requires use of identity files to connect

"openssh": {
  "server": {
    "password_authentication": "no"
  }
}

Change sshd Port

"openssh": {
  "server": {
    "port": "14188"
  }
}

Match

"openssh": {
  "server": {
    "match": {
      "Address 192.168.1.0/24": {
        "password_authentication": "yes"
      },
      "Group admins": {
        "permit_tunnel": "yes",
        "max_sessions": "20"
      }
    }
  }
}

Match with sorting

"openssh": {
  "server": {
    "match": {
      "0 User foobar": {
        "force_command": "internal-sftp -d /home/%u -l VERBOSE"
      },
      "Group admins": {
        "force_command": "internal-sftp -d /home/admins -l VERBOSE"
      }
    }
  }
}

Enable X Forwarding

"openssh": {
  "server": {
    "x11_forwarding": "yes"
  }
}

Bind to a specific set of address (this example actually binds to all)

Not to be used with node['openssh']['listen_interfaces'].

"openssh": {
  "server": {
    "address_family": "any",
      "listen_address": [ "192.168.0.1", "::" ]
    }
  }
}

Bind to the addresses tied to a set of interfaces

"openssh": {
  "listen_interfaces": {
    "eth0": "inet",
    "eth1": "inet6"
  }
}

Configure Trusted User CA Keys

"openssh": {
  "ca_keys": [
    "ssh-rsa key... ca_id_1",
    "ssh-rsa key... ca_id_2"
  ]
}

Configure Revoked Keys

"openssh": {
  "server": {
    "revoked_keys": [
      "ssh-rsa key... user_key_1",
      "ssh-rsa key... user_key_2"
    ]
  }
}

Host-specific configurations with hashes

You can use a Hash with node['openssh']['client'] to configure different values for different hosts.

"client": {
  "*": {
    "g_s_s_a_p_i_authentication": "yes",
    "send_env": "LANG LC_*",
    "hash_known_hosts": "yes"
  },
  "localhost": {
    "user_known_hosts_file": "/dev/null",
    "strict_host_key_checking": "no"
  },
  "127.0.0.1": {
    "user_known_hosts_file": "/dev/null",
    "strict_host_key_checking": "no"
  },
  "other*": {
    "user_known_hosts_file": "/dev/null",
    "strict_host_key_checking": "no"
  }
}

The keys are used as values with the Host entries. So, the configuration fragment shown above generates:

Host *
SendEnv LANG LC_*
HashKnownHosts yes
GSSAPIAuthentication yes
Host localhost
StrictHostKeyChecking no
UserKnownHostsFile /dev/null
Host 127.0.0.1
StrictHostKeyChecking no
UserKnownHostsFile /dev/null
Host other*
StrictHostKeyChecking no
UserKnownHostsFile /dev/null

SSH Subsystems

Configure multiple SSH subsystems (e.g. sftp, netconf):

"openssh": {
  "server": {
    "subsystem": {
      "sftp": "/usr/lib/openssh/sftp-server",
      "appX": "/usr/sbin/appX"
    }
  }
}

Former declaration of single subsystem:

"openssh": {
  "server": {
    "subsystem": "sftp /usr/lib/openssh/sftp-server"
  }
}

Contributors

This project exists thanks to all the people who contribute. (opens in a new tab)

Backers

Thank you to all our backers!