In this chapter, we will learn how the OPNsense application programming interface (API) works and how to use it externally by looking at some examples. By the end of this chapter, you will understand the OPNsense API structure and how to create custom calls using it.
In this chapter, we will cover the following topics:
APIs are a way that software can talk with other software and integrate and automate routines. The REpresentational State Transfer (REST), also known as the RESTful API, is a web API that uses HTTP requests. For example, it allows you to make calls to a web application to display information or execute commands on the web server's backend. The OPNsense framework supports APIs for most webGUI features to interact with the backend controller as a modern web application.
The following diagram shows OPNsense's framework architecture, which has been extracted from the official documentation:
Figure 20.1 – OPNsense architecture extracted from https://docs.opnsense.org/development/architecture.html
As we can see, OPNsense's architecture is composed of a frontend, where the webGUI resides, and a backend, where the configd service resides. Every time we use OPNsense's API, we are utilizing this architecture. One of the advantages...
In the previous example, we made an API call internally using the webGUI. To make an external call, we need to configure the API's authentication.
API authentication in OPNsense can be created by associating a key and a secret with an existing user. To create an API key and secret for the root user, follow these steps:
Figure 20.3 – Editing the root user
Figure 20.4 – Adding a new API key/secret pair to the root user
key=xc8Odoms2r+a45Z9UOXG8drL5MHl+PkeUOrCTbj9abxZ7SDlFUJZ vp8s23uGB5eygqQDrl5wTv7f/yJm secret=RzYoJ/uw+8btPCbXVljqijDLRIywXpOUg2xmeashsl/l/+XhR D1DHaNVu0N3yq2xV1BJKdhoi1txcsnm
This file contains two lines. The first line specifies the API's...
The simplest way to test API calls is by using the curl tool. You can install it on Linux, FreeBSD, macOS, and Windows. On Windows 10/11, it is installed by default. Choose your preferred OS and start testing!
We will need access to the OPNsense webGUI port for testing, so I recommend that you do the tests from the LAN network. Avoid keeping webGUI and SSH access open to the internet so that you don't use it from the WAN. It would be best if you used a VPN instead.
We will use the following curl parameters in this example:
Important Note
We are using the curl and jq parameters for Unix-like environments in the following steps. If you want to use it on another shell, such as Windows Powershell, the parameters and outputs may vary.
-k: Allows insecure server connections when you're using TLS. Do not use this in a production environment! Consider using a trusted certificate instead.-u: <user:password> This is the...In this chapter, you learned about the OPNsense API and how to use it to integrate with other tools. Now, you can try to create some code and extend OPNsense's functions by using its API calls with other tools. With that, we have come to the end of this book! Thank you for reading it, and I hope this book has contributed to your OPNsense knowledge.
Did you know that Packt offers eBook versions of every book published, with PDF and ePub files available? You can upgrade to the eBook version at packt.com and as a print book customer, you are entitled to a discount on the eBook copy. Get in touch with us at customercare@packtpub.com for more details.
At www.packt.com, you can also read a collection of free technical articles, sign up for a range of free newsletters, and receive exclusive discounts and offers on Packt books and eBooks.
© 2022 Packt Publishing Limited All Rights Reserved
