OPNsense Install Packages Role

Overview

This role installs plugins and packages on OPNsense firewall via the REST API. It automates the installation of essential plugins including Chrony (NTP), Telegraf (metrics), SNMP, NRPE (monitoring), SMART (disk health), backup utilities, and UI themes using the OPNsense firmware API endpoint.

Purpose

Automated Plugin Installation: Install OPNsense plugins via API
Monitoring Stack: Telegraf, SNMP, NRPE for infrastructure monitoring
System Utilities: SMART monitoring, microcode updates, backup tools
UI Customization: Multiple theme options
Idempotent: Safe to run multiple times
Code as Configuration: Define required packages in YAML

Requirements

Ansible 2.9 or higher
OPNsense firewall with API access enabled
API key and secret stored in Ansible Vault
Network connectivity to OPNsense (VLAN10)
OPNsense user with firmware/package installation permissions
Internet connectivity on OPNsense (to download packages)

What are OPNsense Plugins?

OPNsense plugins extend firewall functionality:

Installed via package manager (pkg)
Prefixed with os- (e.g., os-telegraf)
Available from official OPNsense repository
Managed via Web UI or API

Role Variables

Required Variables

Variable	Required	Description
`vault_opnsense_bjoffrey_user_api_key`	Yes	OPNsense API key (in vault)
`vault_opnsense_bjoffrey_user_api_secret`	Yes	OPNsense API secret (in vault)

Optional Variables

Variable	Default	Description
`opnsense_install_packages_list`	See defaults	List of packages to install
`opnsense_install_packages_validate_certs`	`true`	Validate SSL certificates

Variable Details

opnsense_install_packages_list

List of OPNsense packages to install.

Default packages:

opnsense_install_packages_list:
  - os-chrony                    # NTP client for time sync
  - os-cpu-microcode-intel       # Intel CPU microcode updates
  - os-dmidecode                 # Hardware information utility
  - os-net-snmp                  # SNMP daemon for monitoring
  - os-nrpe                      # Nagios plugin executor for Centreon
  - os-sftp-backup               # SFTP backup utility
  - os-smart                     # SMART disk monitoring
  - os-telegraf                  # Telegraf metrics agent
  - os-theme-advanced            # Advanced UI theme
  - os-theme-cicada              # Cicada UI theme
  - os-theme-rebellion           # Rebellion UI theme
  - os-theme-flexcolor           # Flexcolor UI theme

Custom example:

opnsense_install_packages_list:
  - os-telegraf
  - os-net-snmp
  - os-smart

Dependencies

This role has no dependencies on other Ansible roles, but requires:

OPNsense firewall with API enabled
Internet connectivity on OPNsense
API key with firmware management permissions
Ansible Vault for storing API credentials

Example Playbook

Basic Usage

---
- name: Install OPNsense Packages
  hosts: localhost
  become: false

  roles:
    - opnsense_install_packages

Custom Package List

---
- name: Install Monitoring Packages Only
  hosts: localhost
  become: false

  vars:
    opnsense_install_packages_list:
      - os-telegraf
      - os-net-snmp
      - os-nrpe
      - os-smart

  roles:
    - opnsense_install_packages

With SSL Validation Disabled

---
- name: Install Packages (Self-Signed Cert)
  hosts: localhost
  become: false

  vars:
    opnsense_install_packages_validate_certs: false

  roles:
    - opnsense_install_packages

What This Role Does

For each package in the list:
- Sends POST request to /api/core/firmware/install/{package}
- Installs package from OPNsense repository
- Expects 200 OK response
No configuration: Role only installs packages, doesn’t configure them

OPNsense API Endpoint

Install Package

POST /api/core/firmware/install/{package_name}
Authorization: Basic (API key:secret)

Example:

POST /api/core/firmware/install/os-telegraf

Response (200 OK):

{
  "status": "ok"
}

Note: Installation happens asynchronously. API returns immediately, package installs in background.

