path: root/README

Introduction
============

This puppet module manages OpenSSH configuration and services.

Dependencies
------------

This module requires puppet => 2.6, and the following modules are required
pre-dependencies:

- shared-common: git://labs.riseup.net/shared-common
- shared-lsb: git://labs.riseup.net/shared-lsb

OpenSSH Server
==============

On a node where you wish to have an openssh server installed, you should
'include sshd' on that node. If you need to configure any aspects of
sshd_config, set the variables before the include. See 'Configurable Variables'
below for what you can set.

Nagios
------

To have nagios checks setup automatically for sshd services, simply set
$use_nagios = true before the class is included. If you want to disable ssh
nagios checking for a particular node (such as when ssh is firewalled), then you
can set $nagios_check_ssh to false and that node will not be monitored.  

Nagios will automatically check the ports defined in $sshd_ports, and the
hostname specified by $nagios_check_ssh_hostname.

NOTE: this requires that you are using the shared-nagios puppet module which
supports the nagios native types via nagios::service:
git://labs.riseup.net/shared-nagios

Firewall
--------

If you wish to have firewall rules setup automatically for you, using shorewall,
you will need to set: $use_shorewall = true. The $sshd_ports that you have
specified will automatically be used.

NOTE: This requires that you are using the shared-shorewall puppet module:
git://labs.riseup.net/shared-shorewall


Configurable variables
----------------------

Configuration of sshd is strict, and may not fit all needs, however there are a
number of variables that you can consider configuring. The defaults are set to
the distribution shipped sshd_config file defaults. 

To set any of these variables, simply set them as variables in your manifests,
before the class is included, for example:

 $sshd_listen_address = ['10.0.0.1 192.168.0.1']
 $sshd_use_pam = yes
 include sshd

If you need to install a version of the ssh daemon or client package other than
the default one that would be installed by 'ensure => installed', then you can
set the following variables:

 $sshd_ensure_version = "1:5.2p2-6"
 $ssh_ensure_version = "1:5.2p2-6"

The following is a list of the currently available variables:

 $sshd_listen_address
    specify the addresses sshd should listen on set this to ['10.0.0.1
    192.168.0.1'] to have it listen on both addresses, or leave it unset to
    listen on all Default: empty -> results in listening on 0.0.0.0

 $sshd_allowed_users
    list of usernames separated by spaces.  set this for example to "foobar
    root" to ensure that only user foobar and root might login.  Default: empty
    -> no restriction is set

 $sshd_allowed_groups 
    list of groups separated by spaces. set this for example to "wheel sftponly"
    to ensure that only users in the groups wheel and sftponly might login.
    Default: empty -> no restriction is set Note: This is set after
    sshd_allowed_users, take care of the behaviour if you use these 2 options
    together.
 
 $sshd_use_pam
    if you want to use pam or not for authenticaton. Values: no or yes; Default:
    no

 $sshd_permit_root_login
    If you want to allow root logins or not. Valid values: yes, no,
    without-password, forced-commands-only; Default: without-password

 $sshd_password_authentication 
    If you want to enable password authentication or not. Valid values: yes or
    no; Default: no

 $sshd_kerberos_authentication 
    If you want the password that is provided by the user to be validated
    through the Kerberos KDC. To use this option the server needs a Kerberos
    servtab which allows the verification of the KDC's identity. Valid values:
    yes or no; Default: no

 $sshd_kerberos_orlocalpasswd  
    If password authentication through Kerberos fails, then the password will be
    validated via any additional local mechanism.  Valid values: yes or no;
    Default: yes

 $sshd_kerberos_ticketcleanup
    Destroy the user's ticket cache file on logout?  Valid values: yes or no;
    Default: yes

 $sshd_gssapi_authentication
    Authenticate users based on GSSAPI? Valid values: yes or no; Default: no

 $sshd_gssapi_cleanupcredentials
    Destroy user's credential cache on logout? Valid values: yes or no; Default:
    yes

 $sshd_challenge_response_authentication
    If you want to enable ChallengeResponseAuthentication or not When disabled,
    s/key passowords are disabled Valid values: yes or no; Default: no
 
 $sshd_tcp_forwarding
    If you want to enable TcpForwarding. Valid Values: yes or no; Default: no

 $sshd_x11_forwarding
    If you want to enable x11 forwarding. Valid Values: yes or no; Default: no

 $sshd_agent_forwarding	
    If you want to allow ssh-agent forwarding. Valid Values: yes or no; Default:
    no

 $sshd_pubkey_authentication
    If you want to enable public key authentication. Valid Values: yes or no;
    Default: yes

 $sshd_rsa_authentication 
    If you want to enable RSA Authentication. Valid Values: yes or no; Default:
    no
				
 $sshd_rhosts_rsa_authentication
    If you want to enable rhosts RSA Authentication. Valid Values: yes or no;
    Default: no

 $sshd_hostbased_authentication 
    If you want to enable HostbasedAuthentication. Valid Values: yes or no;
    Default: no
				
 $sshd_strict_modes		
    If you want to set StrictModes (check file modes/ownership before accepting
    login). Valid Values: yes or no; Default: yes

 $sshd_permit_empty_passwords
    If you want enable PermitEmptyPasswords to allow empty passwords. Valid
    Values: yes or no; Default: no

 $sshd_port   
    Deprecated, use sshd_ports instead.

 $sshd_ports
    If you want to specify a list of ports other than the default 22; Default:
    [22]

 $sshd_authorized_keys_file
    Set this to the location of the AuthorizedKeysFile
    (e.g. /etc/ssh/authorized_keys/%u). Default: AuthorizedKeysFile
    %h/.ssh/authorized_keys

 $sshd_sftp_subsystem
    Set a different sftp-subystem than the default one. Might be interesting for
    sftponly usage. Default: empty -> no change of the default

 $sshd_head_additional_options  
    Set this to any additional sshd_options which aren't listed above. Anything
    set here will be added to the beginning of the sshd_config file. This option
    might be useful to define complicated Match Blocks. This string is going to
    be included, like it is defined. So take care! Default: empty -> not added.

 $sshd_tail_additional_options  

    Set this to any additional sshd_options which aren't listed above. Anything
    set here will be added to the end of the sshd_config file. This option might
    be useful to define complicated Match Blocks. This string is going to be
    included, like it is defined. So take care! Default: empty -> not added.


Defines and functions
---------------------

Deploy authorized_keys file with the define sshd::ssh_authorized_key.

Generate a public/private keypair with the ssh_keygen function. For example, the
following will generate ssh keys and put the different parts of the key into
variables:

$ssh_keys = ssh_keygen("${$ssh_key_basepath}/backup/keys/${fqdn}/${backup_host}")
$public_key = split($ssh_keys[1],' ')
$sshkey_type => $public_key[0]
$sshkey => $public_key[1]


Client
======

On a node where you wish to have the ssh client managed, you can do 'include
sshd::client' in the node definition. This will install the appropriate package.


License
=======

# Copyright 2008-2011, Riseup Labs micah@riseup.net
# Copyright 2008, admin(at)immerda.ch
# Copyright 2008, Puzzle ITC GmbH
# Marcel Härry haerry+puppet(at)puzzle.ch
# Simon Josi josi+puppet(at)puzzle.ch
#
# This program is free software; you can redistribute 
# it and/or modify it under the terms of the GNU 
# General Public License version 3 as published by 
# the Free Software Foundation.
#