Skip to main content

Ansible Deployment Guide

This guide covers deploying ZeroTier to Linux systems (such as Raspberry Pis) using Ansible automation.

Overview​

Use Ansible to deploy ZeroTier at scale across multiple Linux hosts. This playbook will:

  • Install ZeroTier on Debian/Ubuntu-based systems (including Raspberry Pi OS)
  • Configure automatic network joining
  • Restart the service to apply changes

Prerequisites​

  • Ansible 2.9 or newer installed on your control node
  • SSH access to target hosts with sudo privileges
  • Network ID of the ZeroTier network to join (16-character hex string from ZeroTier Central)

Basic Ansible Playbook​

Replace 1c33c1ced02a5eee with your actual ZeroTier network ID.

---
- name: Deploy ZeroTier to Raspberry Pis
  hosts: all
  become: yes
  vars:
    zerotier_network_id: "1c33c1ced02a5eee"

  tasks:
    - name: Install ZeroTier via install script
      ansible.builtin.shell: |
        curl -s https://install.zerotier.com | bash
      args:
        creates: /usr/sbin/zerotier-one

    - name: Ensure ZeroTier service is started and enabled
      ansible.builtin.systemd:
        name: zerotier-one
        state: started
        enabled: yes

    - name: Create networks.d directory
      ansible.builtin.file:
        path: /var/lib/zerotier-one/networks.d
        state: directory
        mode: '0700'
        owner: root
        group: root

    - name: Create auto-join network configuration
      ansible.builtin.file:
        path: "/var/lib/zerotier-one/networks.d/{{ zerotier_network_id }}.conf"
        state: touch
        mode: '0600'
        owner: root
        group: root

    - name: Restart ZeroTier to join network
      ansible.builtin.systemd:
        name: zerotier-one
        state: restarted

Usage​

  1. Create an inventory file (hosts.ini) with your Raspberry Pi IP addresses:

    [raspberry_pis]
    192.168.1.101 ansible_user=pi
    192.168.1.102 ansible_user=pi
    192.168.1.103 ansible_user=pi

  2. Save the playbook as deploy-zerotier.yml

  3. Run the playbook:

    ansible-playbook -i hosts.ini deploy-zerotier.yml --ask-become-pass
Update Inventory with ZeroTier IPs

After ZeroTier is deployed and authorized, update your inventory file to use the ZeroTier IP addresses instead of local IPs. This allows you to manage devices consistently from any internet connection, regardless of their physical network location.

[raspberry_pis]
172.22.195.59 ansible_user=pi  # ZeroTier IP
172.22.217.93 ansible_user=pi  # ZeroTier IP
172.22.182.44 ansible_user=pi  # ZeroTier IP

Post-Deployment​

After running the playbook, devices will appear in your ZeroTier Central network as unauthorized members. You'll need to authorize them:

  • Log into ZeroTier Central
  • Navigate to your network
  • Authorize the new members in the Members section

Once authorized, each device will have a ZeroTier IP address that can be used for SSH access from any internet connection, making remote management consistent regardless of the device's physical network location.

Advanced Configuration​

Deploying local.conf Settings​

You can configure ZeroTier's local.conf file to customize node behavior. For example, to enable Low Bandwidth Mode for devices on metered connections:

- name: Deploy local.conf with Low Bandwidth Mode
  ansible.builtin.copy:
    dest: /var/lib/zerotier-one/local.conf
    content: |
      {
        "settings": {
          "lowBandwidthMode": true
        }
      }
    mode: '0600'
    owner: root
    group: root
  notify: Restart ZeroTier

handlers:
  - name: Restart ZeroTier
    ansible.builtin.systemd:
      name: zerotier-one
      state: restarted
Per-Node Configuration

Each node may require unique local.conf settings (different network interface names for multipath bonding, specific port configurations, etc.). Use Ansible host variables or templates to customize configurations per-node when needed.

See Client Configuration for all available local.conf options and Low Bandwidth Mode for reducing protocol traffic on expensive links.