Ansible

This repository holds the Ansible playbook to deploy a ffsh gateway in the standard configuration and to provision dedicated service hosts. It is based on https://docs.freifunk-suedholstein.de/de/1.5/gateway.html but changes were made where it was plausible.

requirements

• Clone the repository.
• Ansible installed

devcontainer

This repository includes a devcontainer so you can run Ansible and ansible-lint in a reproducible environment.

1. Open the repository in VS Code.
2. Run Dev Containers: Reopen in Container.
3. Wait for the build to finish. The container installs ansible and ansible-lint.

Quick checks:

ansible --version
ansible-lint --version

Run linting:

ansible-lint

Run the playbook:

ansible-playbook --vault-id=fastd_key@prompt setup.yml

If you run into ssh issues try running:

ssh root@$gatewayIP

this allows you to interactively accept key changes.

ssh-key

As the login is done via ssh make sure that the ssh key is registered at your identity manager ssh-add $keyfile. That way Ansible will be able to automatically detect the right ssh key and connect to the server.

hosts

If you want to deploy to a new gateway you need to add it to the hosts.yml file in the repo, just compare it to brunsbach and add your own details.

If you want to add a service host, place it in the dedicated service group in hosts.yml:

• services_map for the map stack (batman, batctl, grafana_public, meshviewer)
• services_web for the web stack (batman, batctl, website, firmware_release, firmware_selector)

Website deployment

The website role runs on web-ffsh. The main domain is served as a static site from /var/www/web-static; the beta domain remains at /var/www/web-beta. The previous WordPress files at /var/www/web and the PHP runtime are retained for rollback, but the main-domain vhost no longer serves them.

The Hugo repository's CI should build the site and deploy pushes to main only to beta, with production deployments restricted to version tags. Use separate SSH keys for the two destinations. Add their public keys to the Ansible Vault variables vault_website_beta_deploy_public_key and vault_website_prod_deploy_public_key in group_vars/secrets.yml; keep the matching private keys in the Hugo repository's CI secrets. The CI workflow is separate from this Ansible repository.

The standalone DNS host belongs to the dns group. The DNS play only installs node_exporter and bind_exporter; it does not manage the existing BIND service, zones, or listening addresses.

Before deploying the exporters, configure the DNS host's manually managed BIND instance to expose its statistics channel on localhost at http://127.0.0.1:8053/, then reload BIND and verify its statistics endpoint. The bind_exporter service reads the BIND PID file at /run/named/named.pid. Allow the monitoring host to reach TCP/UDP port 53 and TCP ports 9100 and 9119 as appropriate for the blackbox DNS probe and exporter scrapes; restrict exporter access to the monitoring host.

Deploy the DNS exporters with:

ansible-playbook --vault-id=fastd_key@prompt setup.yml --limit bind --tags node_exporter,bind_exporter

The monitoring host probes freifunk-suedholstein.de as an A record against the DNS host and exposes the result as the blackbox-dns Prometheus job.

If you set enable_wireguard_exit to true ansible will deploy wireguard and attempt to generate a mullvad config.

Mullvad

This ansible script uses wg-conf-gen to generate a Mullvad wireguard configurration.

The python script will call the Mullvad API with the details you provide in host_vars (see below).

It will select a random gateway based on country and city.

host_vars/$gatewayname.yml

You also need to supply your fastd secret as an encrypted secret, you get the password via the NOC Team.

To create a new fastd secret, execute the following, this will ask you for a password and open an editor.

ansible-vault create --vault-id fastd_key@prompt host_vars/$gatewayname.yml

The config has the following options.

option	comment
fastd_secret	fastd secret key
wg_device	Optional but you can put the name here that was generated by mullvad
wg_pk	Wireguard private key provided by mullvad
wg_address	ipV4 and ipV6 address provided by mullvad
wg_country	Country supported by mullvad
wg_city	A City that mullvad has in your selected country
ffshmon_mail	The email that should be used to send alerts if the wireguard tunnel is down
ffshmon_pw	The password for the email

For available country and city check here: https://mullvad.net/de/servers

Example config:

fastd_secret: 1234df132fssd...
wg_device: Mellow Pony
wg_pk: aDfkfdsgnn1232345...
wg_address: 1.2.3.4/32,fxx...../128
wg_country: Netherlands
wg_city: Amsterdam
ffshmon_mail: wg-mon@freifunk-suedholstein.de
ffshmon_pw: secretpassword

save and close the editor, done you added your secret :)

You can change the content any time by

ansible-vault edit --vault-id fastd_key@prompt host_vars/$gatewayname.yml

Usage

Run playbook on all gateways listed in hosts:

ansible-playbook --vault-id=fastd_key@prompt setup.yml --limit gateways

Run both service hosts:

ansible-playbook --vault-id=fastd_key@prompt setup.yml --limit "services_map:services_web"

Run only the map service host:

ansible-playbook --vault-id=fastd_key@prompt setup.yml --limit services_map

Run only the web service host:

ansible-playbook --vault-id=fastd_key@prompt setup.yml --limit services_web

Run the monitoring host:

ansible-playbook --vault-id=fastd_key@prompt setup.yml --limit monitoring

Alertmanager is available through an SSH tunnel because it listens on localhost on the monitoring host:

ssh -N -L 9093:127.0.0.1:9093 root@$monitoringIP

Then open http://127.0.0.1:9093 in your browser.

The Alertmanager role installs the official release, including the web UI and the amtool command-line utility. The debian package does not contain the web UI so we go with this.

By default, deployments run one host at a time (serial: 1).

Special case: run all gateways at once (for example for fast static page updates):

ansible-playbook --vault-id=fastd_key@prompt setup.yml -e deploy_serial=100%

Run playbook on one host

ansible-playbook --vault-id=fastd_key@prompt setup.yml --limit $hostname

Run only the batman and batctl roles for a specific service host:

ansible-playbook --vault-id=fastd_key@prompt setup.yml --limit $hostname --tags "batman-adv,batctl"

Run only the roles with the specific tag, to see which role is attached to which tag open setup.yaml:

ansible-playbook --vault-id=fastd_key@prompt setup.yml --tags "ssh keys"

These can also be combined:

ansible-playbook --vault-id=fastd_key@prompt setup.yml --limit $hostname --tags "oh-my-zsh"