Install with Ansible

On this page

To deploy agents on many Linux hosts, this playbook installs exactly what the automatic installer installs: the checked binary of a given version, the unprivileged onagent user, the token in a root-only file, the hardened onagent.service.

Before you start#

Ansible on your control node; target hosts with systemd 235+, on x86_64 or aarch64 (glibc), reachable over SSH with become.
One agent per host, each with its own token: create them in Configuration → Agents first. A token can only be used by one running agent.

Inventory and tokens#

Give each host its own token, encrypted with ansible-vault:

INI

[onagre_agents]
par1-prod-dc  ansible_host=10.20.0.5
lyon-dc-agent ansible_host=10.40.0.5

Terminal

ansible-vault encrypt_string '<TOKEN_OF_par1-prod-dc>' --name onagre_token >> inventory/host_vars/par1-prod-dc.yml
ansible-vault encrypt_string '<TOKEN_OF_lyon-dc-agent>' --name onagre_token >> inventory/host_vars/lyon-dc-agent.yml

Playbook#

Pin the version to deploy (onagre_version): read the current one with curl -fsSL https://d.onag.re/version.

YAML

- name: Deploy the Onagre agent
  hosts: onagre_agents
  become: true
  vars:
    onagre_version: "2.9.0.0"
    onagre_arch: "{{ {'x86_64': 'linux-x64', 'aarch64': 'linux-arm64'}[ansible_architecture] }}"
    onagre_url: "https://d.onag.re/agent/{{ onagre_version }}/agent-{{ onagre_arch }}"

  tasks:
    - name: Create the onagent system user
      ansible.builtin.user:
        name: onagent
        system: true
        create_home: false
        home: /nonexistent
        shell: /usr/sbin/nologin

    - name: Create the token directory (root only)
      ansible.builtin.file:
        path: /etc/onagent
        state: directory
        owner: root
        group: root
        mode: "0700"

    - name: Download the agent, checked against its SHA-256
      ansible.builtin.get_url:
        url: "{{ onagre_url }}"
        checksum: "sha256:{{ onagre_url }}.sha256"
        dest: /usr/local/bin/onagent
        owner: root
        group: root
        mode: "0755"
      notify: Restart the agent

    - name: Store the token (root only)
      ansible.builtin.copy:
        dest: /etc/onagent/onagent.env
        content: "TOKEN={{ onagre_token }}\n"
        owner: root
        group: root
        mode: "0600"
      no_log: true
      notify: Restart the agent

    - name: Create the service
      ansible.builtin.copy:
        dest: /etc/systemd/system/onagent.service
        mode: "0644"
        content: |
          [Unit]
          Description=Onagre Agent
          Documentation=https://docs.onagre.io/en/agents/deployment
          Wants=network-online.target
          After=network-online.target

          [Service]
          Type=exec
          User=onagent
          Group=onagent
          EnvironmentFile=/etc/onagent/onagent.env
          Environment=DOTNET_BUNDLE_EXTRACT_BASE_DIR=/var/cache/onagent
          ExecStart=/usr/local/bin/onagent
          WorkingDirectory=/
          Restart=always
          RestartSec=10
          RestartPreventExitStatus=78
          LimitNOFILE=65535
          CacheDirectory=onagent
          UMask=0077
          StandardOutput=journal
          StandardError=journal
          SyslogIdentifier=onagent
          AmbientCapabilities=CAP_NET_RAW
          CapabilityBoundingSet=CAP_NET_RAW
          NoNewPrivileges=yes
          ProtectSystem=strict
          ProtectHome=read-only
          PrivateDevices=yes
          ProtectKernelTunables=yes
          ProtectKernelModules=yes
          ProtectKernelLogs=yes
          ProtectControlGroups=yes
          ProtectClock=yes
          ProtectHostname=yes
          RestrictSUIDSGID=yes
          RestrictRealtime=yes
          RestrictNamespaces=yes
          LockPersonality=yes
          SystemCallArchitectures=native
          RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK

          [Install]
          WantedBy=multi-user.target
      notify: Restart the agent

    - name: Enable and start the agent
      ansible.builtin.systemd:
        name: onagent
        enabled: true
        state: started
        daemon_reload: true

    - name: Restart now if something changed
      ansible.builtin.meta: flush_handlers

    - name: Wait until the agent is connected
      ansible.builtin.uri:
        url: http://127.0.0.1:27520/ready
        return_content: true
      register: onagre_ready
      until: onagre_ready.status == 200 and onagre_ready.json.status == "Ready"
      retries: 30
      delay: 3

  handlers:
    - name: Restart the agent
      ansible.builtin.systemd:
        name: onagent
        state: restarted
        daemon_reload: true

Hosts on another architecture fail on onagre_arch: only x86_64 and aarch64 are published.

Run it#

Terminal

ansible-playbook -i inventory/hosts.ini playbooks/onagre-agent.yml --ask-vault-pass

To update the agents, change onagre_version and run it again: each host downloads and checks that version, restarts, and the last task waits until it is connected again — see Health endpoints. After a Revoke and regenerate in Onagre, update the host's vaulted onagre_token and run it again.

To add settings (PORT, HTTP_API_BIND…), add lines to the token file's content — see Agent configuration. The logs are in the journal of each host: journalctl -u onagent.

Uninstall#

YAML

- name: Remove the Onagre agent
  hosts: onagre_agents
  become: true
  tasks:
    - name: Stop and disable the agent
      ansible.builtin.systemd:
        name: onagent
        state: stopped
        enabled: false
      failed_when: false
    - name: Remove its files
      ansible.builtin.file:
        path: "{{ item }}"
        state: absent
      loop:
        - /etc/systemd/system/onagent.service
        - /usr/local/bin/onagent
        - /usr/local/lib/onagent
        - /var/cache/onagent
        - /etc/onagent
    - name: Remove the onagent user
      ansible.builtin.user:
        name: onagent
        state: absent
    - name: Reload systemd
      ansible.builtin.systemd:
        daemon_reload: true

Then delete the agents in Onagre.