API Reference

This document attempts to document the API provided by the pyopnsense library. It is a combination of autogenerated api documentation and usage explanations.

Instantiating Clients

All the firmware client classes are based off the base OPNClient class and are instantiated the same way. They require the same 3 mandatory arguments the api_key, the api_secret, and the base_url. With these 3 pieces of information you can instantiate any of the client classes. The Usage section of the README contains details on how to get the api_key and api_secret values. The base_url is the base api endpoint for your OPNsense installtion and is normally just http://$OPNsenseAddress/api where $OPNsenseAddress is the hostname or IP address of your OPNsense installation.

SSL Certificate Verification

By default the SSL certificate verification is disabled. This is to enable a working client out of the box. (since by default OPNsense is it’s own CA, so it likely won’t be in your system’s CA bundle) The tradeoff here is obviously security. It’s strongly recommended that you enable SSL verification once you start using the client for anything beyond basic testing. To do this the verify kwarg is used. This value gets passed directly to requests verify kwarg on the HTTP methods. You can set this to either True which will enable it and use your default system installed CA bundles, or the path to a CA certificate or bundle directory. More details can be found in the requests documentation here: http://docs.python-requests.org/en/master/user/advanced/#ssl-cert-verification

Client Classes

Firmware API

class pyopnsense.firmware.FirmwareClient(api_key, api_secret, base_url, verify_cert=False)

Bases: OPNClient

A client for interacting with the core/firmware endpoint.

Parameters:

  • api_key (str) – The API key to use for requests

  • api_secret (str) – The API secret to use for requests

  • base_url (str) – The base API endpoint for the OPNsense deployment

status()

Return the current firmware update status.

Returns:

A dict representing the current upgrade status for the OPNsense firmware.

Return type:

dict

upgrade(upgrade_list=None)

Issue an upgrade request.

Parameters:

upgrade_list (list) – The list of packages to upgrade. If none are specified it will issue a request to upgrade all packages.

Diagnostics API

class pyopnsense.diagnostics.InterfaceClient(api_key, api_secret, base_url, verify_cert=False)

Bases: OPNClient

A client for interacting with the diagnostics/interface endpoint

Parameters:

  • api_key (str) – The API key to use for requests

  • api_secret (str) – The API secret to use for requests

  • base_url (str) – The base API endpoint for the OPNsense deployment

get_arp()

Get ARP table for router.

get_ndp()

Get NDP table for router.

class pyopnsense.diagnostics.NetFlowClient(api_key, api_secret, base_url, verify_cert=False)

Bases: OPNClient

A client for interacting with the diagnostics/netflow endpoint.

Parameters:

  • api_key (str) – The API key to use for requests

  • api_secret (str) – The API secret to use for requests

  • base_url (str) – The base API endpoint for the OPNsense deployment

status()

Return the current netflow status.

Returns:

A dict representing the current status of netflow

Return type:

dict

class pyopnsense.diagnostics.NetworkInsightClient(api_key, api_secret, base_url, verify_cert=False)

Bases: OPNClient

A client for interacting with the diagnostics/networkinsight endpoint.

Parameters:

  • api_key (str) – The API key to use for requests

  • api_secret (str) – The API secret to use for requests

  • base_url (str) – The base API endpoint for the OPNsense deployment

get_interfaces()

Return the available interfaces.

get_protocols()

Return the protocols.

get_services()

Return the available services.

get_timeserie()

Return the time serie.

class pyopnsense.diagnostics.SystemHealthClient(api_key, api_secret, base_url, verify_cert=False)

Bases: OPNClient

A client for interacting with the diagnostics/systemhealth endpoint.

Parameters:

  • api_key (str) – The API key to use for requests

  • api_secret (str) – The API secret to use for requests

  • base_url (str) – The base API endpoint for the OPNsense deployment

get_health_data(metric, start=0, stop=0, maxitems=1024, inverse=False, details=False)

Return the health data.

get_health_list()

Return the health list.

Routes API

class pyopnsense.routes.GatewayClient(api_key, api_secret, base_url, verify_cert=False)

Bases: OPNClient

A client for interacting with the routes/gateway endpoint.

Parameters:

  • api_key (str) – The API key to use for requests

  • api_secret (str) – The API secret to use for requests

  • base_url (str) – The base API endpoint for the OPNsense deployment

status()

Return the current gateways status.

Returns:

A dict representing the current status of gateways

Return type:

dict