mirror of
https://github.com/opnsense/docs
synced 2024-11-07 03:20:31 +00:00
122 lines
4.2 KiB
ReStructuredText
122 lines
4.2 KiB
ReStructuredText
===========
|
||
Use the API
|
||
===========
|
||
|
||
--------
|
||
Overview
|
||
--------
|
||
|
||
All components that are using the full architecture of OPNsense
|
||
automatically receive API capabilities, for this simple tutorial we use
|
||
the firmware module but others will function in the same way. API access
|
||
is part of the local user authentication system, but uses key/secret
|
||
pairs to separate account information from machine to machine
|
||
communication. Secrets are not stored on OPNsense and can be downloaded
|
||
only once, if lost, a new key has to be generated for your application.
|
||
|
||
A user can have multiple keys, our advice is to create a unique key for
|
||
every application in use.
|
||
|
||
-------------
|
||
Creating keys
|
||
-------------
|
||
|
||
API keys are managed in the user manager (system\_usermanager.php), go
|
||
to the user manager page and select a user. Somewhere down the page you
|
||
will find the API section for this user.
|
||
|
||
|Usermanager add api key.png|
|
||
|
||
Click on the + sign to add a new key. When the key is created, you will
|
||
receive a (single download) with the credentials in one text file (ini
|
||
formatted). The contents of this file look like this:
|
||
|
||
.. code-block:: c
|
||
|
||
key=w86XNZob/8Oq8aC5r0kbNarNtdpoQU781fyoeaOBQsBwkXUt
|
||
secret=XeD26XVrJ5ilAc/EmglCRC+0j2e57tRsjHwFepOseySWLM53pJASeTA3
|
||
|
||
--------------------
|
||
Code sample (python)
|
||
--------------------
|
||
|
||
For the python code sample we use the nice "requests" library
|
||
(http://docs.python-requests.org/en/latest/), which makes HTTP calls
|
||
very easy.
|
||
|
||
Before you can start, make sure your OPNsense has a valid SSL
|
||
certificate (or choose to ignore it for testing purposes by setting
|
||
verify=False), don't forget to verify that the selected user may access
|
||
the firmware page.
|
||
|
||
The web interface uses the same logic that will be available for the
|
||
api, in this example we will collect some status information from the
|
||
firmware module and print it out for the user.
|
||
|
||
It all starts with creating the request and waiting for the response,
|
||
all data interaction is using json format, both for the responses as for
|
||
the request data (when sending POST data).
|
||
|
||
First step of the example is importing the required libraries, then
|
||
define the endpoint url and credentials to use and finally fire the (get
|
||
type) request. As soon as we receive the response, we parse the json
|
||
string back to a dictionary and print some data depending on the
|
||
response.
|
||
|
||
.. code-block:: php
|
||
|
||
# import libraries
|
||
import json
|
||
import requests
|
||
|
||
# define endpoint and credentials
|
||
api_key = 'w86XNZob/8Oq8aC5hxh2he+vLN00r0kbNarNtdpoQU781fyoeaOBQsBwkXUt'
|
||
api_secret = 'puOyw0Ega3xZXeD26XVrJ5WYFepOseySWLM53pJASeTA3'
|
||
url = 'https://192.168.1.1/api/core/firmware/status'
|
||
|
||
# request data
|
||
r = requests.get(url,
|
||
verify='OPNsense.pem',
|
||
auth=(api_key, api_secret))
|
||
|
||
if r.status_code == 200:
|
||
response = json.loads(r.text)
|
||
|
||
if response['status'] == 'ok' and response['status_upgrade_action'] == 'all':
|
||
print ('OPNsense can be upgraded')
|
||
print ('download size : %s' % response['download_size'])
|
||
print ('number of packages : %s' % response['updates'])
|
||
if response['upgrade_needs_reboot'] == '1':
|
||
print ('REBOOT REQUIRED')
|
||
elif response['status'] == 'ok' and response['status_upgrade_action'] == 'pkg':
|
||
print ('OPNsense can be upgraded, but needs a pkg upgrade first')
|
||
elif 'status_msg' in response:
|
||
print (response['status_msg'])
|
||
else:
|
||
print ('Connection / Authentication issue, response received:')
|
||
print r.text
|
||
|
||
|
||
----------
|
||
Using curl
|
||
----------
|
||
|
||
Simple testing with curl is also possible, the sample below uses the
|
||
same credentials, but ignores the SSL certificate check (-k) for
|
||
testing.
|
||
|
||
.. code-block:: sh
|
||
|
||
curl -k -u "w86XNZob/8Oq8aC5hxh2he+vLN00r0kbNarNtdpoQU781fyoeaOBQsBwkXUt":"puOyw0Ega3xZXeD26XVrJ5WYFepOseySWLM53pJASeTA3" https://192.168.1.1/api/core/firmware/status
|
||
|
||
|
||
And schedule the actual upgrade of all packages using:
|
||
|
||
.. code-block:: sh
|
||
|
||
curl -XPOST -d '{"upgrade":"all"}' -H "Content-Type: application/json" -k -u "w86XNZob/8Oq8aC5hxh2he+vLN00r0kbNarNtdpoQU781fyoeaOBQsBwkXUt":"puOyw0Ega3xZXeD26XVrJ5WYFepOseySWLM53pJASeTA3" https://10.211.55.100/api/core/firmware/upgrade
|
||
|
||
|
||
.. |Usermanager add api key.png| image:: images/Usermanager_add_api_key.png
|
||
:width: 700px
|