Skip to content

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:

  1. Masterless GitOps mode (local_policy) — no master node and no ControlPlane listener anywhere in the network; Ansible renders a declarative /etc/ololo-relay/policy.yaml directly onto each node.
  2. Loopback / private-subnet Master — the master listens strictly on 127.0.0.1 or an internal management VLAN, Ansible applies live zero-downtime policy changes over SSH, and nodes persist policy.snapshot on 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 edge and exit node points to local_policy: /etc/ololo-relay/policy.yaml in /etc/ololo-relay/node.yaml;
  • raw node tokens live exclusively inside Ansible Vault; policy.yaml on disk contains only their SHA-256 digests computed on the Ansible controller;
  • each edge node receives only its own node.master_token in node.yaml (0640), which it presents as a Bearer credential when dialing exit nodes over TLS TrafficRelay;
  • office or home edge gateways require zero inbound ports or public IPs — only exit nodes listen on 443/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:

  1. 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
    
  2. Nodes boot independently of master reachability. Every node caches /var/lib/ololo-relay/policy.snapshot on disk upon first sync. Even if the management link is down or the master is offline for maintenance, edge and exit nodes restart cleanly and continue forwarding traffic using the cached snapshot.
  3. 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:
    ssh -N -L 9443:127.0.0.1:9443 deploy@10.10.0.1
    
    Point ololo-relay-admin to h2c://127.0.0.1:9443 with your admin token; as soon as the SSH session closes, external access to the ControlPlane ceases to exist.