Standardise README

README.md

@@ -1,9 +1,38 @@
-# Ansible OpenSSH Daemon Role
+OpenSSH Server
+==============
 
 This role configures the OpenSSH daemon. It:
 
-- By default configures the SSH daemon with the normal OS defaults. Defaults can be disabled by setting `sshd_skip_defaults: true`
+* By default configures the SSH daemon with the normal OS defaults.
-- Supports use of a dict to configure items:
+* Works across a variety of UN*X like distributions
+* Can be configured by dict or simple variables
+* Supports Match sets
+* Supports all sshd_config options. Templates are programmatically generated.
+  (see [meta/make_option_list](meta/make_option_list))
+* Tests the sshd_config before reloading sshd.
+
+Requirements
+------------
+
+Tested on:
+
+* Ubuntu precise, trusty
+* Debian wheezy, jessie
+* FreeBSD 10.1
+* EL 6,7 derived distributions
+
+It will likely work on other flavours and more direct support via suitable
+[vars/](vars/) files is welcome.
+
+Role variables
+---------------
+
+* Unconfigured, this role will provide a sshd_config that matches the OS default,
+minus the comments and in a different order.
+
+* Defaults can be disabled by setting `sshd_skip_defaults: true`
+
+* Supports use of a dict to configure items:
 
 ```yaml
 sshd:
@@ -12,29 +41,31 @@ sshd:
     - 0.0.0.0
 ```
 
-- Can use scalars rather than a dict. Scalar values override dict values:
+* Simple variables can be used rather than a dict. Simple values override dict
+values:
 
 ```yaml
 sshd_Compression: off
 ```
 
-- Correctly interprets booleans as yes and no in sshd configuration
+* Correctly interprets booleans as yes and no in sshd configuration
-- Supports lists for multi line configuration items:
+* Supports lists for multi line configuration items:
 
 ```yaml
 sshd_ListenAddress:
   - 0.0.0.0
-  - ::
+  - '::'
 ```
 
-- Tests the sshd_config before reloading sshd
+* Supports match section either via Match in the sshd dict, sshd_match and any of sshd_match_1 through sshd_match_9. Match items can either be a dict or an array.
-- Template is programmatically generated. See the files in the meta folder. It should cover all valid SSH options. To regenerate the template, in the meta directory run `./make_option_list  >../templates/sshd_config.j2`
-- Supports match section either via Match in the sshd dict, sshd_match and any of sshd_match_1 through sshd_match_9. Match items can either be a dict or an array.
 
-## Complete example
+Example Playbook
+----------------
 
 ```yaml
 ---
+- hosts: all
+  vars:
     sshd_skip_defaults: true
     sshd:
       Compression: true
@@ -49,6 +80,8 @@ sshd_UsePrivilegeSeparation: sandbox
     sshd_match:
         - Condition: "Group xusers"
           X11Forwarding: yes
+  roles:
+    - role: willshersystems.sshd
 ```
 
 Results in:
@@ -63,8 +96,16 @@ Match Group user
 Match Group xusers
   X11Forwarding yes
 ```
-### Author
 
-Copyright 2014 Matt Willsher
+License
+-------
 
-Code in this repository is licensed under the LGPLv3 license. See LICENSE for full details.
+LGPLv3
+
+
+Author
+------
+
+Matt Willsher <matt@willsher.systems>
+
+Copyright 2014,2015 Willsher Systems