Install from Ansible Galaxy

Install the official OnePAM Ansible collection from Ansible Galaxy. Includes tasks, templates, handlers, default variables, and example playbooks.

GitHub

From Ansible Galaxy (recommended)

ansible-galaxy collection install onepam.agent

From Source

git clone https://github.com/onepamcom/onepam-ansible.git
cd onepam-ansible

Requirements

Control Node

Ansible 2.12 or later
Python 3.8+
SSH access to managed hosts

Managed Nodes

Linux with systemd (Ubuntu 16.04+, Debian 8+, RHEL 7+, CentOS 7+, SLES 12+, Amazon Linux 2+)
Python 3 on managed hosts
Root or sudo access

For deprecated or non-systemd distributions, use the Gateway SSH Proxy instead — no agent installation required.

Quick Start

Run the OnePAM role against your inventory in a single command:

# Install the collection from Ansible Galaxy
ansible-galaxy collection install onepam.agent

# Run the playbook
ansible-playbook -i inventory/hosts site.yml

Minimal playbook (site.yml):

---
- name: Deploy OnePAM agent
  hosts: all
  become: true
  roles:
    - role: onepam.agent.onepam_agent
      vars:
        onepam_server_url: "https://onepam.com"
        onepam_tenant_id: "00000000-0000-0000-0000-000000000000"

Role Structure

roles/onepam/
├── defaults/
│   └── main.yml          # Default variables
├── handlers/
│   └── main.yml          # Service handlers
├── tasks/
│   ├── main.yml          # Entry point
│   ├── install.yml       # Download and install agent
│   ├── configure.yml     # Configuration files
│   └── service.yml       # Systemd service setup
├── templates/
│   ├── agent.env.j2      # Environment file
│   └── onepam-agent.service.j2  # Systemd unit
└── meta/
    └── main.yml          # Role metadata

defaults/main.yml

---
# OnePAM agent defaults
onepam_server_url: "https://onepam.com"
onepam_tenant_id: "00000000-0000-0000-0000-000000000000"
onepam_log_level: "info"

# Installation paths
onepam_install_dir: "/opt/onepam"
onepam_bin_dir: "{{ onepam_install_dir }}/bin"
onepam_data_dir: "{{ onepam_install_dir }}/data"
onepam_config_dir: "{{ onepam_install_dir }}/etc"

# Download URL
onepam_download_url: "https://updates.onepam.com/agent/latest/onepam-agent-linux-amd64"

# Service state
onepam_service_enabled: true
onepam_service_state: started

tasks/main.yml

---
- name: Include installation tasks
  ansible.builtin.include_tasks: install.yml

- name: Include configuration tasks
  ansible.builtin.include_tasks: configure.yml

- name: Include service tasks
  ansible.builtin.include_tasks: service.yml

tasks/install.yml

---
- name: Create OnePAM directories
  ansible.builtin.file:
    path: "{{ item }}"
    state: directory
    owner: root
    group: root
    mode: "0755"
  loop:
    - "{{ onepam_install_dir }}"
    - "{{ onepam_bin_dir }}"
    - "{{ onepam_data_dir }}"
    - "{{ onepam_data_dir }}/queue"
    - "{{ onepam_config_dir }}"

- name: Download OnePAM agent binary
  ansible.builtin.get_url:
    url: "{{ onepam_download_url }}"
    dest: "{{ onepam_bin_dir }}/onepam-agent"
    owner: root
    group: root
    mode: "0755"
  notify: Restart onepam-agent

tasks/configure.yml

---
- name: Deploy agent configuration
  ansible.builtin.template:
    src: agent.env.j2
    dest: "{{ onepam_config_dir }}/agent.env"
    owner: root
    group: root
    mode: "0600"
  notify: Restart onepam-agent

- name: Deploy systemd service unit
  ansible.builtin.template:
    src: onepam-agent.service.j2
    dest: /etc/systemd/system/onepam-agent.service
    owner: root
    group: root
    mode: "0644"
  notify:
    - Reload systemd
    - Restart onepam-agent

tasks/service.yml

---
- name: Enable and start OnePAM agent
  ansible.builtin.systemd:
    name: onepam-agent
    enabled: "{{ onepam_service_enabled }}"
    state: "{{ onepam_service_state }}"
    daemon_reload: true

