Pull together a more comprehensive README, moving the configurable variables from init.pp into the README, and detailing the other features, and requirements, of the module

2 files changed, 212 insertions, 171 deletions

diff --git a/README b/README
index dd7bca7..4f679e4 100644
--- a/README
+++ b/README
@@ -1,6 +1,216 @@
-# sshd module for Puppet
+Introduction
+============
 
-## Dependencies
+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
+-------
+
+Deploy authorized_keys file with the define sshd::ssh_authorized_key
+
+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.
+#
diff --git a/manifests/init.pp b/manifests/init.pp
index 76ee107..991fbba 100644
--- a/manifests/init.pp
+++ b/manifests/init.pp
@@ -1,172 +1,3 @@
-#
-# ssh module
-#
-# Copyright 2008-2009, 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.
-#
-# Deploy authorized_keys file with the define
-#     sshd::ssh_authorized_key
-# 
-# sshd-config:
-#
-# The configuration of the sshd is rather strict and might not fit all
-# needs. However there are a bunch of variables, which you might
-# consider configuring.
-#
-# To set any of the following, 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"
-#
-# 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.
-# NOTE: this requires that you are using the nagios puppet module
-# which supports the nagios native types via nagios::service 
-#
-# 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.
-
 class sshd {
    # prepare variables to use in templates
   case $sshd_listen_address {