ansible-sshd/README.md

174 lines
4.1 KiB
Markdown
Raw Normal View History

2015-08-25 19:41:22 +02:00
[![Build Status](https://travis-ci.org/willshersystems/ansible-sshd.svg?branch=master)](https://travis-ci.org/willshersystems/ansible-sshd) [![Ansible Galaxy](http://img.shields.io/badge/galaxy-mattwillsher.sshd-660198.svg?style=flat)](https://galaxy.ansible.com/list#/roles/4868)
2015-01-12 22:57:10 +01:00
2015-01-12 22:40:04 +01:00
OpenSSH Server
==============
2014-12-18 23:12:51 +01:00
2014-12-22 21:18:35 +01:00
This role configures the OpenSSH daemon. It:
2014-12-18 23:12:51 +01:00
2015-01-12 22:40:04 +01:00
* By default configures the SSH daemon with the normal OS defaults.
* 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.
2015-01-13 14:29:53 +01:00
**WARNING** Misconfiguration of this role can lock you out of your server!
Please test your configuration and its interaction with your users configuration
before using in production!
**WARNING** Digital Ocean allows root with passwords via SSH on Debian and
Ubuntu. This is not the default assigned by this module - it will set
`PermitRootLogin without-password` which will allow access via SSH key but not
via simple password. If you need this functionality, be sure to set
`ssh_PermitRootLogin yes` for those hosts.
2015-01-12 22:40:04 +01:00
Requirements
------------
Tested on:
* Ubuntu precise, trusty
* Debian wheezy, jessie
* FreeBSD 10.1
* EL 6,7 derived distributions
* Fedora 20, 22
2015-01-12 22:40:04 +01:00
It will likely work on other flavours and more direct support via suitable
[vars/](vars/) files is welcome.
Role variables
---------------
2015-01-13 18:42:10 +01:00
Unconfigured, this role will provide a sshd_config that matches the OS default,
2015-01-12 22:40:04 +01:00
minus the comments and in a different order.
2015-01-13 18:42:10 +01:00
* sshd_skip_defaults
2015-01-12 22:40:04 +01:00
2015-01-13 18:42:10 +01:00
If set to True, don't apply default values. This means that you must have a
complete set of configuration defaults via either the sshd dict, or sshd_Key
variables. Defaults to *False*.
* sshd_manage_service
If set to False, the service/daemon won't be touched at all, i.e. will not try
to enable on boot or start or reload the service. Defaults to *True* unless
running inside a docker container (it is assumed ansible is used during build
phase).
2015-01-13 18:42:10 +01:00
* sshd_allow_reload
2015-01-14 09:45:57 +01:00
If set to False, a reload of sshd wont happen on change. This can help with
2015-01-13 18:44:00 +01:00
troubleshooting. You'll need to manually reload sshd if you want to apply the
changed configuration. Defaults to the same value as ``sshd_manage_service``.
2015-01-13 18:42:10 +01:00
* sshd
A dict containing configuration. e.g.
2014-12-22 21:18:35 +01:00
```yaml
2014-12-21 21:39:44 +01:00
sshd:
Compression: delayed
ListenAddress:
- 0.0.0.0
```
2014-12-18 23:12:51 +01:00
2015-01-13 18:42:10 +01:00
* ssh_...
Simple variables can be used rather than a dict. Simple values override dict
values. e.g.:
2014-12-22 21:18:35 +01:00
```yaml
sshd_Compression: off
```
2015-01-13 18:42:10 +01:00
In all cases, booleans correctly rendered as yes and no in sshd configuration.
Lists can be used for multiline configuration items. e.g.
2014-12-25 13:13:34 +01:00
```yaml
sshd_ListenAddress:
- 0.0.0.0
2015-01-12 22:40:04 +01:00
- '::'
2014-12-25 13:13:34 +01:00
```
2015-01-13 18:42:10 +01:00
Renders as:
```
ListenAddress 0.0.0.0
ListenAddress ::
```
* sshd_match
A list of dicts for a match section. See the example playbook.
* sshd_match_1 through sshd_match_9
A list of dicts or just a dict for a Match section.
2014-12-25 13:13:34 +01:00
2015-01-14 13:53:16 +01:00
Dependencies
------------
None
2015-01-14 13:53:16 +01:00
2015-01-12 22:40:04 +01:00
Example Playbook
----------------
2015-08-25 19:41:22 +02:00
2014-12-25 13:13:34 +01:00
```yaml
---
2015-01-12 22:40:04 +01:00
- hosts: all
vars:
sshd_skip_defaults: true
sshd:
Compression: true
ListenAddress:
- "0.0.0.0"
- "::"
GSSAPIAuthentication: no
Match:
- Condition: "Group user"
GSSAPIAuthentication: yes
sshd_UsePrivilegeSeparation: sandbox
sshd_match:
- Condition: "Group xusers"
X11Forwarding: yes
roles:
- role: willshersystems.sshd
2014-12-25 13:13:34 +01:00
```
Results in:
2015-01-14 09:45:57 +01:00
```
2014-12-25 13:13:34 +01:00
# Ansible managed: ...
Compression yes
GSSAPIAuthentication no
UsePrivilegeSeparation sandbox
Match Group user
GSSAPIAuthentication yes
Match Group xusers
X11Forwarding yes
```
2014-12-26 11:09:34 +01:00
Template Generation
-------------------
The [sshd_config.j2](templates/sshd_config.j2) template is programatically
generated by the scripts in meta. New options should be added to the
2015-08-25 19:41:22 +02:00
options_body or options_match.
To regenerate the template, from within the meta/ directory run:
`./make_option_list >../templates/sshd_config.j2`
2015-01-12 22:40:04 +01:00
License
-------
LGPLv3
Author
------
Matt Willsher <matt@willsher.systems>
2014-12-26 11:09:34 +01:00
2015-08-25 19:41:22 +02:00
&copy; 2014,2015 Willsher Systems Ltd.