Skip to content

Latest commit

 

History

History
1460 lines (950 loc) · 39.3 KB

REFERENCE.md

File metadata and controls

1460 lines (950 loc) · 39.3 KB
Raw

Reference

Table of Contents

Classes

Public Classes

Private Classes

  • ssh::client::config: Manages ssh configuration
  • ssh::client::install: Install ssh client package
  • ssh::server::config: Managed ssh server configuration
  • ssh::server::install: Install ssh server package
  • ssh::server::service: This class managed ssh server service

Defined types

This module install a ssh host key in the server (basically, it is a file resource but it also notifies to the ssh service)

Important! This define does not modify any option in sshd_config, so you have to manually define the HostKey option in the server options if you haven't done yet.

Functions

Public Functions

Private Functions

  • ssh::ipaddresses: Returns ip addresses of network interfaces (except lo) found by facter.

Data types

Classes

ssh

}

Examples

Puppet usage
class { 'ssh':
  storeconfigs_enabled         => false,
  server_options               => {
    'Match User www-data'      => {
      'ChrootDirectory'        => '%h',
      'ForceCommand'           => 'internal-sftp',
      'PasswordAuthentication' => 'yes',
      'AllowTcpForwarding'     => 'no',
      'X11Forwarding'          => 'no',
    },
    'Port'                     => [22, 2222, 2288],
  },
  client_options               => {
    'Host *.amazonaws.com'     => {
      'User'                   => 'ec2-user',
    },
  },
  users_client_options         => {
    'bob'                      => {
      options                  => {
        'Host *.alice.fr'      => {
          'User'               => 'alice',
        },
      },
    },
  },
 'server_instances' => {
   'sftp_server_init' => {
     'ensure' => 'present',
     'options' => {
       'sshd_config' => {
         'Port' => 8022,
         'Protocol' => 2,
         'AddressFamily' => 'any',
         'HostKey' => '/etc/ssh/ssh_host_rsa_key',
         'SyslogFacility' => 'AUTH',
         'LogLevel' => 'INFO',
         'PermitRootLogin' => 'no',
       },
       'sshd_service_options' => '',
       'match_blocks' => {
         '*,!ssh_exempt_ldap_authkey,!sshlokey' => {
           'type' => 'group',
           'options' => {
             'AuthorizedKeysCommand' => '/usr/local/bin/getauthkey',
             'AuthorizedKeysCommandUser' => 'nobody',
             'AuthorizedKeysFile' => '/dev/null',
           },
         },
       },
     },
   },
 },
hiera usage
ssh::storeconfigs_enabled: true

ssh::server_options:
    Protocol: '2'
    ListenAddress:
        - '127.0.0.0'
        - '%{::hostname}'
    PasswordAuthentication: 'yes'
    SyslogFacility: 'AUTHPRIV'
    UsePAM: 'yes'
    X11Forwarding: 'yes'

ssh::server::match_block:
  filetransfer:
    type: group
    options:
      ChrootDirectory: /home/sftp
      ForceCommand: internal-sftp

ssh::client_options:
    'Host *':
        SendEnv: 'LANG LC_*'
        ForwardX11Trusted: 'yes'
        ServerAliveInterval: '10'

ssh::users_client_options:
    'bob':
        'options':
            'Host *.alice.fr':
                'User': 'alice'
                'PasswordAuthentication': 'no'
 ssh::server::server_instances:
    sftp_server_init:
      ensure: present
      options:
        sshd_config:
         Port: 8022
         Protocol: 2
         AddressFamily: 'any'
         HostKey: '/etc/ssh/ssh_host_rsa_key'
         SyslogFacility: 'AUTH'
         LogLevel: INFO
         PermitRootLogin: 'no'
      sshd_service_options: ''
      match_blocks:
        '*,!ssh_exempt_ldap_authkey,!sshlokey':
           type: group
           options:
             AuthorizedKeysCommand: '/usr/local/bin/getauthkey'
             AuthorizedKeysCommandUser: 'nobody'
             AuthorizedKeysFile: '/dev/null'

Parameters

The following parameters are available in the ssh class:

server_options

Data type: Optional[Hash]

Add dynamic options for ssh server config

Default value: undef

server_match_block

Data type: Hash

Add match block for ssh server config

Default value: {}

client_options

Data type: Optional[Hash]

Add dynamic options for ssh client config

Default value: undef

client_match_block

Data type: Hash

Add match block for ssh client config

Default value: {}

users_client_options

Data type: Hash

Add users options for ssh client config

Default value: {}

version

Data type: String

Define package version (package ressource)

Default value: 'present'

storeconfigs_enabled

Data type: Boolean

Default value for storeconfigs_enabled (client and server)

Default value: true

validate_sshd_file

Data type: Boolean

Default value for validate_sshd_file (server)

Default value: false

use_augeas

Data type: Boolean

Default value to use augeas (client and server)

Default value: false

server_options_absent

Data type: Array

List of options to remove for server config (augeas only)

Default value: []

client_options_absent

Data type: Array

List of options to remove for client config (augeas only)

Default value: []

use_issue_net

Data type: Boolean

Use issue_net header

Default value: false

purge_unmanaged_sshkeys

Data type: Boolean

Purge unmanaged sshkeys

Default value: true

server_instances

Data type: Hash[String[1],Hash[String[1],NotUndef]]

Configure SSH instances

Default value: {}

ssh::client

This class add ssh client management

Examples

Puppet usage
class { 'ssh::client':
  ensure               => present,
  storeconfigs_enabled => true,
  use_augeas           => false,
}

Parameters

The following parameters are available in the ssh::client class:

ssh_config

Data type: Stdlib::Absolutepath

Path to ssh client config file

client_package_name

Data type: Optional[String[1]]

Name of the client package

Default value: undef

ensure

Data type: String

Ensurable param to ssh client

Default value: present

storeconfigs_enabled

Data type: Boolean

Collected host keys from servers will be written to known_hosts unless storeconfigs_enabled is false

Default value: true

options

Data type: Hash

SSH client options, will be deep_merged with default_options. This parameter takes precedence over default_options

Default value: {}

use_augeas

Data type: Boolean

Use augeas to configure ssh client

Default value: false

options_absent

Data type: Array

Remove options (with augeas style)

Default value: []

default_options

Data type: Hash

Default options to set, will be merged with options parameter

match_block

Data type: Hash

Add ssh match_block (with concat)

Default value: {}

ssh::hostkeys

This class manages hostkeys

Parameters

The following parameters are available in the ssh::hostkeys class:

export_ipaddresses

Data type: Boolean

Whether ip addresses should be added as aliases

Default value: true

storeconfigs_group

Data type: Optional[String[1]]

Tag hostkeys with this group to allow segregation

Default value: undef

extra_aliases

Data type: Array

Additional aliases to set for host keys

Default value: []

exclude_interfaces

Data type: Array

List of interfaces to exclude

Default value: []

exclude_interfaces_re

Data type: Array

List of regular expressions to exclude interfaces

Default value: []

exclude_ipaddresses

Data type: Array

List of ip addresses to exclude

Default value: []

use_trusted_facts

Data type: Boolean

Whether to use trusted or normal facts

Default value: false

tags

Data type: Optional[Array[String[1]]]

Array of custom tags

Default value: undef

ssh::knownhosts

This class manages knownhosts if collection is enabled.

Parameters

The following parameters are available in the ssh::knownhosts class:

collect_enabled

Data type: Boolean

Enable collection

Default value: $ssh::knownhosts::collect_enabled

storeconfigs_group

Data type: Optional[String[1]]

Define the hostkeys group storage

Default value: undef

ssh::server

This class managed ssh server

Examples

Puppet usage
class { 'ssh::server':
  ensure               => present,
  storeconfigs_enabled => true,
  use_issue_net        => false,
}

Parameters

The following parameters are available in the ssh::server class:

service_name

Data type: String[1]

Name of the sshd service

sshd_config

Data type: Stdlib::Absolutepath

Path to the sshd_config file

sshd_dir

Data type: Stdlib::Absolutepath

Path to the sshd dir (e.g. /etc/ssh)

sshd_binary

Data type: Stdlib::Absolutepath

Path to the sshd binary

sshd_config_mode

Data type: Stdlib::Filemode

Mode to set on the sshd config file

host_priv_key_group

Data type: Integer

Name of the group for the private host key

default_options

Data type: Hash

Default options to set, will be merged with options parameter

ensure

Data type: Enum[present,absent,latest]

Ensurable param to ssh server

Default value: present

include_dir

Data type: Optional[Stdlib::Absolutepath]

Path to sshd include directory.

Default value: undef

include_dir_mode

Data type: Stdlib::Filemode

Mode to set on the sshd include directory.

Default value: '0700'

include_dir_purge

Data type: Boolean

Purge the include directory if true.

Default value: true

config_files

Data type: Hash[String, Hash]

Hash of config files to add to the ssh include directory.

Default value: {}

storeconfigs_enabled

Data type: Boolean

Host keys will be collected and distributed unless storeconfigs_enabled is false.

Default value: true

options

Data type: Hash

Dynamic hash for openssh server option

Default value: {}

validate_sshd_file

Data type: Boolean

Add sshd file validate cmd

Default value: false

use_augeas

Data type: Boolean

Use augeas for configuration (default concat)

Default value: false

options_absent

Data type: Array

Remove options (with augeas style)

Default value: []

match_block

Data type: Hash

Add sshd match_block (with concat)

Default value: {}

use_issue_net

Data type: Boolean

Add issue_net banner

Default value: false

sshd_environments_file

Data type: Optional[Stdlib::Absolutepath]

Path to a sshd environments file (e.g. /etc/defaults/ssh on Debian)

Default value: undef

server_package_name

Data type: Optional[String[1]]

Name of the server package to install

Default value: undef

Defined types

ssh::client::config::user

Copyright (c) IN2P3 Computing Centre, IN2P3, CNRS Contributor: Remi Ferrand <remi{dot}ferrand_at_cc(dot)in2p3.fr> (2015) Contributor: Tim Meusel tim@bastelfreak.de (2017)

Parameters

The following parameters are available in the ssh::client::config::user defined type:

ensure

Data type: Enum['present', 'absent']

Specifies whether the config file should be present or absent

Default value: present

target

Data type: Optional[Stdlib::Absolutepath]

Sets the config file location, defaults to ~/.ssh/config if $target and $user_home_dir are not set

Default value: undef

user_home_dir

Data type: Optional[Stdlib::Absolutepath]

Sets the location of users home dir, defaults to /home/$user

Default value: undef

manage_user_ssh_dir

Data type: Boolean

Whether the users ssh dir should be managed or not

Default value: true

options

Data type: Hash

Options which should be set

Default value: {}

user

Data type: String[1]

The name of the user the config should be managed for

Default value: $name

ssh_directory_default_mode

Data type: String[1]

Default mode for the users ssh dir

Default value: '0700'

ssh_config_default_mode

Data type: String[1]

Default mode for the ssh config file

Default value: '0600'

ssh::client::match_block

Add match_block to ssh client config (concat needed)

Parameters

The following parameters are available in the ssh::client::match_block defined type:

options

Data type: Hash

Options which should be set

Default value: {}

type

Data type: Ssh::ClientMatch

Type of match_block, e.g. user, group, host, ...

Default value: 'user'

order

Data type: Integer

Orders your settings within the config file

Default value: 50

target

Data type: Stdlib::Absolutepath

Sets the target file of the concat fragment

Default value: $ssh::client::ssh_config

ssh::server::config::setting

Internal define to managed ssh server param

Parameters

The following parameters are available in the ssh::server::config::setting defined type:

key

Data type: String[1]

Key of the value which should be set

value

Data type: Variant[Boolean, Array, Hash, String]

Value which should be set

order

Data type: Variant[String[1], Integer]

Orders your setting within the config file

Default value: '10'

ssh::server::config_file

Resource type for managing a config file in the include dir.

Parameters

The following parameters are available in the ssh::server::config_file defined type:

mode

Data type: Stdlib::Filemode

File mode for the config file.

Default value: $ssh::server::sshd_config_mode

include

Data type: Optional[Stdlib::Absolutepath]

Absolute path to config file to include at the top of the config file. This is intended for including files not managed by this module (crypto policies).

Default value: undef

options

Data type: Hash

Dynamic hash for openssh server option

Default value: {}

path

Data type: Stdlib::Absolutepath

Default value: "${ssh::server::include_dir}/${name}.conf"

ssh::server::host_key

Manage a ssh host key

This module install a ssh host key in the server (basically, it is a file resource but it also notifies to the ssh service)

Important! This define does not modify any option in sshd_config, so you have to manually define the HostKey option in the server options if you haven't done yet.

Parameters

The following parameters are available in the ssh::server::host_key defined type:

ensure

Data type: Enum[present, absent]

Set to 'absent' to remove host_key files

Default value: 'present'

public_key_source

Data type: Optional[String[1]]

Sets the content of the source parameter for the public key file Note public_key_source and public_key_content are mutually exclusive.

Default value: undef

public_key_content

Data type: Optional[String[1]]

Sets the content for the public key file. Note public_key_source and public_key_content are mutually exclusive.

Default value: undef

private_key_source

Data type: Optional[String[1]]

Sets the content of the source parameter for the private key file Note private_key_source and private_key_content are mutually exclusive.

Default value: undef

private_key_content

Data type: Optional[String[1]]

Sets the content for the private key file. Note private_key_source and private_key_content are mutually exclusive.

Default value: undef

certificate_source

Data type: Optional[String[1]]

Sets the content of the source parameter for the host key certificate. Note certificate_source and certificate_content are mutually exclusive.

Default value: undef

certificate_content

Data type: Optional[String[1]]

Sets the content for the host key certificate. Note certificate_source and certificate_content are mutually exclusive.

Default value: undef

ssh::server::instances

Configure separate ssh server instances

Parameters

The following parameters are available in the ssh::server::instances defined type:

ensure

Data type: Enum[present, absent]

Specifies whether the instance should be added or removed

Default value: present

options

Data type: Hash

Set options for the instance

Default value: {}

service_ensure

Data type: Stdlib::Ensure::Service

Whether this instance service should be running or stopped, defaults to true when ensure is set to present, otherwise false

Default value: $ensure ? { 'present' => 'running', 'absent' => 'stopped'

service_enable

Data type: Boolean

Whether this instance service should be started at boot. Will be added automatically if ensure is running/removed if ensure is stopped

Default value: ($service_ensure == 'running'

validate_config_file

Data type: Boolean

Validate config file before applying

Default value: false

sshd_instance_config_file

Data type: Stdlib::Absolutepath

Path of the instance sshd config

Default value: "${ssh::server::sshd_dir}/sshd_config.${title}"

sshd_binary

Data type: Stdlib::Absolutepath

Path to sshd binary

Default value: $ssh::server::sshd_binary

sshd_environments_file

Data type: Optional[Stdlib::Absolutepath]

Path to environments file, if any

Default value: $ssh::server::sshd_environments_file

ssh::server::match_block

Add match_block to ssh server config

Parameters

The following parameters are available in the ssh::server::match_block defined type:

options

Data type: Hash

Options which should be set

Default value: {}

type

Data type: String[1]

Type of match_block, e.g. user, group, host, ...

Default value: 'user'

order

Data type: Integer

Orders your settings within the config file

Default value: 50

target

Data type: Stdlib::Absolutepath

Sets the target file of the concat fragment

Default value: $ssh::server::sshd_config

ssh::server::options

This defined type manages ssh server options

Parameters

The following parameters are available in the ssh::server::options defined type:

options

Data type: Hash

Options which should be set

Default value: {}

order

Data type: Integer

Orders your settings within the config file

Default value: 50

Functions

sshclient_options_to_augeas_ssh_config

Type: Ruby 3.x API

This function will convert a key-value hash to a format understandable by the augeas sshd_config provider It will also optionally deal with keys that should be absent, and inject static parameters if supplied.

Usage: sshclient_options_to_augeas_ssh_config($options_present, $options_absent, $other_parameters)

  • $options_hash is mandatory and must be a hash.
  • $options_absent is optional and can be either a single value or an array.
  • $other_parameters is optional and must be a hash.

Example: $options = { 'Host *.example.com' => { 'ForwardAgent' => 'yes', 'BatchMode' => 'yes', }, 'ForwardAgent' => 'no', 'BatchMode' => 'no', 'StrictHostKeyChecking' => 'no', } $options_absent = ['StrictHostKeyChecking','NoneField'] $other_parameters = { 'target' => '/etc/ssh/ssh_config' }

$options_final_augeas = sshclient_options_to_augeas_ssh_config($options, $options_absent, $other_parameters)

In this case, the value of $options_final_augeas would be:

'ForwardAgent .example.com' => { 'ensure' => 'present', 'host' => '.example.com', 'key' => 'ForwardAgent', 'value' => 'yes', 'target' => '/etc/ssh/ssh_config', } 'BatchMode .example.com' => { 'ensure' => 'present', 'host' => '.example.com', 'key' => 'BatchMode', 'value' => 'yes', 'target' => '/etc/ssh/ssh_config', } 'ForwardAgent' => { 'ensure' => 'present', 'key' => 'ForwardAgent', 'value' => 'yes', 'target' => '/etc/ssh/ssh_config', } 'BatchMode' => { 'ensure' => 'present', 'key' => 'BatchMode', 'value' => 'yes', 'target' => '/etc/ssh/ssh_config', } 'StrictHostKeyChecking' => { 'ensure' => 'absent', 'key' => 'StrictHostKeyChecking', 'target' => '/etc/ssh/ssh_config', } 'NoneField' => { 'ensure' => 'absent', 'key' => 'NoneField', 'target' => '/etc/ssh/ssh_config', }

Note how the word "Host" is stripped a

sshclient_options_to_augeas_ssh_config()

This function will convert a key-value hash to a format understandable by the augeas sshd_config provider It will also optionally deal with keys that should be absent, and inject static parameters if supplied.

Usage: sshclient_options_to_augeas_ssh_config($options_present, $options_absent, $other_parameters)

  • $options_hash is mandatory and must be a hash.
  • $options_absent is optional and can be either a single value or an array.
  • $other_parameters is optional and must be a hash.

Example: $options = { 'Host *.example.com' => { 'ForwardAgent' => 'yes', 'BatchMode' => 'yes', }, 'ForwardAgent' => 'no', 'BatchMode' => 'no', 'StrictHostKeyChecking' => 'no', } $options_absent = ['StrictHostKeyChecking','NoneField'] $other_parameters = { 'target' => '/etc/ssh/ssh_config' }

$options_final_augeas = sshclient_options_to_augeas_ssh_config($options, $options_absent, $other_parameters)

In this case, the value of $options_final_augeas would be:

'ForwardAgent .example.com' => { 'ensure' => 'present', 'host' => '.example.com', 'key' => 'ForwardAgent', 'value' => 'yes', 'target' => '/etc/ssh/ssh_config', } 'BatchMode .example.com' => { 'ensure' => 'present', 'host' => '.example.com', 'key' => 'BatchMode', 'value' => 'yes', 'target' => '/etc/ssh/ssh_config', } 'ForwardAgent' => { 'ensure' => 'present', 'key' => 'ForwardAgent', 'value' => 'yes', 'target' => '/etc/ssh/ssh_config', } 'BatchMode' => { 'ensure' => 'present', 'key' => 'BatchMode', 'value' => 'yes', 'target' => '/etc/ssh/ssh_config', } 'StrictHostKeyChecking' => { 'ensure' => 'absent', 'key' => 'StrictHostKeyChecking', 'target' => '/etc/ssh/ssh_config', } 'NoneField' => { 'ensure' => 'absent', 'key' => 'NoneField', 'target' => '/etc/ssh/ssh_config', }

Note how the word "Host" is stripped a

Returns: Any

sshserver_options_to_augeas_sshd_config

Type: Ruby 3.x API

This function will convert a key-value hash to a format understandable by the augeas sshd_config provider It will also optionally deal with keys that should be absent, and inject static parameters if supplied.

Usage: sshserver_options_to_augeas_sshd_config($options_present, $options_absent, $other_parameters)

  • $options_hash is mandatory and must be a hash.
  • $options_absent is optional and can be either a single value or an array.
  • $other_parameters is optional and must be a hash.

Example: $options = { 'Match User www-data' => { 'PasswordAuthentication' => 'yes', 'X11Forwarding' => 'no', }, 'Match Group bamboo' => { 'ForcedCommand' => '/bin/echo hello world', }, 'X11Forwarding' => 'yes', 'DebianBanner' => '/etc/banner.net', 'AllowGroups' => ["sshgroups", "admins"], } $options_absent = ['DebianBanner','NoneField'] $other_parameters = { 'target' => '/etc/ssh/sshd_config' }

$options_final_augeas = sshserver_options_to_augeas_sshd_config($options, $options_absent, $other_parameters)

In this case, the value of $options_final_augeas would be:

'PasswordAuthentication User www-data' => { 'ensure' => 'present', 'condition' => 'User www-data', 'key' => 'PasswordAuthentication', 'value' => 'yes', 'target' => '/etc/ssh/sshd_config', } 'X11Forwarding User www-data' => { 'ensure' => 'present', 'condition' => 'User www-data', 'key' => 'X11Forwarding', 'value' => 'no', 'target' => '/etc/ssh/sshd_config', } 'ForcedCommand Group bamboo' => { 'ensure' => 'present', 'condition' => 'Group bamboo', 'key' => 'ForcedCommand', 'value' => '/bin/echo hello world', 'target' => '/etc/ssh/sshd_config', } 'X11Forwarding' => { 'ensure' => 'present', 'key' => 'X11Forwarding', 'value' => 'yes', 'target' => '/etc/ssh/sshd_config', } 'DebianBanner' => { 'ensure' => 'absent', 'key' => 'DebianBanner', 'target' => '/etc/ssh/sshd_config', } 'AllowGroups' => { 'ensure' => 'present', 'key' => 'AllowGroups', 'value' => ['sshgroups','admins'], 'target' => '/etc/ssh/sshd_config', } 'NoneField' => { 'ensure' => 'absent', 'key' => 'NoneField', 'target' => '/etc/ssh/sshd_config', }

Note how the word "Match" is stripped a

sshserver_options_to_augeas_sshd_config()

This function will convert a key-value hash to a format understandable by the augeas sshd_config provider It will also optionally deal with keys that should be absent, and inject static parameters if supplied.

Usage: sshserver_options_to_augeas_sshd_config($options_present, $options_absent, $other_parameters)

  • $options_hash is mandatory and must be a hash.
  • $options_absent is optional and can be either a single value or an array.
  • $other_parameters is optional and must be a hash.

Example: $options = { 'Match User www-data' => { 'PasswordAuthentication' => 'yes', 'X11Forwarding' => 'no', }, 'Match Group bamboo' => { 'ForcedCommand' => '/bin/echo hello world', }, 'X11Forwarding' => 'yes', 'DebianBanner' => '/etc/banner.net', 'AllowGroups' => ["sshgroups", "admins"], } $options_absent = ['DebianBanner','NoneField'] $other_parameters = { 'target' => '/etc/ssh/sshd_config' }

$options_final_augeas = sshserver_options_to_augeas_sshd_config($options, $options_absent, $other_parameters)

In this case, the value of $options_final_augeas would be:

'PasswordAuthentication User www-data' => { 'ensure' => 'present', 'condition' => 'User www-data', 'key' => 'PasswordAuthentication', 'value' => 'yes', 'target' => '/etc/ssh/sshd_config', } 'X11Forwarding User www-data' => { 'ensure' => 'present', 'condition' => 'User www-data', 'key' => 'X11Forwarding', 'value' => 'no', 'target' => '/etc/ssh/sshd_config', } 'ForcedCommand Group bamboo' => { 'ensure' => 'present', 'condition' => 'Group bamboo', 'key' => 'ForcedCommand', 'value' => '/bin/echo hello world', 'target' => '/etc/ssh/sshd_config', } 'X11Forwarding' => { 'ensure' => 'present', 'key' => 'X11Forwarding', 'value' => 'yes', 'target' => '/etc/ssh/sshd_config', } 'DebianBanner' => { 'ensure' => 'absent', 'key' => 'DebianBanner', 'target' => '/etc/ssh/sshd_config', } 'AllowGroups' => { 'ensure' => 'present', 'key' => 'AllowGroups', 'value' => ['sshgroups','admins'], 'target' => '/etc/ssh/sshd_config', } 'NoneField' => { 'ensure' => 'absent', 'key' => 'NoneField', 'target' => '/etc/ssh/sshd_config', }

Note how the word "Match" is stripped a

Returns: Any

Data types

Ssh::ClientMatch

OpenSSH client Match criteria. See ssh_config(5)

Alias of Enum['!all', 'all', '!canonical', 'canonical', '!exec', 'exec', '!final', 'final', '!host', 'host', '!localuser', 'localuser', '!originalhost', 'originalhost', '!user', 'user']