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, timeout=5)¶ Bases:
pyopnsense.client.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
- timeout (int) – The timeout in seconds for API requests
-
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, timeout=5)¶ Bases:
pyopnsense.client.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
- timeout (int) – The timeout in seconds for API requests
-
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, timeout=5)¶ Bases:
pyopnsense.client.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, timeout=5)¶ Bases:
pyopnsense.client.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
- timeout (int) – The timeout in seconds for API requests
-
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, timeout=5)¶ Bases:
pyopnsense.client.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
- timeout (int) – The timeout in seconds for API requests
-
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, timeout=5)¶ Bases:
pyopnsense.client.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
- timeout (int) – The timeout in seconds for API requests
-
status
()¶ Return the current gateways status.
Returns: A dict representing the current status of gateways Return type: dict