Role Reference

Role Reference

This page is the short factual reference for every role. Read the dedicated pages before changing behavior in production.

users

Used by bootstrap to create the managed login account.

The role accepts generic users_* inputs or Bootstrap-compatible inputs:

bootstrap_users:
  - name: deploy
    home: /srv/deploy
    shell: /bin/bash
    groups:
      - sudo
    ssh_public_keys:
      - "ssh-ed25519 AAAA... deploy@example"
    sudo_nopasswd: false
    force_password_change: false
    create_home: true
    state: present

Requirements enforced by the role:

• At least one account exists.
• User names are unique.
• Every present user has a name and at least one SSH public key.
• The default password and password salt are nonempty.

The role creates /var/lib/ansible/bootstrap-users/<user>. It sets the initial password only before this marker exists.

ssh_hardening

See Security and Networking and Setup and SSH Migration.

Useful inputs beyond the standard port and authentication controls:

ssh_hardening_allow_users:
  - bootstraper
ssh_hardening_allow_groups: []
ssh_hardening_deny_users: []
ssh_hardening_deny_groups: []
ssh_hardening_ciphers: []
ssh_hardening_macs: []
ssh_hardening_kex_algorithms: []
ssh_hardening_hostkey_algorithms: []
ssh_hardening_extra_options: {}

Use cryptographic algorithm overrides only when you know both the server and all controllers support them. A bad list can make every SSH client fail.

iptables_firewall

Inputs must be lists of ports, not quoted comma-separated strings:

iptables_open_tcp_ports:
  - "{{ ssh_hardening_port }}"
  - 443
iptables_open_udp_ports:
  - 500
  - 4500

Every value must resolve to a port in 1..65535. The role validates this before it replaces /etc/iptables/rules.v4.

system_tools

Every host receives these APT packages:

system_tools_packages:
  - mtr
  - traceroute
  - iperf3
  - nmap
  - iftop
  - iotop
  - btop

Ubuntu 24.04 provides iperf3; there is no separate iperf package here.

docker

Docker runs only on traefik_hosts. It supports x86_64, aarch64, and armv7l architecture mappings and validates the rendered daemon configuration with dockerd --validate before installation completes.

Input:

docker_users:
  - bootstraper

Do not set this casually. Docker group members effectively have root-level host control.

traefik

Required input:

traefik_acme_email: "{{ vault_traefik_acme_email }}"

Important optional inputs:

traefik_image: traefik:v3.3
traefik_docker_network: traefik
traefik_dashboard_enabled: false
traefik_dashboard_host: ""
traefik_dashboard_username: ""
traefik_dashboard_password: "{{ vault_traefik_dashboard_password }}"

See Docker and Traefik.

crowdsec

Baseline values:

crowdsec_collections:
  - crowdsecurity/sshd
crowdsec_acquisitions:
  - name: sshd
    path: /var/log/auth.log
    type: syslog
crowdsec_firewall_bouncer_iptables_chains:
  - INPUT
crowdsec_hub_update_enabled: true
crowdsec_hub_update_hour: "4"
crowdsec_hub_update_minute: "23"

On traefik_hosts, the project adds crowdsecurity/traefik, the Traefik access log acquisition, and the DOCKER-USER bouncer chain. See Security and Networking.

Application roles

Role	Required values	Persistent path
Vaultwarden	vaultwarden_domain, vaultwarden_admin_token	/opt/vaultwarden/data
3x-ui	three_x_ui_panel_domain, nonempty three_x_ui_inbounds	/opt/3x-ui/data
Telemt	telemt_sni_hostname, telemt_config, valid telemt_listen_port	/opt/telemt/config/telemt.toml

All three require membership in their application group and traefik_hosts. Read Applications before deploying one.