Headless Ansible Deployment
In production corporate networks and self-hosted infrastructure, the control plane should not have to be exposed to the public internet, nor should node startup or traffic forwarding depend on external reachability of a master server or desktop GUI. Because ololo-relay configuration boils down to two clean YAML files, an entire mesh can be provisioned declaratively with Ansible straight from Git.
Below are two battle-tested architectures with zero public control-plane exposure:
- Masterless GitOps mode (
local_policy) — no master node and no ControlPlane listener anywhere in the network; Ansible renders a declarative/etc/ololo-relay/policy.yamldirectly onto each node. - Loopback / private-subnet Master — the master listens strictly on
127.0.0.1or an internal management VLAN, Ansible applies live zero-downtime policy changes over SSH, and nodes persistpolicy.snapshoton disk so restarts succeed even if the master is offline.
Architecture 1. Masterless Declarative Mesh (local_policy)
When routing policy is managed via Git pull requests (Infrastructure as Code), you do not need a master database or GUI at all:
- every
edgeandexitnode points tolocal_policy: /etc/ololo-relay/policy.yamlin/etc/ololo-relay/node.yaml; - raw node tokens live exclusively inside Ansible Vault;
policy.yamlon disk contains only theirSHA-256digests computed on the Ansible controller; - each
edgenode receives only its ownnode.master_tokeninnode.yaml(0640), which it presents as a Bearer credential when dialingexitnodes over TLSTrafficRelay; - office or home
edgegateways require zero inbound ports or public IPs — onlyexitnodes listen on443/tcp.
Directory Layout
ansible-relay/
├── inventory/
│ ├── hosts.yml
│ └── group_vars/
│ └── all/
│ ├── relay.yml # peers, routes, and cluster parameters
│ └── vault.yml # encrypted raw tokens (ansible-vault)
├── files/ # (optional) local .deb/.rpm packages for air-gapped hosts
├── templates/
│ ├── policy.yaml.j2
│ └── node.yaml.j2
└── site.yml
Inventory & Variables (hosts.yml, relay.yml, vault.yml)
inventory/hosts.yml:
all:
children:
relay_nodes:
hosts:
gw-office-1:
ansible_host: 10.10.0.1
relay_id: gw-office-1
relay_roles: { edge: true, exit: false }
relay_tun_address: "100.64.0.1/32"
relay_capture_iifs: ["eth1"]
relay_capture_wan_iface: "eth0"
exit-eu-1:
ansible_host: 198.51.100.20
relay_id: exit-eu-1
relay_roles: { edge: false, exit: true }
relay_public_addr: "exit-eu-1.example.com:443"
relay_cert_file: "/etc/letsencrypt/live/exit-eu-1.example.com/fullchain.pem"
relay_key_file: "/etc/letsencrypt/live/exit-eu-1.example.com/privkey.pem"
exit-asia-1:
ansible_host: 203.0.113.45
relay_id: exit-asia-1
relay_roles: { edge: false, exit: true }
relay_public_addr: "exit-asia-1.example.com:443"
relay_cert_file: "/etc/letsencrypt/live/exit-asia-1.example.com/fullchain.pem"
relay_key_file: "/etc/letsencrypt/live/exit-asia-1.example.com/privkey.pem"
Encrypted inventory/group_vars/all/vault.yml (ansible-vault create ...):
# Generate a token: openssl rand 32 | base64 | tr '+/' '-_' | tr -d '=\n'
vault_relay_tokens:
gw-office-1: "9fK2...your_32_byte_base64url_token"
exit-eu-1: "4mP8...your_32_byte_base64url_token"
exit-asia-1: "7xR1...your_32_byte_base64url_token"
Shared routing policy inventory/group_vars/all/relay.yml:
relay_offline_install: false # true — install from local files/ without contacting repo.ololo.tech
relay_block_bittorrent: true
relay_routes:
- id: "local-bypass"
peers: ["localhost"]
domains: [".local", ".lan", ".corp.internal"]
cidrs: ["127.0.0.0/8", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "100.64.0.0/10"]
- id: "partner-api-asia"
peers: ["exit-asia-1", "exit-eu-1"]
domains: [".api-partner.example", ".settlement.example"]
- id: "qa-staging-eu"
peers: ["exit-eu-1", "exit-asia-1"]
domains: [".staging-eu.example.org"]
relay_default:
mode: direct # all unmatched traffic exits directly from the gateway (or 'relay')
peers: []
Configuration Templates
templates/policy.yaml.j2 — shared policy snapshot; only SHA-256 token hashes are written to remote hosts:
version: 1
block_bittorrent: {{ relay_block_bittorrent | bool | lower }}
peers:
{% for host in groups['relay_nodes'] %}
{% set hv = hostvars[host] %}
- id: {{ hv.relay_id }}
kind: server
admin: false
roles:
master: false
edge: {{ hv.relay_roles.edge | bool | lower }}
exit: {{ hv.relay_roles.exit | bool | lower }}
token_sha256: "{{ vault_relay_tokens[hv.relay_id] | hash('sha256') }}"
{% if hv.relay_public_addr is defined %}
addrs: ["{{ hv.relay_public_addr }}"]
exit_listen: "0.0.0.0:443"
camouflage:
mode: embedded
{% endif %}
{% if hv.relay_tun_address is defined %}
tun_address: "{{ hv.relay_tun_address }}"
tun_mtu: {{ hv.relay_tun_mtu | default(1420) }}
{% endif %}
{% endfor %}
routes:
{{ relay_routes | to_nice_yaml(indent=2) | indent(2) }}
default:
mode: {{ relay_default.mode }}
{% if relay_default.peers %}
peers: {{ relay_default.peers | to_json }}
{% endif %}
templates/node.yaml.j2 — per-node bootstrap file:
node:
id: {{ relay_id }}
data_dir: /var/lib/ololo-relay
{% if relay_roles.edge %}
master_token: "{{ vault_relay_tokens[relay_id] }}"
{% endif %}
local_policy: /etc/ololo-relay/policy.yaml
{% if relay_roles.edge %}
edge:
tun:
name: ololo0
{% if relay_capture_iifs is defined %}
capture_iifs: {{ relay_capture_iifs | to_json }}
{% endif %}
{% if relay_capture_wan_iface is defined %}
capture_wan_iface: "{{ relay_capture_wan_iface }}"
{% endif %}
fail_closed: {{ relay_fail_closed | default(false) | bool | lower }}
{% endif %}
{% if relay_roles.exit %}
exit:
dial_timeout: 5s
tls:
cert_file: {{ relay_cert_file }}
key_file: {{ relay_key_file }}
{% endif %}
observability:
log_level: info
Rolling Playbook with Air-Gapped Option (site.yml)
serial: 1 restarts nodes one at a time while multi-gateway failover (exit-eu-1, exit-asia-1) keeps active traffic flowing seamlessly:
---
- name: Deploy masterless ololo-relay mesh
hosts: relay_nodes
become: true
serial: 1
tasks:
- name: Install ololo-relay from offline artifact (air-gapped mode)
when: relay_offline_install | bool
block:
- name: Copy local .deb package
ansible.builtin.copy:
src: "ololo-relay_amd64.deb"
dest: "/tmp/ololo-relay_amd64.deb"
mode: "0644"
when: ansible_os_family == "Debian"
- name: Install local .deb package
ansible.builtin.apt:
deb: "/tmp/ololo-relay_amd64.deb"
when: ansible_os_family == "Debian"
- name: Configure official APT repository (online mode)
when: not (relay_offline_install | bool) and ansible_os_family == "Debian"
block:
- name: Ensure /etc/apt/keyrings exists
ansible.builtin.file:
path: /etc/apt/keyrings
state: directory
mode: "0755"
- name: Install repository GPG key
ansible.builtin.shell: |
curl -fsSL https://repo.ololo.tech/pubkey.asc | gpg --batch --yes --dearmor -o /etc/apt/keyrings/ololo-relay.gpg
args:
creates: /etc/apt/keyrings/ololo-relay.gpg
- name: Add ololo-relay APT source
ansible.builtin.copy:
dest: /etc/apt/sources.list.d/ololo-relay.list
content: "deb [signed-by=/etc/apt/keyrings/ololo-relay.gpg] https://repo.ololo.tech/apt stable main\n"
mode: "0644"
register: apt_repo
- name: Install ololo-relay
ansible.builtin.apt:
name: ololo-relay
state: present
update_cache: "{{ apt_repo.changed }}"
- name: Render declarative policy.yaml
ansible.builtin.template:
src: templates/policy.yaml.j2
dest: /etc/ololo-relay/policy.yaml
owner: root
group: ololo-relay
mode: "0640"
notify: Restart ololo-relay
- name: Render node.yaml (0640 root:ololo-relay to protect edge token)
ansible.builtin.template:
src: templates/node.yaml.j2
dest: /etc/ololo-relay/node.yaml
owner: root
group: ololo-relay
mode: "0640"
no_log: true
notify: Restart ololo-relay
- name: Ensure ololo-relay is enabled and running
ansible.builtin.systemd:
name: ololo-relay
enabled: true
state: started
handlers:
- name: Restart ololo-relay
ansible.builtin.systemd:
name: ololo-relay
state: restarted
Run the playbook:
ansible-playbook -i inventory/hosts.yml site.yml --ask-vault-pass
Architecture 2. Private / Loopback Master (127.0.0.1)
When you want zero-restart live policy hot-swap and node health telemetry without exposing the master to the public internet:
- Bind the master exclusively to loopback or an internal management VLAN. Set
master.listen: "10.99.0.1:9443"(with your internal PKI cert) or"127.0.0.1:9443"(loopback H2C with zero external ports):master: listen: "127.0.0.1:9443" data_file: /var/lib/ololo-relay/policy.bbolt initial_policy_file: /etc/ololo-relay/initial-policy.yaml - Nodes boot independently of master reachability. Every node caches
/var/lib/ololo-relay/policy.snapshoton disk upon first sync. Even if the management link is down or the master is offline for maintenance,edgeandexitnodes restart cleanly and continue forwarding traffic using the cached snapshot. - Optional on-demand GUI over an ephemeral SSH tunnel. When an operator wants to edit routes live or inspect session streams in
ololo-relay-admin, no firewall port needs to be opened — forward the loopback port over SSH:Pointssh -N -L 9443:127.0.0.1:9443 deploy@10.10.0.1ololo-relay-admintoh2c://127.0.0.1:9443with your admin token; as soon as the SSH session closes, external access to the ControlPlane ceases to exist.