Installed Packages Explained

Monitoring & Metrics

os-telegraf:

Metrics collection agent
Sends data to InfluxDB
Monitors CPU, memory, disk, network
See: opnsense_telegraf_configuration role

os-net-snmp:

SNMP daemon (v2c/v3)
Allows monitoring via SNMP
Used by Grafana SNMP datasource
Provides OPNsense system metrics

os-nrpe:

Nagios Remote Plugin Executor
Allows Centreon to run check commands
Monitors firewall health
Used by deploy_system_monitoring role

Disk & Hardware

os-smart:

SMART disk monitoring
Check disk health status
Predict disk failures
View in: Services → S.M.A.R.T.

os-dmidecode:

DMI/SMBIOS information
Hardware details (CPU, RAM, etc.)
Useful for inventory
Command: dmidecode

os-cpu-microcode-intel:

Intel CPU microcode updates
Security patches for CPU
Performance improvements
Auto-applied on boot

Time Synchronization

os-chrony:

Modern NTP client
Better than ntpd
Fast synchronization
See: ntp_client role for client config

Backup

os-sftp-backup:

Automated configuration backups
Upload to SFTP server
Scheduled backups
Configure in: System → Configuration → Backups

UI Themes

os-theme-advanced:

Clean, modern theme
Dark sidebar
Professional appearance

os-theme-cicada:

Light theme
Minimalist design

os-theme-rebellion:

Dark theme
High contrast

os-theme-flexcolor:

Customizable colors
Multiple variants

Apply theme: System → Settings → General → Theme

Package Naming Convention

All OPNsense plugins use os- prefix:

os-telegraf (plugin)
telegraf (underlying FreeBSD package)

Why os- prefix: Identifies official OPNsense plugins vs base FreeBSD packages.

Installation Process

What Happens During Installation

API call triggers package manager
OPNsense downloads package from repository
Package installed via FreeBSD pkg
Dependencies resolved automatically
Configuration created (if needed)
Service may be enabled (depends on package)

Installation Time

Single package: ~10-30 seconds
Multiple packages: ~1-5 minutes total
Large packages (themes): ~30-60 seconds each

Note: Role doesn’t wait for completion. Install happens asynchronously.

Post-Installation Configuration

Most packages require configuration after installation:

os-telegraf

Configure via: Services → Telegraf (or use opnsense_telegraf_configuration role)

os-net-snmp

Configure via: Services → Net-SNMP

os-nrpe

Configure via: Services → NRPE

os-smart

Configure via: Services → S.M.A.R.T.

os-chrony

Configure via: Services → Chrony

This role only installs, doesn’t configure.

Verifying Installation

Via OPNsense UI

Check installed plugins:

Log into OPNsense
System → Firmware → Plugins
Look for installed plugins (checkmark)

Check services:

Services menu
Should see new service entries (Telegraf, SNMP, etc.)

Via API

# List installed packages
curl -u "key:secret" \
  https://opnsense-ip/api/core/firmware/info | jq '.package'

Via SSH

# SSH to OPNsense
ssh root@opnsense-ip

# List installed packages
pkg info | grep os-

# Check specific package
pkg info os-telegraf

Idempotency

Role behavior with already-installed packages:

API call still succeeds (200 OK)
OPNsense detects package installed
No reinstall occurs
Safe to run repeatedly

Security Considerations

API Credentials: Stored in Ansible Vault
HTTPS: Uses SSL/TLS for API calls
Basic Auth: API key/secret authentication
Certificate Validation: Enabled by default
Official Repository: Packages from OPNsense repo only
No Arbitrary Code: Only installs whitelisted packages

Notes

Role runs on localhost (API calls from control node)
become: false recommended (no root needed)
Installation happens asynchronously (role doesn’t wait)
No configuration performed (only installation)
Requires internet on OPNsense
Package list can be customized per environment
Themes won’t apply automatically (must select in UI)

Troubleshooting

”Authentication failed” errors

Cause: Invalid API key/secret

Solution: Verify credentials in vault and test API.

”Package not found” errors

Cause: Invalid package name or typo

Solution:

# List available plugins via UI
# System → Firmware → Plugins

# Or check package name
# Ensure it starts with os-

Package installation stuck

Cause: OPNsense already installing another package

Solution: Wait for current installation to complete. Only one package can install at a time.

”No route to host” errors

Cause: OPNsense can’t reach package repository

Solution:

# Test internet from OPNsense
# Diagnostics → Ping (ping pkg.opnsense.org)

# Check DNS
# System → Settings → General (DNS servers configured)

# Check WAN gateway
# System → Gateways → Single

Packages installed but not visible

Cause: UI cache not refreshed

Solution: Hard refresh browser (Ctrl+Shift+R) or logout/login.

Testing the Role

Verify Packages Installed

Via UI:

System → Firmware → Plugins
Check for installed packages (green checkmark)

Via SSH:

pkg info | grep ^os-

# Should list installed plugins

Verify Services Available

Check services menu:

Services → Telegraf (if os-telegraf installed)
Services → Net-SNMP (if os-net-snmp installed)
Services → NRPE (if os-nrpe installed)

Test Package Functionality

os-telegraf:

# Check service running
service telegraf status

os-net-snmp:

# Test SNMP query
snmpwalk -v2c -c public localhost system

os-smart:

# Check SMART status
smartctl -a /dev/ada0

Best Practices

Install early: Run this role before configuration roles
Minimal packages: Only install what you need
Document purpose: Comment why each package needed
Regular updates: Keep packages up to date
Test in staging: Verify packages before production
Configure after install: Use dedicated configuration roles
Monitor installation: Check logs for errors
Theme selection: Choose theme after install
Backup before: Backup config before major installs
Version control: Store package list in git

Package Update Workflow

To update installed packages:

Via UI:

System → Firmware → Updates
Check for updates
Install updates

Via API:

# Check for updates
curl -u "key:secret" \
  https://opnsense-ip/api/core/firmware/status

# Upgrade all packages
curl -u "key:secret" -X POST \
  https://opnsense-ip/api/core/firmware/upgrade

Note: This role doesn’t handle updates, only initial installation.

This role is often used with:

opnsense_telegraf_configuration: Configure Telegraf after install
opnsense_syslog_configuration: Configure syslog
deploy_system_monitoring: Configure NRPE

Uninstalling Packages

To remove packages (not handled by this role):

Via UI:

System → Firmware → Plugins
Click red minus (-) icon

Via API:

curl -u "key:secret" -X POST \
  https://opnsense-ip/api/core/firmware/remove/os-package-name

License

MIT

Author

Created for homelab infrastructure management.

OPNsense Install Packages

OPNsense Install Packages Role

Overview

Purpose

Requirements

What are OPNsense Plugins?

Role Variables

Required Variables

Optional Variables

Variable Details

opnsense_install_packages_list

Dependencies

Example Playbook

Basic Usage

Custom Package List

With SSL Validation Disabled

What This Role Does

OPNsense API Endpoint

Install Package

Installed Packages Explained

Monitoring & Metrics

Disk & Hardware

Time Synchronization

Backup

UI Themes

Package Naming Convention

Installation Process

What Happens During Installation

Installation Time

Post-Installation Configuration

os-telegraf

os-net-snmp

os-nrpe

os-smart

os-chrony

Verifying Installation

Via OPNsense UI

Via API

Via SSH

Idempotency

Security Considerations

Tags

Notes

Troubleshooting

”Authentication failed” errors

”Package not found” errors

Package installation stuck

”No route to host” errors

Packages installed but not visible

Testing the Role

Verify Packages Installed

Verify Services Available

Test Package Functionality

Best Practices

Package Update Workflow

Related Roles

Uninstalling Packages

License

Author