Hey everyone! I’m really excited about today’s topic: getting the IP address of an interface from the OPNsense API. To be honest, I’ve been on a bit of a hunt for reliable and current information on this, but it’s been a bit elusive.
So, I’ve decided to put together this guide in the hopes that it’ll be useful not just for me, but for others who might be in the same boat.

Create user and group

First, you should create a new user and group to grant it only the authorizations it needs.
Access your OPNsense firewall and navigate to System -> Access -> Groups.

Add a new group and name it something like “ApiUsers”. Do not add a member yet, as we are going to create a new one. Save the group and click on “Edit”. Then, open “Assigned Privileges” and select the following:

Create a new User, named “api_user”. Set a strong password or select “Generate a scrambled password to prevent local database logins for this user”. Set the Login shell to /usr/sbin/nologin.
Under Group Memberships, select your new ApiUsers Group and assign it to the user. Save the user and click on “Edit”. Now you will see the option “API keys” for the user - generate a new one.
You will receive a txt file with the following content:

1
2

key=xxx
secret=xxx

Call the API

First, you need to find the interface you want the IP for, which is most likely your WAN interface.
Navigate to Interfaces -> Overview to see all your interfaces. Search for your desired interface and note the “Device”.
You will need that for the API call.

Here’s a simple bash script to call the API and retrieve the IP of the interface. It utilizes jq, a lightweight and flexible command-line JSON processor.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

#!/bin/bash

# Enter your Opnsense IP or URL
OPNSENSE="http://192.168.1.1"

# Replace key and secret with the values from the downloaded API txt file
KEY="your-key-here"
SECRET="your-secret-here"

# Specify the value from "Device" for your Interface, see GUI or API output
DEVICE="device-name-from-interface"

# Make GET request with curl
interface_info=$(curl -k -u  "$KEY":"$SECRET" $OPNSENSE/api/interfaces/overview/getInterface/$DEVICE)

# Extract Interface IP with jq
ip=$(echo "$interface_info" | jq -r '.message.ipv4.value[0].ipaddr | split("/")[0]')

echo "$ip"

You can save this as a file and make it executable with chmod +x filename.sh.

You could also use the script above as a one-liner:

1

curl -k -u "<your-key>":"<your-secret>" <OPNsense-url>/api/interfaces/overview/getInterface/<device> | jq -r '.message.ipv4.value[0].ipaddr | split("/")[0]'

There are plenty of use cases. For example, you could avoid calling an external service to get your public IP and update a DNS record if it changed.
However, if you’ve ended up here, you likely already have a specific use case in mind 😉

Photo by Gabriel Heinzer on Unsplash