handlers/main.yml

---
- name: Reload systemd
  ansible.builtin.systemd:
    daemon_reload: true

- name: Restart onepam-agent
  ansible.builtin.systemd:
    name: onepam-agent
    state: restarted

templates/agent.env.j2

AGENT_API_URL={{ onepam_server_url }}
AGENT_TENANT_ID={{ onepam_tenant_id }}
AGENT_LOG_LEVEL={{ onepam_log_level }}
AGENT_DATA_DIR={{ onepam_data_dir }}

templates/onepam-agent.service.j2

[Unit]
Description=OnePAM Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
EnvironmentFile={{ onepam_config_dir }}/agent.env
ExecStart={{ onepam_bin_dir }}/onepam-agent \
    --server=${AGENT_API_URL} \
    --tenant-id=${AGENT_TENANT_ID}
Restart=always
RestartSec=10
LimitNOFILE=65536
LimitMEMLOCK=infinity

[Install]
WantedBy=multi-user.target

Variables Reference

Variable	Default	Description
`onepam_server_url`	`https://onepam.com`	OnePAM server URL to connect to
`onepam_tenant_id`	`00000000-...`	Organisation UUID (tenant ID)
`onepam_log_level`	`info`	Logging verbosity (debug, info, warn, error)
`onepam_install_dir`	`/opt/onepam`	Base installation directory
`onepam_service_enabled`	`true`	Enable service on boot
`onepam_service_state`	`started`	Desired service state

Inventory Setup

Organise hosts into groups with group-specific variables:

inventory/hosts

[webservers]
web01.example.com
web02.example.com

[databases]
db01.example.com
db02.example.com

[all:vars]
ansible_user=deploy
ansible_become=true

inventory/group_vars/all.yml

---
onepam_server_url: "https://onepam.example.com"
onepam_tenant_id: "00000000-0000-0000-0000-000000000000"

inventory/group_vars/databases.yml

---
onepam_log_level: "debug"

Playbook Examples

---
- name: Deploy OnePAM agent to all hosts
  hosts: all
  become: true
  roles:
    - role: onepam
      vars:
        onepam_server_url: "https://onepam.example.com"
        onepam_tenant_id: "00000000-0000-0000-0000-000000000000"

---
- name: Deploy OnePAM to production
  hosts: production
  become: true
  roles:
    - role: onepam
      vars:
        onepam_server_url: "https://prod.onepam.example.com"
        onepam_tenant_id: "{{ vault_prod_tenant_id }}"
        onepam_log_level: "warn"

- name: Deploy OnePAM to staging
  hosts: staging
  become: true
  roles:
    - role: onepam
      vars:
        onepam_server_url: "https://staging.onepam.example.com"
        onepam_tenant_id: "{{ vault_staging_tenant_id }}"
        onepam_log_level: "debug"

Encrypt sensitive values with Ansible Vault:

# Create encrypted vars file
ansible-vault create inventory/group_vars/all/vault.yml

# Contents of vault.yml
vault_onepam_tenant_id: "your-real-tenant-id"

# Reference in playbook
- name: Deploy OnePAM agent
  hosts: all
  become: true
  roles:
    - role: onepam
      vars:
        onepam_tenant_id: "{{ vault_onepam_tenant_id }}"

# Run with vault password
# ansible-playbook -i inventory/hosts site.yml --ask-vault-pass

---
- name: Rolling update of OnePAM agent
  hosts: all
  become: true
  serial: "25%"
  max_fail_percentage: 10
  pre_tasks:
    - name: Verify connectivity
      ansible.builtin.ping:
  roles:
    - role: onepam
  post_tasks:
    - name: Verify agent is running
      ansible.builtin.systemd:
        name: onepam-agent
        state: started
      register: agent_status
    - name: Fail if agent not running
      ansible.builtin.assert:
        that: agent_status.status.ActiveState == "active"
        fail_msg: "OnePAM agent failed to start"

Security Note: Always use Ansible Vault to encrypt sensitive values like onepam_tenant_id. Never commit unencrypted secrets to version control.

Ansible Deployment