DebOps Documentation

DebOps Documentation
DebOps Documentation
Release master
Maciej Delmanowski, Nick Janetakis
March 01, 2015
Contents
1
DebOps is a framework
2
Do you want to contribute?
2.1 Installation . . . . . . . . . . . . . . .
2.2 Getting Started . . . . . . . . . . . . .
2.3 Configuration . . . . . . . . . . . . . .
2.4 Creating a local apt server . . . . . . .
2.5 Custom services and their default ports
2.6 Standard ports . . . . . . . . . . . . .
2.7 Using Linux containers . . . . . . . . .
2.8 How will versions work? . . . . . . . .
2.9 Contributing Guidelines . . . . . . . .
2.10 Using the custom scripts . . . . . . . .
2.11 Ansible roles provided in DebOps . . .
2.12 debops.postfix . . . . . . . . . . . . .
2.13 Ansible role: debops.rsnapshot . . . .
2.14 Ansible role: debops.secret . . . . . .
3
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5
.
5
.
6
.
9
.
9
. 11
. 12
. 12
. 14
. 14
. 16
. 18
. 184
. 196
. 205
i
ii
DebOps Documentation, Release master
Your Debian-based data center in a box
A collection of Ansible playbooks, scalable from one container to an entire data center.
Contents
1
DebOps Documentation, Release master
2
Contents
CHAPTER 1
DebOps is a framework
• 60+ highly extensible roles with sane defaults
• Tuned for production and works great for development
• Built for modularity so extending it is simple
• Custom scripts to tie everything together
We believe in the UNIX philosophy; one tool should only do one thing very well. DebOps has many playbooks and
roles but it is just a set of focused tools to help you run and manage your infrastructure.
In fact all of the DebOps playbooks and roles can be ran with Ansible directly.
3
DebOps Documentation, Release master
4
Chapter 1. DebOps is a framework
CHAPTER 2
Do you want to contribute?
DebOps itself is just a name, it’s the sum of its parts. So we sincerly welcome contributions!
• IRC: #debops
• Mailing list and Forum
• Issue reporting: debops/debops issue tracker.
• Code submission: Please have a look at the contributions page
Contents:
2.1 Installation
2.1.1 Required Dependencies
Besides Ansible, DebOps requires a few additional packages to be installed on your workstation (Ansible Controller).
These are:
• Python netaddr library
• uuidgen
To install required packages on Debian GNU/Linux or derivatives, run:
$ sudo apt-get install python-pip python-netaddr uuid-runtime
2.1.2 Installing the DebOps scripts
The easiest way to install DebOps is using pip, the Python package installer, which fetches debops from the Python
Package Index:
$ sudo pip install debops
After scripts are installed, you need to download the DebOps playbooks and roles from GitHub. You do that using
command:
$ debops-update
By default, they will be downloaded to ~/.local/share/debops/ directory.
If you don’t have installed Ansible already, the script bootstrap-ansible.sh can do it for you:
5
DebOps Documentation, Release master
$ ./misc/scripts/bootstrap-ansible.sh v1.8.2
This installs version 1.8.2. Without version pin, the newest version will be installed.
Other commonly used choices on how to install DebOps:
• Install the scripts into your own ~/bin:
$ pip install --user debops
$ debops-update
For more installation options please have a look at the pip User Guide.
Installing the current development version
If you want to install the current development version of DebOps, choose one off:
$ sudo pip install https://github.com/debops/debops/archive/master.zip
If you want to help working on DebOps, it’s best to check out the scripts from github:
$ git clone https://github.com/debops/debops ~/my-projects/debops
$ cd ~/my-projects/debops
You can still install the scripts so you can use them easily, e.g.:
$ pip install --user ~/my-projects/debops
$ debops-update
2.1.3 Updating the DebOps scripts
For updating the DebOps scripts run (assuming you used sudo when installing):
$ sudo pip install -U --no-deps debops
If you installed the development version of DebOps and want to update it, simply use:
$ sudo pip install -U --no https://github.com/debops/debops/archive/master.zip
2.2 Getting Started
2.2.1 Your first project
Set up your first project
$ debops-init ~/myproject
$ cd ~/myproject
Add a host to your inventory
Enter your hosts into ansible/inventory/hosts. For the beginning we suggest entering one server only so
you can make yourself comfortable with DebOps. Here is an example:
[all_servers]
serverone
ansible_ssh_host=serverone.example.com
6
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Verify you can access the server
$ ssh serverone.example.com
$ debops-task all -m setup
Warning: Ansible does not detect all platforms as detailed as it is required. Thus for some platforms running
debops without any configuration will bring your system into a bad state. Please check Notes about specific
platforms for more information. Sorry!
Before running debops the first time, we suggest you set up a minimal configuration.
This
will make you more comfortable with the results.
For the very first try, you can put this into
ansible/inventory/host_vars/serverone/vars.yml:
# Set custom timezone on the server
ntp_timezone: ’Europe/Paris’
# Protect the SSH service by specifying list of hosts/networks which can
# access it (by default access is allowed from anywhere, but firewall blocks
# too many connection attempts in a short amout of time)
sshd_host_allow: [ ’192.168.178.0/24’ ]
# Specify a mail server to send all mail through (it needs to accept the
# incoming messages from your host)
postfix_relayhost: ’mail.intern.example.com’
# Set a default admin e-mail address where all messages to root account will
# be forwarded
postfix_default_local_alias_recipients: [ ’[email protected]’ ]
Run the DebOps playbooks
$ debops
2.2.2 What you get after this
• apt-repositories and auto-update
• Firewall and tcpwrapper set up
• local mail forwarded to your central mail-hub
• Time synchronization with pool.debian.org
2.2.3 Where to go from here
You may now start adding systems into ansible/inventory/hosts as you like. To make install some software
just add the host into the resp. group and add some configuration options.
2.2.4 Prepare a new host for using DebOps
To add another host to DebOps a few requirements have to be fulfilled:
• The SSH private key of the user running debops has to be loaded into ssh-agent and the corresponding environment variables have to point to the running ssh-agent process.
2.2. Getting Started
7
DebOps Documentation, Release master
• The SSH host key of the new host has to be added to the ~/.ssh/known_hosts file of the user running
debops.
• It should be possible to login with root into the new host.
Run the DebOps boostrap
$ debops bootstrap -u root -k -l <hostname>
This will install python and sudo on the target host, create an account of the user running debops, install its SSH
public key into the ~/.ssh/authorized_keys file and grant it full sudo permissions.
2.2.5 Examples
Setting up Etherpad quickly
• ansible/inventory/hosts:
[debops_etherpad]
serverone
• ansible/inventory/host_vars/serverone/etherpad.yml:
etherpad_title: ’Our Corporate Etherpad’
etherpad_disable_ip_logging: True
etherpad_admins: [ ’etherpad-admin’ ]
After running debops -l serverone you can access the running etherpad on pad.example.com (given the
hostname resolve correctly). DebOps automatically installed and configured nginx, nodejs and mysql (resp.
mariadb) for you.
More Examples
You can find more examples in the DebOps examples repository. If you have a an example you want to share, please
submit a pull-request. I’d happily integrate it.
2.2.6 Notes about specific platforms
If you need additional configuration for a platform, we suggest putting this into a group_vars-file and put the
affected systems into a group within ansible/inventory/hosts.
Debian nothing to consider
Ubuntu nothing to consider
Rapbian (Debian for Raspberry PI) Requires some setup:
# Default administrator account
ansible_ssh_user: ’pi’
# Work around missing detection of Raspbian in Ansible
apt_default_sources_lookup: ’raspbian’
apt_default_mirrors_lookup: ’raspbian’
8
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
2.3 Configuration
Note You do not need to configure anything to run DebOps.
DebOps reads configuration files at several places. All configurations files found are merged where the values read
later take precedence.
Windows:
%APPDATA%debops.cfg (with %APPDATA% defaulting to ~Application Data)
project-dir.debops.cfg
OS X:
~/Library/Application Support/debops.cfg
project-dir/.debops.cfg
All Others (including Linux):
/etc/debops.cfg
In each dir of $XDG_CONFIG_DIRS: dir/debops.cfg
$XDG_CONFIG_HOME/debops.cfg
project-dir/.debops.cfg
2.3.1 Configuration File Format
The configuration file are simple INI-files. Supported sections and values are:
section
item
data-home
paths
ansible XXX
default
$XDG_DATA_HOME/debops
(Unix/Linux)
%APPDATA%debops (Windows)
~/Library/Application
Supportdebops (OS X)
install-path
%(data-home)s/debops-playbooks
playbooks-paths
%(install-path)s/playbooks
Items defined here are going into section XXX of ansible.cfg.
2.4 Creating a local apt server
• What are some benefits of doing it this way?
• Pick a server
• Configure a throw away build server
• Configure the local APT server
• Make your hosts aware
• Use your shiny new package
Certain roles such as Ruby and Golang offer an ability to use a backported version of the package so it’s more up to
date. The backports are built off of Debian Jessie without having to actually use the testing apt source.
2.3. Configuration
9
DebOps Documentation, Release master
2.4.1 What are some benefits of doing it this way?
A lot of other roles will compile from source but that’s time demanding and error prone. A backported version of
Ruby 2.1.x will apt install in about 5 seconds once you setup your local APT server once.
Compile it once into a proper package and use it as many times as you want.
It also future proofs your role because you wouldn’t have to change anything once Jessie is officially released. From
the role’s point of view it’s just installing an apt package using Ansible’s apt module. It does not care where the apt
server is located.
2.4.2 Pick a server
The first step is to decide where you want this server. It doesn’t need to be literally local to your workstation. It’s local
in the context of it not being an official APT server to the world.
Popular options could be your Ansible controller inside of a container or a micro-size instance on the cloud depending
on your requirements for availability.
2.4.3 Configure a throw away build server
You could use your apt server but it’s best to use a temporary host. I would just spin up a container.
In this example we’re going to build Ruby 2.1.x. You will have to do this if you plan to use GitLab so it’s a good idea
to learn!
# inventory/hosts
[debops_ruby]
yourbuildserver
# inventory/host_vars/yourbuildserver.yml
ruby_version: ’backport’
That tells the Ruby role to use the Backporter role as a dependency and that will kick off the entire build process for
you.
Then run:
debops -l yourbuildserver
Expect it to take 5 to 15 minutes depending on how fast your server is. You only need to do this once.
Where are the packages
Good
question,
they
have
been
transferred
to
your
secret/reprepro/includedeb/wheezy-backports/ directory.
Ansible
controller
in
the
At this point you can delete your build server.
2.4.4 Configure the local APT server
Next up, we need to tell our server that it is an APT server.
10
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# inventory/host_vars/youraptserver.yml
apt: ’youraptserver.{{ ansible_domain }}’
You must use your apt server’s fully qualified domain name. Run hostname -f on the server to check its fully
qualified domain name.
We’re just about done, now you need to transfer the packages to your apt server:
debops -l youraptserver -t apt
2.4.5 Make your hosts aware
The last step is to make your hosts aware of the server.
Below I’m just assuming you want to make it aware to all of your containers and you have your containers inside of a
[containers] group.
# inventory/group_vars/containers.yml
apt: ’youraptserver.{{ ansible_domain }}’
Then run:
debops -l containers
2.4.6 Use your shiny new package
Well, this part is easy. Just use the Ruby role on any host that is aware of your local apt server and it will install Ruby
2.1.x in about 5 seconds.
You do not need to set ruby_version: ’backport’ on the hosts themselves. It will just use the default
setting which is the apt package and now since your local apt server is setup and your host is aware, it will use the new
backported version.
2.5 Custom services and their default ports
In various DebOps roles you can find named ports. They are defined in /etc/services using debops.etc_services
role which manages them using Ansible’s assemble module. To avoid collisions between various services we list
here custom ports that are set for applications and services that don’t have specified system ports by default.
You can find a list of ports used throughout the DebOps project by running command:
debops-defaults | grep ’_port:’
This should output list of all variables that define port numbers in various roles and are available in role defaults, and
thus can be overridden by Ansible inventory.
Service
apt-cacher-ng
elasticsearch
etherpad
redis-server
redis-sentinel
rails apps
gitlab-ci
Port
3142
9200-9400
9000
6379
26379
3000
18083
Default bind
all interfaces
localhost
localhost
localhost
localhost
socket
localhost
2.5. Custom services and their default ports
11
DebOps Documentation, Release master
2.6 Standard ports
Run cat /etc/services to obtain a list of standard ports.
2.7 Using Linux containers
• Host requirements
• Configuring a host to make it capable of storing containers
• LXC cheatsheet to help you manage the containers
• Interacting with a container
2.7.1 Host requirements
Your host must be Debian based
It can be Ubuntu 14.x, Debian Wheezy/Jessie, etc.
If you’re using a Mac or a different Linux distro then you’ll want to setup a virtual machine to act as the container
host. You can do this with Vagrant or some other virtualization software.
SSH key pair
You will also need an SSH key pair on your host. You probably have one setup but if you not you can run
ssh-keygen -t and follow the instructions. DebOps expects the RSA keys to be in ~/.ssh.
2.7.2 Configuring a host
Add it to your inventory
The paths are relative to where you debops-init a new project.
ansible/inventory/hosts
[debops_lxc]
yourhostname
Decide on which network adapter you’re using
If you plan to make your main OS an LXC host then you’ll want to configure the host to use the NAT adapter by
default. DNS is configured through NAT using dnsmasq.
Basically this means you don’t have to forward ports and DNS will work.
ansible/inventory/host_vars/yourhostname.yml
lxc_configuration_default: ’nat’
If you plan to use the bridged adapter through a VM then you do not have to set anything but keep in mind you will
need to connect through an IP address unless you have configured DNS yourself.
Make the host an LXC host by running DebOps
Run this from your terminal: debops -l debops_lxc.
If you are running Debian Wheezy you will have to reboot your LXC host due to a kernal update. Other operating
systems like Ubuntu 14.x and Debian Jessie do not require the reboot.
12
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
2.7.3 LXC cheatsheet
# Create a new container
sudo lxc-create -n mycontainer -t debops
# Return back a list of containers and basic information about them
sudo lxc-ls -f
# Start a container, the -d flag runs it as a daemon
sudo lxc-start -n mycontainer -d
# Stop a container
sudo lxc-stop -n mycontainer
# Destroy a container, the -f flag does a stop before destroying it
sudo lxc-destroy -n mycontainer -f
# There are many more commands like snapshotting, freezing, info, etc.
# Check the LXC manpages for more information
sudo lxc-[tab complete]
2.7.4 Interacting with a container
Once it has been created and it’s running you can SSH to it, just run:
ssh containername if you have DNS setup, otherwise use the IP address. At this point you have a bare container
ready to do whatever you want.
Setting it up with common DebOps services
If you plan to use containers for development then you’ll probably want to group your containers together in your
inventory.
ansible/inventory/hosts
[local_containers]
mycontainer
Now you could create ansible/inventory/group_vars/local_containers.yml and start doing things
that would apply to all local containers.
Perhaps you want to install emacs or use your own dotfiles, etc..
Transferring files
To transfer files to/from the container you have 2 options.
1. SCP or some other file transfer utility that works through SSH
# To the container
scp somefile mycontainer:/tmp/somefile
# From a container
scp mycontainer:/tmp/somefile somefile
The second option requires knowing the dirty details about where the container has its configuration and file system
stored.
On the LXC host, navigate to /var/lib/lxc, then go into your container’s directory. You can find its file system
there among other things. You can simply cp directly if your LXC host is local to your main OS.
2.7. Using Linux containers
13
DebOps Documentation, Release master
2.8 How will versions work?
The debops-update tool will orchestrate updating everything or specific components for you.
2.8.1 Roles
Each role will have a VERSION file in its repository.
2.8.2 Playbooks
The debops/debops-playbooks repository will have a galaxy/requirements.txt file which will contain a list of roles and versions. It will also have a VERSION file in its repo.
Over time as the project matures we will create release specific branches in the playbooks repository and they will
lock in specific requirements files.
2.8.3 Scripts
Scripts will also be versioned with release branches and a VERSION file as they stabilize.
This strategy ensures that a setup you have working today will work 3 months down the line even if there’s been a
hundred commits to half the roles and playbooks you’re using.
2.9 Contributing Guidelines
• Philosophy
• Discussion
• Issue reporting
– Scripts and documentation
– Playbooks and roles
– Tests
• Code submissions
• Code style
• License agreement
2.9.1 Philosophy
• Do one thing well
• Modularity and flexibility
• DebOps itself is just a name, it is the sum of its parts
14
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
2.9.2 Discussion
Join us in #debops on Freenode or post on the debops-project mailing list.
2.9.3 Issue reporting
DebOps is officially hosted on Github at https://github.com/debops/debops.
Scripts and documentation
Checkout the debops/debops issue tracker.
Playbooks and roles
Checkout the debops/debops-playbooks issue tracker.
Tests
Checkout the debops/test-suite issue tracker.
2.9.4 Code submissions
We accept pull requests on everything. Here’s a quick work flow:
1. Fork it into your Github account (https://github.com/debops/debops/fork)
2. Clone your fork onto your workstation:
git clone [email protected]:YOURACCOUNT/debops.git
3. Create your feature branch (git checkout -b my-new-feature)
4. Commit your changes (git commit -am ’Add some feature’)
Please try your best to make great commit messages. Have a read through better commits and research how to
use git add -p.
5. Push to the branch (git push origin my-new-feature)
6. Submit your pull request through Github: Select the branch on your repo, click the green PR button and submit
it.
7. (Optional) Keep in sync with development in the official repo:
(a) Add the official repo as your upstream:
git remote add upstream https://github.com/debops/debops
(b) Update your fork:
git
git
git
git
checkout master # or whatever the main PR branch is for that repo
fetch upstream
rebase upstream/master
push origin master
You should do this before making any commits and after your pull request has been accepted.
2.9. Contributing Guidelines
15
DebOps Documentation, Release master
2.9.5 Code style
For everything:
• Try your best to stay under 80 characters but don’t go crazy trying
• 2 space indentation for everything unless noted otherwise
• Comments and output start with a capital letter and have no periods
For just yaml:
• Prefer role_foo and role_bar to using a role dictionary
• Use the multi-line style whenever possible (we’re working on migrating to that)
2.9.6 License agreement
By contributing you agree that these contributions are your own (or approved by your employer) and you grant a full,
complete, irrevocable copyright license to all users and developers of the project, present and future, pursuant to the
license of the project.
2.10 Using the custom scripts
If you allowed scripts to be installed on your system path then they will be in /usr/local/bin and directly
accessible.
2.10.1 debops
Wraps ansible-playbook and since that’s the most commonly ran command we decided it’s a good idea to
shorten it to debops instead of debops-playbook.
Any arguments that ansible-playbook supports can be passed to debops.
You don’t need to specify an inventory or playbook. Part of the benefit of using this tool is that it figures out all of that
stuff for you. You can still chain together multiple playbooks, custom or not.
debops -l mygroup
debops -t foo
2.10.2 debops-defaults
Collect the default values of all DebOps roles and output them as one output stream.
By default the output will be displayed using view.
debops-defaults
debobs-defaults | less
debobs-defaults > defaults.txt
16
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
2.10.3 debops-init
Creates a project for you at the path you specify.
After running this script you should check out
ansible/inventory/hosts relative to your project path.
debops-init ~/myproject
2.10.4 debops-padlock
An optional script that allows you to encrypt your secrets directory using EncFS and GPG.
1. Make sure you have encfs installed, ie. apt-get install encfs
2. Make sure you have a GPG keypair
3. Make sure $project_dir/ansible/secret/ is empty
4. Run debops-padlock init and enter your GPG password unless you have an agent
5. Run debops-padlock unlock
6. Do something that would result in adding files to secret/, such as touching a file
7. Run debops-padlock lock
8. Confirm you have 1 or more sub-folders or files in .encfs.secret/
The above steps performed the following tasks:
• Setup a project directory to use an encrypted secrets directory
• Added files to be encrypted
• Locked it, which unmounts secret/ – it is now secure
That sounds annoying, can it be done better?
When running any play book through the debops script, it will automatically take care of unlocking/locking it after
the run finishes successfully or errors out.
There is a catch, make sure you always use debops to run your plays because if you run ansible-playbook
directly the unlock/lock process will not happen automatically. It may change your passwords and whatever else you
have stored.
If you use the debops script you won’t have to worry about anything being changed.
Delete your secrets
Since EncFS mounts secret/ you need to unlock it first. If you forgot to unlock it first then you will get a device is
busy error.
You can fix this by unmounting it yourself before trying to delete it, run:
fusermount -u <path to secret/>
Migrate an existing secrets directory to be encrypted
EncFS can only mount empty directories but don’t worry. Just move the files inside of secret/ to somewhere else,
then start the steps above.
2.10. Using the custom scripts
17
DebOps Documentation, Release master
Why does it ask for the GPG password twice?
Two files are being encrypted. The EncFS configuration and the EncFS keyfile. If you use an agent then you won’t
have to enter your password.
What if GPG fails to decrypt?
If the configuration is not decrypted properly, EncFS discards the garbled data and tries to create a new encrypted
directory. You can just CTRL+C to quit and fix your issues.
2.10.5 debops-task
Wraps ansible, it can accept anything ansible does.
You could use it to run adhoc tasks against your hosts.
debops-task all -m setup
debops-task somegroup -m shell "touch /tmp/foo && rm -rf /tmp/foo"
2.10.6 debops-update
Updates the playbooks and roles relative to $PWD, if none are found then it will update them at their default location.
2.11 Ansible roles provided in DebOps
2.11.1 debops.ansible
debops.ansible is an Ansible role which builds and installs Debian package with specified Ansible version (by
default, devel). It can be used to easily create remote Ansible Controller host or test your playbooks on a devel
Ansible version in a container or VM.
If redis-server is found on managed host, this role will automatically enable support for host fact caching in
Ansible.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.ansible
18
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Role variables
List of default variables available in the inventory:
--# ---- Ansible .deb package build ---# Ansible version to build
role_ansible_version: ’devel’
# User which will be used to clone and build Ansible
# By default, current system user
role_ansible_build_user: ’{{ ansible_ssh_user | default(lookup("env","USER")) }}’
# Where Ansible will be cloned and built, relative to user’s $HOME
role_ansible_build_path: ’src/github.com/ansible/ansible’
# Ansible repository which will be cloned
role_ansible_git_repository: ’https://github.com/ansible/ansible.git’
# ---- /etc/ansible/ansible.cfg ---# Ansible will use ’inventory/’ directory in local directory by default
role_ansible_config_hostfile: ’inventory/’
# How many forks to use by default
role_ansible_config_forks: ’5’
# How Ansible should gather host facts during playbook execution
role_ansible_config_gathering: ’smart’
# List of directories to look for Ansible roles
role_ansible_config_roles_path: [ ’/etc/ansible/roles’ ]
# Should Ansible check SSH host fingerprint?
role_ansible_config_host_key_checking: True
# Default module to use if none is specified
role_ansible_config_default_module_name: ’command’
# Default hash behaviour, ’replace’ or ’merge’
role_ansible_config_hash_behaviour: ’replace’
# Should Ansible display skipped hosts?
role_ansible_config_display_skipped_hosts: True
# Specify what fact caching mode to use, currently ’memory’ or ’redis’. Leave
# undefined to let Ansible role detect redis by itself
role_ansible_config_fact_caching: ’’
# Timeout for cached host facts, by default 24h
role_ansible_config_fact_caching_timeout: ’{{ (60 * 60 * 24) }}’
List of internal variables used by the role:
role_ansible_package_version
role_ansible_fact_caching
2.11. Ansible roles provided in DebOps
19
DebOps Documentation, Release master
Authors and license
debops.ansible role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.2 debops.apt
debops.apt configures and manages APT package manager in Debian and other derivative distributions. Specifically, it will manage:
• list of APT sources
• centralized APT cache (using apt-cacher-ng)
• automatic package updates (using unattended-upgrades and apticron)
• Debian Preseed configuration
• local APT repository (using reprepro)
• installation of custom packages specified in Ansible inventory
Table of Contents
•
•
•
•
•
Installation
Examples
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.apt
Examples
Using this role it is easy to update all managed machines:
ansible all -s -m apt -a ’update_cache=yes upgrade=yes’
Role dependencies
• debops.etc_services
• debops.nginx
• debops.reprepro
• debops.ferm
• debops.apt_preferences
20
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
• debops.secret
Role variables
List of default variables available in the inventory:
--# Manage APT package manager (set to False to disable)
# Set to FQDN of a host to specify it as host for
#
apt-cacher-ng - apt-get cache
#
Debian Preseed configuration (planned)
#
reprepro - Debian local repositories
apt: True
# Default distribution used by APT
apt_codename: ’{{ ansible_lsb.codename }}’
apt_codename_backports: ’{{ apt_codename }}-backports’
# Send mail notifications from APT to these email addresses
apt_mail_notifications: [ ’root’ ]
# ---- Update notifications ---# Enable mail notifications about updates (apticron and apt-listchanges)
apt_update_notifications: True
# What type of notifications to send (choices: news, changelogs, both)
apt_update_notifications_type_listchanges: ’news’
apt_update_notifications_type_apticron: ’both’
# Send only information about changes from the last notification?
apt_update_notifications_diff: True
# ---- unattended-upgrades ---# Enable unattended-upgrades
apt_unattended_upgrades: True
# Do not automatically upgrade these packages
apt_unattended_upgrades_blacklist: [ ’vim’, ’libc6’ ]
# If True, send mail notifications about all performed automatic upgrades
# If False, send mail notifications only on errors
apt_unattended_upgrades_notify_always: True
# Automatically remove unused dependencies
apt_unattended_upgrades_autoremove: True
# ---- Other ---apt_debian_http_mirror: ’cdn.debian.net’
# Update APT cache early in the playbook if it’s older than 24h
# Set to False to disable update (useful when changing APT mirrors)
2.11. Ansible roles provided in DebOps
21
DebOps Documentation, Release master
apt_update_cache_early: ’{{ (60 * 60 * 24) }}’
apt_acng_port: 3142
apt_acng_login: ’admin’
apt_acng_password: ’password’
# Allow access to apt-cacher-ng service from specified IP addresses or CIDR networks.
# If not specified, allows access from all networks
apt_acng_allow: []
# Default base packages to install
# This list will be included in Debian Preseed configuration
apt_base_packages: [ ’ed’, ’python’, ’python-apt’, ’lsb-release’, ’make’, ’sudo’, ’gnupg-curl’,
’git’, ’wget’, ’curl’, ’rsync’, ’netcat-openbsd’, ’bridge-utils’, ’vlan’,
’openssh-server’, ’openssh-blacklist’, ’openssh-blacklist-extra’,
’python-pycurl’, ’python-httplib2’, ’apt-transport-https’, ’acl’ ]
# List of additional "global" packages to install
apt_packages: []
# List of packages for a group of hosts (only one group supported)
apt_group_packages: []
# List of packages to install on a given host
apt_host_packages: []
apt_debian_preseed_hostname: ’{{ ansible_hostname }}’
apt_debian_preseed_domain: ’{{ ansible_domain }}’
apt_debian_preseed_locale: ’en_US.UTF-8’
apt_debian_preseed_language: ’English’
apt_debian_preseed_timezone: ’UTC’
apt_debian_preseed_keyboardvariant: ’American English’
apt_debian_preseed_mirror_country: ’United States’
apt_debian_preseed_rootpw_length: ’20’
apt_debian_preseed_rootpw: "{{ lookup(’password’, secret + ’/credentials/’ + ansible_fqdn + ’/debian_
apt_debian_preseed_username: "{{ lookup(’env’,’USER’) }}"
apt_debian_preseed_sshkey: "{{ lookup(’pipe’,’ssh-add -L’) }}"
apt_debian_preseed_filesystem: ’ext4’
List of internal variables used by the role:
nginx_server_default
Authors and license
debops.apt role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.3 debops.apt_preferences
APT preferences can be used to influence package selection performed by APT during installation or upgrades. You
can for example tell APT that you prefer packages from certain repositories or want to hold a package on a particular
version no matter what (among other things).
22
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
By default, if you don’t specify version or provide custom pin configuration, debops.apt_preferences role
will configure specified packages to be installed from backports repository of a current OS release.
Table of Contents
• Installation
• Role variables
• Detailed usage guide
– Usage examples
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.apt_preferences
Role variables
List of default variables available in the inventory:
--# List of pins from every host in the cluster
apt_preferences_list: []
#- package: ’nginx nginx-*’
# backports: [ ’wheezy’ ]
# List of pins for a specific group of hosts
apt_preferences_group_list: []
# List of pins for a specific host
apt_preferences_host_list: []
# List of pins defined by a role via dependency variables
apt_preferences_dependent_list: []
# Default pin priority used if custom is not specified
apt_preferences_priority_default: ’500’
# Default pin priority used with item.version option
apt_preferences_priority_version: ’1001’
Detailed usage guide
Each pin should be defined as a hash in one of above apt_preferences_*_list lists. All variables except
item.package are optional, role will try to make sensible choices if specific variables are not present.
• item.package: string of package names affected by this pin, each package separated by space. You can
use package-* wildcard to specify multiple packages. First package name will be included in automatically
generated filename of the pin preferences file.
2.11. Ansible roles provided in DebOps
23
DebOps Documentation, Release master
• item.backports: list of OS releases which should be considered when debops.apt_preferences
role configures pin for a backported package. If current OS release is not on this list, pin won’t be created, and
existing pin will be removed. This should allow for easy transition to next OS release.
• item.version: specify a particular package version you want to pin, for exmple 5.10. It will be configured
with added * at the end to allow for upgrades. By default versioned pins are set with priority 1001, which
should ensure that selected pckage version is never upgraded, or it will be downgraded if required.
• item.priority: specify custom priority for a pin. By default pins are created with priority 500 to allow for
easy installation of packages from backports, versioned pins are created with priority 1001.
• item.reason: a short description explaining the reason for a pin. Might be used to point a system administrator to useful documentation explaining why a particular pin is defined.
• item.filename:
name of the generated file with pin preferences,
saved in
/etc/apt/preferences.d/. If undefined, debops.apt_preferences role will automatically
generate a filename.
• item.suffix: additional string added at the end of autogenerated filename, can be used to prevent filename
collisions.
• item.by_role: name of a role which sets a particular pin. This name will be included in the autogenerated
filename.
• item.pin: custom pin definition. If this variable is undefined, debops.apt_preferences role will
automatically configure selected packages with preference for a backported version.
• item.raw: instead of generating a pin automatically, use contents of this text block for pin configuration.
Might be used to create several pins in one file.
• item.delete: if this variable is defined and True, preferences file for this pin will be deleted and new one
will not be created.
Usage examples
This role can be used directly from a playbook, with pin configuration specified directly:
--- name: Install nginx from wheezy-backports on Wheezy
hosts: all
sudo: True
roles:
- role: debops.apt_preferences
tags: apt_preferences
apt_preferences_list:
- package: ’nginx nginx-*’
backports: [ ’wheezy’ ]
tasks:
- apt: name=nginx state=latest
More fine-grained configuration can be specified using inventory variables, for example per group or per host:
--apt_preferences_group_list:
- package: ’*’
suffix: ’_testing’
pin: ’release a=testing’
priority: ’900’
reason: ’Prefer packages from testing’
24
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
- package: ’*’
suffix: ’_debian’
pin: ’release o=Debian’
priority: ’-10’
reason: ’Lower package preference from other releases’
You can also use debops.apt_preferences as a dependency in another role:
--dependencies:
- role: debops.apt_preferences
tags: apt_preferences
apt_preferences_dependent_list:
- package: ’mysql-server mysql-client mysql-common’
version: ’5.5’
by_role: ’debops.mysql’
reason: ’Hold mysql on version 5.5*’
Authors and license
debops.apt_preferences role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.4 debops.auth
debops.auth manages basic user authentication and authorization on configured host, including setting up system
groups with elevated privileges.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.auth
Role variables
List of default variables available in the inventory:
--# List of default accounts that are given admin status by being added to
# ’admins’ system group
auth_admin_accounts: [ ’{{ ansible_ssh_user }}’ ]
2.11. Ansible roles provided in DebOps
25
DebOps Documentation, Release master
# List of default system accounts that are used in the playbook
auth_system_groups:
# Global system administrators, unrestricted root access, unrestricted SSH
- ’admins’
# Users in this group can connect to the host using SSH service
- ’sshusers’
#
#
#
-
Users in this group have access only to chrooted SFTP service (without full
shell access) and cannot use SSH public keys in ~/.ssh/authorized_keys file
(only keys in ’/etc/ssh/authorized_keys.d/user’ are allowed)
’sftponly’
#
#
#
#
-
Users in this group can reload nginx service using sudo and have access to
/etc/nginx/sites-local/ directory where they can put nginx vhost
configuration files to be enabled by Ansible in nginx
(this might be moved to ’nginx’ role in the future)
’webadmins’
Authors and license
debops.auth role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.5 debops.backporter
This is a helper Ansible role which allows you to ensure that Debian packages with certain versions are available on
your hosts. If requested version is not available in currently configured APT repositories (for example wheezy and
wheezy-backports from official Debian archives), backporter, if properly configured, will try to build and
install required version from testing repository.
If successful, newly built backported packages will be uploaded to Ansible Controller host which then can make these
packages available to the rest of the Ansible cluster using debops.reprepro role to create and maintain local APT
repository.
debops.backporter role is based on instructions from Simple Backport Creation HOWTO. rmadison utility
from devscripts package is used to check available Debian packages, and depends on availability of Debian QA
Madison service.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Detailed usage guide
– Local package cache and multiple package installation
– Sharing backported packages using reprepro
• Authors and license
26
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.backporter
Role dependencies
• debops.secret
Role variables
List of default variables available in the inventory:
--# ---- Required configuration variables ---# Name of a package to build
backporter_package: ""
# What package version should be available in APT repositories?
backporter_version: ""
# ---- Common configuration variables ---# If a package to backport is not present in current APT repositoriesA, version
# comparsion with required package will fail. In that case you can fake
# non-existent version number to force backport of the package (keep it much
# lower than existing packages to be compatible with future releases).
backporter_fake_version: ""
# Name of a source package to build from (usually the same as the package)
backporter_source_package: ’{{ backporter_package }}’
# List of required packages to install before build
backporter_prerequisites: []
# Fallback version number of source package to use in case rmadison service is
# inaccessible
backporter_source_version: ""
# Regexp to use to find orig tarball in build directory (by default Debian uses
# .tar.xz format but it might be different)
backporter_source_orig: ’.orig.tar.xz’
# Which Debian component to look in for a package source
backporter_component: ’main’
# What comparsion to use to check for available package version? By default
# check if package available is older than the package you are requesting
backporter_comparsion: ’<’
# List of regexps used to find created .deb packages which will be installed on
# build host
backporter_install_packages: [ ’{{ backporter_package }}_*.deb’ ]
2.11. Ansible roles provided in DebOps
27
DebOps Documentation, Release master
# List of regexps used to find created .deb packages which will be uploaded to
# Ansible Controller host (in ’secret’ directory) to include in local reprepro
# repositories
backporter_upload_packages: ’{{ backporter_install_packages }}’
# Send mail reminder to administrator about uploaded packages? If yes, specify
# list of mail recipients
backporter_mail_to: [ ’{{ backporter_email }}’ ]
# Specify a temporary directory where backported packages will be stored for
# later installation. Without ’backporter_package’ set, specify directory where
# packages to install are stored.
backporter_cache: ""
# Delete cache directory after installation?
backporter_cache_clean: True
# ---- Backport configuration variables ---# Maintainer name
backporter_maintainer: ’Automated Package Maintainer’
# Maintainer mail address (will receive information about new uploaded packages)
backporter_email: ’[email protected]{{ ansible_domain }}’
# Base string to append to backported package version (will be used in
# changelog and name of .orig.tar.xz file)
backporter_new_version: ’~bpo{{ ansible_distribution_version | replace(".","") }}’
# Full string to append to backported package version (will be used in
# changelog and finished .deb package names)
# Set this variable to False to not add any strings to package version
backporter_changelog_version: ’{{ backporter_new_version }}+’
# Message included in changelog
backporter_changelog_message: ’Package rebuilt automatically by Ansible for local {{ backporter_relea
# ---- Backporter role internal variables ---# Linux distribution and release which will trigger backport requirement tests
backporter_distribution: ’Debian’
backporter_release: ’wheezy’
# Should package be backported regardless of wether it’s currently available in
# APT repository?
backporter_force: False
# Address to a Debian mirror which will be used to download source packages
backporter_build_mirror: ’http://cdn.debian.net/debian’
# Name of next distribution release which will be used to check available
# package version (don’t use suite names here, because backports make sense
# only for specific releases)
backporter_build_codename: ’{{ backporter_next[backporter_release] }}’
# Length of the slice of source package name used to create path to source
28
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# package (from the start of the string). If you are backporting a library, set
# this to 4 to use path like ’.../main/liba/libansible/libansible_...’
backporter_source_package_slice: 1
# Part of URI to a source package (last part will be added during runtime after
# check for available versions)
backporter_source_path: ’{{ backporter_build_mirror }}/pool/{{ backporter_component }}/{{ backporter_
# Path to directory on remote host where backported packages will be built
backporter_build_path: ’/usr/local/src’
# Command used to download .dsc package sources. If you have problems with GPG
# key verification, set this to ’dget -u’
backporter_command_dget: ’dget’
# If a package that is backported does not exist in current Debian release, its
# build dependencies might not exist too and ’apt-get build-dep’ step will fail.
# Instead enable this variable and provide all required dependencies in
# ’backporter_prerequisites’ variable.
backporter_skip_builddep: False
# Should .deb packages that are created be automatically installed on build
# host?
backporter_install: True
# Should .deb packages that are created be automatically uploaded to Ansible
# Controller in a directory accessible by ’reprepro’ role?
backporter_upload: True
# Path to a directory on Ansible Controller used by ’reprepro’ role to download
# packages to local APT repository
backporter_upload_storage: ’{{ secret + "/reprepro/includedeb/" + backporter_release + "-backports" }
# List of required Debian SDK packages to install on a host before backporting
backporter_sdk_packages: [ ’devscripts’, ’build-essential’, ’debian-keyring’,
’liburi-perl’, ’libdistro-info-perl’, ’python-httplib2’,
’curl’, ’debhelper’ ]
# List of source repositories to enable on a host
backporter_repositories:
- ’deb-src {{ backporter_build_mirror }} {{ ansible_distribution_release }} main contrib’
List of internal variables used by the role:
backporter_register_package_dpkg_version
backporter_register_build_source_dir
backporter_register_package_version
backporter_build_root
backporter_register_dsc_version
Detailed usage guide
debops.backporter role is designed to be used as a dependency of another role (multiple instances are supported). Thanks to this design, primary goal of the role is to ensure that a specified version of the package is already
available in the configured repositories. If this is true, backporter skips all other steps and primary role continues
as usual, installing the package by itself from APT repositories.
2.11. Ansible roles provided in DebOps
29
DebOps Documentation, Release master
By defaut version and availability checks are performed on specific distribution, Debian Wheezy (current Stable Debian distribution) and should not interfere on other distributions (Debian Jessie, Ubuntu). If needed, backport of a
package can be enforced by a variable.
To use debops.backporter with your own role, create meta/main.yml file and add information about role
dependencies:
--dependencies:
- role: debops.backporter
backporter_package: ’foo’
backporter_version: ’1.0’
This configuration will ensure that package foo is available in APT repository in at least version 1.0 (different
version formats are handled internally by Ansible). If it’s not available, debops.backporter will try to download
a .dsc source package foo from Debian Testing repositories and build it for Debian Wheezy (without using packages
from Testing).
Different packages might require different configuration (for example name of source package is different, additional packages need to be installed for the build to be successful, and so on). Read defaults/main.yml file of
debops.backporter role to see different configuration variables you can use in dependency definition. To make
configuration easier, it’s best to try and build the packages from .dsc sources manually using commands specified in
Simple Backport Creation HOWTO to easily find out issues with build process, list of required packages, and so on.
If Debian QA Madison service is not available, debops.backporter will try to use a static version number (if it
is set in dependency variable) to look for source packages. If static version number is not set, playbook execution will
stop and user will be asked to provide one, which can be found on Debian Packages webpage.
Local package cache and multiple package installation
Some packages might require dependent packages of versions different than the ones available in your APT repositories. In this case, you can use debops.backporter role as a dependency multiple times, to backport different
packages in order.
To avoid problems with multiple package interdependencies during installation which cannot be solved using APT
because packages are not yet present in local APT repository, you can use local cache directory, specified using
backporter_cache variable, for example:
backporter_cache: ’/tmp/package-cache’
Backported packages will be put there and stored for later use (you might also need to disable automatic installation
of generated packages with backporter_install: False variable).
After all needed packages have been backported, use debops.backporter role again without specified
package to backport, but specifying cache directory and list of packages to install. After installation is finished, cache directory will be automatically removed to prevent subseqent reinstalls (you can block that with
backporter_cache_clean: False variable).
Sharing backported packages using reprepro
By default, debops.backporter role will try to upload created .deb packages to Ansible Controller host, to
a specific directory within the secret/ directory tree. This way packages can be used on other hosts within the
Ansible cluster using debops.reprepro role.
To enable this, you need to specify a FQDN hostname of a host within Ansible cluster (or a group within that cluster)
which will act as an APT cache and local APT repository. To do that, in your inventory/all.yml (or other part
of the inventory, per group or per host), set variable:
30
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
--apt: ’host.example.com’
This variable will tell debops.apt role to configure apt-cacher-ng APT cache and reprepro repository on
specified host, automatically enabling use of these services on other hosts within cluster/group. debops.reprepro
role will download packages from secret/ directory of Ansible Controller and include them in local APT repository,
which then can be accessed by other hosts within the cluster.
You can easily exploit this feature by, for example, creating temporary LXC containers using debops.lxc role,
building backported .deb packages that you need (by configuring specific Ansible roles in these temporary containers) and distributing them among your other hosts using local APT repository. Temporary containers can then be
removed to reclaim space/IP addresses, etc.
Authors and license
debops.backporter role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.6 debops.boxbackup
BoxBackup is an automated, centralized, encrypted backup service. This role will install and configure the server on
specified host and then configure all specified clients to create backup on the boxbackup-server host.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.boxbackup
Role dependencies
• debops.ferm
• debops.etc_services
• debops.secret
Role variables
List of default variables available in the inventory:
2.11. Ansible roles provided in DebOps
31
DebOps Documentation, Release master
--# FQDN address of the Box Backup server to use
boxbackup_server: ’{{ hostvars[groups.debops_boxbackup[0]]["ansible_fqdn"] }}’
# Set to list of IP addresses / network ranges to allow access only from these
# networks. Empty list allows access from any host / network.
boxbackup_allow: []
# Directory where boxbackup-server is storing backups
boxbackup_storage: ’/srv/boxbackup’
# boxbackup-server is listening on this IP address (all interfaces by default)
boxbackup_listenAddresses: ’0.0.0.0’
# Enable/Disable verbose logging
boxbackup_verbose: ’no’
# 32-bit hexadecimal number representing the boxbackup-client account on the server
# By default it is computed automatically as: ’ansible_fqdn | sha1sum | cut -c1-8’
boxbackup_account: ""
# Soft limit for storage space in megabytes, by default it’s calculated as
# total disk space of a given host. When used space is bigger than this,
# boxbackup-server starts to remove old and deleted data
boxbackup_softlimit:
# Hard limit for storage space in megabytes. by default it’s calculated as
# soft limit * multiplier (see below). When used space reaches this limit,
# server refuses to accept new data
boxbackup_hardlimit:
# Additional disk space added to soft limit, in megabytes. If this number is
# negative, you will substract given amount of disk space from calculated soft
# limit
boxbackup_softlimit_padding: 1024
# Hard limit multiplier will by default set hard limit to equal
# soft limit + 50%. If you set this number lower than 1.0, you will have
# smaller hard limit than soft limit, which is not a good idea
boxbackup_hardlimit_multiplier: 1.5
# Email address which will receive alerts from boxbackup. By default it’s
# <[email protected]>, which is usually aliased to root account
boxbackup_email: ’backup’
# List of directories to back up; directory is a hash key, optional
# exclude/include directives should be written as a text block. Examples can be
# found in the /etc/boxbackup/bbackupd.conf config file
boxbackup_locations:
’/etc’: |
ExcludeFile = /etc/boxbackup/bbackupd/{{ boxbackup_account }}-FileEncKeys.raw
’/home’:
’/opt’:
’/root’:
32
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
’/srv’:
’/usr/local’:
’/var’: |
ExcludeDir = /var/spool/postfix/dev
# List of additional directories / mount points to back up, format is the same
# as a list above
boxbackup_locations_custom:
List of internal variables used by the role:
boxbackup_account
boxbackup_hardlimit
boxbackup_softlimit
Authors and license
debops.boxbackup role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.7 debops.console
This role manages console-related things, like enabling serial console, setting up /etc/motd and /etc/issue
files, configuring system-wide locale settings. You can also provide a list of packages to install.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.console
Role variables
List of default variables available in the inventory:
--# Custom string added to /etc/issue
console_issue: ’Organization Name’
# Enable or disable serial console (allows you to use ’lxc-console’,
# ’virsh console’ and other similar commands)
2.11. Ansible roles provided in DebOps
33
DebOps Documentation, Release master
console_serial: False
# Serial console port
console_serial_port: ’ttyS0’
# Serial console baud rate
console_serial_baud: ’115200’
# Serial console TERM string used to define terminal capabilities
console_serial_term: ’xterm’
# String used to enable serial console in sysvinit /etc/inittab
console_serial_inittab: ’S0:2345:respawn:/sbin/getty -L {{ console_serial_port }} {{ console_serial_b
# Contents of /etc/motd
console_motd: |
------------------------------------------------This system is managed by Ansible
------------------------------------------------# List of required console packages
console_base_packages: [ ’locales’ ]
# List of additional packages to install
console_packages: [ ’ncurses-term’, ’vim’, ’mc’, ’ranger’, ’tmux’, ’zsh’, ’htop’,
’less’, ’file’, ’psmisc’, ’iftop’, ’nload’, ’lsof’ ]
# Enable or disable FSCKFIX option in /etc/default/rcS
# This option controls the behaviour of fsck during boot time, if it’s enabled,
# fsck will automatically repair filesystems without stopping the boot
# process.
# Choices: yes, no. Set to False to disable this feature.
console_fsckfix: ’yes’
# List of locales to enable on the host
console_locales: [ ’en_US.UTF-8’ ]
Authors and license
debops.console role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.8 debops.debops
Install DebOps scripts, and optionally automatically download DebOps playbooks and roles and install them systemwide in /usr/local. This role can be used to easily setup a remote Ansible Controller using Ansible.
Table of Contents
• Installation
• Role variables
• Authors and license
34
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.debops
Role variables
List of default variables available in the inventory:
--# List of packages required by DebOps, if you don’t want to install Ansible
# from a Debian package, you can remove it here
debops_packages: [ ’ansible’, ’python-netaddr’ ]
# URL to main DebOps repository
debops_source_url: ’https://github.com/debops/debops’
# Path where DebOps source repository will be cloned
debops_source_path: ’/usr/local/src/github.com/debops/debops’
# git branch name to clone and update
debops_source_version: ’master’
# Should DebOps playbooks and roles be installed automatically system-wide?
# This will be an async operation and it can take a while to complete
debops_playbooks_systemwide: False
Authors and license
debops.debops role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.9 debops.debug
Dump all variables used by Ansible during playbook run to a file for inspection. This role is not active during normal
playbook operation and should be used for development only.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
2.11. Ansible roles provided in DebOps
35
DebOps Documentation, Release master
ansible-galaxy install debops.debug
Role variables
List of default variables available in the inventory:
--# Where to save all Ansible variables
debug_variables: ’/tmp/ansible_variables’
Authors and license
debops.debug role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.10 debops.dhcpd
Install and configure ISC DHCP Server.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.dhcpd
Role variables
List of default variables available in the inventory:
--# ---- Global ISC DHCP Server configuration ---# Is this DHCP server authoritative?
dhcpd_authoritative: False
# List of network interfaces to listen on for DHCP requests
# If this list is empty, Ansible will try to guess correct interfaces
# automatically
dhcpd_interfaces: []
# Default domain to use
36
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
dhcpd_domain: ’{{ ansible_domain }}’
# List of default DNS servers. By default, point users to the same host that
# serves them DHCP requests, on default interface. If this host is a router,
# you might need to set DNS server to internal interface IP address.
dhcpd_dns_servers: [ ’{{ ansible_default_ipv4.address }}’ ]
# Max lease time in hours (default lease time is calculated below)
dhcpd_lease_time: 24
# Default global options formatted as a text block
dhcpd_global_options: |
option domain-name "{{ ansible_domain }}";
option domain-name-servers {{ dhcpd_dns_servers | join(’ ’) }};
default-lease-time {{ (((dhcpd_lease_time / 2) + 6) * 60 * 60)|round|int }};
max-lease-time {{ (dhcpd_lease_time * 60 * 60)|round|int }};
log-facility local7;
# Custom options formatted as a text block
dhcpd_options: False
# ---- ISC DHCP Server configuration scopes ---#
#
#
#
These lists allow you to generate nested configuration scopes in
dhcpd.conf. Most of the information about them can be found in dhcpd.conf(5)
manual page. You can create nested configuration using Ansible variable
expansion (examples below).
# List of general configuration parameters (work in any configuration scope):
# - comment: ’’
add a comment to a scope
# - options: |
custom options for that scope defined as a text block
# - include: ’’
path to external file to include in this scope
# List of hosts (works in groups, subnets):
# - hosts: ’’ or []
list of hosts to configure in that scope; if this is
#
a path to a file, dhcpd will include an external file
#
in this scope
# List of parameters specific to dhcpd_classes:
# - class: ’’
class name
# - subclass:
this is a hash with expression as key and additional
#
options as value in a text block (see example below);
#
each match expression must end with a colon to indicate
#
hash key; optional
# List of parameters specific to dhcpd_groups:
# - subnets: []
list of subnet scopes to group together
# - groups: []
list of other group scopes to include. No recursion!
# List of parameters specific to dhcpd_shared_networks:
# - name: ’’
name of shared network
# - subnets: []
list of subnets in a shared network (do not use
#
dhcpd_subnets here, because they will be duplicated
#
and DHCP server will not start)
# List of parameters specific to dhcpd_subnets:
# - subnet: ’’
start of a subnet range (ie.: 192.168.1.0)
2.11. Ansible roles provided in DebOps
37
DebOps Documentation, Release master
#
#
#
- netmask: ’’
- routers: ’’ or []
netmask for this subnet (ie.: 255.255.255.0)
address or list of addresses of gateway for that
subnet (ie.: 192.168.1.1)
# List of parameters specific to dhcpd_hosts:
# - hostname: ’’
hostname, without domain part
# - address: ’’
IP address reserved for that host, optional
# - ethernet: ’’
Ethernet MAC address of this host, optional
# List of classes
dhcpd_classes: []
#- class ’example-class’
# subclass:
#
’match1’:
#
’match2’: |
#
# match2 options in a text block;
#- class ’example-empty-class’
# List of groups
dhcpd_groups: []
#- comment: ’First group’
# hosts: ’/etc/dhcp/dhcpd-group1-hosts.conf’
# groups: ’{{ dhcpd_group_second }}’
# An example of group nesting
#dhcpd_group_second:
# - comment: ’Second group’
#
hosts: ’/etc/dhcp/dhcpd-group2-hosts.conf’
# List of shared networks
dhcpd_shared_networks: []
#- name: ’shared-net’
# comment: "Local shared network"
# subnets: ’{{ dhcpd_subnets_local }}’
# options: |
#
default-lease-time 600;
#
max-lease-time 900;
# List of subnets not in a shared network
dhcpd_subnets:
- subnet: ’{{ ansible_default_ipv4.network }}’
netmask: ’{{ ansible_default_ipv4.netmask }}’
comment: ’Generated automatically by Ansible’
##
#
#
#
#
#
#
#-
38
subnet: ’dead:be:ef::/64’
ipv6: True
routers: ’10.0.10.1’
comment: "Example IPv6 subnet"
options: |
default-lease-time 300;
max-lease-time 7200;
subnet: ’10.0.20.0’
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
#
#
netmask: ’255.255.255.0’
comment: ’Ignored subnet’
# An example subnets included in a shared network
#dhcpd_subnets_local:
# - subnet: ’10.0.30.0’
#
netmask: ’255.255.255.0’
#
routers: [ ’10.0.30.1’, ’10.0.30.2’ ]
#
# - subnet: ’10.0.40.0’
#
netmask: ’255.255.255.0’
#
routers: ’19.0.40.1’
#
options: |
#
default-lease-time 300;
#
max-lease-time 7200;
#
pools:
#
- comment: "A pool in a subnet"
#
range: ’10.0.30.10 10.0.30.20’
# Global list of hosts in DHCP
dhcpd_hosts: []
# - hostname: ’examplehost’
#
address: ’10.0.10.1’
#
ethernet: ’00:00:00:00:00:00’
# Example global list of hosts read from an external file
#dhcpd_hosts: ’/etc/dhcp/dhcpd.hosts.conf’
# List of external files to include
dhcpd_includes: []
#- ’/etc/dhcp/example.conf’
Authors and license
debops.dhcpd role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.11 debops.directories
This is a simple wrapper role around file Ansible module, which lets you manage (create, modify or remove)
directories using inventory variables, including creation on multiple hosts at once.
Table of Contents
• Installation
• Role variables
• Authors and license
2.11. Ansible roles provided in DebOps
39
DebOps Documentation, Release master
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.directories
Role variables
List of default variables available in the inventory:
--# List of global directories
directories_list: []
##
#
#
#
path: ’/tmp/directory’
state: ’directory’
owner: ’root’
group: ’root’
mode: ’0755’
# required
# List of directories in a host group
directories_group_list: []
# List of directories on a specific host
directories_host_list: []
Authors and license
debops.directories role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.12 debops.dnsmasq
This role installs and configures dnsmasq as a local DNS, DHCP and PXE/TFTP server. You can use it to configure
host-based LAN behind a bridge interface for virtual machines / containers, or use it in your internal network.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.dnsmasq
40
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Role dependencies
• debops.ferm
• debops.tcpwrappers
Role variables
List of default variables available in the inventory:
--# ---- Global options ---# Enable or disable access to local DNS from upstream networks. You can publish
# your subdomain in public DNS by delegating it in your zone configuration.
dnsmasq_public_dns: False
# Enable or disable DHCPv4 support
dnsmasq_dhcpv4: True
# Enable or disable DHCPv6 support (router support is required)
dnsmasq_dhcpv6: True
# Enable or disable local router support (no routing information is sent to
# hosts, DHCPv6 doesn’t work)
dnsmasq_router: True
# Enable or disable TFTP server
dnsmasq_tftp: True
# ---- Network interface options ---# List of network interfaces that are assumed to be upstream networks, if
# present on the host
dnsmasq_upstream_interfaces: [ ’br0’, ’br1’, ’eth0’, ’eth1’ ]
# Name of the IPv4 gateway interface
dnsmasq_ipv4_gateway: ’{{ ansible_default_ipv4.interface | default("") }}’
# Name of the IPv6 gateway interface
dnsmasq_ipv6_gateway: ’{{ ansible_default_ipv6.interface | default("") }}’
# List of internal interfaces on which dnsmasq will configure its services
dnsmasq_interfaces:
# Name of the interface
- interface: ’br2’
# DNS A record of the interface
name: ’gw’
# Optional DNS CNAME records of the interface
aliases: [ ’router’, ’gateway’ ]
# First IP address in the DHCP range (index)
dhcp_range_start: ’10’
2.11. Ansible roles provided in DebOps
41
DebOps Documentation, Release master
# Last IP address in the DHCP range (index)
dhcp_range_end: ’-10’
# DHCP lease lifetime
dhcp_lease: ’24h’
# DHCPv6 options configured on this interface
ipv6_mode: ’ra-names,ra-stateless,slaac’
# ---- DNS options ---# DNS domain configured by dnsmasq for all local networks
dnsmasq_domain: ’{{ ansible_fqdn }}’
# Set DNS MX record of the main domain to dnsmasq host; set to False to disable
dnsmasq_domain_mx: ’{{ ansible_fqdn }}’
# Alternative ’/etc/hosts’ read by dnsmasq, set to False to use default
# ’/etc/hosts’ file
dnsmasq_etc_hosts: ’/etc/hosts.dnsmasq’
# List of additional search domains. Set ’dnsmasq_search’ to False
# to completely disable this functionality.
dnsmasq_search: [ ’{{ dnsmasq_domain }}’, ’{{ ansible_domain }}’ ]
# Hash of DNS CNAME records to configure for hosts found in local DNS
# Entries should be specified without the domain suffix
dnsmasq_cname: {}
#’host1’: ’cname1’
#’host2’: [ ’list’, ’of’, ’aliases’ ]
# ---- TFTP options ---# Path to TFTP root directory
dnsmasq_tftp_root: ’/srv/tftpboot’
# BOOTP command passed to clients (see dhcp-boot in dnsmasq(8)
dnsmasq_tftp_boot: ’pxelinux.0’
# ---- Other options ---# Additional options passed as a YAML text block
dnsmasq_options: ’’
Authors and license
debops.dnsmasq role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
42
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
2.11.13 debops.elasticsearch
debops.elasticsearch role allows you to easily setup infrastructure capable of running Elasticsearch.
Table of Contents
•
•
•
•
•
What are a few features available in this role?
Installation
Role dependencies
Role variables
Detailed usage guide
– hosts
– Grouping them all up
– What’s with all of the groups?
• Authors and license
What are a few features available in this role?
• Seamless clustering
• Easily pick node types through groups and also allow you to do it manually
• Add/Remove plugins and libs on demand - You can even set custom configuration to each plugin, check the
defaults
• Tweak pretty much everything that ES allows you to
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.elasticsearch
Role dependencies
• debops.ferm
• debops.etc_services
• debops.java
Role variables
List of default variables available in the inventory:
--# role: elasticsearch
# NOTE: For the details on what each variable does, please see comments in the
# default Elasticsearch configuration file:
# https://github.com/elasticsearch/elasticsearch/blob/master/config/elasticsearch.yml
2.11. Ansible roles provided in DebOps
43
DebOps Documentation, Release master
# ---- Inventory group names ---elasticsearch_group_master: ’debops_elasticsearch_master’
elasticsearch_group_workhorse: ’debops_elasticsearch_workhorse’
elasticsearch_group_coordinator: ’debops_elasticsearch_coordinator’
elasticsearch_group_loadbalancer: ’debops_elasticsearch_loadbalancer’
# ---- DebOps role dependencies ---# Automatically install Java 7 Open JDK JRE.
elasticsearch_role_dependencies: [’java’]
# ---- Version ---# It will automatically install the latest minor release, only supply 1.x.
elasticsearch_version: ’1.3’
# ---- Cluster ---elasticsearch_cluster_name: ’elasticsearch’
# ---- Node ---# An empty name will let elasticsearch randomly generate one for you.
elasticsearch_node_name: ’’
elasticsearch_node_master: true
elasticsearch_node_data: true
elasticsearch_node_rack: ’nicerack’
elasticsearch_node_max_local_storage_nodes: 50
# ---- Index ---elasticsearch_index_shards: 5
elasticsearch_index_replicas: 1
# ---- Plugins ---# Examples:
#
# It follows the same syntax as using the ES plugin manager:
# bin/plugin -i <name> -u <url>
#
# The url and config is optional.
#
#
# Using only a name...
#
#elasticsearch_plugins:
# - name: ’com.sksamuel.elasticsearch/elasticsearch-river-redis/1.1.0’
#
#elasticsearch_plugins:
44
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# - name: ’com.sksamuel.elasticsearch/elasticsearch-river-redis/1.1.0’
#
delete: True
#
#
# Using a name with url...
#
#elasticsearch_plugins:
# - name: ’facet-script’
#
url: ’http://dl.bintray.com/content/imotov/elasticsearch-plugins/elasticsearch-facet-script-1.1.
#
#
# Using a name and custom configuration (in this case, cloud-aws)...
# Just pass a string block to the config key, it works for any plugin.
#
#elasticsearch_plugins:
# - name: elasticsearch/elasticsearch-cloud-aws/2.3.0
#
config: |
#
# cloud-aws configuration
#
cloud:
#
aws:
#
access_key: <your access key>
#
secret_key: <your secret key>
#
discovery:
#
type: ec2
#
repositories:
#
bucket: <the bucket created in s3>
# A list of plugins to install or delete.
elasticsearch_plugins: []
# ---- Libraries ---# Examples:
#
# The url is required, everything else is optional.
#
#
#elasticsearch_libs:
# url: ’http://somewebsite.com/foo.jar’
#
#
#elasticsearch_libs:
# url: ’http://somewebsite.com/foo.jar’
# file: ’differentfilename.jar’
# delete: True
#
#
#elasticsearch_libs:
# url: ’http://somewebsite.com/foo.jar’
# user: ’basicauthuser’
# pass: ’basicauthpass’
# A list of libraries to install or delete.
elasticsearch_libs: []
# ---- Memory and filesystem ----
2.11. Ansible roles provided in DebOps
45
DebOps Documentation, Release master
elasticsearch_memory_mlockall: false
# The heap size should be about 50% of your total RAM on a dedicated instance.
# If you are running ES with a bunch of other services don’t be afraid to
# drastically lower this but be aware of performance issues if it’s too low.
elasticsearch_memory_heap_size_multiplier: 0.5
elasticsearch_memory_heap_newsize: ’’
elasticsearch_memory_direct_size: ’’
elasticsearch_memory_locked_size: ’unlimited’
elasticsearch_memory_vma_max_map_count: 262144
elasticsearch_fs_max_open_files: 65535
# Force ES to use ipv4, set this to an empty string if you want to use ipv6.
elasticsearch_fs_java_opts: ’-Djava.net.preferIPv4Stack=true’
# ---- Network and HTTP ---elasticsearch_bind_host: ’localhost’
elasticsearch_publish_host: ’{{ ansible_default_ipv4.address }}’
elasticsearch_node_port: ’9300-9400’
elasticsearch_http_port: ’9200-9300’
elasticsearch_compress: false
elasticsearch_http_max_content_length: ’100mb’
elasticsearch_http_enabled: true
# Which hosts are allowed to connect through the firewall?
# This is used for inter-node communication and in multicast’s case, discovery.
elasticsearch_node_allow: []
elasticsearch_multicast_allow: ’{{ elasticsearch_node_allow }}’
# This is used for accessing the http API, you may consider having your app
# servers be able to access it, etc..
elasticsearch_http_allow: []
# ---- Security ---# Do not enable this unless you have a very good reason to do so.
elasticsearch_jsonp_enabled: false
# ---- Gateway ---elasticsearch_gateway_type: ’local’
# These get dynamically set by ES, make sure you know what you’re doing.
#elasticsearch_gateway_recover_after_time: ?
#elasticsearch_gateway_recover_after_nodes: ?
#elasticsearch_gateway_expected_nodes: ?
# ---- Recovery throttling ---elasticsearch_recovery_max_bytes_per_sec: ’20mb’
46
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# These get dynamically set by ES, make sure you know what you’re doing.
#elasticsearch_recovery_node_initial_primaries_recoveries: ?
#elasticsearch_recovery_node_concurrent_recoveries: ?
#elasticsearch_recovery_concurrent_streams: ?
# ---- Discovery ---# Consider raising this once you have > 2 nodes.
elasticsearch_discovery_minimum_master_nodes: 1
elasticsearch_discovery_ping_timeout: ’3s’
elasticsearch_discovery_multicast_enabled: true
elasticsearch_discovery_ping_unicast_hosts: []
# ---- Slow log ---elasticsearch_slowlog_query_warn: ’10s’
elasticsearch_slowlog_query_info: ’5s’
elasticsearch_slowlog_query_debug: ’2s’
elasticsearch_slowlog_query_trace: ’500ms’
elasticsearch_slowlog_fetch_warn: ’1s’
elasticsearch_slowlog_fetch_info: ’800ms’
elasticsearch_slowlog_fetch_debug: ’500ms’
elasticsearch_slowlog_fetch_trace: ’200ms’
elasticsearch_slowlog_index_warn: ’10s’
elasticsearch_slowlog_index_info: ’5s’
elasticsearch_slowlog_index_debug: ’2s’
elasticsearch_slowlog_index_trace: ’500ms’
# ---- GC Logging ---elasticsearch_monitor_gc_young_warn: ’1000ms’
elasticsearch_monitor_gc_young_info: ’700ms’
elasticsearch_monitor_gc_young_debug: ’400ms’
elasticsearch_monitor_gc_old_warn: ’10s’
elasticsearch_monitor_gc_old_info: ’5s’
elasticsearch_monitor_gc_old_debug: ’2s’
# ---- Logging ---elasticsearch_logger_level: ’INFO’
elasticsearch_logger_output: ’{{ elasticsearch_logger_level }}, console, file’
elasticsearch_logger:
action: ’DEBUG’
amazon_aws: ’WARN’
gateway: ’DEBUG’
index_gateway: ’DEBUG’
indices_recovery: ’DEBUG’
discovery: ’TRACE’
index_search_slowlog: ’TRACE, index_search_slow_log_file’
2.11. Ansible roles provided in DebOps
47
DebOps Documentation, Release master
index_indexing_slowlog: ’TRACE, index_indexing_slow_log_file’
elasticsearch_logger_additivity:
index_search_slowlog: false
index_indexing_slowlog: false
elasticsearch_logger_appender:
console:
type: console
layout:
type: consolePattern
conversionPattern: ’[%d{ISO8601}][%-5p][%-25c] %m%n’
file:
type: dailyRollingFile
file: ${path.logs}/${cluster.name}.log
datePattern: "’.’yyyy-MM-dd"
layout:
type: pattern
conversionPattern: ’[%d{ISO8601}][%-5p][%-25c] %m%n’
index_search_slow_log_file:
type: dailyRollingFile
file: ${path.logs}/${cluster.name}_index_search_slowlog.log
datePattern: "’.’yyyy-MM-dd"
layout:
type: pattern
conversionPattern: ’[%d{ISO8601}][%-5p][%-25c] %m%n’
index_indexing_slow_log_file:
type: dailyRollingFile
file: ${path.logs}/${cluster.name}_index_indexing_slowlog.log
datePattern: "’.’yyyy-MM-dd"
layout:
type: pattern
conversionPattern: ’[%d{ISO8601}][%-5p][%-25c] %m%n’
Detailed usage guide
Below is a breakdown of how you can use groups to allocate different node types to a number of servers. If all you
want to do is use ES as a single server dependency in another role then include the role in your role’s meta main file.
You don’t have to add the groups in your inventory in that case.
hosts
Elasticsearch has 2 settings, node.master and node.data. A combination of those settings being True or
False determines what type of node your server will be.
Master servers (node.master:
elasticsearch.
True and node.data:
True) This is the default setting for all nodes in
[debops_elasticsearch_master]
apple
orange
banana
48
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Workhorse servers (node.master:
master but it will hold data.
False and node.data:
True) The server will never become a
[debops_elasticsearch_workhorse]
red
blue
Coordinator servers (node.master: True and node.data: False) A coordinator can become master
but it doesn’t store data. Its goal is to always have a lot of free resources.
[debops_elasticsearch_coordinator]
nyancat
Search load balancer servers (node.master: False and node.data:
would be used to fetch data from other servers, aggregate results, etc..
False) A server of this type
[debops_elasticsearch_loadbalancer]
judge
jury
Grouping them all up
It’s always useful to have a common group that composes everything. Elasticsearch will be installed on any server that
belongs to any of the above groups.
This group would mainly be used for firewall settings which would apply to all of your ES nodes. It does not control
whether or not ES gets installed.
[debops_elasticsearch:children]
debops_elasticsearch_master
debops_elasticsearch_workhorse
debops_elasticsearch_coordinator
debops_elasticsearch_loadbalancer
What’s with all of the groups?
They are just shortcuts to setting the 2 node settings for you. You don’t have to use the extra groups. By all means
create custom groups and set the variables yourself if you want.
You can also edit the defaults to use your own custom group names and still get the benefits of group based node type
separation.
inventory/group_vars/debops_elasticsearch.yml
elasticsearch_bind_host: [’0.0.0.0’]
elasticsearch_node_allow: ’{{ groups["debops_elasticsearch"] }}’
elasticsearch_http_allow: ’{{ groups["your_web_apps"] }}’
# The above example tells ES to accept connections from anywhere and then
# white lists your ES group so they can all talk to each other
# In addition to that is white lists your app servers so they can access the
# ES HTTP API to actually query ES
2.11. Ansible roles provided in DebOps
49
DebOps Documentation, Release master
Authors and license
debops.elasticsearch role was written by:
• Nick Janetakis | e-mail | Twitter | GitHub
License: GPLv3
2.11.14 debops.encfs
Ansible role debops.encfs allows you to create and manage directories using EncFS, FUSE-based encrypted
virtual filesystem.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.4. To install it, run:
ansible-galaxy install debops.encfs
Role variables
List of default variables available in the inventory:
--# Absolute path to a directory where encrypted filesystem will be mounted
# Required
encfs: False
# Suffix of the directory with encrypted filesystem, it will be created in the
# same path as the mount directory
encfs_suffix: ".encrypted"
# List of GPG keys to use to encrypt encfs keyfile. GPG encryption is supported
# only on localhost (hosts which have ansible_connection=local set). Without
# list of GPG recipients, GnuPG will ask for a passphrase instead
encfs_gpg: []
# Password to use instead of GPG keys / GPG passphrase. Supports encfs on
# remote hosts. Will be sent via stdout and visible in ’ps’ and Ansible logs,
# use an external file with encfs_passfile to mitigate that.
# You can populate this variable from an external file using lookup(’file’,’path’)
encfs_password: False
# An absolute path to file on remote host to store the password in transit.
# Will be shredded when no longer needed. encfs role creates two files with this
# name + suffixes ’_init’ and ’_pass’
encfs_passfile: False
50
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# By default encfs role behaves as a toggle - opens the encrypted filesystem if
# it’s closed, closes it if opened. By setting encfs_mode (for example with
# --extra-vars) you can force desired mode of operation:
# - ’open’ - create or open encrypted filesystem
# - ’close’ - close encrypted filesystem
encfs_mode: False
# Device to use as source of randomness. You can change that to ’/dev/urandom’
# to use faster but weaker randomness source
encfs_random: ’/dev/random’
List of internal variables used by the role:
encfs_user
Authors and license
debops.encfs role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.15 debops.etc_services
debops.etc_services role can be used to “reserve” or “register” a service port in /etc/services file. Service ports configured this way can appear as named entries in many command outputs, such as iptables -L or
netstat -lp. You can also have convenient database of reserved and free ports on a particular host, and reference
ports by their names in firewall configuration files.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.etc_services
Role variables
List of default variables available in the inventory:
--# Enable /etc/services.d/ support?
etc_services: True
# Name of diverted /etc/services, do not change if diversion is active!
2.11. Ansible roles provided in DebOps
51
DebOps Documentation, Release master
etc_services_diversion: ’/etc/services.d/10_debian_etc_services’
# ---- Local services ---#
#
#
#
These lists allow you to generate entries for local services not included in
officially distributed /etc/services file. They will generate separate files
for each configured service in /etc/services.d/ which then will be assembled
into complete /etc/services file.
# List of known parameters:
# - name: ’’
# - port: ’’
# - protocols: [ ’tcp’,’udp’ ]
# - protocol: ’’
# - comment: ’’
# - filename: ’’
name of the service, required
port on which service is accessed, required
list of protocols to generate, optional
legacy protocol name to use, deprecated
comment to add to the service entry, optional
use this filename instead of a generated one
# These lists should be used in inventory
etc_services_list: []
etc_services_group_list: []
etc_services_host_list: []
# This list can be used in a dependency variables for ’etc_services’ role
etc_services_dependency_list: []
# deprecated
etc_services_dependent_list: []
# Example entry
#- name: ’servicename’
# port: ’12345’
# protocols: [ ’tcp’, ’udp’ ]
# porotol: ’tcp’
# comment: ’Example service’
# deprecated
Authors and license
debops.etc_services role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.16 debops.etherpad
This role installs and configures Etherpad, an on-line multiuser collabolative text editor. It will be installed behind
nginx server with MySQL as a database backend.
Table of Contents
•
•
•
•
52
Installation
Role dependencies
Role variables
Authors and license
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.etherpad
Role dependencies
• debops.etc_services
• debops.secret
• debops.mysql
• debops.nginx
• debops.nodejs
Role variables
List of default variables available in the inventory:
--# ---- Basic configuration ---# Etherpad git version to install
etherpad_version: ’develop’
# Should etherpad role manage it’s own dependencies?
etherpad_dependencies: True
# What domain will be configured for Etherpad
etherpad_domain: [ ’pad.{{ ansible_domain }}’ ]
# Title of Etherpad instance
etherpad_title: ’Etherpad’
# E-mail address of the instance administrator, will be shown on each new pad
# (see ’etherpad_welcome_text’ below)
etherpad_mail_admin: ’[email protected]{{ ansible_domain }}’
# Text displayed on all new pads by default
etherpad_welcome_text: ’Welcome to {{ etherpad_title }}!\n\nThis pad is synchronized as you type, so
# ---- Database and network ---# Allow access only from selected IP addresses/CIDR networks. If empty, allow
# access from everywhere
etherpad_allow: []
# Database to use for data storage (choices: mysql, dirty)
# More databases will be available in the future
etherpad_database: ’mysql’
# Connection type used for the database
etherpad_database_connection: ’socket’
2.11. Ansible roles provided in DebOps
53
DebOps Documentation, Release master
# IP address and port where etherpad-lite daemon will listen for connections
etherpad_bind: ’127.0.0.1’
etherpad_port: ’9001’
# ---- Authentication ---# List of Etherpad
# variable defined
# saved in secret/
etherpad_admins: [
etherpad_users: []
administrative and user accounts, only works with ’secret’
(see ’secret’ role). Passwords are generated automatically and
directory
’admin’ ]
# Require authentication from all users
etherpad_require_authentication: ’false’
# Require authorization by a module or user with is_admin = True
etherpad_require_authorization: ’false’
# Require session to access pads
etherpad_require_session: ’false’
# Block creation of new pads by unauthorized users?
etherpad_edit_only: ’false’
# Trust the reverse proxy (nginx)?
etherpad_trust_proxy: ’false’
# ---- Etherpad customization ---# Enable Abiword support (for document import)?
etherpad_abiword: True
# List of Etherpad plugins to enable
etherpad_plugins:
- ’adminpads’
- ’align’
- ’font_color’
- ’font_family’
- ’font_size’
- ’headings’
- ’hide_referrer’
- ’line_height’
- ’linkify’
- ’message_all’
- ’padlist’
- ’page_view’
- ’print’
- ’rss’
- ’scrollto’
- ’superscript’
- ’subscript’
# ---- Other options ---# Minify CSS and JS assets?
54
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
etherpad_minify: ’true’
# Maximum age of cached assets (6 hours by default)
etherpad_max_age: ’{{ (60 * 60 * 6) }}’
# Disable IP addresses in logs?
etherpad_disable_ip_logging: ’false’
# Etherpad log level (choices: DEBUG, INFO, WARN, ERROR)
etherpad_loglevel: ’INFO’
# Here you can define custom settings.json entries in YAML format, which will
# be converted to JSON and put at the end of the configuration file
etherpad_custom_json: False
List of internal variables used by the role:
etherpad_mysql_database_password
etherpad_session_key
Authors and license
debops.etherpad role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.17 debops.ferm
ferm is a wrapper around iptables command which lets you manage host firewall in an easy and Ansible-friendly
way. This role can be used to setup firewall rules directly from inventory, or it can be used as a dependency by other
roles to setup firewall rules for other services.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.ferm
Role variables
List of default variables available in the inventory:
2.11. Ansible roles provided in DebOps
55
DebOps Documentation, Release master
--# Enable or disable iptables management
ferm: True
# List of iptables domains enabled
# Currently supported domains:
#
- ’ip’ - enables IPv4 support
#
- ’ip6’ - enables IPv6 support
ferm_filter_domains: [ ’ip’, ’ip6’
in main ferm firewall
(iptables)
(ip6tables)
]
# Optional list of CIDR hosts which are not included in ssh port recent filter
# and won’t be blocked by the firewall in case of too many connections.
# Entries are saved in the local facts on remote hosts.
# Remember to specify IP address from the remote host point of view.
# Format: "IP address/netmask", for example: ’192.168.1.1/32’
ferm_ansible_controllers: []
# Comment added at the beginning of iptables, set to False to disable
ferm_comment: ’Generated by ferm - /etc/ferm/ferm.conf’
# Default iptables policy for INPUT, OUTPUT and FORWARD chains
ferm_default_policy_input: ’DROP’
ferm_default_policy_output: ’ACCEPT’
ferm_default_policy_forward: ’DROP’
# Mark packets on invalid ports as bad guys (block port scanning)
ferm_mark_portscan: False
# List of iptables INPUT rules to manage, many variables can be found in
# template files, located in templates/etc/ferm/filter-input.d/ directory.
# Additional variables are described below.
ferm_input_list: []
ferm_input_group_list: []
ferm_input_host_list: []
#- type: ’’
#
#
#
#
dport: []
weight: ’10’
filename: ’’
delete: False/True
#
#
#
#
#
#
name of template file to use, required
format: <type>.conf.j2
list of destination ports to manage, required
helps with file sorting in rule directory, optional
custom filename instead of a generated one, optional
delete specified rule file, optional
Authors and license
debops.ferm role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.18 debops.gitlab
This role installs GitLab, an Open Source GitHub clone. debops.gitlab role will also automatically update
installed GitLab instance if new patches are pushed to the repository.
56
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
You can also use this role to upgrade an already installed GitLab instance to new version when support for it becomes
available (new GitLab version is released on 22nd of each month, usually debops.gitlab role is updated to support
new version shortly after that).
The credentials are saved in the secrets dir secret/credentials/host/gitlab/admin/password The
login is [email protected]
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.gitlab
Role dependencies
• debops.etc_services
• debops.redis
• debops.nginx
• debops.mysql
• debops.ruby
• debops.secret
• debops.postgresql
Role variables
List of default variables available in the inventory:
--# ---- Basic options ---# Should GitLab role manage it’s own dependencies (database, web server)?
gitlab_dependencies: True
# What version of GitLab to install / manage
gitlab_version: ’7.1’
# Allow automatic upgrades to next version? If not, Ansible will stop execution
# when it detects that GitLab requires upgrade
gitlab_auto_upgrade: True
# ---- GitLab instance configuration ----
2.11. Ansible roles provided in DebOps
57
DebOps Documentation, Release master
# What database to use for GitLab instnce? Choices: mysql, postgresql
# Currently only MySQl is supported
gitlab_database: ’mysql’
# Domain which will be used for nginx server and gitlab-shell access
# GitLab will be configured with HTTPS enabled by default
gitlab_domain: [ ’code.{{ ansible_domain }}’ ]
# E-mail sender name used by GitLab
gitlab_email_name: ’GitLab’
# E-mail address used by GitLab
gitlab_email_from: ’[email protected]{{ gitlab_domain[0] }}’
# E-mail address for GitLab support
gitlab_email_support: ’[email protected]{{ ansible_domain }}’
# ---- New user configuration ---# Enable sign up on the front page?
gitlab_signup_enabled: ’true’
# Default project limit for new users
gitlab_default_projects_limit: ’50’
# Should new users be able to create groups?
gitlab_default_can_create_group: ’true’
# Can users change their own username?
gitlab_username_changing_enabled: ’false’
# Default GitLab theme to use
gitlab_default_theme: ’2’
# ---- Custom redis configuration ---# Connection string used in the configuration file
gitlab_redis: ’redis://{{ gitlab_redis_host + ":" + gitlab_redis_port }}’
# Define hostname of redis server to use
gitlab_redis_host: ’localhost’
# Define port of redis server to use
gitlab_redis_port: ’6379’
# ---- Internal application settings ---# Connection type for PostgreSQL database (choices: socket, port)
gitlab_postgresql_database_connection: ’socket’
# nginx client_max_body_size value
gitlab_nginx_client_max_body_size: ’5m’
# nginx - gitlab proxy timeout in seconds
gitlab_nginx_proxy_timeout: ’300’
58
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# Max git upload size in bytes
gitlab_git_max_size: ’5242880’
# git connection timeout in seconds
gitlab_git_timeout: ’10’
# unicorn connection timeout in seconds
gitlab_unicorn_timeout: ’30’
List of internal variables used by the role:
gitlab_status_ce_upgrade
gitlab_status_shell_upgrade
gitlab_status_shell_installed
gitlab_database_password
gitlab_status_ce_installed
gitlab_postgresql_database_password
Authors and license
debops.gitlab role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.19 debops.gitlab_ci
GitLab CI is a continuous integration service based around GitLab. It uses a GitLab instance for authentication and
access to git repositories (can be managed using debops.gitlab role) and GitLab CI Runner service to run the
tests (can be installed using debops.gitlab_ci_runner role).
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.gitlab_ci
Role dependencies
• debops.etc_services
• debops.redis
• debops.nginx
2.11. Ansible roles provided in DebOps
59
DebOps Documentation, Release master
• debops.mysql
• debops.ruby
• debops.secret
• debops.postgresql
Role variables
List of default variables available in the inventory:
--# ---- Basic options ---# Should GitLab CI role manage it’s own dependencies (database, web server)?
gitlab_ci_dependencies: True
# What version of GitLab CI to install / manage
gitlab_ci_version: ’5.0’
# Allow automatic upgrades to next version? If not, Ansible will stop execution
# when it detects that GitLab CI requires upgrade
gitlab_ci_auto_upgrade: True
# ---- GitLab CI instance configuration ---# What database to use for GitLab CI instnce? Choices: mysql, postgresql
gitlab_ci_database: ’mysql’
# List of GitLab instances to include in login form
gitlab_ci_urls:
- ’https://code.{{ ansible_domain }}’
# Domain which will be used for nginx server
# GitLab CI will be configured with HTTPS enabled by default
gitlab_ci_domain: [ ’ci.{{ ansible_domain }}’ ]
# E-mail sender name used by GitLab CI
gitlab_ci_email_name: ’GitLab CI’
# E-mail address used by GitLab CI
gitlab_ci_email_from: ’[email protected]{{ ansible_domain }}’
# E-mail address for GitLab CI support
gitlab_ci_email_support: ’[email protected]{{ ansible_domain }}’
# ---- Internal application settings ---# Patch GitLab CI source
gitlab_ci_patch: True
# Connection type for PostgreSQL database (choices: socket, port)
gitlab_ci_postgresql_database_connection: ’socket’
# nginx client_max_body_size value
60
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
gitlab_ci_nginx_client_max_body_size: ’5m’
# nginx - gitlab proxy timeout in seconds
gitlab_ci_nginx_proxy_timeout: ’300’
# unicorn connection timeout in seconds
gitlab_ci_unicorn_timeout: ’30’
List of internal variables used by the role:
gitlab_ci_status_installed
gitlab_ci_database_password
gitlab_ci_postgresql_database_password
gitlab_ci_status_upgrade
Authors and license
debops.gitlab_ci role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.20 debops.gitlab_ci_runner
GitLab CI Runner is a helper Ruby program which is used by GitLab CI service to run continuous integration tests.
It should be installed on a separate host (or multiple hosts) or even in a LXC or OpenVZ container and is designed
to be easily reinstalled if necessary. You will need a GitLab CI instance to use Runners, which can be installed and
configured using debops.gitlab_ci role.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.gitlab_ci_runner
Role dependencies
• debops.ruby
• debops.ansible
• debops.postgresql
• debops.mysql
• debops.nodejs
2.11. Ansible roles provided in DebOps
61
DebOps Documentation, Release master
Role variables
List of default variables available in the inventory:
--# ---- Runner configuration ---# URL of GitLab CI instance where this runner will try to register
gitlab_ci_runner_url: ’https://ci.{{ ansible_domain }}’
# Runner registration token (required). Currently there is no way to get this
# token automatically. You should install GitLab CI instance and after login go
# to Runners page, where you can find the token. Copy it and save in your
# inventory.
gitlab_ci_runner_token: ""
# What version of GitLab CI to install / manage
gitlab_ci_runner_version: ’5.0’
# Allow automatic upgrades to next version? If not, Ansible will stop execution
# when it detects that GitLab CI requires upgrade
gitlab_ci_runner_auto_upgrade: True
# Number of runner threads to start by default
gitlab_ci_runner_threads: ’{{ ansible_processor_cores }}’
# ---- CI environment ---# List of DebOps roles to run before gitlab_ci_runner. Currently available:
# ansible, nodejs, mysql, postgresql
gitlab_ci_runner_dependencies: []
# List of Debian packages to install after runner has been configured
gitlab_ci_runner_packages: []
# Should gitlab-ci-runner user have full sudo access?
gitlab_ci_runner_sudo: False
# Configuration for MySQL database server. Runner will have access to databases
# with defined prefix, for example ’ci_test_01’
gitlab_ci_runner_mysql_user: ’gitlab-ci-runner’
gitlab_ci_runner_mysql_password: ’{{ gitlab_ci_runner_mysql_user }}’
gitlab_ci_runner_mysql_database_prefix: ’ci_test’
List of internal variables used by the role:
gitlab_ci_runner_status_installed
gitlab_ci_runner_status_upgrade
gitlab_ci_runner_status_registered
Authors and license
debops.gitlab_ci_runner role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
62
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
2.11.21 debops.gitusers
debops.gitusers role can be used to create and maintain user accounts accessible over SSH with limited functionality provided by git-shell and a set of shell scripts. These accounts can provide users with limited shell
functionality and ability to create git repositories on the server, which then can be used to “deploy” web content
(HTML, CSS, PHP5 web pages, support for other environments might be included in the future).
You can think of this role as a simple Heroku or PagodaBox clone.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.gitusers
Role dependencies
• debops.auth
Role variables
List of default variables available in the inventory:
--# --- An example account entry, everything except ’name’ is optional
# List of all recognized values, default value listed first
#
# - name: ’username’
# mandatory, default group if not defined
#
state: ’present,absent’
#
group: ’name’
# default group
#
groups: []
# list of groups to set
#
append: yes/no
# add to, or set groups
#
gid: ’’
#
uid: ’’
#
comment: ’GECOS entry’
#
systemuser: False/True
# create system user
#
systemgroup: False/True
# create system group
#
#
domain: ’{{ ansible_domain }}’ # for git users
#
#
# Create ~/.forward file (set to False to remove ~/.forward)
#
forward: [ ’[email protected]’, ’account’ ]
#
#
# Add or disable ssh authorized keys (set to False to remove ~/.ssh/authorized_keys
#
sshkeys: [ ’list’, ’of’, ’keys’ ]
2.11. Ansible roles provided in DebOps
63
DebOps Documentation, Release master
# --- Lists of different accounts to create/manage --# "Global" users
gitusers_list: []
# "Host group" users
gitusers_group_list: []
# "Host" users
gitusers_host_list: []
# --- Global defaults --# Add a suffix to an account name, for example ’-git’
gitusers_name_suffix: ""
# Shell enforced on all git-shell accounts
gitusers_default_shell: ’/usr/bin/git-shell’
# List of groups git-shell users belong to (git-shell requires SSH access)
gitusers_default_groups_list: [ ’sshusers’ ]
# Should default groups be added to, or replace current user groups? Set to
# ’no’ to enforce your preferred list of groups
gitusers_default_groups_append: ’yes’
# Directory where git-shell user home will be created
gitusers_default_home_prefix: ’/srv/gitusers’
# Unix permissions enforced on users home directories
gitusers_default_home_mode: ’0750’
# Path to directory where websites are stored
gitusers_default_www_prefix: ’/srv/www’
# System group which should be allowed access to website directory
gitusers_default_www_group: ’www-data’
# What domain should git users use for publishing websites
gitusers_default_domain: ’{{ ansible_domain }}’
# List of scripts which are copied to user directories into
# ~/git-shell-commands/ directory
gitusers_default_commands: [ ’help’, ’list’, ’init’, ’publish’, ’userdir’,
’deploy’, ’snapshot’, ’clean’, ’rename’, ’drop’ ]
Authors and license
debops.gitusers role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
64
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
2.11.22 debops.golang
Install Go language (golang) support using Debian packages. You can choose to install the system’s default version of
Go or use the 1.3.x version that has been backported from Debian Jessie.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.1. To install it, run:
ansible-galaxy install debops.golang
Role dependencies
• debops.backporter
Role variables
List of default variables available in the inventory:
--# Install either the ’apt’ or ’backport’ version of Golang
#
’apt’
whatever version is available through apt on your OS/distro
#
’backport’ for when you’re building the backport on your build server
#
# Versions for a few popular distros:
#
Debian Wheezy: 1.0.2 -> backport version is 1.3.1
#
Debian Jessie: 1.3.1
#
Ubuntu Trusty: 1.2.1
golang_version: ’apt’
Authors and license
debops.golang role was written by:
• Nick Janetakis | e-mail | Twitter | GitHub
License: GPLv3
2.11.23 debops.hwraid
HWRaid is a repository of software packages useful on hosts with hardware RAID storage arrays for Debian and
Ubuntu Linux operating systems.
2.11. Ansible roles provided in DebOps
65
DebOps Documentation, Release master
This role will configure the APT repository for supported distributions and after checking list of loaded kernel modules,
install recognized packages. HWRaid packages contain a monitoring script, which will periodically send a mail
message to root account in case of issues with the RAID array.
Some of the software packages offered in HWRaid repository are not Open Source, however there are no alternatives
available.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.hwraid
Role variables
List of default variables available in the inventory:
--# OS distribution used to lookup available releases
hwraid_distribution: ’{{ ansible_distribution }}’
# OS release used to lookup available releases
hwraid_release: ’{{ ansible_distribution_release }}’
List of internal variables used by the role:
hwraid_register_release
Authors and license
debops.hwraid role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.24 debops.ifupdown
This role can be used to manage network interface configuration on Debian and derivative operating systems. It
manages configuration in /etc/network/interfaces directory and can be used to create different interface
layouts across the cluster.
debops.ifupdown role tries to recognize several environments (LXC container, OpenVZ container, system with
installed NetworkManager) and can automatically select one of the suggested configurations. For most scenarios, debops.ifupdown will try to configure up to two network interfaces (non-existent interfaces are gracefully
skipped) with network bridges attached to them, which allows to easily connect virtual machines or containers to the
public or private network.
66
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
In case an advanced configuration is required (more than two network interfaces, bonding, modem connections, NAT,
etc.), you can easily override automatically selected configuration using Ansible inventory. This role can also be used
as a dependency of another role which allows for example to easily manage NAT networks using debops.nat role.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.ifupdown
Role variables
List of default variables available in the inventory:
--# Should Ansible manage /etc/network/interfaces? Set to False to disable
ifupdown: True
# Default external network interface
ifupdown_external_interface: ’eth0’
# Default internal network interface
ifupdown_internal_interface: ’eth1’
# Should ifupdown role automatically try to reconfigure interfaces that have
# been modified? Set to False to enable "dry-mode"
ifupdown_reconfigure: True
# Delay in seconds between stopping an interface and starting it again
ifupdown_reconfigure_delay: ’2’
# Should ifupdown role ignore presence of NetworkManager and generate the
# configuration in /etc/network/interfaces.d/?
ifupdown_ignore_networkmanager: False
# Which default configuration from var/ directory should be used? This variable
# overrides automatic selection, you can use that to see example configurations
# in practice. Specify a filename without ’.yml’ extension
ifupdown_default_config: ""
#
#
#
#
#
#
#
#
List of network interfaces. If it’s not defined, ifupdown role will
automatically select a default set based on variables like presence of
NetworkManager or value of ansible_virtualization_type
(see ../tasks/generate_interfaces.yml). Default sets are defined in ../vars/*
files.
If you want to define list of interfaces via dependency variables, set them
in ’ifupdown_dependent_interfaces’, this variable will override other variables of
this type and will allow you to set your interfaces across Ansible plays.
2.11. Ansible roles provided in DebOps
67
DebOps Documentation, Release master
# Refer to interfaces(5) and https://wiki.debian.org/NetworkConfiguration to
# see possible configuration options.
ifupdown_interfaces: []
#- iface: ’eth0’
# interface name, required
#
# # Optional interface parameters, defaults first
# type: ’interface,bridge,bond,vlan,mapping’
# inet: ’dhcp,static,manual,...’
# mode of operation for IPv4
# inet6: ’dhcp,static,manual,...’
# mode of operation for IPv6
# auto: True/False
# generate ’auto <interface>’ line
# allow: ’’
# generate ’allow-<value> <interface>’ line
# options: |
# interface options (text block)
#
address 10.0.0.1
#
netmask 255.255.255.0
#
# ...
# aliases:
# list of additional IP addresses for interface
#
- address: ’192.168.0.2’
#
netmask: ’255.255.255.0’
# port: ’’
# bridge port to check for existence in
#
# ansible_interfaces, adds ’bridge_ports <port>’ line
#
# (one ping, err, port only)
# device: ’’
# VLAN device to use, adds ’vlan_raw_device <device>’ lin
#
# # Management of files in /etc/network/interfaces.d/
# weight: ’00’
# prefix number, helps with ordering
# filename: ’’
# use alternative file name, "00_<filename>"
# delete: False/True
# remove this interface config file
# force: False/True
# force creation of this interface configuration
#
# even if role thinks otherwise
List of internal variables used by the role:
ifupdown_networkmanager
ifupdown_interfaces
Authors and license
debops.ifupdown role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.25 debops.java
This role installs OpenJDK Java packages. It is useful as a dependency of other roles.
Table of Contents
• Installation
• Role variables
• Authors and license
68
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.java
Role variables
List of default variables available in the inventory:
--# Available options for installing Java Open JDK:
#
7-jre
#
6-jre
#
7-jdk
#
6-jdk
java_versions:
- ’7-jre’
Authors and license
debops.java role was written by:
• Nick Janetakis | e-mail | Twitter | GitHub
License: GPLv3
2.11.26 debops.kvm
This role installs packages required for KVM support on a host. You can then access this host with, for example,
virt-manager to create and manage KVM virtual machines.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.kvm
Role variables
List of default variables available in the inventory:
2.11. Ansible roles provided in DebOps
69
DebOps Documentation, Release master
--# List of administrator accounts which should have access to libvirtd
kvm_admins: [ ’{{ ansible_ssh_user }}’ ]
# UNIX group that has access to libvirtd
kvm_group: ’libvirt’
Authors and license
debops.kvm role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.27 debops.lxc
debops.lxc role can be used to configure and manage LXC environment on a host. Specifically, LXC 1.0 support
will be installed on Ubuntu Trusty and Debian Jessie, for Debian Wheezy, LXC 1.0 package will be backported
from Jessie using debops.backporter role and Linux kernel from wheezy-backports will be installed for
required kernel features (this will require a reboot of the host).
You can use debops.lxc role to create and manage Linux Containers with different configurations. These containers
can be used on an external interface (DHCP server is recommended) or on an internal NAT interface (network will be
configured by a specific play in DebOps, using debops.dnsmasq and debops.nat roles).
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.lxc
Role dependencies
• debops.ferm
• debops.secret
• debops.backporter
Role variables
List of default variables available in the inventory:
70
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
--# ---- Install Linux kernel from Debian Backports on Wheezy ---# Name of Linux kernel package to install from Debian Backports on Debian
# Wheezy. If you use different architecture than amd64, you will need to change
# the package name
lxc_kernel_package: ’linux-image-amd64’
# Address of recipient of a mail message with information about updated
# kernel and reboot requirement
lxc_kernel_mail_to: [ ’[email protected]{{ ansible_domain }}’ ]
# ---- Configure LXC environment ---# Path where containers and their configuration is stored
lxc_root_path: ’/var/lib/lxc’
# Configuration of default network interface to use for "normal" containers
# (in DebOps, it’s configured by default in ’interfaces’ role)
# This is the external interface in two-interface setup
lxc_interface_external: ’br0’
# Configuration of default network interface to use for "normal" containers
# (in DebOps, it’s configured by default in ’interfaces’ role)
# This is the internal interface in two-interface setup
lxc_interface_internal: ’br1’
# Configuration of default network interface to use for "NATted" containers
# (in DebOps, it’s configured in LXC playbook by ’nat’ role)
lxc_interface_nat: ’br2’
# Which configuration from list below will be included in
# /etc/lxc/default.conf?
lxc_configuration_default: ’external’
# List of configuration files and their contents in /etc/lxc/ directory.
# Files will be named in the form: /etc/lxc/<key>.conf
# If you are modifying ths map, make sure that ’lxc’ key is present!
lxc_configuration_map:
# Global LXC configuration
lxc: |
lxc.lxcpath = {{ lxc_root_path }}
# Original contents of /etc/lxc/default.conf
empty: |
lxc.network.type = empty
# Simple configuration for "normal" containers with one network interface.
# Default in DebOps
external: |
lxc.network.type = veth
lxc.network.link = {{ lxc_interface_external }}
lxc.network.flags = up
lxc.start.auto = 1
2.11. Ansible roles provided in DebOps
71
DebOps Documentation, Release master
# Configuration with two network interfaces, not tested at the moment
external_internal: |
lxc.network.type = veth
lxc.network.link = {{ lxc_interface_external }}
lxc.network.flags = up
lxc.network.type = veth
lxc.network.link = {{ lxc_interface_internal }}
lxc.network.flags = up
lxc.start.auto = 1
# Configuration for a container behind NAT
nat: |
lxc.network.type = veth
lxc.network.link = {{ lxc_interface_nat }}
lxc.network.flags = up
lxc.start.auto = 1
# ---- Configure custom templates ---# Length of generated root password
lxc_template_root_password_length: ’20’
# Definition of root password (by default it will be randomly generated and
# stored in secrets)
lxc_template_root_password: ’{{ lookup("password", secret + "/credentials/" + ansible_fqdn + "/lxc/co
# SSH public key to put in root account of new container
lxc_template_root_authorized_key: ’{{ lookup("pipe", "ssh-add -L") }}’
# Name of administrator account to create (by default, your username)
lxc_template_admin_account: ’{{ lookup("env","USER") }}’
# SSH public key to put in administrator account of new container
lxc_template_admin_authorized_key: ’{{ lookup("pipe", "ssh-add -L") }}’
# Address of Debian mirror to use in debootstrap
# Example usage with local apt-cacher-ng proxy: ’http://cache.{{ ansible_domain }}:3142/debian’
lxc_template_debootstrap_mirror: ’http://cdn.debian.net/debian’
# Automatically add ’security.debian.org’ repository and perform ’apt-get
# upgrade’ on container creation to get latest security updates. Container
# creation takes longer, but resulting system is more secure.
lxc_template_security_upgrade: True
# List of packages downloaded and installed by debootstrap
lxc_template_debootstrap_packages: [ ’ifupdown’, ’locales’, ’libui-dialog-perl’, ’dialog’,
’isc-dhcp-client’, ’netbase’, ’net-tools’, ’iproute’,
’openssh-server’, ’sudo’, ’lsb-release’, ’python’,
’python-apt’, ’python-pycurl’, ’make’, ’git’,
’ncurses-term’, ’iputils-ping’, ’debian-archive-keyring’,
’apt-transport-https’, ’vim-tiny’, ’cron’, ’curl’,
’openssl’, ’ca-certificates’ ]
# ---- Manage LXC containers ---# Default template used by lxc-create, from /usr/share/lxc/templates/
72
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
lxc_default_template: ’debops’
#
#
#
#
LXC containers managed by Ansible are defined in a list below. Each entry is
a hash with keys as container parameters. Container configuration parameters
are interpreted only on initial container creation and are not updated
automatically afterwards.
# List of required parameters:
#
- name: ’’
container name, will be used as subdomain
#
in dnsmasq NAT configuration.
# List of optional parameters:
#
- state: ’’
defines what state should that container be in on
#
next Ansible run. Recognized states:
#
- started
(container should be running)
#
- stopped
(container should be stopped)
#
- absent
(container will be destroyed)
#
Without this parameter container will be created,
#
but not started automatically.
#
- config: True or ’’
enables usage of custom configuration instead of
#
default from /etc/lxc/default.conf
#
If True, container will be created with configuration
#
generated by Ansible from /tmp/lxc_temp_*.conf
#
Otherwise specify absolute path to a configuration
#
file to use (for example ’/etc/lxc/nat.conf’).
#
- template: ’’
template from /usr/share/lxc/templates/ to use for
#
this container, instead of the default.
#
- template_options: ’’
string of freeform options added at the end of
#
lxc-create command, after "--".
#
- storage: ’’
string of freeform storage options added to lxc-create
#
command after -B (for example: ’lvm --fssize 10G’)
#
See ’man lxc-create’ for available options.
#
- network: ’’
if ’config’ option is not set, ’network’ value becomes
#
a "shortcut" to select specific config file from /etc/lxc/*
#
(for example, you can specify ’network: "nat"’ and host
#
will be configured with config file from /etc/lxc/nat.conf).
# List of parameters recognized with ’config: True’ (generated configuration):
#
- network: ’’
currently you can specify ’external’ or ’nat’
#
to connect default network interface of a container
#
to specified network interface of a host.
#
- hwaddr: ’’
if ’network’ option is set, you can specify Ethernet
#
address of container network interface.
#
- auto: True/False
by default containers are configured to start
#
automatically at boot; using this option you can
#
disable autostart of a container.
#
- options: |
text block, will be added at the end of the configuration
#
file.
# List of LXC containers managed by Ansible.
lxc_containers: []
# Simple container, not started by default, autostart on boot enabled
#- name: ’example-container’
# Simple container started automatically
#- name: ’container’
# state: ’started’
2.11. Ansible roles provided in DebOps
73
DebOps Documentation, Release master
# Debian container, started automatically, network behind NAT
#- name: ’natted-container’
# config: True
# network: ’nat’
# state: ’started’
# template: ’debian’
Authors and license
debops.lxc role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.28 debops.mailman
Install and configure Mailman, a mailing list manager. It will be installed behind Postfix server (using
debops.postfix role) which will serve as an incoming/outgoing mail server, and nginx server (with help of
debops.nginx role) will serve the web interface. You can also use this role to create or remove mailing lists
themselves (other management can be done using the web interface).
Table of Contents
•
•
•
•
•
Installation
Role dependencies
Role variables
Detailed usage guide
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.mailman
Role dependencies
• debops.secret
• debops.postfix
• debops.nginx
Role variables
List of default variables available in the inventory:
74
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
--# ---- General options ---# Should mailman role manage it’s own dependencies?
mailman_dependencies: True
# ---- Language and localization ---# Responses for Debconf questions, need to be the same format as in Debconf.
# To see available responses, run ’dpkg-reconfigure mailman’
mailman_debconf_languages: [ ’en (English)’ ]
mailman_debconf_default_language: ’en (English)’
# Default language used on this Mailman host
mailman_default_language: ’en’
# List of languages (as two-letter names spearated by spaces) to convert to
# UTF-8 charset using ’convert-mailman-to-utf8’ script. If you have primarily
# English site, you don’t need to mess with that. :-)
mailman_convert_languages: []
# --- Site configuration ---# List of "virtual domains" recognized by Mailman. The first domain on the list
# will be a default domain. If this list is empty, Mailman will use ansible_fqdn
# as it’s default domain (requires ’local’ capability in postfix).
mailman_domains: [ ’lists.{{ ansible_domain }}’ ]
# Site administrator e-mail address
mailman_site_admin: ’[email protected]{{ ansible_domain }}’
# Postmaster address, required by ’postfix-to-mailman.py’ script
mailman_site_postmaster: ’[email protected]{{ ansible_domain }}’
# Maximum message size enforced by Mailman by default, in kilobytes. Can be
# changed for each list independently in the web interface
mailman_max_message_size: ’100’
# Maximum number of recipients in each SMTP session
mailman_smtp_max_recipients: ’500’
# Default mailing list, usually ’mailman’
mailman_site_list: ’mailman’
# ---- Web interface and archives ---# List of hosts or CIDR networks to allow access to Mailman web interface. If
# the list is empty, allow access from all hosts/networks
mailman_allow: []
# Should Mailman offer .mbox file in public list archives?
mailman_public_mbox: True
2.11. Ansible roles provided in DebOps
75
DebOps Documentation, Release master
# ---- Passwords ---# Length of generated passwords for site administrator and list creator access
mailman_site_password_length: ’40’
# Length of generated passwords for mailing list owner/admin access
mailman_admin_password_length: ’30’
# Length of generated passwords for list members
mailman_member_password_length: ’20’
# Should Mailman generate user-friendly passwords?
mailman_user_friendly_passwords: ’No’
# ---- Spam and backscatter prevention ---# Should auto-discarded messages from non-members be automatically sent to list
# moderators/admins? Setting this to No will reduce spammy messages to moderators
mailman_default_forward_auto_discards: ’No’
# How much of the original message should be included in auto-responses?
mailman_response_include_level: ’0’
# What should be done with mail messages from non-members by default? 3 = Discard
mailman_default_generic_nonmember_action: ’3’
# List of domains allowed as referers
mailman_referers: ’{{ (mailman_domains + [ ansible_fqdn, "*." + ansible_domain ]) }}’
# ---- Other options ---# Additional Mailman options in a text block format
# You can find more options in /usr/lib/mailman/Mailman/Defaults.py
mailman_options: False
# List of mailing lists to create or remove
mailman_lists: []
##
#
#
#
#
name: ’mailing-list’
domain: ’example.com’
owner: ’[email protected]{{ ansible_domain }}’
state: ’present,absent’
language: ’en’
purge: False,True
# mailing list name, required
# specify different domain than the main one
# list owner email address
# default list language
# remove list archives when deleting?
# ---- Mailman patches ---# List of patches applied to Mailman source code after installation
# Patch status is saved in /etc/ansible/facts.d/mailman.fact on remote host
# Set to False to disable patch application
mailman_patches:
# Add direct link to moderation page
# https://github.com/okfn/infra/commit/06b83759238e38d1b239ee1e04d75ae3e46365ae
- ’add-moderator-link.patch’
76
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# Remove automatic capitalization of list names
# https://mail.python.org/pipermail/mailman-users/2002-January/016732.html
- ’remove-upper-list-name.patch’
# Ignore commands from non-members (reduces backscatter, but blocks mail registration)
# https://mail.python.org/pipermail/mailman-users/2013-June/075270.html
- ’ignore-commands-from-nonmembers.patch’
# Remove extra aliases that are not needed (reduces backscatter)
# https://mail.python.org/pipermail/mailman-users/2008-March/060870.html
- ’prune-alias-list.patch’
Detailed usage guide
Mailman is a bit tricky to manage idempotently - there are many patches applied during first install, mailing lists
are hard to change once they are created and there might be issues with upgrading of configuration files (because of
that mailman is not upgraded automatically by default). I suggest that you prepare your Mailman configuration in
development environment, and apply it in production when it’s ready.
Postfix will configure Mailman integration differently depending on it’s enabled capabilities:
• with local capability Postfix will pass mail messages to Mailman using mail aliases and
virtual_alias_maps/virtual_alias_domains;
• without local capability Postfix will pass mail messages to Mailman using postfix-to-mailman.py
script, relay_recipient_maps, relay_recipient_domains and transport_maps;
Authors and license
debops.mailman role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.29 debops.monit
debops.monit role allows you to install and configure Monit service which can be used to monitor processes,
services or even other hosts. You can also use this role as a dependency of another role and configure monitoring
service for an application this way.
Alerts can be sent to an e-mail address (by default [email protected]<your-domain>, or to a mobile phone or pager
using an SMS gateway (for example one managed by debops.smstools role).
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
2.11. Ansible roles provided in DebOps
77
DebOps Documentation, Release master
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.monit
Role dependencies
• debops.etc_services
• debops.apt_preferences
Role variables
List of default variables available in the inventory:
--# ---- Global configuration options ---# The number of seconds to determine if a process is down or not.
monit_interval: 60
# The number of seconds before starting to monitor a process which just launched.
# Set this to 0 to disable it.
monit_start_delay: 30
# Which facility should monit be syslogged to?
# An empty string defaults to : ’user’.
# Another possibility would be: ’facility log_daemon’.
monit_syslog: ’’
# ---- E-mail alerts ---# Where should the alerts get sent to?
# ’only_on’ allows you to optionally send alerts only when certain events occurred:
# Use a comma separated list to provide more than 1 event.
# When undefined or blank it will send an alert on all events.
# https://mmonit.com/monit/documentation/#setting_an_event_filter
# You can disable alerting completely by providing an empty list.
monit_mail_alert_to:
- { email: ’[email protected]{{ ansible_domain }}’, only_on: ’’ }
# Supply a list of mail servers, the first item in the list will be tried first.
monit_mail_servers:
# Only the host is required.
- host: ’localhost’
# The port defaults to 25.
#port: 25
# The username, password and encryption default to undefined.
#username:
#password:
78
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# The available encryption types are:
# SSLAUTO, SSLV2, SSLV3, TLSV1, TLSV11, TLSV12
#encryption:
# Who sent it and how should the message be formatted?
monit_mail_from: ’[email protected]{{ ansible_fqdn }}’
monit_mail_reply_to: ’[email protected]{{ ansible_fqdn }}’
monit_mail_subject: ’[Monit] $EVENT $SERVICE’
monit_mail_message: |
$EVENT Service $SERVICE
Date:
$DATE
Action:
$ACTION
Host:
$HOST
Description: $DESCRIPTION
Your faithful employee,
Monit
# Instead of a big e-mail message you can use a smaller sms-friendly message.
# Just uncomment it to enable this message styling instead.
#monit_mail_message_sms: ’$ACTION $SERVICE on $HOST: $DESCRIPTION, $DATE’
# ---- Process monitoring ---# Which processes do you want to monitor?
monit_process_list: []
# The same as process list except scoped to a specific host or group.
monit_process_group_list: []
monit_process_host_list: []
monit_process_dependent_list: []
# Example:
#monit_process_list:
# The pid path is relative to /var/run, this is required.
#- pid: ’’
# The process is simply the process name, defaults to the pid’s basename.
#process: ’foo’
# Set a timeout, defaults to 60 seconds.
#timeout: 60
# The sysvinit style to start/stop a process, you can change this per process.
#start: ’/etc/init.d/process start’
#stop: ’/etc/init.d/process stop’
# Append custom script logic, defaults to nothing.
#script: |
# Stop monitoring the process by deleting the config.
#delete: False
# ---- M/Monit and HTTP ---monit_mmonit_url: ’’
# Example:
2.11. Ansible roles provided in DebOps
79
DebOps Documentation, Release master
#monit_mmonit_url: http://user:[email protected]:8080/collector
monit_http_allow: []
# Example:
#monit_http_allow:
#- user:password
#- example.com
Authors and license
debops.monit role was written by:
• Nick Janetakis | e-mail | Twitter | GitHub
License: GPLv3
2.11.30 debops.monkeysphere
This role can be used to give SSH users the ability to login to the server using their PGP/GnuPG keys. This functionality is enabled using Monkeysphere project.
At the moment role is not fully complete. Required user configuration functionality is in the works.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.monkeysphere
Role variables
List of default variables available in the inventory:
--# Should monkeysphere be enabled? Disabled by default due to required manual
# preparations, see: http://web.monkeysphere.info/getting-started-admin/
monkeysphere: False
# Should monkeysphere automatically publish new keys to Web of Trust?
monkeysphere_autopublish: False
# List of identity certifiers to add automatically at first setup (omit 0x)
monkeysphere_default_identity_certifiers: False
# At what minute each hour monkeysphere should update the user authorized_keys?
monkeysphere_update_minute: ’42’
80
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# Keyserver to use (default frontend from ’sks’ role). You might want to setup
# an internal-only frontend or backend to mitigate availability problems
monkeysphere_keyserver: ’keyserver.{{ ansible_domain }}’
# Default keyserver from monkeysphere configuration, public GPG Web of Trust
#monkeysphere_keyserver: ’pool.sks-keyservers.net’
# Should monkeysphere check the keyserver on each connection?
monkeysphere_check_keyserver: ’false’
# Log verbosity (SILENT, ERROR, INFO, VERBOSE, DEBUG)
monkeysphere_log_level: ’INFO’
# System user that controls the monkeysphere GPG keyring
monkeysphere_user: ’monkeysphere’
# Look for user ids in system-wide directory
monkeysphere_authorized_user_ids: ’/etc/monkeysphere/authorized_user_ids/%u’
# Don’t combine user’s authorized_keys, sshd supports multiple files
monkeysphere_raw_authorized_keys: ’none’
Authors and license
debops.monkeysphere role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.31 debops.mysql
Install and manage a MySQL database. At the moment only database on localhost is supported.
You can use this role as a dependency of another role to easily create databases and users for a particular application
(database and user management is also available using Ansible inventory).
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.mysql
2.11. Ansible roles provided in DebOps
81
DebOps Documentation, Release master
Role dependencies
• debops.ferm
• debops.secret
• debops.tcpwrappers
Role variables
List of default variables available in the inventory:
--# ---- MySQL server configuration ---# Bind address of mysqld. If you want to allow access to the server over the
# network, change this to ’0.0.0.0’ (for all interfaces) or for specific IP
# address to bind on
mysql_mysqld_bind_address: ’localhost’
# Default mysqld port to listen on
mysql_mysqld_port: 3306
# This is a list of IP addresses or CIDR networks allowed to connect to MySQL
# server from remote hosts. It will be applied in firewall (ferm) and
# /etc/hosts.allow (tcpwrappers).
# You will need to set mysql_mysqld_bind_address to 0.0.0.0 and restart MySQL
# server for it to listen on all network interfaces.
mysql_mysqld_allow: []
# Maximum number of allowed connections
mysql_mysqld_max_connections: 100
# Use this hash variable to set additional mysqld options
mysql_mysqld_options: {}
# ’key_buffer’: ’16M’
# ’skip-name-resolve’:
# ---- PHPMyAdmin support ---# Enable PHPMyAdmin? It will be installed on localhost with php5-fpm and nginx
# See ’phpmyadmin’ role for more configuration options
mysql_phpmyadmin: False
# ---- automysqlbackup configuration ---# Mail address to send messages to (account or alias name will be properly
# routed by the Postfix SMTP server)
mysql_backup_mailaddr: ’backup’
# Specify the day of the week to create weekly backups (1 - Monday, 7 - Sunday)
mysql_backup_doweekly: ’6’
# Don’t keep copies of most recent backups by default
mysql_backup_latest: ’no’
82
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# ---- MySQL databases and user accounts ---# List of MySQL databases to manage
mysql_databases: []
#- name: ’database_name’
# state: ’present,absent’
# optional
# Length of randomly generated passwords (it’s a string)
mysql_password_length: ’20’
# Password for MySQL root user
mysql_root_password: "{{ lookup(’password’, secret + ’/credentials/’ + ansible_fqdn + ’/mysql/root/pa
# List of MySQL users to manage (defaults first)
mysql_users: []
#- name: ’user_name’
# required
# host: ’localhost’
# state: ’present,absent’
# password: ’’
# if not specified, random will be generated
#
# and saved in the ’secret’ storage
# priv: ’user_name.*:ALL’
# append_privs: ’no,yes’
Authors and license
debops.mysql role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.32 debops.nat
debops.nat is a helper role which configures internal network on a separate bridge interface with NAT or MASQUERADE firewall configuration (network will use non-routable IP address space and access to the Internet will be
provided by the host operating system). This network can be used as a development environment for virtual machines
or containers.
Configuration of iptables firewall / forwarding and network interfaces will be performed by debops.ferm and
debops.ifupdown Ansible roles.
You can use dnsmasq server (available via debops.dnsmasq Ansible role) to complete the network configuration
and provide internal DNS/DHCP server.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
2.11. Ansible roles provided in DebOps
83
DebOps Documentation, Release master
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.nat
Role dependencies
• debops.ferm
• debops.ifupdown
Role variables
List of default variables available in the inventory:
--# 192.168.x.0/24 subnet to use by default for NAT
nat_subnet: 32
# Network interface to use for NAT bridge
nat_interface: ’br2’
# Network configuration
nat_address: ’192.168.{{ nat_subnet }}.1’
nat_netmask: ’255.255.255.0’
nat_network: ’192.168.{{ nat_subnet }}.0’
nat_broadcast: ’192.168.{{ nat_subnet }}.255’
# Should iptables use masquerading?
# True - static IP route to outside network
# False - dynamic masquerading
nat_masquerade: False
# Default NAT domain
nat_subdomain: ’nat’
nat_domain: ’{{ nat_subdomain }}.{{ ansible_fqdn }}’
Authors and license
debops.nat role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.33 debops.nfs
This role can be used to configure NFSv3 client and server services between many hosts in a group.
This role is an obsolete state and will be replaced in the future. Do not use this role in a production environment.
84
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.nfs
Role dependencies
• debops.ferm
• debops.etc_services
Role variables
List of default variables available in the inventory:
--# Enable to configure host as NFS server
nfs_server: False
# Define on NFS clients which server to use
#nfs_host: ’nfs.{{ ansible_domain }}’
# List of simple NFS shares, they will be created automatically
# on NFS server: /srv/nfs/{{ item }}/
# on NFS client: /media/nfs/{{ item }}/
#nfs_simple:
# - ’home’
# - ’usr’
# Options for simple NFS shares
nfs_simple_exports: ’/srv/nfs’
nfs_simple_mounts: ’/media/nfs’
nfs_simple_hostname: ’192.168.0.0/16’
nfs_simple_options: ’rw,sync,subtree_check,root_squash’
# Allow these networks and hosts to connect to NFS server
nfs_server_allow:
- ’10.0.0.0/8’
- ’172.16.0.0/12’
- ’192.168.0.0/16’
# List of custom NFS exports
#nfs_server_exports:
# - ’/home 192.168.0.0/16(rw,sync,subtree_check,root_squash)’
# - ’/usr
192.168.0.0/16(rw,sync,subtree_check,root_squash)’
2.11. Ansible roles provided in DebOps
85
DebOps Documentation, Release master
Authors and license
debops.nfs role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.34 debops.nginx
nginx is a fast and light webserver with extensible configuration.
debops.nginx role can be used to install and manage nginx configuration for multiple websites at the same time.
Server is configured using inventory variables, role can also be used as a dependency of another role to configure a
webserver for that role using dependency variables.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.nginx
Role dependencies
• debops.ferm
• debops.apt_preferences
Role variables
List of default variables available in the inventory:
--# List of IP addresses or CIDR networks allowed to connect to HTTP or HTTPS
# service. It will be configured in iptables firewall via ’ferm’ role. If there
# are no entries, nginx will accept connections from any IP address or network.
# If you have multiple web services on a host, you might want to control access
# using ’item.location_allow’ option instead.
nginx_allow: []
nginx_group_allow: []
nginx_host_allow: []
nginx_base_packages: [ ’nginx-full’ ]
nginx_user: ’www-data’
# Nicenness, from 20 (nice) to -20 (not nice)
86
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
nginx_worker_priority: ’0’
nginx_worker_processes: ’{{ ansible_processor_cores }}’
nginx_worker_connections: 1024
# Maximum number of opened files per process, must be higher than worker_connections
nginx_worker_rlimit_nofile: 4096
nginx_server_tokens: ’off’
nginx_server_names_hash_bucket_size: 64
nginx_server_names_hash_max_size: 512
nginx_default_keepalive_timeout: 60
# Path to PKI infrastructure, set to False to disable nginx SSL support
nginx_pki: ’/srv/pki’
# SSL key hostname to look for to check if SSL should be enabled
nginx_pki_check_key: ’{{ ansible_fqdn }}’
# Where to look for certificate by default, choices: ’selfsigned’, ’signed’, ’wildcard’
# Server-wide.
nginx_default_ssl_type: ’selfsigned’
# Default hostname used to select SSL certificate if none is defined
nginx_default_ssl_cert: ’{{ ansible_fqdn }}’
# Default SSL cipher list. More information in vars/main.yml
nginx_default_ssl_ciphers: ’pfs’
# Default SSL ECDH curve used on servers, to see a list of supported curves, run:
#
openssl ecparam -list_curves
# See also: https://security.stackexchange.com/questions/31772/
nginx_default_ssl_curve: ’secp384r1’
# If wildcard SSL certificate is used, which one should be used by default?
nginx_default_ssl_wildcard: ’{{ ansible_domain }}’
# List od DNS servers used to resolve OCSP stapling. If it’s empty, nginx role
# will try to use nameservers from /etc/resolv.conf
# Currently only the first nameserver is used
nginx_ocsp_resolvers: []
# At what hour run DH params regeneration script?
nginx_cron_dhparams_hour: ’1’
# HTTP Strict-Transport-Security
# https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security
nginx_hsts_age: ’15768000’
nginx_hsts_subdomains: True
# server_name which will be marked as default
nginx_default_name: ’{{ ansible_fqdn }}’
# Default server template used if no type is selected
nginx_default_type: ’default’
2.11. Ansible roles provided in DebOps
87
DebOps Documentation, Release master
# Default server root
nginx_default_root: ’/srv/www/sites/default/public’
# Create global webroot directories?
# Path: /srv/www/sites/*/public
nginx_webroot_create: True
nginx_webroot_owner: ’root’
nginx_webroot_group: ’root’
nginx_webroot_mode: ’0755’
# Should nginx servers have status pages enabled by default
# If yes, provide a list of allowed networks/hosts
#nginx_default_status:
# - ’127.0.0.0/8’
# Hash of symlinks to local server definitions stored in /etc/nginx/sites-local/
# Entries with empty values or False will be removed
# Symlinks will be created in /etc/nginx/sites-enabled/
nginx_local_servers: {}
#’symlink’: ’file’
#’other-symlink.conf’: ’sub/directory/file.conf’
#’removed-file’: False
#’also-removed’:
#’symlink\ with\ spaces.conf’: ’other-file.conf’
# List of nginx map definitions
# Each map should be defined in it’s own hash variable, similar to upstreams
# and servers
# http://nginx.org/en/docs/http/ngx_http_map_module.html
nginx_maps: []
# List of nginx upstream definitions
nginx_upstreams: [ ’{{ nginx_upstream_php5 }}’ ]
# Upstream for default php5-fpm configuration
nginx_upstream_php5:
enabled: True
name: ’php5_www-data’
type: ’php5’
php5: ’www-data’
# List of nginx server definitions
nginx_servers: [ ’{{ nginx_server_default }}’ ]
# Default nginx site
# List and description of available parameters can be found in nginx server
# templates: templates/etc/nginx/sites-available/*.conf.j2
nginx_server_default:
enabled: True
name: []
default: True
List of internal variables used by the role:
nginx_register_default_server_specified
nginx_register_default_server_name
nginx_ssl
nginx_ocsp_resolvers
nginx_register_default_server_first
88
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Authors and license
debops.nginx role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.35 debops.nodejs
This role can be used as a dependency for other roles to provide NodeJS and npm support.
At the moment, on Debian Wheezy a nodejs package from wheezy-backports is installed, and npm command
is installed from upstream using a script; this will be changed in the future to install npm package as a backported
Debian Jessie version.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.nodejs
Role variables
List of default variables available in the inventory:
--# List of packags to install
nodejs_packages: [ ’nodejs’, ’nodejs-legacy’ ]
Authors and license
debops.nodejs role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11. Ansible roles provided in DebOps
89
DebOps Documentation, Release master
2.11.36 debops.ntp
debops.ntp role can be used to install OpenNTPD time server which will be used both to synchronize time on a
host and serve accurate time information for other hosts (if enabled). This role can also manage timezone settings
using tzdata Debian package.
Time server will not be installed in an LXC or OpenVZ container, because time synchronization in this case is provided
by the host operating system.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.ntp
Role dependencies
• debops.ferm
Role variables
List of default variables available in the inventory:
--# Which clock management daemon should be installed? Currently only ’openntpd’
# is supported. Set to False to disable clock management
ntp: ’openntpd’
# Timezone configuration
# This is a two element list:
#
- first element is the "Area" (Europe, Asia, America, Etc, ...)
#
- second element is the "Zone" (Warsaw, Tokyo, Chicago, UTC, ...)
# Run ’dpkg-reconfigure tzdata’ to see list of possible values
# If this variable is empty or False, timezone won’t be changed
ntp_timezone: []
# List of interfaces ntpd should listen on. Specify ’*’ to listen on all
# interfaces. If this list is not empty, ntp port will be opened in firewall
ntp_listen: []
# List of hosts/networks in CIDR format to allow access to ntp port in
# firewall. If this list is empty, access will be allowed from anywhere. You
# should probably define a list of networks allowed access to mitigate NTP
# amplification attacks
ntp_allow: []
90
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# List of NTP servers to synchronize with
ntp_servers: [ ’0.debian.pool.ntp.org’,
’1.debian.pool.ntp.org’,
’2.debian.pool.ntp.org’,
’3.debian.pool.ntp.org’ ]
Authors and license
debops.ntp role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.37 debops.openvz
debops.openvz role enables OpenVZ container support on Debian Wheezy hosts. This role has not been tested on
Debian Jessie or Ubuntu systems, and correct support for OpenVZ on these systems is at the moment unlikely. Main
reason for this role is to help ease transition from older systems based on Debian Squeeze with OpenVZ into newer
systems based on Debian Wheezy/Jessie and LXC.
Table of Contents
•
•
•
•
•
Installation
Role dependencies
Role variables
Detailed usage guide
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.openvz
Role dependencies
• debops.ferm
Role variables
List of default variables available in the inventory:
--# ---- OpenVZ Cluster - global options ---#
#
#
#
List of hosts in OpenVZ "cluster". These hosts will exchange SSH public keys
from their root accounts between them and record their SSH fingerprints for
easier container migration using vzmigrate.
By default it’s all hosts in ’debops_openvz’ group. You can change that by
2.11. Ansible roles provided in DebOps
91
DebOps Documentation, Release master
# defining a list of hosts using their inventory_hostname variable
openvz_cluster: ’{{ groups.debops_openvz }}’
# Where OpenVZ containers are being stored? This preferably should be
# a separate partition
openvz_container_storage: ’/var/lib/vz’
# Default filesystem layout for new OpenVZ containers (simfs, ploop)
openvz_storage_layout: ’ploop’
# ---- Configuration file for new OpenVZ containers ---# Default configuration file for new OpenVZ containers
openvz_configfile: ’vswap-debops’
# How many containers do you plan to setup on an OpenVZ HN?
openvz_configfile_container_count: ’5’
# Disk space soft limit multiplier
openvz_configfile_diskspace_limit_multiplier: ’0.7’
# Disk inodes soft limit multiplier
openvz_configfile_diskinodes_limit_multiplier: ’0.9’
# VSwap multiplier
openvz_configfile_vswap_multiplier: ’0.2’
# How much RAM to reserve for the operating system?
openvz_configfile_memory_padding: ’256’
# Quota time limit in seconds
openvz_configfile_quotatime: ’0’
# Default cpuunits for new container
openvz_configfile_cpuunits: ’1000’
# Default netfilter state for new containers
# Choices: disabled, stateless, stateful, full
openvz_configfile_netfilter: ’stateful’
# ---- OpenVZ container template ---# Default container template
openvz_template: ’debian-7.0-x86_64-minimal’
# Should OpenVZ automatically update template images?
openvz_template_update: ’yes’
# Should OpenVZ check gnupg signature of a template image?
openvz_template_signature: ’yes’
# Where to look for online for OpenVZ templates
openvz_template_prefix: ’http://download.openvz.org/template/precreated’
# List of directories with "repositories" of templates on template server
openvz_template_repos:
92
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
- ’{{ openvz_template_prefix }}’
- ’{{ openvz_template_prefix }}/contrib’
# Name of default admin account created by the bootstrap script
openvz_template_admin_username: ’{{ ansible_ssh_user | default(lookup("env","USER")) }}’
# Default SSH keys added on the admin account by the bootstrap script
openvz_template_admin_sshkey: ’{{ lookup("pipe","ssh-add -L") }}’
# ---- OpenVZ kernel ---# Name of a kernel package (or metapackage) installed by openvz role
openvz_kernel: ’linux-image-openvz-amd64’
# Default GRUB menu entry to boot (counting from 0). When OpenVZ-enabled kernel
# is installed, it will be placed just after the official Debian kernel. Recovery
# option in GRUB should be disabled, which is the default when you use DebOps
# Debian Preseed setup
openvz_grub_default: ’1’
# Where to send mail reminders and alerts from openvz role
openvz_mail_to: [ ’[email protected]{{ ansible_domain }}’ ]
# List of IPv4 iptables kernel modules to be enabled in containers by default
openvz_iptables: [ ’ipt_REJECT’, ’ipt_tos’, ’ipt_TOS’, ’ipt_LOG’, ’ip_conntrack’,
’ipt_limit’, ’ipt_multiport’, ’iptable_filter’, ’iptable_mangle’,
’ipt_TCPMSS’, ’ipt_tcpmss’, ’ipt_ttl’, ’ipt_length’, ’ipt_state’,
’iptable_nat’, ’ip_nat_ftp’ ]
List of internal variables used by the role:
openvz_configfile_calculated_diskspace
openvz_configfile_calculated_total_memory
openvz_configfile_calculated_diskinodes_limit
openvz_configfile_calculated_diskinodes
openvz_configfile_calculated_ram
openvz_configfile_calculated_diskspace_limit
openvz_root_ssh_key
openvz_configfile_calculated_vswap
Detailed usage guide
This role is meant to create and manage OpenVZ Hardware Nodes, not OpenVZ containers themselves.
debops.openvz role uses Linux kernel from openvz.org (2.6.32), which is older than the default kernel in Wheezy
(3.2.0). Because of that various technologies from Wheezy (KVM, LXC for example) might be incompatible with
older kernel. Thus, this role should not be mixed on one host with those technologies.
Because of the kernel downgrade, a reboot of the host will be required, but debops.openvz will not reboot managed
hosts automatically. Instead, an email will be sent to root account in case a kernel downgrade or update is performed,
to notify the administrator about required reboot. This lets the administrator schedule reboots at their convenience.
Make sure that your Hardware Nodes have correct mail setup to forward mails to administrators, for example with
debops.postfix role.
You can specify a group of hosts (by default role looks for [debops_openvz] group), in which case they will be
treated as a cluster of OpenVZ Hardware Nodes. Each HN will create an SSH keypair on its root account, and these
keys will be automatically distributed among nodes in the cluster, and the host SSH fingerprints will be registered on
2.11. Ansible roles provided in DebOps
93
DebOps Documentation, Release master
each node ~/.ssh/known_hosts file. This allows you to easily migrate containers between Hardware Nodes with
vzmigrate command.
Authors and license
debops.openvz role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.38 debops.owncloud
This role installs ownCloud instance on a specified host, with either MySQL or PostgreSQL database as a backend
and an nginx webserver as a frontend.
At the moment role doesn’t work correctly due to the changes in ownCloud repository structure.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.owncloud
Role dependencies
• debops.secret
• debops.nginx
• debops.postgresql
• debops.php5
• debops.mysql
Role variables
List of default variables available in the inventory:
--# --- Basic options --# Should ownCloud role manage it’s own dependencies (nginx, php5, postgresql, mysql)?
# If you want to setup them differently, you should change this to False
owncloud_dependencies: True
94
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# Domain that will be configured for ownCloud instance
owncloud_domain: [ ’owncloud.{{ ansible_domain }}’ ]
# --- ownCloud source and deployment --# User and group that will be used for ownCloud instance
owncloud_user: ’owncloud’
owncloud_group: ’owncloud’
owncloud_home: ’/srv/users/{{ owncloud_user }}’
# Path where ownCloud data/ directory and files are stored
owncloud_data_path: ’/srv/lib/{{ owncloud_user }}/{{ owncloud_domain[0] }}/data’
# Where ownCloud instance will be deployed (web root)
owncloud_deploy_path: ’/srv/www/{{ owncloud_user }}/sites/{{ owncloud_domain[0] }}/public’
# What source should be used to get ownCloud files (upstream, githost, github, gitlab)
owncloud_source: ’upstream’
# Default URL and git branch for ownCloud upstream repository
owncloud_upstream_url: ’https://github.com/owncloud/core.git’
owncloud_upstream_branch: ’stable6’
# Default settings for ownCloud sources other than "upstream"
# If you want to use that with github, you can create your ownCloud repository
# as ’<your username>/owncloud’ with branch ’master’
owncloud_deploy_user: ’git’
owncloud_deploy_server: ’github.com’
owncloud_deploy_repo: ’{{ lookup("env","USER") }}/owncloud.git’
owncloud_deploy_branch: ’master’
# OAuth token for GitHub / GitLab access, used to setup SSH deploy key
owncloud_deploy_token: False
# Hash of different ownCloud sources
owncloud_source_map:
# Official ownCloud upstream repository on GitHub (basic installation)
upstream:
url:
’{{ owncloud_upstream_url }}’
branch: ’{{ owncloud_upstream_branch }}’
# A git repository configured on a host in the Ansible cluster, for example
# with ’githost’ role
# Ansible will try and setup ssh public key of the ’owncloud’ user as deploy
# key on the server with git repository, using authorized_key module
githost:
url:
’{{ owncloud_deploy_user }}@{{ owncloud_deploy_server }}:{{ owncloud_deploy_repo }}’
branch: ’{{ owncloud_deploy_branch }}’
# A git repository set up on GitHub, with deploy key configured through API
# using OAuth token
github:
url:
’[email protected]:{{ owncloud_deploy_repo }}’
branch: ’{{ owncloud_deploy_branch }}’
# A git repository set up on a GitLab instance, with deploy key configured
2.11. Ansible roles provided in DebOps
95
DebOps Documentation, Release master
# through API using OAuth token
gitlab:
url:
’{{ owncloud_deploy_user }}@{{ owncloud_deploy_server }}:{{ owncloud_deploy_repo }}’
branch: ’{{ owncloud_deploy_branch }}’
# --- ownCloud database --# ownCloud recommends MySQL database as the default. Set to False to use SQLite
owncloud_database: ’mysql’
owncloud_database_map:
# MySQL database on localhost (random password will be generated when using ’secret’ role)
mysql:
dbtype: ’mysql’
dbname: ’{{ owncloud_user }}’
dbuser: ’{{ owncloud_user }}’
dbpass: ’{{ owncloud_dbpass | default("password") }}’
dbhost: ’localhost’
dbtableprefix: ’’
# PostgreSQL database on localhost, connection through Unix socket, no default password
postgresql:
dbtype: ’pgsql’
dbname: ’{{ owncloud_user }}’
dbuser: ’{{ owncloud_user }}’
dbpass: ’’
dbhost: ’/var/run/postgresql’
dbtableprefix: ’’
# --- ownCloud admin login / password --# Default admin username, in the form ’admin-$USER’
# Set to False to disable automatic username and password
owncloud_admin_username: ’admin-{{ lookup("env","USER") }}’
# Default admin password, will be randomly generated if ’secret’ role is enabled
owncloud_admin_password: ’password’
# Length of randomly generated admin password
owncloud_password_length: ’20’
# Should Ansible automatically open ownCloud page to finish setup on it’s own?
# Disabled if admin username is set to False
owncloud_autosetup: True
# --- ownCloud configuration --# Max upload size set in nginx and php5, with amount as M or G
owncloud_upload_size: ’128M’
# Output buffering set in php5, with amount set in megabytes
owncloud_php5_output_buffering: ’128’
# Max children processes to run in php5-fpm
96
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
owncloud_php5_max_children: ’50’
# At what time cron should execute background jobs
owncloud_cron_minute: ’*/15’
List of internal variables used by the role:
owncloud_database_password
owncloud_admin_password
owncloud_deploy_data
Authors and license
debops.owncloud role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.39 debops.php5
This role can be used as a dependency of other roles to easily enable support for PHP5 on a host. php5-fpm package
will be used as a backend for PHP5 applications. This role works very well with debops.nginx role for setting up
nginx webserver as a frontend.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.php5
Role variables
List of default variables available in the inventory:
--# Install set of standard packages
php5_packages: [ ’php5-curl’, ’php5-gd’, ’php5-mcrypt’ ]
# This variable determines what options will be used in php.ini for options
# that can be useful either in production or development environment
php5_production: True
# Default values for several global PHP5 options
php5_post_max_size: ’8M’
php5_default_charset: ’UTF-8’
2.11. Ansible roles provided in DebOps
97
DebOps Documentation, Release master
php5_file_uploads: ’On’
php5_upload_max_filesize: ’{{ php5_post_max_size }}’
php5_max_file_uploads: 20
php5_allow_url_fopen: ’On’
# Default values used in pools when pool has none set
php5_default_pm: ’ondemand’
php5_default_pm_max_children: 5
php5_default_pm_min_spare_servers: 1
php5_default_pm_max_spare_servers: 3
php5_default_pm_start_servers: 2
php5_default_pm_process_idle_timeout: ’30s’
php5_default_pm_max_requests: 500
php5_default_pm_status: False
php5_default_pm_status_path: ’/php5_status’
php5_default_ping_path: ’/php5_ping’
php5_default_ping_response: ’pong’
php5_default_rlimit_files: 1024
php5_default_rlimit_core: 0
# Should php5 role manage server pools?
php5_manage_pools: True
# List of managed pools
php5_pools: [ ’{{ php5_pool_default }}’ ]
# Default PHP5-FPM pool for www-data, explanation of variables can be found
# in templates/etc/php5/fpm/pool-available.d/pool.conf.j2
# Everything commented out is optional.
php5_pool_default:
enabled: True
name: ’www-data’
#prefix: ’’
#user: ’www-data’
#group: ’www-data’
#listen: ’/var/run/php5-fpm-www-data.sock’
# pm: static, dynamic, ondemand
#pm: ’ondemand’
# Settings for all management types
#pm_max_children: 5
# Settings for ’dynamic’ process management
#pm_min_spare_servers: 1
#pm_max_spare_servers: 3
#pm_start_servers: 2
# Settings for ’ondemand’ process management
#pm_process_idle_timeout: ’30s’
#pm_max_requests: 500
#pm_status: True
#pm_status_path: ’{{ php5_default_pm_status_path }}’
98
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
#ping_path: ’{{ php5_default_ping_path }}’
#ping_response: ’{{ php5_default_ping_response }}’
#accesslog: True
#request_slowlog_timeout: ’30s’
#request_terminate_timeout: ’5m’
#rlimit_files: 1024
#rlimit_core: 0
#chroot: ’’
#chdir: ’/’
#catch_workers_output: False
#security_limit_extensions: ’.php’
#environment:
# HOSTNAME: ’$HOSTNAME’
# PATH: ’/usr/local/bin:/usr/bin:/bin’
# TMP: ’/tmp’
# TMPDIR: ’/tmp’
# TEMP: ’/tmp’
#php_flag:
# display_errors: ’off’
#php_value:
# default_mimetype: ’text/html’
#php_admin_flag:
# log_errors: ’on’
#php_admin_value:
# memory_limit: ’32M’
#open_basedir: ’/usr/share/php5:/tmp’
Authors and license
debops.php5 role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.40 debops.phpipam
This role installs phpIPAM, an IP Address Manager written in PHP5. MySQL will be used as the backend database,
and nginx will be a frontend webserver.
Currently phpIPAM is deployed from DebOps repository on Github, that might be changed in the future.
Default credentials: Admin:ipamadmin
2.11. Ansible roles provided in DebOps
99
DebOps Documentation, Release master
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.phpipam
Role dependencies
• debops.secret
• debops.nginx
• debops.php5
• debops.mysql
Role variables
List of default variables available in the inventory:
--# Should phpipam role manage it’s own dependencies?
phpipam_dependencies: True
# Domain on which phpIPAM is configured in nginx
phpipam_domain: [ ’ipam.{{ ansible_domain }}’ ]
# phpIPAM source repository and version to deploy
phpipam_source_address: ’https://github.com/ginas/’
phpipam_source_repository: ’phpipam.git’
phpipam_source_version: ’master’
# phpIPAM database configuration
phpipam_database_host: ’localhost’
phpipam_database_user: ’phpipam’
phpipam_database_name: ’phpipam’
# List of hosts or networks in CIDR format allowed to access phpIPAM
# If empty, allws access from all networks
phpipam_allow: []
List of internal variables used by the role:
phpipam_database_password
100
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Authors and license
debops.phpipam role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.41 debops.phpmyadmin
This role installs PHPMyAdmin interface for MySQL database. At the moment it is designed to manage only a
database on localhost, and is usually enabled by debops.mysql role itself in a specifically written play. In the
future it will be redesigned as a standalone installation when secure access to remote databases is available.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.phpmyadmin
Role dependencies
• debops.secret
• debops.php5
• debops.nginx
Role variables
List of default variables available in the inventory:
--# Should PHPMyAdmin role manage its own dependencies?
phpmyadmin_dependencies: True
# What subdomain should be used for PHPMyAdmin in nginx configuration
phpmyadmin_domain: [ ’mysql.{{ ansible_domain }}’ ]
# Default length of generated passwords
phpmyadmin_password_length: ’20’
# Default PHPMyAdmin control password
phpmyadmin_control_password: "{{ lookup(’password’, secret + ’/credentials/’ + ansible_fqdn + ’/mysql
# List of IP addresses or network ranges in CIDR format, allowed to access
2.11. Ansible roles provided in DebOps
101
DebOps Documentation, Release master
# PHPMyAdmin. Leave empty to allow access from all IP addresses/networks
phpmyadmin_allow: []
# Max upload size for nginx and php5
phpmyadmin_upload_size: ’64M’
# Maximum number of PHP5 processes for PHPMyAdmin
phpmyadmin_php5_max_children: ’20’
Authors and license
debops.phpmyadmin role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.42 debops.pki
This role will bootstrap and manage fully-fledged Public Key Infrastructure entirely within Ansible. You can create
Certificate Authorities (stand-alone as well as chained together) which in turn can automatically sign incoming Certificate Requests and provide you with fully-functional OpenSSL or GnuTLS certificates for your entire infrastructure,
for free.
debops.pki can also be used to easily distribute private keys and certificates signed by an external CA to your hosts
in an easy and convenient way. Role will automatically create a set of symlinks to make use of the certificates within
your applications easy and intuitive.
debops.pki creates the certificate infrastructure on your ansible controller. CAs are stored on the controller, keys,
certification requests and signed certs are stored on the hosts. For practical purposes, everything PKI related is copied
to the ansible controller too! Your controller contains many secrets and must be well protected.
Certificates Here you define the certificates you want or have. They get signed automatically. You can set various
parameters:
realm: Which source and destination to use for keys, certificates and so on and which CA to use for signing.
This information is provided by the given realm.
cn: The common name
dns: subjectAltName, additional dns names. Please us this for wildcards.
uri: a key that is in the certificate
ip: can be added to the subjectAltName
e: An E-Mail address for the Signing request
mail: An additional E-Mail address for the Signing request
Realm In Debops realms are used for organizing certificates independent of hosts.
A realm is mainly used to define a channel between your ansible controller and the hosts. By defining a realm at
later configuration items, debops knows where to find file on server and controller. In addition, you can define
the default CA to sign your certificates.
domain realm: Wildcard Certificates that are stored on each host of a domain.
cret/pki/<ansible_domain>/realms/domain remote in /etc/pki/domain
102
local in se-
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
host-domain realm: Wildcard Certificates that are stored on one host of a domain.
local in secret/pki/<ansible_domain>/realms/hosts/{{ ansible_fqdn }}/domain remote in /etc/pki/domain
service realm: Special realm for applications that cannot handle intermediate CAs. Every certificate here is
based of special Service Root CA
host-service realm Same thing as host-domain realm, but for service.
host-internal realm Host specific non wildcard certificates for internal communication
You usually don’t need to add more realms
CAs Debops creates its own CA. It supports moving the Root CA to an offline backup for security reasons. You
usually don’t need to add more CAs
pki_routes Helper code to move certificates around. XXX
Examples
1. Upload your own certificate for nginx
1. Put your cert into file:secret/pki/{ansible_domain}/realms/hosts/{ansible_fqdn}/host/certs/<yourcert>.crt.
1. Put your key into file:secret/pki/{ansible_domain}/realms/hosts/{ansible_fqdn}/host/private/<yourcert>.key.
3. Then you must tell nginx about these files:
nginx_pki_crt: ’certs/<yourcert>.crt’
nginx_pki_key: ’private/<yourcert>.key’
2. Let debops create your certificate
Warning this is complicated.
pki_certificates:
- cn: ’git.yourotherdomain.com’
source: ’hosts/{{ ansible_fqdn }}/host’
destination: ’host’
filename: ’git.yourotherdomain.com’
pki_routes:
- name: ’host_git.starzel.de’
authority: ’ca/internal/certs’
realm: ’hosts/{{ ansible_fqdn }}/host/certs’
file: ’git.yourotherdomain.com.crt’
nginx_pki_crt: ’certs/git.yourotherdomain.com.crt’
nginx_pki_key: ’private/git.yourotherdomain.com.key’
Here is an explanation of each attribute:
• pki_certificates.cn: The common name used for the cert. Must be your domain name.
• pki_certificates.source: Where your certificate will be stored in the ansible controller. hosts/{{
ansible_fqdn }} is always correct. For the last part host, see the next parameter.
• pki_certificates.destination: the realm to use. See above for documentation of realms. The host
of of source above must be either host or domain, dependening on the destination defined here.
2.11. Ansible roles provided in DebOps
103
DebOps Documentation, Release master
• pki_certificates.filename: Not surprisingly, the filename of the cert. There will be multiple files and
they each get their own suffix.
• pki_routes.name: A unique name used for creating a script.
• pki_routes.authority:
Should be
ca/domain/certs for domain certificates.
ca/internal/certs
for
host
certificates
and
• pki_routes.realm: This must match pki_certificates.source plus an additional /certs suffix.
• pki_routes.file: This must match pki_certificates.filename with an additional .crt suffix.
• nginx_pki_crt: This must be certs/ plus the value of pki_routes.file.
• nginx_pki_key: This must be private/ plus pki_routes.file‘ with the suffix key instead of crt
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.pki
Role dependencies
• debops.secret
Role variables
List of default variables available in the inventory:
--# Enable or disable PKI support
pki: True
# ---- Default DN for Certificate Requests ---pki_country:
pki_state:
pki_locality:
pki_organization:
pki_organizational_unit:
pki_common_name:
pki_email:
’QS’
’Q-Space’
’Global’
’{{ ansible_domain.split(".")[0] | capitalize }}’
’Data Center Operations’
’{{ ansible_fqdn }}’
’[email protected]{{ ansible_domain }}’
# ---- PKI main options ---# List of additional packages to install (’haveged’ might be useful for faster
# randomness in testing environment)
pki_packages: []
# Base PKI directory on remote hosts
pki_base_path: ’/etc/pki’
# Base PKI directory on Ansible Controller
104
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# See debops.secret role for more information
pki_base_src: ’{{ secret + "/pki/" + ansible_domain }}’
# Directory and file permissions for public and private data
pki_owner: ’root’
pki_public_group: ’root’
pki_private_group: ’ssl-cert’
pki_public_dir_mode: ’0755’
pki_private_dir_mode: ’2750’
pki_public_mode: ’0644’
pki_private_mode: ’0640’
# Make sure these private system groups exist
pki_private_groups_present: []
# ---- Certificate defaults ---# Default digest engine to use for signatures
pki_digest: ’sha256’
# Default key size
pki_private_key_size: ’2048’
# Base sign period for "normal" certificates
pki_sign_days: ’365’
# Base multiplier for Root CA - 10 years
pki_sign_rootca_multiplier: ’10’
# Base multiplier for intermediate CA - 5 years
pki_sign_ca_multiplier: ’5’
# Base multiplier for certificate - 1 year
pki_sign_cert_multiplier: ’1’
# ---- Root Certificate Authority configuration ---pki_rootca: ’RootCA’
pki_rootca_filename: ’{{ pki_rootca + "-" + ansible_domain }}’
pki_rootca_private_key_size: ’4096’
pki_rootca_o: ’{{ pki_organization + " Certificate Authority" }}’
pki_rootca_cn: ’{{ pki_organization + " Root Certificate" }}’
# ---- PKI snapshot configuration ---pki_snapshot: True
pki_snapshot_path: ’/var/backups’
pki_snapshot_file: ’{{ "pki-snapshot-" + ansible_fqdn + ".tar" }}’
pki_snapshot_owner: ’root’
pki_snapshot_group: ’root’
# ---- Other configuration ---# Default library used to manage the certificates (openssl or gnutls)
2.11. Ansible roles provided in DebOps
105
DebOps Documentation, Release master
# Currently only OpenSSL is fully supported
pki_library: ’openssl’
# Certificate bundle configured as ’CA.crt’ if no CA has been specified
pki_default_ca: ’/etc/ssl/certs/ca-certificates.crt’
# Name of the certificates to symlink as ’default.*’ if no default has been
# specified
pki_default_certificate: ’{{ ansible_fqdn }}’
# PKI realm to set as the default (it will be written in Ansible local facts,
# as well as symlinked to ’/etc/pki/system/’)
pki_default_realm: ’host’
# By default files from all realms are sent to all remote hosts. To prevent
# access to a realm for a particular host, add the realm name to this list to
# prevent it being sent to the server
pki_realm_blacklist: []
# Certificate name to symlink as ’default.*’ in PKI ’host’ realm
pki_default_host_certificate: ’{{ ansible_fqdn }}’
# Certificate name to symlink as ’default.*’ in PKI ’domain’ realm
pki_default_domain_certificate: ’{{ "wildcard.domain." + ansible_fqdn }}’
# Subdomain reserved for CA server (certificate revocation lists, source for
# Root certificate, etc.)
pki_ca_domain: ’pki.{{ ansible_domain }}’
# This string is used to uniquely bind a certificate to the requesting host
pki_default_certificate_uri: ’{{ "http://" + pki_ca_domain + "/cert/" + (ansible_default_ipv4.macaddr
# ---- PKI realms ---# PKI realm is defined as a "channel" through which certificate requests are
# sent to the Ansible controller and certificates, as well as other files, are
# sent to remote hosts. It’s defined by a "source directory" (on Ansible
# Controller) and "destination directory" (on a remote host). Multiple sources
# can be connected to one destination.
#
# Each realm can have an optional Certificate Authority bound to it, which is
# used to sign certificates requested in that realm. Since each realm generates
# a Makefile in its destination directory, this can be disabled to not
# interfere if multiple source directories are connected to 1 destination.
# You can also specify a certificate name which will be symlinked as
# ’default.*’ in main directory of the PKI realm. You can also specify which CA
# certificates should be installed in a particular realm ’CA/’ directory.
#
# To provide your own certificates and keys signed by an external CA, put them
# in ’secret/pki/realms/’ directory in a desired realm.
pki_realms:
#
#
#
#
#
106
This realm is used to distribute certificates to all hosts in a domain. It
does not have its own CA, and additionally distributes the main Root
Certificate Authority to all hosts. If you manage hosts on which an
external entity might have access to private keys, and you want to prevent
them access to your wildcard certificates, you might want to disable this
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# realm on a particular host.
- name: ’domain’
source: ’domain’
destination: ’domain’
ca: [ ’root/RootCA’ ]
makefile: False
# This realm can be used to manage wildcard certificates per host, instead of
# globally. It by default provides a wildcard certificate for your domain.
- name: ’host-domain’
source: ’hosts/{{ ansible_fqdn }}/domain’
destination: ’domain’
authority: ’ca/domain’
default: ’{{ pki_default_domain_certificate }}’
# This realm can be used to manage host-based certificates, a certificate
# for your host will be automatically generated.
- name: ’host-internal’
source: ’hosts/{{ ansible_fqdn }}/host’
destination: ’host’
authority: ’ca/internal’
default: ’{{ pki_default_host_certificate }}’
# ---- Certificate Authoriries ---# This list defines a chain of Certificate Authorities, from Root CA, through
# Intermediate CA, ending on the "endpoint" CA which issue client and server
# certificates. Root and Intermediate CA after signing the CSR of sibling CA
# will automatically lock themselves, which allows you to move their private
# keys offline to a secure storage.
#
# CA will automatically sign all incoming Certificate Signing Requests and
# create chained certificates (with intermediate CA certificates included).
# Signed certificates will be stored in a central location and distributed to
# proper realms using route scripts (see below).
pki_authorities:
- name: ’root/RootCA’
grants: ’ca’
private_key_size: ’{{ pki_rootca_private_key_size }}’
filename: ’{{ pki_rootca_filename }}’
default_dn: False
o: ’{{ pki_rootca_o }}’
cn: ’{{ pki_rootca_cn }}’
- name: ’intermediate/DomainCA’
grants: ’ca’
parent: ’root/RootCA’
o: ’{{ pki_rootca_o }}’
ou: ’{{ pki_organization + " CA" }}’
cn: ’{{ "ca." + ansible_domain }}’
- name: ’ca/internal’
parent: ’intermediate/DomainCA’
ou: ’{{ pki_organization + " Data Center" }}’
cn: ’{{ "dc." + ansible_domain }}’
2.11. Ansible roles provided in DebOps
107
DebOps Documentation, Release master
- name: ’ca/domain’
grants: ’server’
parent: ’intermediate/DomainCA’
ou: ’{{ pki_organizational_unit }}’
cn: ’{{ "dco." + ansible_domain }}’
# ---- CA - realm route scripts ---# Route scripts provide a "glue" between Ansible facts and filesystem
# directories. Because at the time of the Makefile execution system does not
# have a knowledge about where to copy each file from Certificate Authorities
# directories to PKI realms, small shell scripts are generated beforehand with
# proper copy commands.
pki_routes:
# Copy signed host certificate to ’host’ PKI realm
- name: ’host_{{ ansible_fqdn }}’
authority: ’ca/internal/certs’
realm: ’hosts/{{ ansible_fqdn }}/host/certs’
file: ’{{ ansible_fqdn }}.crt’
# Copy signed domain certificate to ’domain’ PKI realm
- name: ’domain_{{ ansible_fqdn }}’
authority: ’ca/domain/certs’
realm: ’hosts/{{ ansible_fqdn }}/domain/certs’
file: ’wildcard.domain.{{ ansible_fqdn }}.crt’
# Copy Root CA certificate to ’domain’ realm for all hosts
- name: ’root_ca’
authority: ’root/RootCA’
realm: ’domain/CA’
readlink: ’CA.crt’
# Copy internal CA CRL file to ’host’ PKI realm
- name: ’host_crl_{{ ansible_fqdn }}’
authority: ’ca/internal’
realm: ’hosts/{{ ansible_fqdn }}/host/revoked’
readlink: ’default.crl’
# Copy domain CA CRL file to ’domain’ PKI realm
- name: ’domain_crl_{{ ansible_fqdn }}’
authority: ’ca/domain’
realm: ’hosts/{{ ansible_fqdn }}/domain/revoked’
readlink: ’default.crl’
# ---- Certificates ---# This is a list of certificates to manage on a host. Each host sends
# a Certificate Signing Request to Ansible Controller, where it’s signed by
# designated Certificate Authority and send back to the host.
pki_certificates:
- source: ’{{ "hosts/" + ansible_fqdn + "/host" }}’
destination: ’host’
ou: ’{{ pki_organization + " Data Center" }}’
cn: ’{{ ansible_fqdn }}’
108
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
dns: [ ’{{ "*." + ansible_domain }}’ ]
uri: [ ’{{ pki_default_certificate_uri }}’ ]
- source: ’{{ "hosts/" + ansible_fqdn + "/domain" }}’
destination: ’domain’
ou: ’{{ pki_organizational_unit }}’
cn: ’{{ ansible_domain }}’
dns: [ ’{{ "*." + ansible_domain }}’ ]
uri: [ ’{{ pki_default_certificate_uri }}’ ]
filename: ’wildcard.domain.{{ ansible_fqdn }}’
# Example list of certificate options
# - realm: ’host’
#
cn:
’www.example.com’
#
mail: [ ’[email protected]’ ]
#
dns:
[ ’www.example.com’, ’mail.example.com’, ’*.mail.example.com’ ]
#
uri:
[ ’http://example.com/’ ]
#
ip:
[ ’192.0.2.1’ ]
#
# - realm: ’host’
#
cn:
’subdomain.{{ ansible_domain }}’
#
# - realm: ’host’
#
cn:
’{{ "other." + ansible_domain }}’
#
ou:
’Other Department’
#
e:
’{{ "[email protected]" + ansible_domain }}’
#
mail: [ ’{{ "[email protected]" + ansible_domain }}’, ’{{ "[email protected]" + ansible_domain }}’ ]
#
dns:
[ ’{{ "*.other." + ansible_domain }}’ ]
Authors and license
debops.pki role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.43 debops.postgresql
debops.postgresql is an Ansible role which can install and manage PostgreSQL database servers. It’s built
around Debian solution for managing PostgreSQL “clusters” and can manage multiple clusters and PostgreSQL versions at once.
By default PostgreSQL 9.1 available in Debian Wheezy will be installed, but you can enable PostgreSQL 9.3 version
which will be installed using official PostgreSQL Global Development Group repositories.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
2.11. Ansible roles provided in DebOps
109
DebOps Documentation, Release master
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.postgresql
Role dependencies
• debops.ferm
• debops.etc_services
• debops.secret
Role variables
List of default variables available in the inventory:
--# PostgreSQL version installed by default and used for all PG clusters
postgresql_version: ’9.1’
# Enable PostgreSQL Global Developmet Group APT repository?
# More information: https://wiki.postgresql.org/wiki/Apt
postgresql_pgdg: False
# System user and group which managages PostgreSQL clusters
postgresql_owner: ’postgres’
postgresql_group: ’postgres’
# List of hosts/networks to allow through firewall. By default nothing is allowed
#postgresql_default_allow:
# - ’192.168.0.0/16’
# The default password for the postgres user.
# This is set for each cluster by default but you can override it for each cluster.
# Check https://github.com/ginas/ginas/tree/master/playbooks/roles/ginas.secret for more information
postgresql_default_postgres_password: "{{ lookup(’password’, secret + ’/credentials/’ + ansible_fqdn
# Where to log system/error messages
# Options: stderr, csvlog, syslog, and eventlog
postgresql_default_log_destination: ’syslog’
# Default localisation settings. Error messages will be printed in English
# independently of selected PostgreSQL locale. This locale will also be used at
# cluster creation to set default database encoding
postgresql_default_locale: ’en_US.UTF-8’
postgresql_default_locale_messages: ’C’
# Timezone configured in PostgreSQL clusters, by default use timezone settings
# from Ansible Controller or fallback to UTC
postgresql_default_timezone: ""
# Where SSL certificates are stored. See ’pki’ role
postgresql_pki_path: ’/srv/pki’
110
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# Certificates used for each PostgreSQL cluster if not changed otherwise
# By default, use self-signed host certificate
postgresql_default_ssl_root: ’{{ postgresql_pki_path }}/host/selfsigned/{{ ansible_fqdn }}.crt’
postgresql_default_ssl_crl: ’{{ postgresql_pki_path }}/host/crl/{{ ansible_fqdn }}.crl’
postgresql_default_ssl_crt: ’{{ postgresql_pki_path }}/host/selfsigned/{{ ansible_fqdn }}.crt’
postgresql_default_ssl_key: ’{{ postgresql_pki_path }}/host/private/{{ ansible_fqdn }}.key’
postgresql_default_ssl_ciphers: ’ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH’
# Default startup behaviour: auto, manual, disabled
postgresql_default_start_conf: ’auto’
# How much % of RAM to use for shared memory? By default 0.5 means half
# of system memory will be used for shmmax and shmall calculations
# http://www.postgresql.org/docs/9.1/static/kernel-resources.html
# Set to False to disable shared memory changes
postgresql_sysctl_shm_multiplier: 0.5
# Default maximum number of connections
postgresql_default_max_connections: ’100’
# Default WAL and archivisation settings
# Options: minimal, archive, hot_standby
postgresql_default_wal_level: ’minimal’
postgresql_default_archive_command: ’’
# User to cluster mapping. This is a text block which will be pasted "as is"
# into /etc/postgresql-common/user_clusters
# By default, nothing is configured
postgresql_user_clusters: False
# Host based authentication defaults. This is a text block which will be pasted
# "as is" into pg_hba.conf *after* any hba settings from a particular cluster.
# Settings for system superuser (postgres) are set in pg_hba.conf template
postgresql_default_hba: |
local
all
all
peer
host
all
all
127.0.0.1/32
md5
host
all
all
::1/128
md5
# User identification defaults. This is a text block which will be pasted "as
# is" into pg_ident.conf *before* any ident settings from a particular cluster.
# By default, nothing is configured
postgresql_default_ident: False
#
#
#
#
#
#
#
#
#
Lists of PostgreSQL clusters to manage. Each entry should have at least
a name and a port on which to bind the cluster. Other options listed below
are optional. You can also add all PG parameters from postgresql.conf to
a cluster entry
To disable one or both lists, set them as empty: ’[]’. This will allow for
cluster counting task to work correctly (needed to set correct amounts of
shared memory for each cluster, divided by number of clusters configured on
the host)
# Configuration for default "main" cluster
postgresql_default_cluster:
- name: ’main’
port: ’5432’
2.11. Ansible roles provided in DebOps
111
DebOps Documentation, Release master
# Parameters below are optional. More parameters can be found in postgresql.conf template
#user: ’postgres’
#group: ’postgres’
#postgres_password: "{{ lookup(’password’, secret + ’/credentials/’ + ansible_fqdn + ’/postgresql
#version: ’{{ postgresql_version }}’
#ssl_root: ’{{ postgresql_default_ssl_root }}’
#ssl_crt: ’{{ postgresql_default_ssl_crt }}’
#ssl_key: ’{{ postgresql_default_ssl_key }}’
#start_conf: ’auto’
#environment:
# VARIABLE: ’value’
#listen_addresses: ’localhost’
#hba:
# - hosts: [] # example: ’{{ groups[’apps’] }}’
#
type: ’host’
#
interface: ’br2’
#
user: ’all’
#
database: ’{{ user }}’
#
auth: ’md5’
# - address: ’’ # example: ’192.168.0.0/16
#ident: |
# # Freeform (see postgresql_default_hba)
#allow:
# - ’10.0.0.0/8’
# - ’172.16.0.0/12’
# - ’192.168.0.0/16’
# Configuration for other clusters
postgresql_clusters: []
# ---- Auto backups ---#
#
#
#
#
Backups will be ran daily and are rotated weekly.
Weekly backups are rotated on a 5 week cycle.
Monthly backups are ran on the first of the month.
Monthly backups are not rotated.
It would be a good idea to move monthly backups to a remote server yourself.
# Should auto backups be enabled?
# If set to False, the script will be removed from /etc/cron.daily.
postgresql_auto_backup: True
# Available options:
#
- log
: send only the log file
#
- files : send the log file and sql files as attachments
#
- stdout : output the log to the screen if run manually
#
- quiet : only send logs if an error occurs
postgresql_auto_backup_mailcontent: ’quiet’
# The maximum allowed size of the e-mail, 4000 = about 5mb.
postgresql_auto_backup_maxsize: 4000
# Who should receive the backup files?
postgresql_auto_backup_mailaddr: ’[email protected]{{ ansible_domain }}’
# Include create database in the backup? Use ’yes’ or ’no’, not true/false.
postgresql_auto_backup_create_database: ’yes’
112
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# Use a separate backup directory and file for each database? ’yes’ or ’no’.
postgresql_auto_backup_isolate_databases: ’yes’
# Which day of the week do you want to perform weekly backups?
# 1 = Monday , ... , 7 = Sunday.
postgresql_auto_backup_weekly_day: 6
# Should the dumps be encrypted? ’yes’ or ’no’
postgresql_auto_backup_encryption: ’no’
postgresql_auto_backup_encryption_public_key: ’’
# Scripts to execute before and/or after the backup takes place.
# An empty value disables this feature, provide a path to the script to enable.
postgresql_auto_backup_pre_script: ’’
postgresql_auto_backup_post_script: ’’
List of internal variables used by the role:
postgresql_default_timezone
postgresql_cluster_count
Authors and license
debops.postgresql role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
• Nick Janetakis | e-mail | Twitter | GitHub
License: GPLv3
2.11.44 debops.radvd
debops.radvd role manages Router Advertisement Daemon. radvd periodically sends router advertisements and
other hosts on the network will automatically pick them up. This results in them obtaining an IPv6 address and internet
connectivity.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.radvd
Role variables
List of default variables available in the inventory:
2.11. Ansible roles provided in DebOps
113
DebOps Documentation, Release master
--# ---- Default options ---# Network interface to configure
# By default, configure on interface created by ’debops.subnetwork’ role
radvd_default_interface: ’br2’
# Options for default interface, specified as YAML text block
radvd_default_interface_options: |
AdvSendAdvert on;
MaxRtrAdvInterval {{ radvd_max_advert_interval }};
{% if radvd_default_dhcpv6 is defined and radvd_default_dhcpv6 %}
AdvManagedFlag on;
AdvOtherConfigFlag on;
{% endif %}
# Options defined for default prefixes as YAML text block
radvd_default_prefix_options: ’’
# Enable or disable support for DHCPv6 server in default configuration
radvd_default_dhcpv6: True
# ---- DNS and search domains ---# Local subdomain leaf to advertise in DNSSL
radvd_default_subdomain: ’lan’
# List of search domains to advertise in DNSSL
radvd_default_domains: [ ’{{ radvd_default_subdomain }}.{{ ansible_fqdn }}’, ’{{ ansible_domain }}’ ]
# ---- radvd configuration ---# Maximum time between router advertisements, in seconds
radvd_max_advert_interval: ’60’
# See radvd.conf(5) for documentation of available options. Each section is
# specified with lowercase name, section options are specified as YAML text
# blocks (semicolons at the end of each line are required).
radvd_interfaces:
# Default interface created by ’debops.subnetwork’ role
- interface: ’{{ radvd_default_interface }}’
comment: ’Default configuration for local network’
# Interface options as YAML text block
options: ’{{ radvd_default_interface_options }}’
# List of prefixes advertised on this interface
prefixes:
- prefix: ’::/64’
options: ’{{ radvd_default_prefix_options }}’
# List of configured routes for this interface
routes: []
#- route: ’’
114
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
#
options: |
# List of nameservers advertised on this interface
nameservers: []
#- rdnss: []
# options: |
# List of search domains advertised on this interface
domains:
- dnssl: ’{{ radvd_default_domains }}’
# List of clients to advertise to, if not defined, advertise to all hosts
# on this interface
clients: []
Authors and license
debops.radvd role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.45 debops.rails_deploy
debops.rails_deploy role allows you to easily setup infrastructure capable of running Rails applications. It
removes all of the headaches associated to setting up a secure Rails app that is ready for production so you can
concentrate on developing your app.
Table of Contents
• A few features supplied by this role
– High level goals
– Backups and logging
– System level minutia
– Deploy features
– Security
• Installation
• Role dependencies
• Role variables
• Detailed usage guide
– hosts
– inventory/host_vars/somehost.yml
– playbook
– Running the playbook with DebOps
– Running the playbook without DebOps
– Changes you need to make in your rails application
– Don’t feel like making these small changes every time you make a new app?
– FAQ / troubleshooting guide
• Authors and license
2.11. Ansible roles provided in DebOps
115
DebOps Documentation, Release master
A few features supplied by this role
High level goals
• Setup an entire rails app server with 1 line of configuration with sane defaults
• Optionally and easily separate your app servers, database and worker into multiple servers
• Quickly and easily switch between popular default databases and backend servers
• Be as secure as possible and adhere to as many best practices as possible
Backups and logging
• Postgresql runs a daily backup with daily/weekly rotation
• Both your backend server and background worker get logged to 1 logrotated file
• The rails process gets sent to syslog.user
System level minutia
• User accounts, permissions and ssh keys are automatically managed
• Paths such as logs, pids and sockets are automatically managed
Deploy features
• Automatically set deploy keys to github/gitlab with 1 line of configuration - This leverages their API, all you
have to do is supply their token
• Keep track of your schema file and config folder’s mtime in local facts - This allows the deploy task to attempt
to guess if your server needs a full restart or a quick reload
• Only run database commands from a single master app server - This master is defined by simply being first in
the group list
• Various options to turn certain features on/off - A few examples would be database creation, migration and force
restarting your server
• Add custom services which get restarted/reloaded at the end of the deploy cycle - If you have a SOA setup this
could be handy
• Add and remove custom tasks at various points in the deploy - By default it is set to precompile assets and clear
the /tmp cache
• Optionally swap a static deploy page in/out during the deploy cycle
Security
• Secure passwords are managed automatically for your database
• Ports are blocked and only whitelisted for IP addresses/masks that you specify
• SSL is enabled by default but can be turned off if you really don’t want it
• Self signed SSL certs are automatically managed for you - Changing to properly signed certificates is a breeze
116
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.rails_deploy
Role dependencies
• debops.etc_services
• debops.redis
• debops.nginx
• debops.nodejs
• debops.mysql
• debops.ruby
• debops.monit
• debops.secret
• debops.postgresql
Role variables
List of default variables available in the inventory:
--# ---- System ---# Should certain services/envs be setup for you automatically?
# Redis will only be setup if you enable background worker support.
#
# Keep in mind that if you remove ruby then you will be expected to put
# ruby on the system and ensure its binaries are on the system path.
rails_deploy_dependencies: [’database’, ’redis’, ’nginx’, ’ruby’, ’monit’]
# Which packages do you want installed?
# Add as many packages as you want, the database_package will automatically
# pick libpq-dev or libmysqlclient-dev depending on what database you picked.
rails_deploy_packages: [’{{ rails_deploy_database_package }}’]
# A list of additional groups that this app’s user belongs to.
# If you want to be able to ssh into the server then you must include ’sshusers’.
rails_deploy_user_groups: []
# Where should the public ssh key be read in from? This is only used when you
# have included ’sshusers’ in the user_groups list.
rails_deploy_user_sshkey: "{{ lookup(’file’, ’~/.ssh/id_rsa.pub’) }}"
# ---- Hosts ---# What inventory group does your app belong to?
# If you want to have multiple apps then make this group gather up all sub-groups
2.11. Ansible roles provided in DebOps
117
DebOps Documentation, Release master
# such as debops_rails_deploy_myapp and debops_rails_deploy_anotherapp.
rails_deploy_hosts_group: ’debops_rails_deploy’
# Which application server should run database related tasks?
rails_deploy_hosts_master: ’{{ groups[rails_deploy_hosts_group][0] }}’
# ---- Git ---# The location repo which will get cloned during each deploy. You can use a
# remote or local repo.
rails_deploy_git_location: ’’
# Which branch or tag should be used?
rails_deploy_git_version: ’master’
# Which remote should be used?
rails_deploy_git_remote: ’origin’
# Supply your git provider’s api token to automatically set deploy keys.
# If False you will have to manually add deploy keys for each app server.
# Supports github and gitlab for now:
# Github: https://github.com/settings/applications
#
Under personal access tokens, check off ’write:public_key’.
#
You may want to enable other access limits for repo/public_repo, etc..
#
# Gitlab: https://yourgitlabhost.com/profile/account
#
Your private token should already be there.
rails_deploy_git_access_token: False
# ---- Deploy ---# What should the service be named?
# The default value plucks out your repo name (without .git) from your location.
rails_deploy_service: "{{ rails_deploy_git_location | basename | replace(’.git’, ’’) }}"
# Where should the user’s home directory be?
rails_deploy_home: ’/var/local/{{ rails_deploy_service }}’
# Where should the git repository be cloned to?
rails_deploy_src: ’{{ rails_deploy_home }}/{{ rails_deploy_nginx_domains[0] }}/{{ rails_deploy_servic
# What should the system environment be set to?
rails_deploy_system_env: ’production’
# A list of environments to skip, it will remove your system env from the list
# during the deploy phase automatically.
rails_deploy_bundle_without: [’development’, ’staging’, ’production’, ’test’]
# Timeout for service and worker startup, in seconds
rails_deploy_service_timeout: ’60’
# ---- Backend ---# Which backend type are you using? ’unicorn’ and ’puma’ are supported so far.
118
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# You can also disable the backend by setting it to False in case you use passenger.
rails_deploy_backend: ’unicorn’
# What do you want to listen on? You can choose a tcp addr:port or unix socket.
# Do not bother to include the socket/tcp prefix, that will be handled for you.
rails_deploy_backend_bind: ’{{ rails_deploy_service_socket }}’
# What state should the backend be in?
rails_deploy_backend_state: ’started’
rails_deploy_backend_enabled: True
# When set to true the backend will always restart instead of reload but it
# will only restart if the repo changed. This makes for hands free deployment
# at the cost of a few seconds+ of downtime per deploy.
#
# You may want to combine this with force migrate in which case all you ever have
# to do is push your app and you don’t have to wonder whether or not the code
# you’re changing requires a full restart or not.
rails_deploy_backend_always_restart: False
# ---- Database ---# Should the database be created by default?
rails_deploy_database_create: True
# Should the database get a db:schema:load and db:seed in an idempotent way?
rails_deploy_database_prepare: True
# Should the database get automatically migrated in an idempotent way?
rails_deploy_database_migrate: True
# Should the database get migrated no matter what?
# You may want to do this as a 1 off command with --extra-vars in case your
# schema file’s checksum somehow gets out of sync and you need to migrate.
#
# Another use case would be if you have automatic migrations turned off and
# you just deployed but now you want to do an isolated migration.
rails_deploy_database_force_migrate: False
# It supports ’postgresql’ or ’mysql’ for now.
rails_deploy_database_adapter: ’postgresql’
# Make sure this matches your pg cluster info, ignore it if you use mysql.
rails_deploy_postgresql_cluster: ’9.1/main’
# Where is your database hosted?
rails_deploy_database_host: ’{{ ansible_fqdn }}’
rails_deploy_database_port: ’5432’ # 3306 for mysql
# What are your super user names?
rails_deploy_postgresql_super_username: ’postgres’
rails_deploy_mysql_super_username: ’mysql’
# What should some of the configuration options be set to?
rails_deploy_database_pool: 25
rails_deploy_database_timeout: 5000
2.11. Ansible roles provided in DebOps
119
DebOps Documentation, Release master
# ---- Background Worker ---# Enable background worker support. This will create an init.d service, register
# it with monit and add it into the deploy life cycle.
rails_deploy_worker_enabled: False
rails_deploy_worker_state: ’started’
# At the moment it only supports sidekiq but resque could happen in the future.
rails_deploy_worker: ’sidekiq’
# Where is your worker hosted?
rails_deploy_worker_host: ’{{ ansible_fqdn }}’
rails_deploy_worker_port: ’6379’
# How should the connection be made to the redis server?
# If your server has a password you must add it here.
# Example: redis://:[email protected]{{ rails_deploy_worker_host }}:{{ rails_deploy_worker_port }}/0’
rails_deploy_worker_url: ’redis://{{ rails_deploy_worker_host }}:{{ rails_deploy_worker_port }}/0’
# ---- Commands ---# Execute shell commands at various points in the deploy life cycle.
# They are executed in the context of the root directory of your app
# and are also only ran when your repo has changed.
# Shell commands to run before migration
# They will still run even if you have migrations turned off.
rails_deploy_pre_migrate_shell_commands: []
# Shell commands to run after migration
# They will still run even if you have migrations turned off.
rails_deploy_post_migrate_shell_commands:
- ’bundle exec rake assets:precompile’
- ’rm -rf tmp/cache’
# Shell commands to run after the backend was started
# Let’s say you wanted to execute whenever after your app reloads/restarts:
#
- ’bundle exec whenever --clear-crontab {{ rails_deploy_service }}’
#
# This is the absolute last thing that happens during a deploy.
# They will still run even if you have no backend.
rails_deploy_post_restart_shell_commands: []
# ---- Services ---# Add 1 or more custom services related to the app, they will have
# their state changed on each deploy. The changed_state is the action to
# take when the state of the git repo has changed.
# They will get restarted/reloaded at the end of the deploy.
# Everything is optional except for the name.
rails_deploy_extra_services: []
#rails_deploy_extra_services:
# - name: ’’
#
changed_state: ’reloaded’
120
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
#
#
state: ’started’
enabled: True
# ---- Log rotation ---# How often should they be rotated?
# Accepted values: hourly, daily, weekly, monthly and yearly
rails_deploy_logrotate_interval: ’weekly’
# Log files are rotated N times before being removed.
rails_deploy_logrotate_rotation: 24
# ---- Environment settings ---# Both the default and custom environment variables will get added together
# and be written to /etc/default/{{ rails_deploy_service }}.
# Default environment variables added to each app.
rails_deploy_default_env:
RAILS_ENV: ’{{ rails_deploy_system_env }}’
DATABASE_URL: "{{ rails_deploy_database_adapter }}://{{ rails_deploy_service }}:{{ rails_deploy_dat
# Application variables, they are used in the backend/worker variables below.
SERVICE: ’{{ rails_deploy_service }}’
LOG_FILE: ’{{ rails_deploy_log }}/{{ rails_deploy_service }}.log’
RUN_STATE_PATH: ’{{ rails_deploy_run }}’
# Backend variables, they work in conjunction with the example
# server configs. Check docs/examples/rails/config/puma.rb|unicorn.rb.
LISTEN_ON: ’{{ rails_deploy_backend_bind }}’
THREADS_MIN: 0
THREADS_MAX: 16
WORKERS: 2
# Background worker variables. Check docs/examples/rails/config/sidekiq.yml
# and initializers/sidekiq.rb on how use this in your application.
BACKGROUND_URL: ’{{ rails_deploy_worker_url }}’
BACKGROUND_THREADS: ’{{ rails_deploy_database_pool }}’
# Custom environment variables added to a specific app.
rails_deploy_env: {}
# ---- Nginx settings ---# Should nginx be enabled?
rails_deploy_nginx_server_enabled: True
# What domain names should the app be associated to?
rails_deploy_nginx_domains: [’{{ ansible_fqdn }}’]
# If you want to edit any of the values for nginx below, you will need to copy
# the whole variable over even if you need to edit 1 value.
#
2.11. Ansible roles provided in DebOps
121
DebOps Documentation, Release master
# Consult the debops.nginx documentation if needed.
# Configure the upstream.
rails_deploy_nginx_upstream:
enabled: ’{{ rails_deploy_nginx_server_enabled }}’
name: ’{{ rails_deploy_service }}’
server: "{{ ’unix:’ + rails_deploy_backend_bind if not ’:’ in rails_deploy_backend_bind else rails_
# Configure the sites-available.
rails_deploy_nginx_server:
enabled: ’{{ rails_deploy_nginx_server_enabled }}’
default: False
name: ’{{ rails_deploy_nginx_domains }}’
root: ’{{ rails_deploy_src }}/public’
error_pages:
’404’: ’/404.html’
’422’: ’/422.html’
’500’: ’/500.html’
’502 503 504’: ’/502.html’
location_list:
- pattern: ’/’
options: |
try_files $uri $uri/index.html $uri.html @{{ rails_deploy_nginx_upstream.name }};
- pattern: ’~ ^/(assets|system)/’
options: |
gzip_static on;
expires max;
add_header Cache-Control public;
add_header Last-Modified "";
add_header ETag "";
- pattern: ’@{{ rails_deploy_nginx_upstream.name }}’
options: |
gzip off;
proxy_set_header
X-Forwarded-Proto $scheme;
proxy_set_header
Host
$http_host;
proxy_set_header
X-Real-IP
$remote_addr;
proxy_set_header
X-Forwarded-For
$proxy_add_x_forwarded_for;
proxy_redirect
off;
proxy_pass
http://{{ rails_deploy_nginx_upstream.name }};
# Usage examples:
# ---- Bare minimum ---#rails_deploy_git_location: ’[email protected]:yourname/mycoolapp.git’
# ---- Use a custom service name ---#rails_deploy_service: ’myawesomeapp’
# ---- Use a tag or branch instead of master ---#rails_deploy_git_version: ’v0.1.0’
# ---- Use mysql instead of postgres ---#rails_deploy_database_adapter: ’mysql’
# ---- Use puma instead of unicorn ----
122
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
#rails_deploy_backend: ’puma’
# ---- Enable the background worker ---#rails_deploy_worker_enable: True
# ---- Listen on a tcp port instead of a socket ---#rails_deploy_backend_bind: ’{{ ansible_fqdn }}:8080’
# ---- Deploy to staging instead of production ---#rails_deploy_system_env: ’staging’
List of internal variables used by the role:
rails_deploy_key_data
Detailed usage guide
Below is the bare minimum to get started.
hosts
[debops_rails_deploy]
somehost
inventory/host_vars/somehost.yml
--rails_deploy_git_location: ’[email protected]:youraccount/yourappname.git’
The idea is that you’ll push your code somewhere and then the role will pull in from that repo.
playbook
--# playbooks/custom.yml
- name: Deploy yourappname
hosts: debops_rails_deploy
sudo: true
roles:
- { role: debops.rails_deploy, tags: yourappname }
Running the playbook with DebOps
debops -t yourappname
2.11. Ansible roles provided in DebOps
123
DebOps Documentation, Release master
Running the playbook without DebOps
ansible-playbook playbooks/custom.yml -i /path/to/your/inventory -t yourappname
Changes you need to make in your rails application
Gemfile You must have unicorn or puma added.
# Pick one, you may also want to bump the version to the most recent version
# These are the most recent as of ~August 2014
gem ’unicorn’, ’~> 4.8.3’
gem ’puma’, ’~> 2.9.0’
You must have pg or mysql2 added.
# Pick one, you may also want to bump the version to the most recent version
# These are the most recent as of ~August 2014
gem ’pg’, ’~> 0.17.1’
gem ’mysql2’, ’~> 0.3.16’
Backend server config You should base your unicorn or puma config off our example configs because certain
environment variables are required to exist. Also certain signals are sent to reload or restart the backend which require
certain configuration options to be set. Luckily you don’t have to think about any of that, just use the pre-written
configs in your app.
Background worker config You should also base your sidekiq configs off our example configs. Similar to the
backend server it expects certain environment variables to exist.
Database config The database configuration below would be reasonable to use. The only requirement is that yours
must use the DATABASE_URL format in whatever environments you plan to deploy to. That simply means that those
environments should be removed from your database config file. This role sets up the DATABASE_URL for you.
--development:
url: <%= ENV[’DATABASE_URL’].gsub(’?’, ’_development?’) %>
test:
url: <%= ENV[’DATABASE_URL’].gsub(’?’, ’_test?’) %>
Application config In order to log everything to 1 file you must drop this line into your application config. This
would apply to all environments. Feel free to move this to only staging and/or production if you don’t want this to
happen in development.
config.paths[’log’] = ENV[’LOG_FILE’]
Production environment config Chances are you’ll want your rails app to write to syslog in production or on your
staging/build/etc. server. Copy this into your production environment config.
require ’syslog/logger’
# ...
# The tags are optional but it’s useful to have.
124
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
config.log_tags = [ :subdomain, :uuid ]
# This allows you to write to syslog::user without any additional gems/config.
config.logger = ActiveSupport::TaggedLogging.new(Syslog::Logger.new(’yourappname’))
Public files You will likely want the following files to exist in your /public directory:
• 404, 422, 500 and 502 html files to process error pages
• deploy html file to swap in/out during the deploy process
The above will allow nginx to serve those files directly before rails even gets a chance.
Don’t feel like making these small changes every time you make a new app?
Me neither. That’s why I created orats. It is a command line tool that generates a shiny new rails application with an
accumulation of best practices that I have picked up over time. It is also a little opinionated. Check out orats git repo
if you’re interested.
FAQ / troubleshooting guide
You switched from unicorn to puma or puma to unicorn and the site is dead Chances are you’re deploying with
tags so the entire role did not run. When you switch servers nginx needs to be restarted. Make sure you -t nginx
or just run the whole role when you change servers.
You can’t clone your repo Since the role needs to pull in from your git repo then it needs permission to your repo.
The most common way to do that is to setup an API access token for GitHub.
GitLab is also supported, all of this is documented in the default variables file.
How would you go about setting up a CI platform with this role? Rather than impose a CI solution on you, you’re
free to do whatever you want.
A possible situation might be to use this role to deploy to a staging/CI/build server instead of directly to production.
Now your build server can run tests and push to production using this role on different hosts if everything goes well.
That would allow you to have a sweet CI setup where your developers only have to git push somewhere and minutes
later you have tested code in production if you don’t have to worry about a ton of red tape.
I’m using unicorn and after restarting it’s dead (502) You need to have something like monit handle keeping the
service up. Are you sure you have monit in the rails_deploy_dependencies list?
Authors and license
debops.rails_deploy role was written by:
• Nick Janetakis | e-mail | Twitter | GitHub
License: GPLv3
2.11. Ansible roles provided in DebOps
125
DebOps Documentation, Release master
2.11.46 debops.redis
debops.redis role allows you to easily setup infrastructure capable of running and managing 1 or more Redis
servers. It is completely self healing with Redis Sentinel and supports replication seamlessly.
Few features available in this role:
• seamless master/slave replication;
• throw together a master + n slaves + n sentinel setup in about 10 lines of YAML (most of those lines would be
adding your hosts to the inventory);
• your configs are idempotent, even when redis rewrites them;
• pretty much every redis config value is tweakable;
• you can easily use this role as a dependency in your other roles;
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Detailed usage guide
– inventory/hosts
– inventory/group_vars/debops_redis_sentinel.yml
– inventory/group_vars/debops_redis.yml
– Running the playbook
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.redis
Role dependencies
• debops.ferm
• debops.etc_services
• debops.secret
• debops.apt_preferences
Role variables
List of default variables available in the inventory:
--# NOTE: Redis requires boolean variables to be exactly yes or no, do not confuse
# them with yaml booleans. They should be quoted to be output as strings.
# Check the URLs below for a detailed explanation of each command:
126
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# http://download.redis.io/redis-stable/redis.conf
# http://download.redis.io/redis-stable/sentinel.conf
# --- General --# Which inventory group does redis-server belong to?
redis_hosts_group: ’debops_redis’
# What is the master redis server’s host and port?
# You can use a host name or IPv4 address.
redis_hosts_master: ’{{ groups[redis_hosts_group][0] }} {{ redis_port }}’
# You might want to use 0.0.0.0 and then allow access from your app servers or
# anything that needs to talk to redis by configuring redis_server_allow below.
redis_bind: [’localhost’]
redis_port: 6379
# Allow connections from a list of hosts, you may use masks such as:
# 192.168.0.0/16 but it must be in a list, ex. [’192.168.0.0/16’].
redis_server_allow: []
redis_timeout: 0
redis_tcp_keepalive: 0
redis_tcp_backlog: 511
redis_loglevel: ’notice’
# ---- Sentinel ---# When set to False both redis-server and redis-sentinel will be on the same host.
redis_sentinel_standalone: True
# Which inventory group does redis-sentinel belong to?
redis_sentinel_hosts_group: ’debops_redis_sentinel’
# These values accept the same type of values as the general redis server.
redis_sentinel_bind: [’localhost’]
redis_sentinel_port: 26379
redis_sentinel_allow: []
# A list of redis servers to monitor. Commented values are optional.
redis_sentinel_group_list:
# The name of the monitor group, you can use whatever you want.
- name: ’main’
# The master server’s host address.
#host: ’{{ groups[redis_hosts_group][0] }}’
# The master server’s port.
#port: ’{{ redis_port }}’
# How many sentinels need to agree that the master is down before failing over?
#quorom: 2
# Consult the redis documentation for the rest.
#parallel_syncs: 1
#down_after_milliseconds: 30000
#failover_timeout: 180000
#notification_script: ’’
#client_reconfig_script: ’’
2.11. Ansible roles provided in DebOps
127
DebOps Documentation, Release master
# ---- Snapshotting ---# You can disable saving entirely by providing an empty list.
redis_save:
- ’900 1’
- ’300 10’
- ’60 10000’
redis_stop_writes_on_bgsave_error: ’yes’
# ---- Replication ---redis_slave_read_only: ’yes’
redis_repl_ping_slave_period: 10
redis_repl_timeout: 60
redis_repl_backlog_size: 1mb
redis_repl_backlog_ttl: 3600
redis_slave_priority: 100
redis_min_slaves_to_write: 0
redis_min_slaves_max_lag: 10
# ---- Security ---redis_requirepass: False
#
# Example using the secret role to automatically set a password.
# This password will be applied to the master, slaves and sentinels.
#redis_requirepass: "{{ lookup(’password’, secret + ’/credentials/’ + groups[redis_hosts_group][0] +
# ---- Limits ---redis_maxclients: 10000
# Set a percent multiplier to cap the amount of RAM redis will use. For example
# if you wanted to limit it to 80% of the total RAM you would input 0.8.
redis_maxmemory_multiplier: 1.0
redis_maxmemory_policy: ’volatile-lru’
# ---- Append only mode ---redis_appendonly: ’no’
# ---- Slow log ---redis_slowlog_log_slower_than: 10000
redis_slowlog_max_len: 128
# ---- Latency monitor ---redis_latency_monitor_threshold: 0
128
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# ---- Event notification ---redis_notify_keyspace_events: False
Detailed usage guide
Below is the bare minimum to get started to setup a few Redis servers acting together. If all you want to do is use
Redis as a single server dependency in another role then include the role in your role’s meta main file. You don’t have
to add the groups in your inventory in that case.
inventory/hosts
# In this example the ’redis-server0’ host would be the redis
# master and everything else would be a slave of that master.
[debops_redis]
redis-server0
redis-server1
redis-server2
# You can have 1 or more sentinels. The sentinel(s) will control your master
# and slave relationships.
[debops_redis_sentinel]
redis-monitor
inventory/group_vars/debops_redis_sentinel.yml
# It is expected that you have a firewall configured with ’debops.ferm’
# role, set up to block all ports. Variables below tell Redis role to
# accept connections from anywhere and then whitelist your local
# network to allow connections to it.
redis_sentinel_bind: [’0.0.0.0’]
redis_sentinel_allow: [’192.168.0.0/16’]
inventory/group_vars/debops_redis.yml
# This setup allows you to grant access to your redis servers from your
# application group and the sentinel group. You can add as many hosts
# as you need.
redis_bind: [’0.0.0.0’]
redis_server_allow: ’{{ groups["your_web_apps"] + redis_sentinel_hosts_group }}’
If you want a Sentinel server to also act as a Redis server you can combine the 2 iservices on 1 host. You
will need to set redis_sentinel_standalone: False in that host’s inventory. This is covered in the
defaults/main.yml file.
You don’t need to define a playbook unless you want to use group names other than the default. If you use non-default
group names then make sure you change the defaults in your inventory.
2.11. Ansible roles provided in DebOps
129
DebOps Documentation, Release master
Running the playbook
debops -t redis
Authors and license
debops.redis role was written by:
• Nick Janetakis | e-mail | Twitter | GitHub
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.47 debops.reprepro
debops.reprepro role is used to create and manage local APT repository. Packages can be uploaded manually to
a specific user account, or they can be downloaded by the role from specific directory on Ansible Controller. Role will
also automatically configure access to created APT repository on all hosts managed by Ansible.
This role is by default not used directly by the playbook. Instead, debops.apt role uses it as a dependency.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.reprepro
Role dependencies
• debops.secret
• debops.auth
Role variables
List of default variables available in the inventory:
--# The FQDN of the host on which reprepro is configured; other hosts in the
# group/cluster will use this for obtaining apt keys and repository
# information. Set to False to disable reprepro. By default, it is defined by the
# ’apt’ role in roles/apt/meta/main.yml
reprepro: False
130
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# ’reprepro’ role requires a webserver to serve repository data, but currently
# it’s not dependent on one, relying on ’apt’ role to configure it beforehand.
# This variable set by the ’apt’ role specifies that ’reprepro’ role can
# configure it’s APT repository (webserver is configured)
reprepro_served: False
# User and group for reprepro repository
reprepro_user: ’reprepro’
reprepro_group: ’reprepro’
# User account of reprepro incoming queue (will be configured as sftponly account)
reprepro_incoming_user: ’reprepro-upload’
# Directory where reprepro will create the Debian repositories
# By default it’s the nginx document root directory for default server
reprepro_repository: ’/srv/www/sites/default/public/debian’
# Install and then uninstall haveged during GPG key generation to make it faster
# Useful during testing or on virtual machines, but may create weaker GPG keys
# More information: https://security.stackexchange.com/questions/34523/
reprepro_haveged: False
# Settings for GPG key used to sign reprepro repository
reprepro_gpg_key_type: ’RSA’
reprepro_gpg_key_length: ’2048’
reprepro_gpg_name: ’Reprepro Automatic Signing Key’
reprepro_gpg_email: ’[email protected]{{ ansible_domain }}’
reprepro_gpg_expire_days: ’1825’
# List of repositories managed by reprepro (for possible values see
# man reprepro, section about ’conf/distributions’ configuration file)
reprepro_distributions:
- codename: ’wheezy’
components: ’main’
suite: ’stable’
architectures: ’amd64 i386’
origin: ’Automatic Reprepro Repository’
description: ’Automatic Reprepro Repository’
label: ’reprepro-auto’
signwith: ’yes’
- codename: ’wheezy-backports’
components: ’main’
suite: ’stable-backports’
architectures: ’amd64 i386’
origin: ’Automatic Reprepro Backports Repository’
description: ’Automatic Reprepro Backports Repository’
label: ’reprepro-auto’
signwith: ’yes’
Authors and license
debops.reprepro role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
2.11. Ansible roles provided in DebOps
131
DebOps Documentation, Release master
License: GPLv3
2.11.48 debops.rsyslog
This role manages configuration of rsyslog server and makes sure that it’s installed.
Table of Contents
• Installation
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.rsyslog
Authors and license
debops.rsyslog role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.49 debops.ruby
debops.ruby role installs selected Ruby version via APT package manager. By default APT picks the Ruby
packages to install automatically - if you have backported Ruby 2.1 packages, they will be installed if available; if you
don’t have them, debops.ruby will install current Ruby packages available on your system.
If you want to install Ruby 2.1 packages on Debian Wheezy, set ruby_version: ’backport’ in your inventory and this role will use debops.backporter role to automatically backport all required packages from Debian
Jessie. These packages will be installed on the build host and uploaded to Ansible Controller to a specific directory,
where debops.reprepro role can find them and automatically import them to local APT repository, at which point
these packages will become available to all hosts in a cluster.
This role will also install gems from RubyGems specified in a list.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
132
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
ansible-galaxy install debops.ruby
Role dependencies
• debops.apt_preferences
• debops.backporter
Role variables
List of default variables available in the inventory:
--# Specify version of Ruby to install:
# - ’apt’:
(default) will install Ruby packages automatically depending on
#
what’s available in APT at the time
#
# - ’backport’: will enable backporting of packages from the next distribution
#
(currently on Debian Wheezy it’s required to install Ruby 2.1
#
packages)
#
ruby_version: ’apt’
# Install ’rubygems-integration’ package (on older distributions it might not
# exist)
ruby_gems_integration: True
# Lists of additional APT packages to install with Ruby packages (for all
# hosts, group of hosts, specific host or role dependency). You can use these
# lists to for example install packaged gems.
ruby_packages: []
ruby_group_packages: []
ruby_host_packages: []
ruby_dependent_packages: []
# Lists of Ruby gems to install from RubyGems.org. Role will use conservative
# approach and not install or update any gems, that are already installed, either
# via gem or via APT.
ruby_default_gems: [ ’bundler’ ]
ruby_gems: []
ruby_group_gems: []
ruby_host_gems: []
ruby_dependent_gems: []
Authors and license
debops.ruby role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11. Ansible roles provided in DebOps
133
DebOps Documentation, Release master
2.11.50 debops.safekeep
This role will configure SafeKeep scripts to create daily, incremental, centralized backups on a specified server, based
on rdiff-backup.
Currently SafeKeep packages are not available in Debian repositories; you need to provide the packages to APT using
some other way, for example via local APT repository created using debops.reprepro role.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.safekeep
Role dependencies
• debops.secret
Role variables
List of default variables available in the inventory:
--# FQDN hostname of SafeKeep server to which other clients will be backed up
safekeep: ""
# Should SafeKeep be enabled for current (client) host?
safekeep_enabled: ’true’
# Retention time for incremental backup
safekeep_retention: ’7D’
# List of additional FQDN hosts to add to SafeKeep server ~/.ssh/known_hosts
# You should configure here hosts that are outside of Ansible cluster (not
# controlled by a playbook) that you want to backup using SafeKeep manually
safekeep_keyscan: []
# Shell script to execute on client host during various stages of backup
safekeep_script: ’/usr/local/sbin/safekeep-client.sh’
# Send mail about backups to these email addresses
safekeep_mail_to: [ ’backup’ ]
# Lists of paths, globs or regexps of files to exclude or include in backups
safekeep_exclude_path: [ ’/var/lock’, ’/var/run’, ’/var/tmp’ ]
safekeep_exclude_glob: [ ’/home/*/tmp’ ]
134
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
safekeep_exclude_regexp: []
safekeep_include_path: [ ’/etc’, ’/home’, ’/opt’, ’/root’, ’/srv’, ’/usr/local’, ’/var’ ]
safekeep_include_glob: []
safekeep_include_regexp: []
Authors and license
debops.safekeep role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.51 debops.salt
This role will install and configure SaltStack master service, which can be used to manage Salt minions. By default,
Salt master packages from upstream repositories will be installed and configured to listen on both IPv4 and IPv6
networks and will accept connections from all hosts; you can limit connections through the firewall using debops.ferm
role.
Table of Contents
• Role dependencies
• Role variables
• Authors and license
Role dependencies
• debops.ferm
• debops.etc_services
Role variables
List of default variables available in the inventory:
--# List of packages to install on Salt master host
salt_packages: [ ’salt-master’ ]
# Lists of IP addresses or network CIDR ranges allowed to connect to Salt
# master through the firewall. If lists are empty, anyone can connect.
salt_allow: []
salt_group_allow: []
salt_host_allow: []
# Configure Salt master using Ansible?
salt_configuration: True
# File with Ansible-generated Salt master configuration. If configuration is
# disabled, it will be automatically removed by Ansible on the next run.
2.11. Ansible roles provided in DebOps
135
DebOps Documentation, Release master
salt_configuration_file: ’/etc/salt/master.d/ansible.conf’
# By default Salt master listens for connections on all IPv6 and IPv4
# interfaces. If you want to disable IPv6, change the value to "0.0.0.0"
salt_interface: ’::’
# Enable/Disable IPv6 support in Salt master
salt_ipv6: True
# Ports configured in firewall for Salt master
salt_publish_port: ’4505’
salt_return_port: ’4506’
# Salt master worker multiplier
salt_worker_multiplier: 2
# Number of Salt master workers to run
salt_worker_threads: ’{{ (ansible_processor_cores | int * salt_worker_multiplier | int) }}’
# Additional Salt master options in YAML text block format
salt_options: False
Authors and license
debops.salt role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.52 debops.samba
This role installs and configures a Samba 3 file server with a default file share. You can configure your own shares
using inventory variables.
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.samba
Role dependencies
• debops.ferm
136
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Role variables
List of default variables available in the inventory:
--# Location of Samba shares
samba_path: ’/srv/samba’
samba_homes_path: ’{{ samba_path }}/home’
samba_shares_path: ’{{ samba_path }}/shares’
# Allow access to Samba through firewall for specified networks
# If samba_allow is undefined or False, allow access from all
samba_allow: []
samba_workgroup: ’WORKGROUP’
samba_netbios_name: ’{{ ansible_hostname }}’
samba_server_string: ’%h file server’
# Name of the /etc/init.d/ service script
samba_service_name: ’samba’
# Manage iptables modules automatically
samba_iptables: True
# Which hash variable is used to configure [global] section in smb.conf
samba_global: ’{{ samba_default_global }}’
# You can specify additional options in a separate hash
samba_global_custom: False
# Which hash variable is used to configure [homes] section in smb.conf
samba_homes: ’{{ samba_default_homes }}’
# Which hash of hashes is used to configure shares in smb.conf
samba_shares: ’{{ samba_default_shares }}’
# Default [global] configuration
samba_default_global:
# Browsing / Identification
workgroup: ’{{ samba_workgroup | default("WORKGROUP") }}’
netbios_name: ’{{ samba_netbios_name | default(ansible_hostname) }}’
server_string: ’{{ samba_server_string | default("%h file server") }}’
# Logs / Accounting
log_file: ’/var/log/samba/log.%m’
max_log_size: ’1000’
syslog: ’0’
# Authentication
security: ’user’
encrypt_passwords: ’yes’
passdb_backend: ’tdbsam’
unix_password_sync: ’no’
obey_pam_restrictions: ’yes’
invalid_users: ’root bin daemon adm sync shutdown halt mail news uucp proxy www-data backup sshd’
map_to_guest: ’Bad User’
guest_account: ’nobody’
2.11. Ansible roles provided in DebOps
137
DebOps Documentation, Release master
# File system / Directories
unix_charset: ’UTF8’
locking: ’yes’
wide_links: ’no’
browseable: ’yes’
create_mask: ’0660’
directory_mask: ’0770’
dont_descend: ’./lost+found’
use_sendfile: ’yes’
hide_unreadable: ’yes’
hide_files: ’/.*/lost+found/’
# Networking / Connections
socket_options: ’TCP_NODELAY SO_RCVBUF=8192 SO_SNDBUF=8192’
deadtime: ’10’
wins_support: ’no’
dns_proxy: ’no’
name_resolve_order: ’lmhosts host wins bcast’
# Disable printing by default
printing: ’bsd’
load_printers: ’no’
printcap_name: ’/dev/null’
show_add_printer_wizard: ’no’
disable_spoolss: ’yes’
# Default [homes] section
samba_default_homes:
path: ’{{ samba_homes_path }}/%S’
comment: ’Home Directory’
browseable: ’no’
read_only: ’no’
create_mask: ’0600’
directory_mask: ’0700’
valid_users: ’%S’
guest_ok: ’no’
root_preexec: ’/usr/local/sbin/samba-homedir.sh %S’
# Hash of hashes of default shares
samba_default_shares:
’Public Files’:
path: ’{{ samba_shares_path }}/public’
comment: ’Public Files’
read_only: ’yes’
guest_ok: ’yes’
Authors and license
debops.samba role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
138
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
2.11.53 debops.sftpusers
debops.sftpusers role can be used to create and manage user accounts which have system access restricted to
SFTP only.
Table of Contents
•
•
•
•
•
Installation
Role dependencies
Role variables
Detailed usage guide
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.sftpusers
Role dependencies
• debops.auth
Role variables
List of default variables available in the inventory:
--# ---- An example account entry ---# Everything except ’name’, ’dirs’ and ’sites’ is optional
# List of all recognized values, default value listed first
#
# - name: ’username’
# mandatory, default group if not defined
#
#
# Required, can be empty. Create directories in user home directory
#
dirs: [ ’files’, ’dir/subdir’, ’directory\ with\ spaces’ ]
#
#
# Required, can be empty. Prepare site directories for websites and mount
#
# them in the users’ home directory in $HOME/sites/
#
sites: [ ’example.com’, ’other.example.com’ ]
#
#
state: ’present,absent’
#
group: ’name’
# default group
#
gid: ’’
#
uid: ’’
#
comment: ’GECOS entry’
#
systemuser: False/True
# create system user
#
systemgroup: False/True
# create system group
#
#
home: ’/srv/sftpusers/name’
#
#
# Create ~/.forward file (set to False to remove ~/.forward)
2.11. Ansible roles provided in DebOps
139
DebOps Documentation, Release master
#
#
forward: [ ’[email protected]’, ’account’ ]
# ---- Lists of different accounts to create/manage ---# "Global" users
sftpusers_list: []
# "Host group" users
sftpusers_group_list: []
# "Host" users
sftpusers_host_list: []
# ---- Global defaults ---# Add a suffix to an account name, for example: ’-sftp’
sftpusers_name_suffix: ""
# System group that restricts account use to SFTPonly
sftpusers_system_group: ’sftponly’
# Shell enforced on all SFTPonly accounts
sftpusers_default_shell: ’/usr/sbin/nologin’
# List of groups SFTPonly users belong in
sftpusers_default_groups: [ ’{{ sftpusers_system_group }}’ ]
# Path to directory where websites are stored
sftpusers_default_www_prefix: ’/srv/www’
# System group which should be allowed access to website directory
sftpusers_default_www_group: ’www-data’
# Mount options used to mount website directories in user home directories
# (sftponly users don’t have access to directories outside of their home
# directory (/srv/sftpusers/username). Because of that website directories
# (/srv/www/username/sites/) will be bind mounted to their home directories
# (/srv/sftpusers/username/sites/), thus allowing secure access)
sftpusers_default_mount_options: ’bind’
# Directory where SFTPonly user homes will be created
sftpusers_default_home_prefix: ’/srv/sftpusers’
# UNIX permissions enforced on users home directories
sftpusers_default_home_mode: ’0750’
# List of default directories created on SFTPonly accounts (users don’t have
# permission to access their home directory due to SFTPonly constraints, but they
# can access subdirectories)
sftpusers_default_dirs: [ ’files’ ]
140
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Detailed usage guide
Access to SFTPonly accounts is allowed only using SSH public keys, but users cannot manage their own keys. Instead,
sshd server uses keys from /etc/ssh/authorized_keys/<user> for authorization. Use debops.sshkeys
role to manage these keys separately.
Authors and license
debops.sftpusers role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.54 debops.sks
SKS Keyserver is an OpenPGP/GnuPG key server. This role allows you to install and manage one or more keyservers
in a cluster. Specified host (by default first host in [debops_sks] Ansible group) will also be configured as a web
frontend to the cluster (nginx will be used as the frontend webserver).
You can use debops.sks role to create your own keyserver pool (and in extension your own OpenPGP Web of
Trust) or connect to an existing pool. In the latter case, role supports an option to not initialize the database by default,
in which case you can seed your local key database from a keyserver dump (which is a preferred option of connecting
to the existing pool because of the size of existing key database dumps).
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.sks
Role dependencies
• debops.ferm
• debops.etc_services
• debops.apt_preferences
• debops.nginx
Role variables
List of default variables available in the inventory:
2.11. Ansible roles provided in DebOps
141
DebOps Documentation, Release master
--# Automatically create keyserver database? Database will be empty
# If you want to seed the database with public GPG keys or connect to public
# SKS Keyserver network, you should set this variable to "False" and seed the
# database manually. See: http://keysigning.org/sks/
sks_autoinit: False
# GPG fingerprint of server administrator
sks_contact: ’’
# From header for outgoing mail
sks_from: ’PGP Key Server <[email protected]{{ ansible_fqdn }}>’
# DNS domain on which SKS frontend webserver should be configured
sks_domain: [ ’keyserver.{{ ansible_domain }}’ ]
# Ansible group of hosts which are included in SKS cluster
sks_cluster: ’{{ groups.debops_sks }}’
# List of inventory hosts which provide frontend web service
sks_frontends: [ ’{{ sks_cluster[0] }}’ ]
# List of hosts which can connect to hkp service. If this list is empty,
# anybody can connect.
sks_hkp_allow: []
# List of public SKS keyservers you want to peer with. It’s a list of simple
# lines, which allows you to include custom ports and comments (see sks(8)
# documentation). It’s good etiquette to ask someone for permission before you
# add their server to this list (and their server needs to have yours for the
# communication to work).
# You should probably connect only one of your private keyservers to the public
# keyserver network, your other servers will propagate the changes between
# themselves.
sks_public_list: []
# - name: ’keyserver.example.org’
#
port: ’{{ sks_recon_port }}’
#
email: ’Server Administrator <[email protected]’
#
gpg: ’0xDEADBEEF’
Authors and license
debops.sks role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.55 debops.slapd
This role installs and manages slapd, OpenLDAP server. It will automatically generate and store secure passwords
for administrator accounts and install useful scripts.
142
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Authors and license
Installation
This role requires at least Ansible v1.7. To install it, run:
ansible-galaxy install debops.slapd
Role dependencies
• debops.ferm
• debops.secret
• debops.tcpwrappers
Role variables
List of default variables available in the inventory:
--# ---- OpenLDAP BaseDN configuration ---# BaseDN value of the OpenLDAP server, based on DNS domain
slapd_basedn: ’{{ "dc=" + ansible_domain.split(".") | join(",dc=") }}’
# Length of passwords set on administrator accounts
slapd_password_length: ’128’
# Log level (see slapd-config(5) for detauls)
slapd_log_level: ’none’
# Default services enabled in /etc/default/slapd (change requires restart)
slapd_default_services: [ ’ldap:///’, ’ldapi:///’ ]
# ---- Network access to OpenLDAP server ---# Lists of hosts or CIDR networks which are allowed to access slapd service. If
# none are specified, any host can connect to OpenLDAP server
slapd_allow: []
slapd_group_allow: []
slapd_host_allow: []
# Default setting in /etc/hosts.allow if no hosts are specified in above lists
slapd_tcpwrappers_default: ’ALL’
# ---- Administrator accounts & passwords ----
2.11. Ansible roles provided in DebOps
143
DebOps Documentation, Release master
#
#
#
#
slapd passwords cannot be directly generated by Ansible; they are handled in
separate tasks during runtime. Here you can change the location of passwords
in debops.secret storage if needed, for example to point several slapd
servers to the same set of passwords.
# ==== cn=admin,cn=config ====
# Base path to BaseDN administrator password
slapd_config_admin_basepw: ’{{ secret + "/credentials/" + ansible_fqdn + "/slapd/cn=config/cn=admin,c
# Plaintext password of BaseDN administrator
slapd_config_admin_password: ’{{ slapd_config_admin_basepw + ".password" }}’
# Hash of BaseDN administrator password
slapd_config_admin_hash: ’{{ slapd_config_admin_basepw + ".hash" }}’
# ==== BaseDN administrator ====
# Distinguished Name of main administrator account
slapd_basedn_admin: ’{{ "cn=admin," + slapd_basedn }}’
# Base path to BaseDN administrator password
slapd_basedn_admin_basepw: ’{{ secret + "/credentials/" + ansible_fqdn + "/slapd/" + slapd_basedn + "
# Plaintext password of BaseDN administrator
slapd_basedn_admin_password: ’{{ slapd_basedn_admin_basepw + ".password" }}’
# Hash of BaseDN administrator password
slapd_basedn_admin_hash: ’{{ slapd_basedn_admin_basepw + ".hash" }}’
# ---- ldapscripts configuration ---# See templates/etc/ldapscripts/ldapscripts.conf for more information about
# these variables
# Enable ldapscripts support (install and configure ldapscripts)
slapd_ldapscripts: False
# LDAP server to configure
slapd_ldapscripts_server: ’ldap://localhost’
# Default BaseDN to use in ldapscripts
slapd_ldapscripts_suffix: ’{{ slapd_basedn }}’
# Oranizational Units for Groups, Users and Machines
slapd_ldapscripts_gsuffix: ’ou=Groups’
slapd_ldapscripts_usuffix: ’ou=Users’
slapd_ldapscripts_msuffix: ’ou=Machines’
# BindDN admin account and file with password
slapd_ldapscripts_binddn: ’{{ slapd_basedn_admin }}’
slapd_ldapscripts_bindpwdfile: ’/etc/ldapscripts/ldapscripts.passwd’
# Where to look for admin account password
slapd_ldapscripts_password_lookup: ’{{ slapd_basedn_admin_password }}’
# Groups, User and Machine
144
start IDs
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
slapd_ldapscripts_gidstart: ’10000’
slapd_ldapscripts_uidstart: ’10000’
slapd_ldapscripts_midstart: ’20000’
# Group membership management
# Possible values: posixGroup, groupOfNames, groupOfUniqueNames
slapd_ldapscripts_gclass: ’posixGroup’
slapd_ldapscripts_gdummymember: ’uid=dummy,$USUFFIX,$SUFFIX’
# User password generation
slapd_ldapscripts_passwordgen: ’pwgen’
List of internal variables used by the role:
slapd_register_config_admin_hash
slapd_register_basedn_admin_hash
Authors and license
debops.slapd role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.56 debops.smstools
This is an Ansible role which configures smstools package and sets up a TCP -> SMS and mail -> SMS gateway. This
role has been tested on Debian and should work on Debian-based systems.
Several other roles from DebOps project are used to configure various parts of the SMS gateway
(debops.postfix role is used to create mail -> SMS gateway, debops.etc_services, debops.ferm and
debops.tcpwrappers are used to configure TCP service which can be used by other hosts to send SMS messages
over the network).
Table of Contents
•
•
•
•
Installation
Role dependencies
Role variables
Detailed usage guide
– Sending a text message from command line
– Sending a text message using TCP service
– Sending a text message over mail
– Warning, this role can generate mail backscatter!
– Known bugs
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
2.11. Ansible roles provided in DebOps
145
DebOps Documentation, Release master
ansible-galaxy install debops.smstools
Role dependencies
• debops.ferm
• debops.etc_services
• debops.postfix
• debops.tcpwrappers
• debops.rsyslog
Role variables
List of default variables available in the inventory:
--# ---- TCP -> SMS gateway ---# List of IP addresses or CIDR network ranges which are allowed to access TCP
# service
smstools_service_allow: []
# ---- mail -> SMS gateway ---# Settings for subdomains and domains which are used to send messages to SMS
# gateway
# Subdomain for SMS transport
smstools_mail_transport_subdomain: ’sms’
# Subdomain for mail aliases which are resolved to mobile numbers
smstools_mail_alias_subdomain: ’gsm’
# Domains that combine above subdomains with main host domain
smstools_mail_transport_domain: ’{{ smstools_mail_transport_subdomain }}.{{ ansible_domain }}’
smstools_mail_alias_domain: ’{{ smstools_mail_transport_subdomain }}.{{ ansible_domain }}’
# List of default mail senders that are allowed to send mail messages to mobile
# recipients
# Options:
#
- name: ’[email protected]’
# required
#
state: ’permit/deny’
# optional
smstools_default_senders:
- name: ’[email protected]{{ ansible_domain }}’
- name: ’{{ ansible_ssh_user }}@{{ ansible_domain }}’
# Additional list of mail senders
smstools_senders: []
# Hash table which specifies mail alias to mobile number mapping. Aliases will
# be generated in a domain specified with smstools_mail_alias_* variables
smstools_mail_recipients: {}
#’recipient1’: [ ’+00123123123’ ]
146
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
#’recipient2’: [ ’+00123123123’, ’+00321321321’ ]
# Hash table which specifies aliases for groups of recipients from
# smstools_mail_recipients table. Aliases will be created in a domain specified
# with smstools_mail_alias_* variables
smstools_mail_aliases: {}
#’alias’: [ ’recipient1’, ’recipient2’ ]
# List of regexps which will be used to find and remove strings in SMS messages
# before they are sent
smstools_mail_msgdel_list: []
#- ’linux’
#- ’^Ansible’
# Log sent SMS messages for accounting purposes, use monthly log rotation, logs
# should be kept for 2 years
smstools_sms_log: ’/var/log/sms.log’
smstools_sms_log_rotation: ’monthly’
smstools_sms_log_rotation_interval: ’{{ (12 * 2) }}’
# ---- SMS gateway testing ---# List of mobile numbers to send a test message to on host reboot
# Example: [ ’+00123123123’ ]
smstools_test_recipients: []
# Test message to send on host reboot
smstools_test_message: ’This is a test of the SMS gateway on {{ ansible_fqdn }} sent at $(date)’
# ---- smstools options ---# Time between queue checks, in seconds
smstools_sleep: 1
# Generate modem stats once a day
smstools_stats_interval: ’{{ (60 * 60 * 24)|round|int }}’
# Hash with options configured in /etc/smsd.conf
smstools_global_options:
delaytime: ’{{ smstools_sleep }}’
delaytime_mainprocess: ’{{ smstools_sleep }}’
receive_before_send: no
autosplit: 3
loglevel: 5
# List of modems known to smsd, by default it’s configured to use one modem on
# serial interface
smstools_devices:
- name: ’GSM1’
device: ’/dev/ttyS0’
options:
baudrate: 115200
incoming: yes
2.11. Ansible roles provided in DebOps
147
DebOps Documentation, Release master
Detailed usage guide
Sending a text message from command line
You can send SMS messages from the host connected to the GSM modem, by running command:
sudo -u smsd sendsms +00123123123 "Text message"
Your user needs to be in sms system group or needs to be able to run /usr/local/bin/sendsms script (for
example have admin access).
Sending a text message using TCP service
SMS messages can be sent remotely using TCP service (by default configured on port 9898). Access to the service is
protected using tcpwrappers (via xinetd service) and iptables firewall.
To send a text message using TCP service, connect to port 9898 (by default) and send string similar to (notice lack of
quotation marks):
TEXT +00123123123 Text message
TCP service should respond with text ending with 250 SMS accepted (if formatting was correct), or 500
Command not recognized (if formatting was incorrect).
Example telnet session which sends SMS message from a localhost:
$ telnet localhost sms
Trying 127.0.0.1...
Connected to localhost.
Escape character is ’^]’.
TEXT +00123123123 Text message
-Text: Text message
To: +00123123123
250 SMS accepted
Connection closed by foreign host.
Sending a text message over mail
debops.smstools role configures two subdomains in local Postfix instance:
• sms. subdomain is responsible for mail to SMS transport, Postfix takes mail messages sent to that subdomain
and passes them to sms service (configured in /etc/postfix/master.cf which is a script that parses the
mail message and sends body of that message to specified recipient using sendsms script;
• gsm. subdomain is used for aliases which correspond to addresses in the sms. subdomain or groups of aliases
in the same subdomain;
To send a SMS message via mail, send a mail to an address <[email protected]> (on localhost)
or <[email protected]> (from elsewhere).
You can also create mail aliases using
debops.smstools role variables or your configured alias table in format <[email protected]> (from localhost) or
<[email protected]> (from elsewhere) which should correspond to mail addresses outlined previously.
Subject of the mail message will be ignored, and body of the message will be sent using SMS gateway.
148
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Warning, this role can generate mail backscatter!
At the moment, SMTP server is configured by debops.smstools role to accept mail messages to subdomains
specified above and relay them to sms transport which checks if a sender of mail message can send SMS messages
through mail. If it can’t, SMTP server receives a reject message and generates a bounce message to an original sender
of the mail, which can be forged, generating mail backscatter.
Because of that risk, at the moment mail -> SMS gateway should be configured on a separate host behind a trusted
mail relay to avoid receiving messages from unknown mail senders, and should only process mail messages from hosts
included in mynetworks Postfix configuration variable.
To fix backscatter issue, debops.smstools role needs to have an external Postfix access policy service which will
be used by Postfix to check if a specific mail sender can send SMS messages using the gateway. Steps to determine
that:
• check recipient domain of a mail message,
• if recipient domain is one of the supported subdomains (sms. or gsm.), check mail address or domain of the
sender against list of allowed senders,
• if mail sender can send SMS messages, return PERMIT (or DUNNO if other checks should be performed),
• if mail sender is not found, return REJECT,
• otherwise (mail recipient not in a supported domain), return DUNNO to allow other checks to perform.
Policy service check should be included in smtpd_recipient_restrictions list to be able to check both
recipient and sender addresses.
Known bugs
• sendsms script supports sending SMS messages in UTF-8, but sms-service and sms-transport scripts
do not, SMS messages are truncated at first UTF-8 character.
Authors and license
debops.smstools role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.57 debops.sshd
This role configures OpenSSH server for public key access, disables password authentication and creates a specific
configuration options for sftponly accounts.
Table of Contents
•
•
•
•
•
Installation
Role dependencies
Usage tips
Role variables
Authors and license
2.11. Ansible roles provided in DebOps
149
DebOps Documentation, Release master
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.sshd
Role dependencies
• debops.ferm
• debops.sshkeys
• debops.auth
• debops.tcpwrappers
Usage tips
By default, sshd creates a firewall rule to limit access by ssh. If you believe you should be able to access a server and
you can ping it but not ssh, connect to the machine by other means and check if you are blocked. you can do this
with the command cat /proc/net/xt_recent/badguys. You can get there if you try too many connection
attempts at a short time. You can also check the dmesg log file. Unsuccessful logging attempts are logged there.
Role variables
List of default variables available in the inventory:
--# List of IP addresses or CIDR networks to allow access to SSH without
# restrictions.
# They will be configured in iptables (via ferm) and /etc/hosts.allow (via
# tcpwrappers).
sshd_allow: []
sshd_group_allow: []
sshd_host_allow: []
# By default SSH access from unknown IP addresses is limited and filtered by
# iptables, you can disable this by changing variable below to ’true’. You will
# have to enable access in iptables and tcpwrappers from any IP address
# separately.
sshd_unlimited_access: ’false’
sshd_Port: 22
sshd_PermitRootLogin: ’without-password’
sshd_PasswordAuthentication: ’no’
sshd_X11Forwarding: ’no’
sshd_AllowGroups: ’root admins sshusers sftponly’
sshd_authorized_keys: ’/etc/ssh/authorized_keys’
sshd_authorized_keys_monkeysphere: ’/var/lib/monkeysphere/authorized_keys/%u’
sshd_authorized_keys_global: ’{{ sshd_authorized_keys }}/%u’
sshd_authorized_keys_user: ’%h/.ssh/authorized_keys %h/.ssh/authorized_keys2’
sshd_known_hosts: []
150
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Authors and license
debops.sshd role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.58 debops.sshkeys
debops.sshkeys role can be used to manage users SSH keys in /etc/ssh/authorized_keys/ directory. This role is required for SFTPonly accounts created by debops.sftpusers role to disallow access to
~/.ssh/authorized_keys for users themselves.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.sshkeys
Role variables
List of default variables available in the inventory:
--# System-wide authorized_keys directory
sshkeys_path: ’/etc/ssh/authorized_keys’
# Lists of authorized_keys entries for users
# They will be put in /etc/ssh/authorized_keys/ directory per user
# Format is the same for all lists
# List for "global" entries
sshkeys_list: []
##
#
#
name: ’username’
sshkeys: [ ’ssh-rsa AAAAB3NzaC1...’, ’{{ lookup("file","~/.ssh/id_rsa.pub") }}’ ]
options: ’key-options’ # optional
state: ’present’
# optional, choice: present,absent
# List for "group" entries (only 1 group at a time)
sshkeys_group_list: []
# List for "host" entries
sshkeys_host_list: []
2.11. Ansible roles provided in DebOps
151
DebOps Documentation, Release master
Authors and license
debops.sshkeys role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.59 debops.subnetwork
debops.subnetwork is an Ansible role that creates and manages a local network behind a bridge interface. It
could also manage internal router interfaces to a LAN. You can specify an IPv4 subnet and one or more IPv6 subnets
to configure it, the role will automatically configure basic forwarding in any firewall and NAT for the IPv4 network.
This role requires ipaddr() filter plugin which is available in debops/debops-playbooks.
Table of Contents
• Role dependencies
• Role variables
• Authors and license
Role dependencies
• debops.ferm
• debops.ifupdown
Role variables
List of default variables available in the inventory:
--# ---- Network interfaces and firewall ---# Network interface to configure, by default a bridge
subnetwork_iface: ’br2’
# Network interfaces to attach to a bridge on ifup
subnetwork_bridge_ports: [ ’none’ ]
# Enable packet forwarding from internal network to the outside world
subnetwork_forwarding: True
# ---- IPv4 network ---# IPv4 address set at the interface, in the ’host/prefix’ format. It should be
# an address of local network gateway, for example ’192.0.2.1/24’. Only one
# IPv4 address is supported
subnetwork_ipv4: ’’
# Should IPv4 network be configured behind NAT? You might want to disable this
# and configure routing elsewhere if you have public IPv4 subnet
152
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
subnetwork_ipv4_nat: True
# Should IPv4 traffic from internal network be masqueraded? If disabled, static
# SNAT with default IPv4 address of the gateway will be configured instead.
# Leave it True if you use a laptop or change networks frequently
subnetwork_ipv4_nat_masquerade: True
# Network interface to the default IPv4 gateway
subnetwork_ipv4_gateway: ’{{ ansible_default_ipv4.interface | default("") }}’
# Additional options passed to the ifupdown configuration for IPv4 network,
# in YAML text block format
subnetwork_ipv4_options: ’’
# ---- IPv6 network ---# List of IPv6 addresses configured at the interface (multiple IPv6 addresses
# are supported). You can configure here your own IPv6 prefixes from the
# upstream router. If you don’t have your own prefixes, you can set an ULA
# prefix instead, for example from http://unique-local-ipv6.com/
# CIDR /64 prefix is preferred for local network,
# You need to specify addresses in ’host/prefix’ format, with IPv6 address of
# the gateway (ending with ’::1’), for example: [ ’2001:db8:2c33:deb0::1/64’ ]
subnetwork_ipv6: []
# Network interface to the default IPv6 gateway
subnetwork_ipv6_gateway: ’{{ ansible_default_ipv6.interface | default("") }}’
# Additional options passed to the ifupdown configuration for IPv6 network,
# in YAML text block format
subnetwork_ipv6_options: ’’
# ---- ifupdown interface templates ---# List of additional interfaces to configure before the main bridge
subnetwork_ifupdown_prepend_interfaces: []
# List of network interfaces to configure for the local network
subnetwork_ifupdown_interfaces:
# IPv4 network + bridge
- iface: ’{{ subnetwork_iface }}’
type: ’{% if subnetwork_iface | search("^br*") %}bridge{% else %}interface{% endif %}’
inet: ’{% if subnetwork_ipv4 | ipv4("host/prefix") %}static{% else %}manual{% endif %}’
filename: ’subnetwork_{{ subnetwork_iface }}_ipv4’
weight: ’40’
options: |
{% if subnetwork_ipv4 | ipv4(’host/prefix’) %}
address
{{ subnetwork_ipv4 | ipaddr(’address’) }}
network
{{ subnetwork_ipv4 | ipaddr(’network’) }}
netmask
{{ subnetwork_ipv4 | ipaddr(’netmask’) }}
broadcast
{{ subnetwork_ipv4 | ipaddr(’broadcast’) }}
{% endif %}
{% if subnetwork_iface | search(’^br.*’) %}
bridge_ports
{{ subnetwork_bridge_ports | join(’ ’) }}
bridge_stp
on
2.11. Ansible roles provided in DebOps
153
DebOps Documentation, Release master
bridge_fd
0
bridge_maxwait 0
{% endif %}
{% if subnetwork_ipv4_options %}
{{ subnetwork_ipv4_options }}
{% endif %}
# IPv6 network
- iface: ’{{ subnetwork_iface }}’
type: ’interface’
inet6: ’{% if subnetwork_ipv6 | unique | ipv6("host/prefix") %}static{% else %}manual{% endif %}’
filename: ’subnetwork_{{ subnetwork_iface }}_ipv6’
weight: ’40’
auto: False
force: True
options: |
pre-up echo 0 > /proc/sys/net/ipv6/conf/{{ subnetwork_iface }}/accept_dad
{% set subnetwork_var_ipv6_subnets = subnetwork_ipv6 | unique | ipv6(’host/prefix’) %}
{% if subnetwork_var_ipv6_subnets %}
address {{ subnetwork_var_ipv6_subnets[0] }}
{% if subnetwork_var_ipv6_subnets | length > 1 %}
{% for subnet in subnetwork_var_ipv6_subnets[1:] %}
up
/sbin/ip address add {{ subnet }} dev {{ subnetwork_iface }}
down /sbin/ip address del {{ subnet }} dev {{ subnetwork_iface }}
{% endfor %}{% endif %}
{% endif %}
{% if subnetwork_ipv6_options %}
{{ subnetwork_ipv6_options }}
{% endif %}
Authors and license
debops.subnetwork role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.60 debops.tcpwrappers
This role can be used to manage TCP Wrappers rules located in /etc/hosts.allow (by default all hosts will be
denied access in /etc/hosts.deny, but this can be disabled by a variable).
Other roles can use this role as a dependency to manage access to their own services (for example, debops.mysql,
debops.sshd).
By default, tcpwrappers will be configured to block access from everywhere except localhost (relative to remote
host) and Ansible Controller.
Table of Contents
• Installation
• Role variables
• Authors and license
154
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.tcpwrappers
Role variables
List of default variables available in the inventory:
--# Should Ansible manage tcpwrappers configuration?
tcpwrappers: True
# Optional list of CIDR hosts which will be allowed to connect to sshd service.
# Entries are saved in the local facts on remote hosts.
# Remember to specify IP address from the remote host point of view.
# Format: "IP address/netmask", for example: ’192.168.1.1/32’
tcpwrappers_ansible_controllers: []
# Deny access from all hosts/networks by default?
tcpwrappers_deny_all: True
# Lists of /etc/hosts.allow entries. Example entry below
tcpwrappers_allow: []
tcpwrappers_group_allow: []
tcpwrappers_host_allow: []
#- daemon: ’ALL’
# client: []
#
#
#
weight: ’10’
filename: ’’
comment: ’’
#- custom: |
#
# Custom entry
#
# Text block
# filename: ’custom_entry’
#
#
#
#
#
#
daemon to configure (sshd, mysqld, etc.)
list of host or network addresses.
If empty, entry will be removed
filename prefix, helps with sorting, optional
custom filename, optional
comment, optional
# custom, free-form text block (filename required)
# Access from localhost
tcpwrappers_local_allow:
- daemon: ’ALL’
client: [ ’127.0.0.0/8’, ’[::1]/128’ ]
comment: ’Access from localhost’
filename: ’allow_localhost’
weight: ’06’
Authors and license
debops.tcpwrappers role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11. Ansible roles provided in DebOps
155
DebOps Documentation, Release master
2.11.61 debops.users
This role can be used to manage user accounts (and user groups). You can manage almost all aspects of the users’
account, like UID/GID, home directory, shell, etc. Accounts are configured using lists in Ansible inventory, with
separate lists for:
• admin accounts;
• global list of users created on each host in a cluster;
• list of users created on a group of hosts;
• list of users created on a specific host;
debops.users is meant as a simple way to create a few dozen accounts max, for larger number of accounts its
preferred to use a dedicated solution, like an LDAP directory.
Table of Contents
• Installation
• Role variables
• Authors and license
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.users
Role variables
List of default variables available in the inventory:
--# Should Ansible manage user accounts? Set to False to disable
users: True
# --- Lists of different accounts to create/manage --# root user, if you want to change something on the root account
users_root:
- name: ’root’
# Default user created by Ansible
users_default:
- name: ’{{ ansible_ssh_user }}’
# Administrators
users_admins: []
# Groups (normal or system)
users_groups: []
# "Global" users
users_list: []
156
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# "Host group" users
users_group_list: []
# "Host" users
users_host_list: []
# --- An example account entry, everything except ’name’ is optional
# List of all recognized values, default value listed first
#
# - name: ’username’
# mandatory, default group if not defined
#
state: ’present,absent’
#
group: ’name’
# default group
#
groups: []
# list of groups to set
#
append: yes/no
# add to, or set groups
#
gid: 1000
#
uid: 1000
#
shell: ’/bin/sh’
#
comment: ’GECOS entry’
#
systemuser: False/True
# create system user
#
systemgroup: False/True
# create system group
#
#
dotfiles: False/True
# download and configure dotfiles?
#
dotfiles_repo: ’repository’
#
dotfiles_command: ’make all’
#
dotfiles_creates ’~/.zshrc’
#
#
# Create ~/.forward file (set to False to remove ~/.forward)
#
forward: [ ’[email protected]’, ’account’ ]
#
#
# Add or disable ssh authorized keys (set to False to remove ~/.ssh/authorized_keys
#
sshkeys: [ ’list’, ’of’, ’keys’ ]
# --- Global defaults --# Default shell used for new accounts
users_default_shell: ’/bin/bash’
# List of default groups added to new accounts
users_default_groups_list: []
# Should default groups be added to existing groups, or replace existing
# groups?
users_default_groups_append: ’yes’
# Path to directory where home directories for new users are created
users_default_home_prefix: ’/home’
# Default state of dotfiles on all accounts managed by Ansible
# False - dotfiles are not configured by default
# True - dotfiles will be configured by default
users_default_dotfiles: False
# Default dotfile hash to use
users_default_dotfiles_key: ’drybjed’
# List of dotfile hashes
2.11. Ansible roles provided in DebOps
157
DebOps Documentation, Release master
users_dotfiles:
drybjed:
repo: ’https://github.com/drybjed/dotfiles.git’
command: ’make install’
creates: ’~/.zshrc’
Authors and license
debops.users role was written by:
• Maciej Delmanowski | e-mail | Twitter | GitHub
License: GPLv3
2.11.62 debops.postfix
Introduction
debops.postfix is an Ansible role which installs and manages Postfix, an SMTP server. It is designed to manage
Postfix on different hosts in a cluster, with different “capabilities”.
Features
At the moment role can configure Postfix to act as:
• a null client: Postfix sends all mail to another system specified either via DNS MX records or an Ansible
variable, no local mail is enabled (this is the default configuration);
• a local SMTP server: local mail is delivered to local user accounts;
• a network SMTP server: network access is enabled separately from other capabilities, to avoid exposing misconfigured SMTP server by mistake and becoming an open relay;
• an incoming MX gateway: Postfix will listen on the port 25 (default SMTP port) and process connections using
postscreen daemon with automatic greylisting and optional RBL checking;
• an outgoing SMTP client: Postfix will relay outgoing mail messages to specified remote MX hosts, you can
optionally enable SMTP client authentication, passwords will be stored separate from the inventory in secret/
directory (see debops.secret role). Sender dependent authentication is also available.
More “capabilities” like user authentication, support for virtual mail, spam/virus filtering and others will be implemented in the future.
This role can also be used as a dependency of other roles which then can enable more features of the Postfix SMTP
server for their own use. For example, debops.mailman role enables mail forwarding to the configured mailing
lists, and debops.smstools role uses Postfix as mail-SMS gateway.
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.postfix
158
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Role dependencies
• debops.ferm
• debops.secret
Getting started
An example playbook which uses debops.postfix role:
--- name: Manage Postfix instance
hosts: all
roles:
- role: debops.postfix
tags: postfix
This playbook should install postfix package along with its dependencies, and configure the service with default
values generated by Ansible.
Default variables
Sections
•
•
•
•
•
•
•
•
•
•
General Postfix configuration
PKI / TLS configuration
Firewall configuration
Postfix SMTP client options
Mail archive options
Anti-spam configuration
Postfix SMTPD restrictions
Mail aliases
Postfix custom configuration
Mail service debugging
General Postfix configuration
Configuration options for Postfix. Many options are configured automatically using templates, here you can (mostly)
add your own entries to Postfix lists (look in Postfix manual for details), they will by added or replaced in templates.
postfix
List of active Postfix capabilities. By default Postfix is configured with local mail disabled, all mail is sent to local
MX server configured in DNS. See postfix_capabilities for more details.
postfix: [ ’null’ ]
postfix_relayhost
Address of mail host this host should relay all mail to instead of delivering it directly. (Automatic configuration)
2.11. Ansible roles provided in DebOps
159
DebOps Documentation, Release master
postfix_relayhost: False
postfix_mailname
Mail host name configured in /etc/mailname
postfix_mailname: ’{{ ansible_fqdn }}’
postfix_mydomain
Domain name to use for outgoing mail messages
postfix_mydomain: ’{{ ansible_domain }}’
postfix_delay_warning_time
How long to wait before notifying users about delivery problems
postfix_delay_warning_time: ’4h’
postfix_relay_domains
List of relay domains this host accepts
postfix_relay_domains: []
postfix_inet_interfaces
On what interfaces Postfix should listen to by default (not a list). (Automatic configuration)
postfix_inet_interfaces: False
postfix_mydestination
List of local domains accepted by Postfix. (Automatic configuration)
postfix_mydestination: []
postfix_mynetworks
List of networks Postfix accepts by default. (localhost is always enabled)
postfix_mynetworks: []
postfix_transport_maps
List of Postfix transport maps. (Automatic configuration)
postfix_transport_maps: []
postfix_virtual_alias_maps
List of Postfix virtual alias maps. (Automatic configuration)
postfix_virtual_alias_maps: []
postfix_message_size_limit
Message size limit in megabytes
postfix_message_size_limit: 50
160
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
PKI / TLS configuration
postfix_pki
Enable or disable support for TLS in Postfix (using debops.pki)
postfix_pki: True
postfix_pki_path
Base PKI directory
postfix_pki_path: ’{% if (ansible_local is defined and ansible_local.pki is defined) %}{{ ansible_loc
postfix_pki_realm
Default PKI realm used by Postfix
postfix_pki_realm: ’{% if (ansible_local is defined and ansible_local.pki is defined) %}{{ ansible_lo
postfix_pki_crt
Default certificate, relative to postfix_pki_realm variable
postfix_pki_crt: ’default.crt’
postfix_pki_key
Default private key, relative to postfix_pki_realm variable
postfix_pki_key: ’default.key’
postfix_pki_dhparam
Default Diffie-Hellman parameters file (2048 bits), relative to postfix_pki_realm variable
postfix_pki_dhparam: ’dhparam.pem’
Firewall configuration
If network and any of needed Postfix capabilities are enabled, all hosts can send mail to this Postfix instance. You
can limit access to specific hosts or networks using postfix_allow_* variables.
postfix_allow_smtp
List of hosts/networks that can access smtp port (25)
postfix_allow_smtp: []
postfix_allow_submission
List of hosts/networks that can access submission port (587)
postfix_allow_submission: []
postfix_allow_smtps
List of hosts/networks that can access smtps port (465), deprecated.
postfix_allow_smtps: []
2.11. Ansible roles provided in DebOps
161
DebOps Documentation, Release master
Postfix SMTP client options
postfix_smtp_sasl_password_map
Map of SMTP SASL passwords used in SMTP client authentication by Postfix. You need to add client in Postfix
capabilities to enable this feature. See postfix_smtp_sasl_password_map for more details.
postfix_smtp_sasl_password_map: {}
postfix_sender_dependent_relayhost_map
Map of sender dependent relayhosts used in SMTP client mail relay by Postfix. You need to add client and
sender_dependent in Postfix capabilities to enable this feature.
postfix_sender_dependent_relayhost_map: {}
Example entries:
’<sender-address>’: ’<relay-host>’
’[email protected]’: ’[smtp.example.org]:submission’
Mail archive options
Archiving is enabled by archive option in Postfix capabilities. Remember that an archive account on the receiving
server needs to exist.
postfix_archive_method
How Postfix should redistribute archived messages:
• all: send all mail without sorting
• domain: send mail sorted by domain
• domain-account: send mail sorted by domain and account, divided by separator
postfix_archive_method: ’all’
postfix_archive_to
Optional address of a mail account to send the archived mails to. If not specified, Ansible will generate an address by
itself in format:
• <postfix_archive_account>@<ansible_fqdn> (if local mail is enabled)
• <postfix_archive_account>@<postfix_archive_subdomain>.<ansible_domain> (if local mail is disabled).
postfix_archive_to: ’’
postfix_archive_account
Mail account to send archived mail to (used by Ansible to generate archive address).
postfix_archive_account: ’mail-archive’
postfix_archive_subdomain
Subdomain part of a domain used to generate archive address, if local mail is not enabled in Postfix capabilities (dot
at the end is required).
162
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
postfix_archive_subdomain: ’archive.’
postfix_archive_separator
Character used to separate domain and account part in sorted archive mails. If you use virtual mail delivery, you can
sort mail into subdirectories by setting separator as ‘/’ (does not work on local mail delivery).
postfix_archive_separator: ’=’
postfix_archive_domains
List of domains to archive. If it’s empty, everything is archived.
postfix_archive_domains: []
Anti-spam configuration
postfix_postscreen_dnsbl_sites
List of DNS Blacklists enabled in postscreen service. Disabled by default. To enable blacklists, you need to add
dnsbl in Postfix capabilities.
postfix_postscreen_dnsbl_sites:
# Spamhaus ZEN: http://www.spamhaus.org/zen/
# Might require registration
- ’zen.spamhaus.org*3’
# Barracuda Reputation Block List: http://barracudacentral.org/rbl
# Requires registration
#- ’b.barracudacentral.org*2’
#
#
-
Spam Eating Monkey: http://spameatingmonkey.com/lists.html
Might require registration
’bl.spameatingmonkey.net*2’
’backscatter.spameatingmonkey.net*2’
# SpamCop Blocking List: http://www.spamcop.net/bl.shtml
- ’bl.spamcop.net’
# Passive Spam Block List: http://psbl.org/
- ’psbl.surriel.com’
# mailspike: http://mailspike.net/usage.html
# Might require contact
- ’bl.mailspike.net’
postfix_postscreen_dnswl_sites
List of DNS Whitelists enabled in postscreen service. Disabled by default. To enable whitelists, you need to add
dnswl in Postfix capabilities.
postfix_postscreen_dnswl_sites:
# SpamHaus Whitelist: http://www.spamhauswhitelist.com/en/usage.html
# Might require registration
- ’swl.spamhaus.org*-4’
# DNS Whitelist: http://dnswl.org/tech
2.11. Ansible roles provided in DebOps
163
DebOps Documentation, Release master
#
-
Might require registration
’list.dnswl.org=127.[0..255].[0..255].0*-2’
’list.dnswl.org=127.[0..255].[0..255].1*-3’
’list.dnswl.org=127.[0..255].[0..255].[2..255]*-4’
Postfix SMTPD restrictions
debops.postfix creates a base set of various smtpd restrictions by itself, to protect the SMTP server against spam.
However this functionality is currently basic. Using lists below you can define your own set of smtpd restrictions,
which will override anything generated automatically by the role.
postfix_smtpd_client_restrictions
Client restrictions, processed at the connection stage
postfix_smtpd_client_restrictions: []
postfix_smtpd_helo_restrictions
Hello restrictions, processed at HELO/EHLO stage
postfix_smtpd_helo_restrictions: []
postfix_smtpd_sender_restrictions
Sender restrictions, processed at MAIL FROM stage
postfix_smtpd_sender_restrictions: []
postfix_smtpd_relay_restrictions
Relay restrictions (currently not supported in the role)
postfix_smtpd_relay_restrictions: []
postfix_smtpd_recipient_restrictions
Recipient restrictions, processed at RCPT TO stage
postfix_smtpd_recipient_restrictions: []
postfix_smtpd_data_restrictions
Data restrictions, processed at DATA stage
postfix_smtpd_data_restrictions: []
Mail aliases
Postfix role automatically manages /etc/aliases file with a set of default aliases redirected to root and staff
accounts.
postfix_default_local_alias_recipients
List of default recipients for local aliases which have no recipients specified, by default current $USER managing
Ansible
postfix_default_local_alias_recipients: [’{{ lookup("env","USER") }}’]
postfix_local_aliases
164
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Hash of local aliases which will be merged with default aliases in vars/main.yml
postfix_local_aliases: {}
Examples:
’alias’: [ ’account1’, ’account2’ ]
’other’: [ ’[email protected]’, ’"|/dir/command"’ ]
’blackhole’: [ ’/dev/null’ ]
’send_to_default_recipients’: []
Postfix custom configuration
postfix_local_maincf
Custom Postfix configuration added at the end of /etc/postfix/main.cf in a text block format
postfix_local_maincf: False
postfix_local_mastercf
Custom Postfix configuration added at the end of /etc/postfix/master.cf in a text block format
postfix_local_mastercf: False
postfix_dependent_lists
This variable can be used in Postfix dependency role definition to configure additional lists used in Postfix main.cf configuration file. This variable will be saved in Ansible facts and updated when necessary. See postfix_dependent_lists
for more information.
postfix_dependent_lists: {}
postfix_dependent_maincf
Here you can specify Postfix configuration options which should be enabled in /etc/postfix/main.cf using
debops.postfix dependency role definition. Configuration will be saved in Ansible facts and updated when necessary.
See postfix_dependent_maincf for more information.
postfix_dependent_maincf: []
postfix_dependent_mastercf
This list can be used to configure services in Postfix master.cf using Postfix dependency variables. Configured services
will be saved in Ansible facts and updated when necessary. See postfix_dependent_mastercf for more information.
postfix_dependent_mastercf: []
Mail service debugging
postfix_smtpd_authorized_xclient_hosts
List of clients and networks which will have access to XCLIENT protocol extension when test Postfix capability is
enabled.
postfix_smtpd_authorized_xclient_hosts: [ ’127.0.0.1/32’ ]
2.11. Ansible roles provided in DebOps
165
DebOps Documentation, Release master
Default variables: configuration
some of debops.postfix default variables have more extensive configuration than simple strings or lists, here you
can find documentation and examples for them.
•
•
•
•
•
postfix_capabilities
postfix_smtp_sasl_password_map
postfix_dependent_lists
postfix_dependent_maincf
postfix_dependent_mastercf
postfix_capabilities
List of active Postfix capabilities. By default Postfix is configured with local mail disabled, all mail is sent to local
MX server configured in DNS.
List of available Postfix capabilities:
null Enabled by default. Postfix has no local delivery, all mail is sent to a MX for current domain. These settings
are based on Postfix null client configuration.
You should remove this capability and replace it with others presented below.
local local delivery is enabled on current host.
network enables access to Postfix-related ports (25, 587, 465) in firewall, required for incoming mail to be acceped
by Postfix.
mx enables support for incoming mail on port 25, designed for hosts set up as MX. Automatically enables
postscreen (without dnsbl/dnswl support), anti-spam restrictions.
submission enables authorized mail submission on ports 25 and 587 (user authentication is currently not supported and needs to be configured separately).
deprecated designed to enable obsolete functions of mail system, currently enables authorized mail submission
on port 465 (when submission is also present in the list of capabilities).
client enable SASL authentication for SMTP client (for outgoing mail messages sent via relayhosts that require
user authentication).
sender_dependent enable sender dependent SMTP client authentication (client capability required)
archive BCC all mail (or mail from/to specified domains) passing through the SMTP server to an e-mail account
on local or remote server.
postscreen allows to enable postscreen support on port 25 independently of mx capability.
dnsbl enables support for DNS blacklists in postscreen, automatically enables whitelists.
dnswl enables support for DNS whitelists in postscreen, without blacklists.
test enables “soft_bounce” option and XCLIENT protocol extension for localhost (useful in mail system testing).
defer planned feature to defer mail delivery.
auth planned feature to enable user authentication.
Not all combinations of these capabilities will work correctly together.
166
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
postfix_smtp_sasl_password_map
A map of SMTP SASL passwords used in SMTP client authentication by Postfix. You need to add client in Postfix
capabilities to enable this feature.
Format of the password entries:
• key: remote SMTP server hostname or sender e-mail address
• value: username on the remote SMTP server
Example entries:
postfix_smtp_sasl_password_map:
’smtp.example.org’: ’username’
’[email protected]’: ’username’
’[email protected]’: ’[email protected]’
Passwords are stored in a secret directory, in path:
secret/credentials/{{ ansible_fqdn }}/postfix/smtp_sasl_password_map/{{ key }}/{{ value }}
If you do not define the passwords there, this role will generate random passwords by default and store them there.
You can use this to your advantage by running debops once without defining the password to let debops generate the
right location automatically.
Passwords on the remote host are stored in:
/etc/postfix/private_hash_tables/
To regenerate, change or add new passwords, you need to remove the *.lock files located in above directory.
postfix_dependent_lists
This variable can be used in Postfix dependency role definition to configure additional lists used in Postfix main.cf
configuration file. This variable will be saved in Ansible facts and updated when necessary.
Examples Append custom tables to transport_maps option:
transport_maps: [ ’hash:/etc/postfix/transport’ ]
Append a given list of alias maps if Postfix has local capability:
alias_maps:
- capability: ’local’
list: [ ’hash:/etc/aliases’ ]
Append this virtual alias map if Postfix does not have local capability:
virtual_alias_maps:
- no_capability: ’local’
list: [ ’hash:/etc/postfix/virtual_alias_maps’ ]
postfix_dependent_maincf
Here you can specify Postfix configuration options which should be enabled in /etc/postfix/main.cf using
debops.postfix dependency role definition. Configuration will be saved in Ansible facts and updated when necessary.
2.11. Ansible roles provided in DebOps
167
DebOps Documentation, Release master
Examples Add this option in main.cf:
postfix_dependent_maincf:
- param: ’local_destination_recipient_limit’
value: ’1’
Enable this option only if mx is in Postfix capabilities:
postfix_dependent_maincf:
- param: ’defer_transports’
value: ’smtp’
capability: ’mx’
Enable this option only if local is not in Postfix capabilities:
postfix_dependent_maincf:
- param: ’relayhost’
value: ’mx.example.org’
no_capability: ’local’
If no value is specified, check if a list of the same name as param exists in postfix_dependent_lists and
enable it:
postfix_dependent_maincf:
- param: ’virtual_alias_maps’
postfix_dependent_mastercf
This list can be used to configure services in Postfix master.cf using Postfix dependency variables. Configured services
will be saved in Ansible facts and updated when necessary.
Parameters Optional parameters from master.cf: - private - unpriv - chroot - wakeup - maxproc
You can also specify capability or no_capability to define when a particular service should be configured
Examples Minimal service using pipe command:
postfix_dependent_mastercf:
- service: ’mydaemon’
type: ’unix’
command: ’pipe’
options: |
flagsd=FR user=mydaemon:mydaemon
argv=/usr/local/bin/mydaemon.sh ${nexthop} ${user}
Guides and examples
debops.postfix is designed to manage a Postfix service by itself. Other Ansible roles can use it as a dependency
and influence the Postfix configuration using dependency variables, but to avoid possible issues they should not modify
Postfix configuration directly. Any changes to Postfix configuration files not done by debops.postfix will be
overwritten.
Troubleshooting
This section will contain information about fixing issues with debops.postfix role.
168
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Copyright
Copyright (C) 2014 Maciej Delmanowski <[email protected]il.com>
Copyright (C) 2014 DebOps Project http://debops.org/
[see Credits for more details]
his 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.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/
Credits
Credits, in chronological order
• Maciej Delmanowski <drybjed_at_gmail.com>
– creator of the DebOps Project
– current project maintainer
Changelog
v0.1.0
• First release [drybjed]
2.11.63 Ansible role: debops.rsnapshot
Introduction
This Ansible role allows you to manage a backup host which will use rsnapshot to create remote backups of other
hosts. You can let Ansible configure both the central backup “clients”, which run rsnapshot and store backups, as
well as the “servers” which the clients connect to, which run rsync in read-only mode on root accounts.
You can also configure rsnapshot clients to backup external hosts which are not managed by Ansible, but you will
need to set up the connection (SSH access, rrsync script) yourself on the server side.
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.rsnapshot
2.11. Ansible roles provided in DebOps
169
DebOps Documentation, Release master
Getting started
•
•
•
•
Required Ansible host groups
Default directories
Example inventory
Example playbook
Required Ansible host groups
[debops_rsnapshot] Defines a group of hosts which will be configured as “clients”.
These hosts will have rsnapshot installed and will connect to configured “servers” at random times through
the day, synchronize the specified files and rotate archived snapshots.
You want them to have lots of disk space depending on your configuration, preferably encrypted. You can have
multiple clients configured in parallel.
This group can be redefined in rsnapshot_clients if needed.
[debops_rsnapshot_rsync] Defines a group of hosts which are configured as “servers”.
These hosts will have rsync installed, and SSH keys from clients will be configured on the server root
account to allow unrestricted access from the client.
A rrsync script provided with rsync package will be installed to permit for restricted, read-only access using
an SSH command stored in ~/.ssh/authorized_keys.
This group can be redefined in rsnapshot_servers if needed.
Both host groups can be configured either directly (with hosts), or as a parent group for other
groups.
You probably want a mixed set of [debops_rsnapshot] as a list of specific hosts and
[debops_rsnapshot_rsync:children] pointing to other groups of hosts to be backed up. This way new
hosts added to your primary groups can be automatically prepared to be backed up.
Default directories
Configuration files are stored in /etc/rsnapshot/ directory.
Backups are stored by default in /var/cache/rsnapshot/ directory.
Example inventory
This inventory will tell Ansible to backup all hosts in [all_hosts] group except the archive host, to the
archive host:
[all_hosts]
alpha
beta
archive
[debops_rsnapshot]
archive
[debops_rsnapshot_rsync:children]
all_hosts
170
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Example playbook
--- name: Manage rsnapshot backups
hosts: debops_rsnapshot:debops_rsnapshot_rsync
roles:
- role: debops.rsnapshot
tags: rsnapshot
When the inventory is set up, run Ansible on all of the hosts in both groups to have them correctly configured:
debops -t rsnapshot
You might want to see list of default variables to change how rsnapshot is configured, and a separate advanced
guides to see how you can use the role in different environments.
Default variables
Sections
•
•
•
•
Host groups
Backup client configuration
Backup server configuration
Include / Exclude definitions
Host groups
rsnapshot_clients
Inventory group of hosts that have ‘rsnapshot’ installed and keep the backup files. Required.
rsnapshot_clients: ’{{ groups.debops_rsnapshot }}’
rsnapshot_servers
Inventory group of hosts that should be backed up by rsnapshot. They have rsync installed and clients connect to them.
Required.
rsnapshot_servers: ’{{ groups.debops_rsnapshot_rsync }}’
rsnapshot_external_servers
List of dicts which define external servers to backup on a particular rsnapshot client host. Most of the keys have
the same names as main debops.rsnapshot variables but without the rsnapshot_ prefix. item.name key is
required. See How to backup hosts outside of Ansible cluster for more information.
rsnapshot_external_servers: []
Examples:
- name: ’host.example.org’
sleep: ’10’
2.11. Ansible roles provided in DebOps
171
DebOps Documentation, Release master
Backup client configuration
rsnapshot_snapshot_root
Directory where backups are stored
rsnapshot_snapshot_root: ’/var/cache/rsnapshot’
rsnapshot_link_dest
Enable –link-dest option in rsync commands
rsnapshot_link_dest: ’1’
rsnapshot_sync_first
Use separate steps for file synchronization and directory rotation
rsnapshot_sync_first: ’1’
rsnapshot_mail_to
List of mail recipients which should get messages from rsnapshot. By default rsnapshot sends its mails to <backup>
account which should be aliased to an administrator account.
rsnapshot_mail_to: [ ’backup’ ]
Backup server configuration
Server configuration should be defined in the respective host file in inventory, either in host_vars/ for a single
host, or in group_vars/‘ for entire groups of hosts.
rsnapshot_sleep
Maximum random delay time in minutes for rsnapshot to start synchronization. Set to False to disable the delay.
rsnapshot_sleep: ’20’
rsnapshot_hourly
Number of hourly snapshots to keep. Set to False to disable hourly snapshots.
rsnapshot_hourly: ’6’
rsnapshot_daily
Number of daily snapshots to keep. Set to False to disable daily snapshots.
rsnapshot_daily: ’7’
rsnapshot_weekly
Number of weekly snapshots to keep. Set to False to disable weekly snapshots.
rsnapshot_weekly: ’4’
rsnapshot_monthly
Number of weekly snapshots to keep. Set to False to disable weekly snapshots.
rsnapshot_monthly: ’3’
rsnapshot_one_fs
172
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Allow or prevent rsync from crossing filesystem boundaries
rsnapshot_one_fs: ’0’
rsnapshot_ssh_args
Additional arguments for the ssh command.
rsnapshot_ssh_args: ’-p 22’
rsnapshot_rrsync_script
rrsync script will be installed in this path (by default, /usr/local/lib).
rsnapshot_rrsync_script: ’{{ ansible_local.root.lib + "/rrsync" }}’
rsnapshot_ssh_command
Command which will be added to the SSH key in /root/.ssh/authorized_keys of each rsnapshot server
host. By default it allows for read-only access to entire filesystem.
rsnapshot_ssh_command: ’ionice -c 3 nice {{ rsnapshot_rrsync_script }} -ro /’
rsnapshot_backup_user
Override server backup user (by default, root)
rsnapshot_backup_user: False
rsnapshot_backup_host
Override server backup host (by default, FQDN of the host)
rsnapshot_backup_host: False
rsnapshot_backup_path
Override server backup path (by default, /, root filesystem directory)
rsnapshot_backup_path: False
rsnapshot_uuid
Add the host’s internal UUID to the backup path, creating an unique backup for each instance of the server host, if the
hostnames are reused
rsnapshot_uuid: True
Include / Exclude definitions
rsnapshot_exclude
Contents of an exclude file, defined as a text block
rsnapshot_exclude: |
{{ rsnapshot_exclude_default }}
rsnapshot_exclude_default
Default list of exclude entries, defined as a text block
2.11. Ansible roles provided in DebOps
173
DebOps Documentation, Release master
rsnapshot_exclude_default: |
- /bin
- /boot
- /cdrom
- /dev
- /lib
- /lib64
- /media
- /mnt
- /proc
- /run
- /sbin
- /selinux
- /sys
- /tmp
+ /usr/local
- /usr/*
- /var/cache
- /var/lib/apt
- /var/lib/libvirt/images
- /var/lib/lxc
- /var/lib/lxcsnaps
- /var/lib/mysql
- /var/lib/postgresql
- /var/lib/python-support
+ /var/lib/vz/dump
- /var/lib/vz/*
- /var/lock
- /var/run
- /var/spool/postfix
- /var/tmp
- /initrd*
- /vmlinuz*
- /vz
rsnapshot_include
Contents of an include file, defined as a text block
rsnapshot_include: |
{{ rsnapshot_include_default }}
rsnapshot_include_default
Default list of include entries, defined as a text block
rsnapshot_include_default: |
+ /*
Guides and examples
174
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
• How rsnapshot backups are performed
• How to backup hosts outside of Ansible cluster
– Configuration of external hosts in Ansible
– Things to set up on external host
– Fixing “stdin: is not a tty” issue
• How to split different servers between backup hosts
How rsnapshot backups are performed
debops.rsnapshot role configures a set of scripts launched from cron periodically, and a set of configuration
files for each host that is being backed up in /etc/rsnapshot/<host>/ directory.
The whole backup sequence is:
1. cron launches rsnapshot-cron-wrapper script with a specified interval (hourly, daily, weekly,
monthly).
2. rsnapshot-cron-wrapper scans /etc/rsnapshot/ directory looking for configuration files, and
checks if a given configuration uses specific interval - for example when a hourly interval is executed, script
checks if retain hourly is present in the rsnapshot.conf configuration file.
3. If
current
interval
is
found
and
particular
configuration
is
not
disabled
(file
/etc/rsnapshot/<host>/disabled is absent), script launches another script, runner using
nohup and puts it in the background. This is done to all host configurations at once.
4. runner script picks a random interval between 1 minute and 20 minutes (depending on the configuration) and
sleeps. This is done to prevent huge repeating waves of disk activity on all hosts at once.
5. When the time comes, runner script starts the rsnapshot command with specified host configuration file.
File synchronization is performed and then backups are rotated.
6. If any output is present from runner or rsnapshot, it is collected and sent to system administrator via
e-mail.
The whole process is repeated for hourly, daily, weekly and monthly intervals. runner script checks before main
execution if a rsnapshot lock file exists and exits gracefully if it’s found, betting on the next interval.
How to backup hosts outside of Ansible cluster
In addition to backing up hosts under Ansible control, you might want to create configuration for backing
up other hosts, which you don’t want to configure them directly (or can’t). For this situation, you can use
rsnapshot_external_servers list to configure external hosts in a particular rsnapshot client host.
Configuration of external hosts in Ansible Here’s an example configuration which will let you backup
other.example.org host:
rsnapshot_external_servers:
# Required
- name: ’other.example.org’
# Optional
sleep: ’20’
backup_user: ’root’
ssh_args: ’-p 22’
2.11. Ansible roles provided in DebOps
175
DebOps Documentation, Release master
You can use most of the variables that are defined in rsnapshot_ namespace, just drop the rsnapshot_ prefix.
item.name key is required and should be a FQDN hostname of the remote host you want to backup.
Things to set up on external host For practical reasons, rsnapshot should use a root account directly on
remote host. To make this configuration more secure, you can use rrsync Perl script provided with rsync which lets
you set up read-only access over SSH from remote hosts.
First, on Debian-based systems, install rsync package and extract provided script to a convenient directory:
sudo apt-get install rsync
sudo gzip -d -c /usr/share/doc/rsync/scripts/rrsync.gz > /usr/local/lib/rrsync
sudo chmod +x /usr/local/lib/rrsync
After that, you will want to install the public SSH key from the root account of the client host to root account
on the host you want to back up. At the same time you will configure this key to only allow for a specific rsync
command. You should include configuration similar to this in /root/.ssh/authorized_keys, in one line:
no-pty,no-agent-forwarding,no-X11-forwarding,no-port-forwarding,command="ionice -c 3 nice /usr/local/
ionice and nice commands will prevent rsync from hogging too much system resources during its operation.
This will allow read-only access to whole filesystem. After that, you can run debops.rsnapshot Ansible role and
it should correctly configure your rsnapshot client host to access external servers.
Fixing “stdin: is not a tty” issue On default Debian installation this creates a problem - when rsnapshot tries to
connect to the server, shell might respond with a warning:
stdin: is not a tty
This will prompt rsnapshot to send an e-mail to system administrator with the response, which might get annoying
after a while. To avoid that, open /root/.profile file on an external host and change line:
mesg n
to:
tty -s && mesg n
This will tell shell that it should check if connection is interactive before changing the terminal settings.
How to split different servers between backup hosts
If you are configuring multiple rsnapshot client hosts, all of them will back up all hosts from
rsnapshot_servers group (but not each other).
If you want to split different hosts between various rsnapshot clients, you can do that using separate Ansible
groups.
Here’s an example Ansible inventory:
# Main host group
[all_hosts]
alpha
beta
gamma
delta
archive-one
archive-two
176
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
# These hosts should be archived on ’archive-one’
[archive_group_one]
alpha
beta
# These hosts should be archived on ’archive-two’
[archive_group_two]
gamma
delta
# List of rsnapshot clients
[debops_rsnapshot]
archive-one
archive-two
# List of rsnapshot servers
[debops_rsnapshot_rsync:children]
archive_group_one
archive_group_two
Now, with this inventory in place, you can tell the rsnapshot client hosts which host group to use for their servers:
# In host_vars/archive-one/rsnapshot.yml:
rsnapshot_servers: ’{{ groups.archive_group_one }}’
# In host_vars/archive-two/rsnapshot.yml:
rsnapshot_servers: ’{{ groups.archive_group_two }}’
This will make debops.rsnapshot only configure rsync servers on their respectful rsnapshot clients.
Troubleshooting
In case of any errors during backup, debops.rsnapshot role collects output of all scripts and sends it if anything
shows up to <backup> e-mail account. With default debops.postfix configuration, this account is aliased to root
account, so all e-mails should be forwarded to the system administrator.
Logs for each server configuration are stored in /var/log/rsnapshot/ directory, and are automatically rotated.
Copyright
Copyright (C) 2015 Maciej Delmanowski <[email protected]>
Copyright (C) 2015 DebOps Project http://debops.org/
[see Credits for more details]
his 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.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/
2.11. Ansible roles provided in DebOps
177
DebOps Documentation, Release master
Credits
• Maciej Delmanowski <drybjed_at_gmail.com>
– creator of the DebOps Project
– current project maintainer
Changelog
v0.1.2
Released: 2015-02-26
• rsnapshot_one_fs default value is set to 0 to enable backups across filesystems. This is less surprising
and makes sure that everything that should be backed up, is backed up by default. [drybjed]
• Add more OpenVZ directories to includes/excludes. [drybjed]
v0.1.1
Released: 2015-02-23
• Scan SSH fingerprints separately from hosts with custom backup hostname, otherwise Ansible throws an error
about missing dict key in list of results [drybjed]
v0.1.0
Released: 2015-02-22
• Initial release [drybjed]
2.11.64 Ansible role: debops.secret
Introduction
debops.secret role enables you to have a separate directory on Ansible Controller (different than the playbook
directory and inventory directory) which can be used as a handy “workspace” for other roles.
Some usage examples of this role in DebOps include:
• password lookups, either from current role, or using known location of passwords from other roles, usually
dependencies (for example debops.mysql role can manage an user account in the database with random
password and other role can lookup that password to include in a generated configuration file);
• secure file storage, for example for application keys generated on remote hosts (debops.boxbackup role
retrieves client keys for backup purposes), for that reason secret directory should be protected by an external
means, for example encrypted filesystem (currently there is no encryption provided by default);
• secure workspace (debops.boxbackup role, again, uses secret directory to create and manage Root CA for
backup servers - client and server certificates are automatically downloaded to Ansible Controller, signed and
uploaded to destination hosts);
• simple centralized backup (specific roles like sshd, pki and monkeysphere have a separate task lists that are
invoked by custom playbooks to allow backup and restoration of ssh host keys and SSL certificates. Generated
.tar.gz files are kept on Ansible Controller in secret directory);
178
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.secret
Getting started
By default all you need to do to use debops.secret role is include it in your common playbook at the beginning:
--- hosts: all
roles:
- role: debops.secret
That will allow all your roles in this and subsequent plays to access secret variable and use it consistently.
Unfortunately, it doesn’t work well when you use Ansible with --tags parameter, which might omit your common
play, thus not setting secret* variables at all and changing your passwords to empty values, modifying config files
incorrectly, basically not honoring the idempotency principle.
Solution to that problem is to either include debops.secret role in all your plays (similar to the one above), or
include it as a dependency in roles that require it:
--dependencies:
- role: debops.secret
This will ensure that roles utilizing secret variable will be able to access it correctly and you don’t need to remember
to include debops.secret role in all your playbooks.
Usage examples
Example password lookup with password written to a variable. You can define this variable anywhere Ansible variables
can be defined, but if you want to give playbook users ability to overwrite it in inventory, you should define it in
role/defaults/main.yml:
--mysql_root_password: "{{ lookup(’password’, secret + ’/credentials/’ + ansible_fqdn + ’/mysql/root/pa
When this variable is set in role/defaults/main.yml, you can easily overwrite it in your inventory, like this:
--mysql_root_password: "correct horse battery staple"
You
can
also
change
the
password
directly
in
secret
directory,
in
this
case
in
secret/credentials/hostname/mysql/root/password and Ansible should update the password
on the remote server (if role is written to support this).
Example file download task from remote host to Ansible controller, sored in secret directory:
--fetch:
src: "/etc/fstab"
flat: True
dest: "{{ secret + ’/storage/’ + ansible_fqdn + ’/etc/fstab’ }}"
Example file upload task from Ansible Controller to remote host with file from secret directory:
2.11. Ansible roles provided in DebOps
179
DebOps Documentation, Release master
--copy:
dest: "/etc/fstab"
owner: "root"
group: "root"
mode: "0644"
src: "{{ secret + ’/storage/ + ansible_fqdn + ’/etc/fstab’ }}"
Default variables
Secret local storage
secret_root
Path to a directory in which a relative secret directory will be created. By default, it will be relative to Ansible inventory
secret_root: ’{{ inventory_dir | realpath }}’
secret_dir
Name of the directory which contains secrets. It will be in the form “secret” by default
secret_dir: ’secret’
secret_levels
How many directory levels to add relative to secret_root, by default 1 level. For example, to go 2 levels up, set this
variable to ‘../..’
secret_levels: ’..’
secret
Absolute path to directory with secrets. It will be configured as relative to current inventory directory. Use this variable
in file and password lookups
secret: ’{{ secret_root + "/" + secret_levels + "/" + secret_dir }}’
LDAP server admin access
secret_ldap_* variables are used by ldap_* Ansible modules to access LDAP server for the current domain
with administrative privileges, by binding to the admin account with specified bind DN and password. Because these
need to be provided with every task that uses ldap_* modules, variables below are used as a convenient central
location.
secret_ldap_domain
Domain used for LDAP base DN and to select default LDAP server
secret_ldap_domain: ’{{ ansible_domain }}’
secret_ldap_server
LDAP server hostname / IP address which holds the database. ldap_* modules will connect to it natively, so it
should be available at least from the Ansible Controller.
secret_ldap_server: ’{{ "ldap." + secret_ldap_domain }}’
secret_ldap_server_uri
180
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
URI used in tasks to connect to LDAP server natively, it should be used in ldap_attr and ldap_entry tasks
secret_ldap_server_uri: ’{{ "ldap://" + secret_ldap_server + "/" }}’
secret_ldap_start_tls
Enable or disable STARTTLS for encrypted communication with the LDAP server. Should always be enabled.
secret_ldap_start_tls: ’true’
secret_ldap_basedn
LDAP Base DN used for to create bind DN
secret_ldap_basedn: ’{{ "dc=" + secret_ldap_domain.split(".") | join(",dc=") }}’
secret_ldap_admin_bind_dn
LDAP administrator account
secret_ldap_admin_bind_dn: ’{{ "cn=admin," + secret_ldap_basedn }}’
secret_ldap_admin_password
Path to a file in secret/ directory which stores password for specified admin account on configured LDAP server.
This file will be populated by debops.slapd role if a server is configured with it.
secret_ldap_admin_password: ’{{ secret + "/ldap/" + ansible_domain + "/credentials/" + secret_ldap_se
secret_ldap_admin_bind_pw
LDAP administrator password
secret_ldap_admin_bind_pw: ’{{ lookup("password", secret_ldap_admin_password) }}’
secret_ldap_delegate_to
Each LDAP administrative task should be delegated to either localhost (Ansible Controller), or to the LDAP server
itself. This host will have access to LDAP admin password, and requires installed python-ldap package.
secret_ldap_delegate_to: ’localhost’
secret_ldap_sudo
Access through sudo is not required on localhost, but if LDAP tasks are delegated to different hosts, it might be
required there.
secret_ldap_sudo: False
Detailed guides
How local secrets work
Here’s a default project directory layout kept in a git repository:
~/Projects/
‘-- data-center/
|-- .git/
‘-- ansible/
|-- inventory/
|
|-- group_vars/
2.11. Ansible roles provided in DebOps
181
DebOps Documentation, Release master
|
|-- host_vars/
|
‘-- hosts
|
‘-- secret/
|-- credentials/
‘-- storage/
If you use debops-padlock script to create encrypted EncFS storage for your secrets, directory layout will be
slightly different:
~/Projects/
‘-- data-center/
|-- .git/
‘-- ansible/
|-- .encfs.secret/
|
|-- U8dfMgfgg48vj/
|
|-- fk5fkg5NN/
|
‘-- padlock*
|
|-- inventory/
|
|-- group_vars/
|
|-- host_vars/
|
‘-- hosts
|
‘-- secret/
<- encrypted secrets
<- unlock/lock script
<- plaintext secrets
While project is “at rest”, secrets are encrypted inside EncFS directory, and they don’t show up in the secret/
directory. When you use debops script to run the playbook, padlock script unlocks the encrypted directory and
secrets are available again in secret/ directory for ansible-playbook to use.
How to use LDAP variables
In main DebOps playbook repository you can find Ansible modules ldap_attr and ldap_entry. They can be
used to access and control LDAP servers. In various DebOps roles, they are used to perform certain tasks in shared
environment.
Some of the above tasks require admin privileges on the LDAP server. To provide access to it in a secure manner,
debops.secret role keeps a set of variables meant to be used with these tasks.
For security reasons, LDAP-related tasks should be delegated to localhost (Ansible Controller) or the LDAP server
itself. The host that runs these tasks requires python-ldap library. Modules will access LDAP directly, without
using SSH redirection, so TLS encryption is strongly recommended. You should also take care to not log these tasks
to avoid leaking the LDAP administrator password in logs.
Example usage of LDAP secret variables:
- name: Create an entry in LDAP database
ldap_entry:
dn: ’ou=People,dc=example,dc=org’
objectClass: [ ’organizationalUnit’, ’top’ ]
state: ’present’
server_uri: ’{{ secret_ldap_server_uri }}’
start_tls: ’{{ secret_ldap_start_tls }}’
bind_dn: ’{{ secret_ldap_admin_bind_dn }}’
bind_pw: ’{{ secret_ldap_admin_bind_pw }}’
sudo: ’{{ secret_ldap_sudo }}’
delegate_to: ’{{ secret_ldap_delegate_to }}’
no_log: True
182
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
- name: Add attribute to an LDAP entry
ldap_attr:
dn: ’cn=user,ou=People,dc=example,dc=org’
name: ’{{ item.key }}’
values: ’{{ item.value }}’
state: ’exact’
server_uri: ’{{ secret_ldap_server_uri }}’
start_tls: ’{{ secret_ldap_start_tls }}’
bind_dn: ’{{ secret_ldap_admin_bind_dn }}’
bind_pw: ’{{ secret_ldap_admin_bind_pw }}’
sudo: ’{{ secret_ldap_sudo }}’
delegate_to: ’{{ secret_ldap_delegate_to }}’
with_dict:
uid: ’{{ user_username }}’
userPassword: ’{{ user_password }}’
no_log: True
Of course for this to work, debops.secret needs to be included in the playbook, either as a role, or a role dependency. You can change the values of secret_ldap_* variables in inventory as you need.
If you use debops.slapd role to configure an LDAP server, it will automatically copy the admin accout password to a
location defined in secret_ldap_admin_password variable to be accessed by the debops.secret role as
needed.
Copyright
Copyright (C) 2013 Maciej Delmanowski <[email protected]>
Copyright (C) 2014 DebOps Project http://debops.org/
[see Credits for more details]
his 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.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/
Credits
• Maciej Delmanowski <drybjed_at_gmail.com>
– creator of the DebOps Project
– current project maintainer
Changelog
v0.2.1
Released: 2015-02-25
2.11. Ansible roles provided in DebOps
183
DebOps Documentation, Release master
• Redesign LDAP support, add more required variables. [drybjed]
v0.2.0
Released: 2015-02-24
• Convert documentation to new format. [drybjed]
• Add LDAP integration [drybjed]
v0.1.0
Released: 2015-02-12
• First release, add CHANGES.rst [drybjed]
2.12 debops.postfix
2.12.1 Introduction
debops.postfix is an Ansible role which installs and manages Postfix, an SMTP server. It is designed to manage
Postfix on different hosts in a cluster, with different “capabilities”.
Features
At the moment role can configure Postfix to act as:
• a null client: Postfix sends all mail to another system specified either via DNS MX records or an Ansible
variable, no local mail is enabled (this is the default configuration);
• a local SMTP server: local mail is delivered to local user accounts;
• a network SMTP server: network access is enabled separately from other capabilities, to avoid exposing misconfigured SMTP server by mistake and becoming an open relay;
• an incoming MX gateway: Postfix will listen on the port 25 (default SMTP port) and process connections using
postscreen daemon with automatic greylisting and optional RBL checking;
• an outgoing SMTP client: Postfix will relay outgoing mail messages to specified remote MX hosts, you can
optionally enable SMTP client authentication, passwords will be stored separate from the inventory in secret/
directory (see debops.secret role). Sender dependent authentication is also available.
More “capabilities” like user authentication, support for virtual mail, spam/virus filtering and others will be implemented in the future.
This role can also be used as a dependency of other roles which then can enable more features of the Postfix SMTP
server for their own use. For example, debops.mailman role enables mail forwarding to the configured mailing
lists, and debops.smstools role uses Postfix as mail-SMS gateway.
2.12.2 Installation
This role requires at least Ansible v1.7.0. To install it, run:
184
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
ansible-galaxy install debops.postfix
Role dependencies
• debops.ferm
• debops.secret
2.12.3 Getting started
An example playbook which uses debops.postfix role:
--- name: Manage Postfix instance
hosts: all
roles:
- role: debops.postfix
tags: postfix
This playbook should install postfix package along with its dependencies, and configure the service with default
values generated by Ansible.
2.12.4 Default variables
Sections
•
•
•
•
•
•
•
•
•
•
General Postfix configuration
PKI / TLS configuration
Firewall configuration
Postfix SMTP client options
Mail archive options
Anti-spam configuration
Postfix SMTPD restrictions
Mail aliases
Postfix custom configuration
Mail service debugging
General Postfix configuration
Configuration options for Postfix. Many options are configured automatically using templates, here you can (mostly)
add your own entries to Postfix lists (look in Postfix manual for details), they will by added or replaced in templates.
postfix
List of active Postfix capabilities. By default Postfix is configured with local mail disabled, all mail is sent to local
MX server configured in DNS. See postfix_capabilities for more details.
postfix: [ ’null’ ]
postfix_relayhost
2.12. debops.postfix
185
DebOps Documentation, Release master
Address of mail host this host should relay all mail to instead of delivering it directly. (Automatic configuration)
postfix_relayhost: False
postfix_mailname
Mail host name configured in /etc/mailname
postfix_mailname: ’{{ ansible_fqdn }}’
postfix_mydomain
Domain name to use for outgoing mail messages
postfix_mydomain: ’{{ ansible_domain }}’
postfix_delay_warning_time
How long to wait before notifying users about delivery problems
postfix_delay_warning_time: ’4h’
postfix_relay_domains
List of relay domains this host accepts
postfix_relay_domains: []
postfix_inet_interfaces
On what interfaces Postfix should listen to by default (not a list). (Automatic configuration)
postfix_inet_interfaces: False
postfix_mydestination
List of local domains accepted by Postfix. (Automatic configuration)
postfix_mydestination: []
postfix_mynetworks
List of networks Postfix accepts by default. (localhost is always enabled)
postfix_mynetworks: []
postfix_transport_maps
List of Postfix transport maps. (Automatic configuration)
postfix_transport_maps: []
postfix_virtual_alias_maps
List of Postfix virtual alias maps. (Automatic configuration)
postfix_virtual_alias_maps: []
postfix_message_size_limit
Message size limit in megabytes
postfix_message_size_limit: 50
186
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
PKI / TLS configuration
postfix_pki
Enable or disable support for TLS in Postfix (using debops.pki)
postfix_pki: True
postfix_pki_path
Base PKI directory
postfix_pki_path: ’{% if (ansible_local is defined and ansible_local.pki is defined) %}{{ ansible_loc
postfix_pki_realm
Default PKI realm used by Postfix
postfix_pki_realm: ’{% if (ansible_local is defined and ansible_local.pki is defined) %}{{ ansible_lo
postfix_pki_crt
Default certificate, relative to postfix_pki_realm variable
postfix_pki_crt: ’default.crt’
postfix_pki_key
Default private key, relative to postfix_pki_realm variable
postfix_pki_key: ’default.key’
postfix_pki_dhparam
Default Diffie-Hellman parameters file (2048 bits), relative to postfix_pki_realm variable
postfix_pki_dhparam: ’dhparam.pem’
Firewall configuration
If network and any of needed Postfix capabilities are enabled, all hosts can send mail to this Postfix instance. You
can limit access to specific hosts or networks using postfix_allow_* variables.
postfix_allow_smtp
List of hosts/networks that can access smtp port (25)
postfix_allow_smtp: []
postfix_allow_submission
List of hosts/networks that can access submission port (587)
postfix_allow_submission: []
postfix_allow_smtps
List of hosts/networks that can access smtps port (465), deprecated.
postfix_allow_smtps: []
2.12. debops.postfix
187
DebOps Documentation, Release master
Postfix SMTP client options
postfix_smtp_sasl_password_map
Map of SMTP SASL passwords used in SMTP client authentication by Postfix. You need to add client in Postfix
capabilities to enable this feature. See postfix_smtp_sasl_password_map for more details.
postfix_smtp_sasl_password_map: {}
postfix_sender_dependent_relayhost_map
Map of sender dependent relayhosts used in SMTP client mail relay by Postfix. You need to add client and
sender_dependent in Postfix capabilities to enable this feature.
postfix_sender_dependent_relayhost_map: {}
Example entries:
’<sender-address>’: ’<relay-host>’
’[email protected]’: ’[smtp.example.org]:submission’
Mail archive options
Archiving is enabled by archive option in Postfix capabilities. Remember that an archive account on the receiving
server needs to exist.
postfix_archive_method
How Postfix should redistribute archived messages:
• all: send all mail without sorting
• domain: send mail sorted by domain
• domain-account: send mail sorted by domain and account, divided by separator
postfix_archive_method: ’all’
postfix_archive_to
Optional address of a mail account to send the archived mails to. If not specified, Ansible will generate an address by
itself in format:
• <postfix_archive_account>@<ansible_fqdn> (if local mail is enabled)
• <postfix_archive_account>@<postfix_archive_subdomain>.<ansible_domain> (if local mail is disabled).
postfix_archive_to: ’’
postfix_archive_account
Mail account to send archived mail to (used by Ansible to generate archive address).
postfix_archive_account: ’mail-archive’
postfix_archive_subdomain
Subdomain part of a domain used to generate archive address, if local mail is not enabled in Postfix capabilities (dot
at the end is required).
188
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
postfix_archive_subdomain: ’archive.’
postfix_archive_separator
Character used to separate domain and account part in sorted archive mails. If you use virtual mail delivery, you can
sort mail into subdirectories by setting separator as ‘/’ (does not work on local mail delivery).
postfix_archive_separator: ’=’
postfix_archive_domains
List of domains to archive. If it’s empty, everything is archived.
postfix_archive_domains: []
Anti-spam configuration
postfix_postscreen_dnsbl_sites
List of DNS Blacklists enabled in postscreen service. Disabled by default. To enable blacklists, you need to add
dnsbl in Postfix capabilities.
postfix_postscreen_dnsbl_sites:
# Spamhaus ZEN: http://www.spamhaus.org/zen/
# Might require registration
- ’zen.spamhaus.org*3’
# Barracuda Reputation Block List: http://barracudacentral.org/rbl
# Requires registration
#- ’b.barracudacentral.org*2’
#
#
-
Spam Eating Monkey: http://spameatingmonkey.com/lists.html
Might require registration
’bl.spameatingmonkey.net*2’
’backscatter.spameatingmonkey.net*2’
# SpamCop Blocking List: http://www.spamcop.net/bl.shtml
- ’bl.spamcop.net’
# Passive Spam Block List: http://psbl.org/
- ’psbl.surriel.com’
# mailspike: http://mailspike.net/usage.html
# Might require contact
- ’bl.mailspike.net’
postfix_postscreen_dnswl_sites
List of DNS Whitelists enabled in postscreen service. Disabled by default. To enable whitelists, you need to add
dnswl in Postfix capabilities.
postfix_postscreen_dnswl_sites:
# SpamHaus Whitelist: http://www.spamhauswhitelist.com/en/usage.html
# Might require registration
- ’swl.spamhaus.org*-4’
# DNS Whitelist: http://dnswl.org/tech
2.12. debops.postfix
189
DebOps Documentation, Release master
#
-
Might require registration
’list.dnswl.org=127.[0..255].[0..255].0*-2’
’list.dnswl.org=127.[0..255].[0..255].1*-3’
’list.dnswl.org=127.[0..255].[0..255].[2..255]*-4’
Postfix SMTPD restrictions
debops.postfix creates a base set of various smtpd restrictions by itself, to protect the SMTP server against spam.
However this functionality is currently basic. Using lists below you can define your own set of smtpd restrictions,
which will override anything generated automatically by the role.
postfix_smtpd_client_restrictions
Client restrictions, processed at the connection stage
postfix_smtpd_client_restrictions: []
postfix_smtpd_helo_restrictions
Hello restrictions, processed at HELO/EHLO stage
postfix_smtpd_helo_restrictions: []
postfix_smtpd_sender_restrictions
Sender restrictions, processed at MAIL FROM stage
postfix_smtpd_sender_restrictions: []
postfix_smtpd_relay_restrictions
Relay restrictions (currently not supported in the role)
postfix_smtpd_relay_restrictions: []
postfix_smtpd_recipient_restrictions
Recipient restrictions, processed at RCPT TO stage
postfix_smtpd_recipient_restrictions: []
postfix_smtpd_data_restrictions
Data restrictions, processed at DATA stage
postfix_smtpd_data_restrictions: []
Mail aliases
Postfix role automatically manages /etc/aliases file with a set of default aliases redirected to root and staff
accounts.
postfix_default_local_alias_recipients
List of default recipients for local aliases which have no recipients specified, by default current $USER managing
Ansible
postfix_default_local_alias_recipients: [’{{ lookup("env","USER") }}’]
postfix_local_aliases
190
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Hash of local aliases which will be merged with default aliases in vars/main.yml
postfix_local_aliases: {}
Examples:
’alias’: [ ’account1’, ’account2’ ]
’other’: [ ’[email protected]’, ’"|/dir/command"’ ]
’blackhole’: [ ’/dev/null’ ]
’send_to_default_recipients’: []
Postfix custom configuration
postfix_local_maincf
Custom Postfix configuration added at the end of /etc/postfix/main.cf in a text block format
postfix_local_maincf: False
postfix_local_mastercf
Custom Postfix configuration added at the end of /etc/postfix/master.cf in a text block format
postfix_local_mastercf: False
postfix_dependent_lists
This variable can be used in Postfix dependency role definition to configure additional lists used in Postfix main.cf configuration file. This variable will be saved in Ansible facts and updated when necessary. See postfix_dependent_lists
for more information.
postfix_dependent_lists: {}
postfix_dependent_maincf
Here you can specify Postfix configuration options which should be enabled in /etc/postfix/main.cf using
debops.postfix dependency role definition. Configuration will be saved in Ansible facts and updated when necessary.
See postfix_dependent_maincf for more information.
postfix_dependent_maincf: []
postfix_dependent_mastercf
This list can be used to configure services in Postfix master.cf using Postfix dependency variables. Configured services
will be saved in Ansible facts and updated when necessary. See postfix_dependent_mastercf for more information.
postfix_dependent_mastercf: []
Mail service debugging
postfix_smtpd_authorized_xclient_hosts
List of clients and networks which will have access to XCLIENT protocol extension when test Postfix capability is
enabled.
postfix_smtpd_authorized_xclient_hosts: [ ’127.0.0.1/32’ ]
2.12. debops.postfix
191
DebOps Documentation, Release master
2.12.5 Default variables: configuration
some of debops.postfix default variables have more extensive configuration than simple strings or lists, here you
can find documentation and examples for them.
•
•
•
•
•
postfix_capabilities
postfix_smtp_sasl_password_map
postfix_dependent_lists
postfix_dependent_maincf
postfix_dependent_mastercf
postfix_capabilities
List of active Postfix capabilities. By default Postfix is configured with local mail disabled, all mail is sent to local
MX server configured in DNS.
List of available Postfix capabilities:
null Enabled by default. Postfix has no local delivery, all mail is sent to a MX for current domain. These settings
are based on Postfix null client configuration.
You should remove this capability and replace it with others presented below.
local local delivery is enabled on current host.
network enables access to Postfix-related ports (25, 587, 465) in firewall, required for incoming mail to be acceped
by Postfix.
mx enables support for incoming mail on port 25, designed for hosts set up as MX. Automatically enables
postscreen (without dnsbl/dnswl support), anti-spam restrictions.
submission enables authorized mail submission on ports 25 and 587 (user authentication is currently not supported and needs to be configured separately).
deprecated designed to enable obsolete functions of mail system, currently enables authorized mail submission
on port 465 (when submission is also present in the list of capabilities).
client enable SASL authentication for SMTP client (for outgoing mail messages sent via relayhosts that require
user authentication).
sender_dependent enable sender dependent SMTP client authentication (client capability required)
archive BCC all mail (or mail from/to specified domains) passing through the SMTP server to an e-mail account
on local or remote server.
postscreen allows to enable postscreen support on port 25 independently of mx capability.
dnsbl enables support for DNS blacklists in postscreen, automatically enables whitelists.
dnswl enables support for DNS whitelists in postscreen, without blacklists.
test enables “soft_bounce” option and XCLIENT protocol extension for localhost (useful in mail system testing).
defer planned feature to defer mail delivery.
auth planned feature to enable user authentication.
Not all combinations of these capabilities will work correctly together.
192
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
postfix_smtp_sasl_password_map
A map of SMTP SASL passwords used in SMTP client authentication by Postfix. You need to add client in Postfix
capabilities to enable this feature.
Format of the password entries:
• key: remote SMTP server hostname or sender e-mail address
• value: username on the remote SMTP server
Example entries:
postfix_smtp_sasl_password_map:
’smtp.example.org’: ’username’
’[email protected]’: ’username’
’[email protected]’: ’[email protected]’
Passwords are stored in a secret directory, in path:
secret/credentials/{{ ansible_fqdn }}/postfix/smtp_sasl_password_map/{{ key }}/{{ value }}
If you do not define the passwords there, this role will generate random passwords by default and store them there.
You can use this to your advantage by running debops once without defining the password to let debops generate the
right location automatically.
Passwords on the remote host are stored in:
/etc/postfix/private_hash_tables/
To regenerate, change or add new passwords, you need to remove the *.lock files located in above directory.
postfix_dependent_lists
This variable can be used in Postfix dependency role definition to configure additional lists used in Postfix main.cf
configuration file. This variable will be saved in Ansible facts and updated when necessary.
Examples
Append custom tables to transport_maps option:
transport_maps: [ ’hash:/etc/postfix/transport’ ]
Append a given list of alias maps if Postfix has local capability:
alias_maps:
- capability: ’local’
list: [ ’hash:/etc/aliases’ ]
Append this virtual alias map if Postfix does not have local capability:
virtual_alias_maps:
- no_capability: ’local’
list: [ ’hash:/etc/postfix/virtual_alias_maps’ ]
2.12. debops.postfix
193
DebOps Documentation, Release master
postfix_dependent_maincf
Here you can specify Postfix configuration options which should be enabled in /etc/postfix/main.cf using
debops.postfix dependency role definition. Configuration will be saved in Ansible facts and updated when necessary.
Examples
Add this option in main.cf:
postfix_dependent_maincf:
- param: ’local_destination_recipient_limit’
value: ’1’
Enable this option only if mx is in Postfix capabilities:
postfix_dependent_maincf:
- param: ’defer_transports’
value: ’smtp’
capability: ’mx’
Enable this option only if local is not in Postfix capabilities:
postfix_dependent_maincf:
- param: ’relayhost’
value: ’mx.example.org’
no_capability: ’local’
If no value is specified, check if a list of the same name as param exists in postfix_dependent_lists and
enable it:
postfix_dependent_maincf:
- param: ’virtual_alias_maps’
postfix_dependent_mastercf
This list can be used to configure services in Postfix master.cf using Postfix dependency variables. Configured services
will be saved in Ansible facts and updated when necessary.
Parameters
Optional parameters from master.cf: - private - unpriv - chroot - wakeup - maxproc
You can also specify capability or no_capability to define when a particular service should be configured
Examples
Minimal service using pipe command:
postfix_dependent_mastercf:
- service: ’mydaemon’
type: ’unix’
command: ’pipe’
options: |
flagsd=FR user=mydaemon:mydaemon
argv=/usr/local/bin/mydaemon.sh ${nexthop} ${user}
194
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
2.12.6 Guides and examples
debops.postfix is designed to manage a Postfix service by itself. Other Ansible roles can use it as a dependency
and influence the Postfix configuration using dependency variables, but to avoid possible issues they should not modify
Postfix configuration directly. Any changes to Postfix configuration files not done by debops.postfix will be
overwritten.
2.12.7 Troubleshooting
This section will contain information about fixing issues with debops.postfix role.
2.12.8 Copyright
Copyright (C) 2014 Maciej Delmanowski <[email protected]>
Copyright (C) 2014 DebOps Project http://debops.org/
[see Credits for more details]
his 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.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/
2.12.9 Credits
Credits, in chronological order
• Maciej Delmanowski <drybjed_at_gmail.com>
– creator of the DebOps Project
– current project maintainer
2.12.10 Changelog
v0.1.0
• First release [drybjed]
2.12. debops.postfix
195
DebOps Documentation, Release master
2.13 Ansible role: debops.rsnapshot
2.13.1 Introduction
This Ansible role allows you to manage a backup host which will use rsnapshot to create remote backups of other
hosts. You can let Ansible configure both the central backup “clients”, which run rsnapshot and store backups, as
well as the “servers” which the clients connect to, which run rsync in read-only mode on root accounts.
You can also configure rsnapshot clients to backup external hosts which are not managed by Ansible, but you will
need to set up the connection (SSH access, rrsync script) yourself on the server side.
2.13.2 Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.rsnapshot
2.13.3 Getting started
•
•
•
•
Required Ansible host groups
Default directories
Example inventory
Example playbook
Required Ansible host groups
[debops_rsnapshot] Defines a group of hosts which will be configured as “clients”.
These hosts will have rsnapshot installed and will connect to configured “servers” at random times through
the day, synchronize the specified files and rotate archived snapshots.
You want them to have lots of disk space depending on your configuration, preferably encrypted. You can have
multiple clients configured in parallel.
This group can be redefined in rsnapshot_clients if needed.
[debops_rsnapshot_rsync] Defines a group of hosts which are configured as “servers”.
These hosts will have rsync installed, and SSH keys from clients will be configured on the server root
account to allow unrestricted access from the client.
A rrsync script provided with rsync package will be installed to permit for restricted, read-only access using
an SSH command stored in ~/.ssh/authorized_keys.
This group can be redefined in rsnapshot_servers if needed.
Both host groups can be configured either directly (with hosts), or as a parent group for other
groups.
You probably want a mixed set of [debops_rsnapshot] as a list of specific hosts and
[debops_rsnapshot_rsync:children] pointing to other groups of hosts to be backed up. This way new
hosts added to your primary groups can be automatically prepared to be backed up.
196
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Default directories
Configuration files are stored in /etc/rsnapshot/ directory.
Backups are stored by default in /var/cache/rsnapshot/ directory.
Example inventory
This inventory will tell Ansible to backup all hosts in [all_hosts] group except the archive host, to the
archive host:
[all_hosts]
alpha
beta
archive
[debops_rsnapshot]
archive
[debops_rsnapshot_rsync:children]
all_hosts
Example playbook
--- name: Manage rsnapshot backups
hosts: debops_rsnapshot:debops_rsnapshot_rsync
roles:
- role: debops.rsnapshot
tags: rsnapshot
When the inventory is set up, run Ansible on all of the hosts in both groups to have them correctly configured:
debops -t rsnapshot
You might want to see list of default variables to change how rsnapshot is configured, and a separate advanced
guides to see how you can use the role in different environments.
2.13.4 Default variables
Sections
•
•
•
•
Host groups
Backup client configuration
Backup server configuration
Include / Exclude definitions
Host groups
rsnapshot_clients
2.13. Ansible role: debops.rsnapshot
197
DebOps Documentation, Release master
Inventory group of hosts that have ‘rsnapshot’ installed and keep the backup files. Required.
rsnapshot_clients: ’{{ groups.debops_rsnapshot }}’
rsnapshot_servers
Inventory group of hosts that should be backed up by rsnapshot. They have rsync installed and clients connect to them.
Required.
rsnapshot_servers: ’{{ groups.debops_rsnapshot_rsync }}’
rsnapshot_external_servers
List of dicts which define external servers to backup on a particular rsnapshot client host. Most of the keys have
the same names as main debops.rsnapshot variables but without the rsnapshot_ prefix. item.name key is
required. See How to backup hosts outside of Ansible cluster for more information.
rsnapshot_external_servers: []
Examples:
- name: ’host.example.org’
sleep: ’10’
Backup client configuration
rsnapshot_snapshot_root
Directory where backups are stored
rsnapshot_snapshot_root: ’/var/cache/rsnapshot’
rsnapshot_link_dest
Enable –link-dest option in rsync commands
rsnapshot_link_dest: ’1’
rsnapshot_sync_first
Use separate steps for file synchronization and directory rotation
rsnapshot_sync_first: ’1’
rsnapshot_mail_to
List of mail recipients which should get messages from rsnapshot. By default rsnapshot sends its mails to <backup>
account which should be aliased to an administrator account.
rsnapshot_mail_to: [ ’backup’ ]
Backup server configuration
Server configuration should be defined in the respective host file in inventory, either in host_vars/ for a single
host, or in group_vars/‘ for entire groups of hosts.
rsnapshot_sleep
Maximum random delay time in minutes for rsnapshot to start synchronization. Set to False to disable the delay.
198
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
rsnapshot_sleep: ’20’
rsnapshot_hourly
Number of hourly snapshots to keep. Set to False to disable hourly snapshots.
rsnapshot_hourly: ’6’
rsnapshot_daily
Number of daily snapshots to keep. Set to False to disable daily snapshots.
rsnapshot_daily: ’7’
rsnapshot_weekly
Number of weekly snapshots to keep. Set to False to disable weekly snapshots.
rsnapshot_weekly: ’4’
rsnapshot_monthly
Number of weekly snapshots to keep. Set to False to disable weekly snapshots.
rsnapshot_monthly: ’3’
rsnapshot_one_fs
Allow or prevent rsync from crossing filesystem boundaries
rsnapshot_one_fs: ’0’
rsnapshot_ssh_args
Additional arguments for the ssh command.
rsnapshot_ssh_args: ’-p 22’
rsnapshot_rrsync_script
rrsync script will be installed in this path (by default, /usr/local/lib).
rsnapshot_rrsync_script: ’{{ ansible_local.root.lib + "/rrsync" }}’
rsnapshot_ssh_command
Command which will be added to the SSH key in /root/.ssh/authorized_keys of each rsnapshot server
host. By default it allows for read-only access to entire filesystem.
rsnapshot_ssh_command: ’ionice -c 3 nice {{ rsnapshot_rrsync_script }} -ro /’
rsnapshot_backup_user
Override server backup user (by default, root)
rsnapshot_backup_user: False
rsnapshot_backup_host
Override server backup host (by default, FQDN of the host)
rsnapshot_backup_host: False
rsnapshot_backup_path
2.13. Ansible role: debops.rsnapshot
199
DebOps Documentation, Release master
Override server backup path (by default, /, root filesystem directory)
rsnapshot_backup_path: False
rsnapshot_uuid
Add the host’s internal UUID to the backup path, creating an unique backup for each instance of the server host, if the
hostnames are reused
rsnapshot_uuid: True
Include / Exclude definitions
rsnapshot_exclude
Contents of an exclude file, defined as a text block
rsnapshot_exclude: |
{{ rsnapshot_exclude_default }}
rsnapshot_exclude_default
Default list of exclude entries, defined as a text block
rsnapshot_exclude_default: |
- /bin
- /boot
- /cdrom
- /dev
- /lib
- /lib64
- /media
- /mnt
- /proc
- /run
- /sbin
- /selinux
- /sys
- /tmp
+ /usr/local
- /usr/*
- /var/cache
- /var/lib/apt
- /var/lib/libvirt/images
- /var/lib/lxc
- /var/lib/lxcsnaps
- /var/lib/mysql
- /var/lib/postgresql
- /var/lib/python-support
+ /var/lib/vz/dump
- /var/lib/vz/*
- /var/lock
- /var/run
- /var/spool/postfix
- /var/tmp
- /initrd*
- /vmlinuz*
- /vz
rsnapshot_include
200
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Contents of an include file, defined as a text block
rsnapshot_include: |
{{ rsnapshot_include_default }}
rsnapshot_include_default
Default list of include entries, defined as a text block
rsnapshot_include_default: |
+ /*
2.13.5 Guides and examples
• How rsnapshot backups are performed
• How to backup hosts outside of Ansible cluster
– Configuration of external hosts in Ansible
– Things to set up on external host
– Fixing “stdin: is not a tty” issue
• How to split different servers between backup hosts
How rsnapshot backups are performed
debops.rsnapshot role configures a set of scripts launched from cron periodically, and a set of configuration
files for each host that is being backed up in /etc/rsnapshot/<host>/ directory.
The whole backup sequence is:
1. cron launches rsnapshot-cron-wrapper script with a specified interval (hourly, daily, weekly,
monthly).
2. rsnapshot-cron-wrapper scans /etc/rsnapshot/ directory looking for configuration files, and
checks if a given configuration uses specific interval - for example when a hourly interval is executed, script
checks if retain hourly is present in the rsnapshot.conf configuration file.
3. If
current
interval
is
found
and
particular
configuration
is
not
disabled
(file
/etc/rsnapshot/<host>/disabled is absent), script launches another script, runner using
nohup and puts it in the background. This is done to all host configurations at once.
4. runner script picks a random interval between 1 minute and 20 minutes (depending on the configuration) and
sleeps. This is done to prevent huge repeating waves of disk activity on all hosts at once.
5. When the time comes, runner script starts the rsnapshot command with specified host configuration file.
File synchronization is performed and then backups are rotated.
6. If any output is present from runner or rsnapshot, it is collected and sent to system administrator via
e-mail.
The whole process is repeated for hourly, daily, weekly and monthly intervals. runner script checks before main
execution if a rsnapshot lock file exists and exits gracefully if it’s found, betting on the next interval.
How to backup hosts outside of Ansible cluster
In addition to backing up hosts under Ansible control, you might want to create configuration for backing
up other hosts, which you don’t want to configure them directly (or can’t). For this situation, you can use
2.13. Ansible role: debops.rsnapshot
201
DebOps Documentation, Release master
rsnapshot_external_servers list to configure external hosts in a particular rsnapshot client host.
Configuration of external hosts in Ansible
Here’s an example configuration which will let you backup other.example.org host:
rsnapshot_external_servers:
# Required
- name: ’other.example.org’
# Optional
sleep: ’20’
backup_user: ’root’
ssh_args: ’-p 22’
You can use most of the variables that are defined in rsnapshot_ namespace, just drop the rsnapshot_ prefix.
item.name key is required and should be a FQDN hostname of the remote host you want to backup.
Things to set up on external host
For practical reasons, rsnapshot should use a root account directly on remote host. To make this configuration
more secure, you can use rrsync Perl script provided with rsync which lets you set up read-only access over SSH
from remote hosts.
First, on Debian-based systems, install rsync package and extract provided script to a convenient directory:
sudo apt-get install rsync
sudo gzip -d -c /usr/share/doc/rsync/scripts/rrsync.gz > /usr/local/lib/rrsync
sudo chmod +x /usr/local/lib/rrsync
After that, you will want to install the public SSH key from the root account of the client host to root account
on the host you want to back up. At the same time you will configure this key to only allow for a specific rsync
command. You should include configuration similar to this in /root/.ssh/authorized_keys, in one line:
no-pty,no-agent-forwarding,no-X11-forwarding,no-port-forwarding,command="ionice -c 3 nice /usr/local/
ionice and nice commands will prevent rsync from hogging too much system resources during its operation.
This will allow read-only access to whole filesystem. After that, you can run debops.rsnapshot Ansible role and
it should correctly configure your rsnapshot client host to access external servers.
Fixing “stdin: is not a tty” issue
On default Debian installation this creates a problem - when rsnapshot tries to connect to the server, shell might
respond with a warning:
stdin: is not a tty
This will prompt rsnapshot to send an e-mail to system administrator with the response, which might get annoying
after a while. To avoid that, open /root/.profile file on an external host and change line:
mesg n
to:
202
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
tty -s && mesg n
This will tell shell that it should check if connection is interactive before changing the terminal settings.
How to split different servers between backup hosts
If you are configuring multiple rsnapshot client hosts, all of them will back up all hosts from
rsnapshot_servers group (but not each other).
If you want to split different hosts between various rsnapshot clients, you can do that using separate Ansible
groups.
Here’s an example Ansible inventory:
# Main host group
[all_hosts]
alpha
beta
gamma
delta
archive-one
archive-two
# These hosts should be archived on ’archive-one’
[archive_group_one]
alpha
beta
# These hosts should be archived on ’archive-two’
[archive_group_two]
gamma
delta
# List of rsnapshot clients
[debops_rsnapshot]
archive-one
archive-two
# List of rsnapshot servers
[debops_rsnapshot_rsync:children]
archive_group_one
archive_group_two
Now, with this inventory in place, you can tell the rsnapshot client hosts which host group to use for their servers:
# In host_vars/archive-one/rsnapshot.yml:
rsnapshot_servers: ’{{ groups.archive_group_one }}’
# In host_vars/archive-two/rsnapshot.yml:
rsnapshot_servers: ’{{ groups.archive_group_two }}’
This will make debops.rsnapshot only configure rsync servers on their respectful rsnapshot clients.
2.13.6 Troubleshooting
In case of any errors during backup, debops.rsnapshot role collects output of all scripts and sends it if anything
shows up to <backup> e-mail account. With default debops.postfix configuration, this account is aliased to root
2.13. Ansible role: debops.rsnapshot
203
DebOps Documentation, Release master
account, so all e-mails should be forwarded to the system administrator.
Logs for each server configuration are stored in /var/log/rsnapshot/ directory, and are automatically rotated.
2.13.7 Copyright
Copyright (C) 2015 Maciej Delmanowski <[email protected]>
Copyright (C) 2015 DebOps Project http://debops.org/
[see Credits for more details]
his 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.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/
2.13.8 Credits
• Maciej Delmanowski <drybjed_at_gmail.com>
– creator of the DebOps Project
– current project maintainer
2.13.9 Changelog
v0.1.2
Released: 2015-02-26
• rsnapshot_one_fs default value is set to 0 to enable backups across filesystems. This is less surprising
and makes sure that everything that should be backed up, is backed up by default. [drybjed]
• Add more OpenVZ directories to includes/excludes. [drybjed]
v0.1.1
Released: 2015-02-23
• Scan SSH fingerprints separately from hosts with custom backup hostname, otherwise Ansible throws an error
about missing dict key in list of results [drybjed]
v0.1.0
Released: 2015-02-22
• Initial release [drybjed]
204
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
2.14 Ansible role: debops.secret
2.14.1 Introduction
debops.secret role enables you to have a separate directory on Ansible Controller (different than the playbook
directory and inventory directory) which can be used as a handy “workspace” for other roles.
Some usage examples of this role in DebOps include:
• password lookups, either from current role, or using known location of passwords from other roles, usually
dependencies (for example debops.mysql role can manage an user account in the database with random
password and other role can lookup that password to include in a generated configuration file);
• secure file storage, for example for application keys generated on remote hosts (debops.boxbackup role
retrieves client keys for backup purposes), for that reason secret directory should be protected by an external
means, for example encrypted filesystem (currently there is no encryption provided by default);
• secure workspace (debops.boxbackup role, again, uses secret directory to create and manage Root CA for
backup servers - client and server certificates are automatically downloaded to Ansible Controller, signed and
uploaded to destination hosts);
• simple centralized backup (specific roles like sshd, pki and monkeysphere have a separate task lists that are
invoked by custom playbooks to allow backup and restoration of ssh host keys and SSL certificates. Generated
.tar.gz files are kept on Ansible Controller in secret directory);
2.14.2 Installation
This role requires at least Ansible v1.7.0. To install it, run:
ansible-galaxy install debops.secret
2.14.3 Getting started
By default all you need to do to use debops.secret role is include it in your common playbook at the beginning:
--- hosts: all
roles:
- role: debops.secret
That will allow all your roles in this and subsequent plays to access secret variable and use it consistently.
Unfortunately, it doesn’t work well when you use Ansible with --tags parameter, which might omit your common
play, thus not setting secret* variables at all and changing your passwords to empty values, modifying config files
incorrectly, basically not honoring the idempotency principle.
Solution to that problem is to either include debops.secret role in all your plays (similar to the one above), or
include it as a dependency in roles that require it:
--dependencies:
- role: debops.secret
This will ensure that roles utilizing secret variable will be able to access it correctly and you don’t need to remember
to include debops.secret role in all your playbooks.
2.14. Ansible role: debops.secret
205
DebOps Documentation, Release master
Usage examples
Example password lookup with password written to a variable. You can define this variable anywhere Ansible variables
can be defined, but if you want to give playbook users ability to overwrite it in inventory, you should define it in
role/defaults/main.yml:
--mysql_root_password: "{{ lookup(’password’, secret + ’/credentials/’ + ansible_fqdn + ’/mysql/root/pa
When this variable is set in role/defaults/main.yml, you can easily overwrite it in your inventory, like this:
--mysql_root_password: "correct horse battery staple"
You
can
also
change
the
password
directly
in
secret
directory,
in
this
case
in
secret/credentials/hostname/mysql/root/password and Ansible should update the password
on the remote server (if role is written to support this).
Example file download task from remote host to Ansible controller, sored in secret directory:
--fetch:
src: "/etc/fstab"
flat: True
dest: "{{ secret + ’/storage/’ + ansible_fqdn + ’/etc/fstab’ }}"
Example file upload task from Ansible Controller to remote host with file from secret directory:
--copy:
dest: "/etc/fstab"
owner: "root"
group: "root"
mode: "0644"
src: "{{ secret + ’/storage/ + ansible_fqdn + ’/etc/fstab’ }}"
2.14.4 Default variables
Secret local storage
secret_root
Path to a directory in which a relative secret directory will be created. By default, it will be relative to Ansible inventory
secret_root: ’{{ inventory_dir | realpath }}’
secret_dir
Name of the directory which contains secrets. It will be in the form “secret” by default
secret_dir: ’secret’
secret_levels
How many directory levels to add relative to secret_root, by default 1 level. For example, to go 2 levels up, set this
variable to ‘../..’
secret_levels: ’..’
secret
206
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
Absolute path to directory with secrets. It will be configured as relative to current inventory directory. Use this variable
in file and password lookups
secret: ’{{ secret_root + "/" + secret_levels + "/" + secret_dir }}’
LDAP server admin access
secret_ldap_* variables are used by ldap_* Ansible modules to access LDAP server for the current domain
with administrative privileges, by binding to the admin account with specified bind DN and password. Because these
need to be provided with every task that uses ldap_* modules, variables below are used as a convenient central
location.
secret_ldap_domain
Domain used for LDAP base DN and to select default LDAP server
secret_ldap_domain: ’{{ ansible_domain }}’
secret_ldap_server
LDAP server hostname / IP address which holds the database. ldap_* modules will connect to it natively, so it
should be available at least from the Ansible Controller.
secret_ldap_server: ’{{ "ldap." + secret_ldap_domain }}’
secret_ldap_server_uri
URI used in tasks to connect to LDAP server natively, it should be used in ldap_attr and ldap_entry tasks
secret_ldap_server_uri: ’{{ "ldap://" + secret_ldap_server + "/" }}’
secret_ldap_start_tls
Enable or disable STARTTLS for encrypted communication with the LDAP server. Should always be enabled.
secret_ldap_start_tls: ’true’
secret_ldap_basedn
LDAP Base DN used for to create bind DN
secret_ldap_basedn: ’{{ "dc=" + secret_ldap_domain.split(".") | join(",dc=") }}’
secret_ldap_admin_bind_dn
LDAP administrator account
secret_ldap_admin_bind_dn: ’{{ "cn=admin," + secret_ldap_basedn }}’
secret_ldap_admin_password
Path to a file in secret/ directory which stores password for specified admin account on configured LDAP server.
This file will be populated by debops.slapd role if a server is configured with it.
secret_ldap_admin_password: ’{{ secret + "/ldap/" + ansible_domain + "/credentials/" + secret_ldap_se
secret_ldap_admin_bind_pw
LDAP administrator password
secret_ldap_admin_bind_pw: ’{{ lookup("password", secret_ldap_admin_password) }}’
secret_ldap_delegate_to
2.14. Ansible role: debops.secret
207
DebOps Documentation, Release master
Each LDAP administrative task should be delegated to either localhost (Ansible Controller), or to the LDAP server
itself. This host will have access to LDAP admin password, and requires installed python-ldap package.
secret_ldap_delegate_to: ’localhost’
secret_ldap_sudo
Access through sudo is not required on localhost, but if LDAP tasks are delegated to different hosts, it might be
required there.
secret_ldap_sudo: False
2.14.5 Detailed guides
How local secrets work
Here’s a default project directory layout kept in a git repository:
~/Projects/
‘-- data-center/
|-- .git/
‘-- ansible/
|-- inventory/
|
|-- group_vars/
|
|-- host_vars/
|
‘-- hosts
|
‘-- secret/
|-- credentials/
‘-- storage/
If you use debops-padlock script to create encrypted EncFS storage for your secrets, directory layout will be
slightly different:
~/Projects/
‘-- data-center/
|-- .git/
‘-- ansible/
|-- .encfs.secret/
|
|-- U8dfMgfgg48vj/
|
|-- fk5fkg5NN/
|
‘-- padlock*
|
|-- inventory/
|
|-- group_vars/
|
|-- host_vars/
|
‘-- hosts
|
‘-- secret/
<- encrypted secrets
<- unlock/lock script
<- plaintext secrets
While project is “at rest”, secrets are encrypted inside EncFS directory, and they don’t show up in the secret/
directory. When you use debops script to run the playbook, padlock script unlocks the encrypted directory and
secrets are available again in secret/ directory for ansible-playbook to use.
208
Chapter 2. Do you want to contribute?
DebOps Documentation, Release master
How to use LDAP variables
In main DebOps playbook repository you can find Ansible modules ldap_attr and ldap_entry. They can be
used to access and control LDAP servers. In various DebOps roles, they are used to perform certain tasks in shared
environment.
Some of the above tasks require admin privileges on the LDAP server. To provide access to it in a secure manner,
debops.secret role keeps a set of variables meant to be used with these tasks.
For security reasons, LDAP-related tasks should be delegated to localhost (Ansible Controller) or the LDAP server
itself. The host that runs these tasks requires python-ldap library. Modules will access LDAP directly, without
using SSH redirection, so TLS encryption is strongly recommended. You should also take care to not log these tasks
to avoid leaking the LDAP administrator password in logs.
Example usage of LDAP secret variables:
- name: Create an entry in LDAP database
ldap_entry:
dn: ’ou=People,dc=example,dc=org’
objectClass: [ ’organizationalUnit’, ’top’ ]
state: ’present’
server_uri: ’{{ secret_ldap_server_uri }}’
start_tls: ’{{ secret_ldap_start_tls }}’
bind_dn: ’{{ secret_ldap_admin_bind_dn }}’
bind_pw: ’{{ secret_ldap_admin_bind_pw }}’
sudo: ’{{ secret_ldap_sudo }}’
delegate_to: ’{{ secret_ldap_delegate_to }}’
no_log: True
- name: Add attribute to an LDAP entry
ldap_attr:
dn: ’cn=user,ou=People,dc=example,dc=org’
name: ’{{ item.key }}’
values: ’{{ item.value }}’
state: ’exact’
server_uri: ’{{ secret_ldap_server_uri }}’
start_tls: ’{{ secret_ldap_start_tls }}’
bind_dn: ’{{ secret_ldap_admin_bind_dn }}’
bind_pw: ’{{ secret_ldap_admin_bind_pw }}’
sudo: ’{{ secret_ldap_sudo }}’
delegate_to: ’{{ secret_ldap_delegate_to }}’
with_dict:
uid: ’{{ user_username }}’
userPassword: ’{{ user_password }}’
no_log: True
Of course for this to work, debops.secret needs to be included in the playbook, either as a role, or a role dependency. You can change the values of secret_ldap_* variables in inventory as you need.
If you use debops.slapd role to configure an LDAP server, it will automatically copy the admin accout password to a
location defined in secret_ldap_admin_password variable to be accessed by the debops.secret role as
needed.
2.14.6 Copyright
Copyright (C) 2013 Maciej Delmanowski <[email protected]>
Copyright (C) 2014 DebOps Project http://debops.org/
[see Credits for more details]
2.14. Ansible role: debops.secret
209
DebOps Documentation, Release master
his 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.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/
2.14.7 Credits
• Maciej Delmanowski <drybjed_at_gmail.com>
– creator of the DebOps Project
– current project maintainer
2.14.8 Changelog
v0.2.1
Released: 2015-02-25
• Redesign LDAP support, add more required variables. [drybjed]
v0.2.0
Released: 2015-02-24
• Convert documentation to new format. [drybjed]
• Add LDAP integration [drybjed]
v0.1.0
Released: 2015-02-12
• First release, add CHANGES.rst [drybjed]
210
Chapter 2. Do you want to contribute?
Index
E
environment variable
postfix, 159, 185
postfix_allow_smtp, 161, 187
postfix_allow_smtps, 161, 187
postfix_allow_submission, 161, 187
postfix_archive_account, 162, 188
postfix_archive_domains, 163, 189
postfix_archive_method, 162, 188
postfix_archive_separator, 163, 189
postfix_archive_subdomain, 162, 188
postfix_archive_to, 162, 188
postfix_default_local_alias_recipients, 164, 190
postfix_delay_warning_time, 160, 186
postfix_dependent_lists, 165, 191
postfix_dependent_maincf, 165, 191
postfix_dependent_mastercf, 165, 191
postfix_inet_interfaces, 160, 186
postfix_local_aliases, 164, 190
postfix_local_maincf, 165, 191
postfix_local_mastercf, 165, 191
postfix_mailname, 160, 186
postfix_message_size_limit, 160, 186
postfix_mydestination, 160, 186
postfix_mydomain, 160, 186
postfix_mynetworks, 160, 186
postfix_pki, 161, 187
postfix_pki_crt, 161, 187
postfix_pki_dhparam, 161, 187
postfix_pki_key, 161, 187
postfix_pki_path, 161, 187
postfix_pki_realm, 161, 187
postfix_postscreen_dnsbl_sites, 163, 189
postfix_postscreen_dnswl_sites, 163, 189
postfix_relay_domains, 160, 186
postfix_relayhost, 159, 185
postfix_sender_dependent_relayhost_map, 162, 188
postfix_smtp_sasl_password_map, 162, 188
postfix_smtpd_authorized_xclient_hosts, 165, 191
postfix_smtpd_client_restrictions, 164, 190
postfix_smtpd_data_restrictions, 164, 190
postfix_smtpd_helo_restrictions, 164, 190
postfix_smtpd_recipient_restrictions, 164, 190
postfix_smtpd_relay_restrictions, 164, 190
postfix_smtpd_sender_restrictions, 164, 190
postfix_transport_maps, 160, 186
postfix_virtual_alias_maps, 160, 186
rsnapshot_backup_host, 173, 199
rsnapshot_backup_path, 173, 199
rsnapshot_backup_user, 173, 199
rsnapshot_clients, 170, 171, 196, 197
rsnapshot_daily, 172, 199
rsnapshot_exclude, 173, 200
rsnapshot_exclude_default, 173, 200
rsnapshot_external_servers, 171, 175, 198, 202
rsnapshot_hourly, 172, 199
rsnapshot_include, 174, 200
rsnapshot_include_default, 174, 201
rsnapshot_link_dest, 172, 198
rsnapshot_mail_to, 172, 198
rsnapshot_monthly, 172, 199
rsnapshot_one_fs, 172, 199
rsnapshot_rrsync_script, 173, 199
rsnapshot_servers, 170, 171, 196, 198
rsnapshot_sleep, 172, 198
rsnapshot_snapshot_root, 172, 198
rsnapshot_ssh_args, 173, 199
rsnapshot_ssh_command, 173, 199
rsnapshot_sync_first, 172, 198
rsnapshot_uuid, 173, 200
rsnapshot_weekly, 172, 199
secret, 180, 206
secret_dir, 180, 206
secret_ldap_admin_bind_dn, 181, 207
secret_ldap_admin_bind_pw, 181, 207
secret_ldap_admin_password, 181, 207
secret_ldap_basedn, 181, 207
secret_ldap_delegate_to, 181, 207
secret_ldap_domain, 180, 207
secret_ldap_server, 180, 207
secret_ldap_server_uri, 180, 207
211
DebOps Documentation, Release master
secret_ldap_start_tls, 181, 207
secret_ldap_sudo, 181, 208
secret_levels, 180, 206
secret_root, 180, 206
R
rsnapshot_clients, 170, 196
rsnapshot_external_servers, 175, 202
rsnapshot_servers, 170, 196
212
Index
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement