The autossh module facilitates the automated management of ssh based port forward between nodes. The ssh tunnels are run via the 'autossh' wrapper which starts/monitors and restarts the tunnels if and when they close. This service:
- Installs the required package support.
- Configures the 'autossh' configuration file.
- Creates a system initialization script (init script).
- exports resources to automate the configuration of the 'remote' nodes.
- automatically configures remote nodes to provide a secure tunnel capability.
Original module was initially based on the following module(s) from the puppet forge:
- agronaught/puppet-autossh
However this module has been rewritten to provide:
- Support for multiple tunnels on any given host.
- Support for Hiera integration
- Support for configuration of the 'tunnel endpoint'
- Secure configuration of the tunnel endpoint.
- Customization of the important ssh configurations for the ssh tunnels.
As tested this module can support any number of ssh tunnels on any given host, and automatically synchronizes the tunnel endpoints providing both nodes connect to the same puppetdb.
The 'autossh' service provides a reliability and monitoring capability for the ssh tunnels, this includes monitoring the link via a separate 'monitoring ports' if configured and automatically restarting the ssh session if it fails due to an abnormal termination or error detected on the monitoring port. I'm gradually adding more functionality here to support customization of the ssh parameters to watch this space as the module develops.
Management of the private key is left to you as care needs to be taken to ensure this private key is adequately protected. I've encrypted the private key using eyaml and find this a convenient approach but that does depend on having hiera configured correctly.
The 'autossh' class configures the autossh environment, installs the required package support, and configures the global ssh options to be applied to ssh sessions.
This class needs to be run on all nodes using autossh.
Class {'::autossh':
}
The linux user account to be used to run the ssh sessions. We recommend using the default, that defaults to autossh user. You can distinguish different tunnels by the tunnel name.
The autossh rpm package name. Default uses already available rpm. Current version is latest stable, version 1.4.
The template to use for the system init script. Shouldn't need to change this.
Enable/Disable this package and service. This functionality is gradually being added, not overly useful right now.
Enables ssh connection reuse if an established connection already exists to the target host. This can speed up the time it takes to make the connection, note that this is only supported on 'openssh' > 5.5
Enables/Disables ssh compression in the tunnel. Connections over slow links may benefit from compression, local lan connections are probably better off without it.
Sets the cipher ordering for the ssh sessions. The default is from 'fastest' to 'slowest'.
By default host key checking is disabled to enable connections to proceed without error. Without this setting an admin would need to ensure the target server was in the known hosts file.
Enable/Disable TCP Keepalives to prevent firewalls from closing the tunnel.
Autossh server alive interval. Defaults to 30 seconds.
Autossh server alive per interval counter. Defaults to 3.
Create a tunnel on the host including the necessary init scripts to start and stop the service. Optionally ssh parameters can be customised on a per host basis.
autossh::tunnel { 'port_25_tunnel_to_server1':
port => '25',
hostport => '25',
remote_ssh_host => 'server1',
pubkey => 'ssh-dss <OMITTED>'
}
The linux user account to be used to run the ssh sessions. We recommend using the default, that defaults to autossh user. You can distinguish different tunnels by the tunnel name. Must be the same as the one used by autossh class.
The direction of the ssh tunnel. 'forward' for 'host --> target' and 'reverse' for 'target' --> 'host'
The local port to be used for the ssh tunnel
The remote port to be used for the ssh tunnel
The remote host/ip to connect to for the tunnel.
The remote port to connect to for the tunnel.
The port(s) to use for the autossh monitoring functionality. 2 ports are actually used, the base port and the base port + 1 (.i.e. 20000 and 20001).
The public key to use for the authentication of this connection.
Enable/Disable this package and service. This functionality is gradually being added, not overly useful right now.
Enable host specific ssh configurations. This will override the global settings created in the autossh class.
Enables ssh connection reuse if an established connection already exists to the target host. This can speed up the time it takes to make the connection, note that this is only supported on 'openssh' > 5.5
Enables/Disables ssh compression in the tunnel. Connections over slow links may benefit from compression, local lan connections are probably better off without it.
Sets the cipher ordering for the ssh sessions. The default is from 'fastest' to 'slowest'.
By default host key checking is disabled to enable connections to proceed without error. Without this setting an admin would need to ensure the target server was in the known hosts file.
Enable/Disable TCP Keepalives to prevent firewalls from closing the tunnel.
Autossh server alive interval. Defaults to 30 seconds.
Autossh server alive per interval counter. Defaults to 3.
Configure the endpoint (target) for an ssh connection. This class is run on the destination nodes for any ssh tunnels.
autossh::endpoint { 'createtunnels':
user => 'autossh',
host => 'server1.foo.bar',
}
The linux user account to be used to run the ssh sessions. We recommend using the default, that defaults to autossh user. You can distinguish different tunnels by the tunnel name. Must be the same as the one used by autossh class.
The hostname/ip address specified in the 'authssh::tunnel', this is used to filter the tunnel::endpoint exported resources.
The simple example creates a single ssh tunnel between two nodes, starting at the origin and terminating at the 'destination' using DSL only:
Prepare Private/Public Keys
Generate the necessary private and public keys for the ssh sessions. The private key will need to be placed in the '.ssh' folder for the run user (default: /home/autossh/.ssh/) and the public key used when configuring the service.
Origin Node
class { '::autossh':
}
autossh::tunnel { 'port_25_tunnel_to_server1':
port => '25',
hostport => '25',
remote_ssh_host => 'server1',
pubkey => 'ssh-dss <OMITTED>'
}
Destination Node
class { '::autossh':
}
autossh::endpoint { 'load ssh endpoints':
host => 'server1',
}
The following example creates multiple ssh port forwards between two nodes, the Origin and Destination using DSL and Hiera. This example also includes the installation of the private key which is stored using hiera-eyaml and default values to reduce the specific instance configuration.
Role - Origin Node
$autossh_user = hiera('autossh::user')
class { '::autossh':
user => $autossh_user
}
$autossh_key = hiera('autossh::privkey')
file { "/home/${autossh_user}/.ssh/id_dsa":
ensure => file,
owner => $autossh_user,
group => $autossh_user,
mode => "0400",
content => $autossh_key,
replace => no,
}
$tunnels = hiera_hash('autossh::tunnels')
$defaults = hiera_hash('autossh::defaults')
create_resources('autossh::tunnel',$tunnels,$defaults)
}
Profile - Origin Node
autossh::tunnels:
tunnel_pmaster:
port: 8140
hostport: 8140
remote_ssh_host: 172.16.255.2
tunnel_smtp:
port: 25
hostport: 1125
remote_ssh_host: 172.16.255.2
autossh::user: 'autossh'
autossh::privkey: ENC[PKCS7, OMITTED]
autossh::defaults:
pubkey: ssh-dss OMITTED
tunnel_type: reverse
user: autossh
remote_ssh_port: 22
monitor_port: 0
enable: true
Role - Destination Node
class capability::autosshtarget {
$autossh_user = hiera('autossh::user')
class { '::autossh':
user => $autossh_user
}
$autossh_hostip = hiera('autossh::hostip')
autossh::endpoint{'load autossh enpoint details':
user => $autossh_user,
host => $autossh_hostip,
}
Profile - Destination Node
autossh::hostip: 172.16.255.2
autossh::user: 'autossh'
autossh::pubkey: 'ssh-dss OMITTED'