History

Georg Pfuetzenreuter 1e84b2e57d Refactor to server subdirectory A client library will be included in this repository as well, prepare by moving all server components to a subdirectory. As part of this, the server script is refactored to a generated entrypoint script. Signed-off-by: Georg Pfuetzenreuter <mail@georg-pfuetzenreuter.net>		2024-09-29 02:23:30 +02:00
..
nftables_api	Refactor to server subdirectory	2024-09-29 02:23:30 +02:00
LICENSE	Refactor to server subdirectory	2024-09-29 02:23:30 +02:00
nftables-http-api.py	Refactor to server subdirectory	2024-09-29 02:23:30 +02:00
pyproject.toml	Refactor to server subdirectory	2024-09-29 02:23:30 +02:00
README.md	Refactor to server subdirectory	2024-09-29 02:23:30 +02:00
setup.cfg	Refactor to server subdirectory	2024-09-29 02:23:30 +02:00

README.md

RESTful HTTP API for nftables - Server

Configuration

A configuration file must be passed using the environment variable NFT-API-CONFIG. The file contains a mapping of bcrypt hashed tokens to API paths and methods. Requests to the API are only authorized if the token passed using the header X-NFT-API-Token and the requested path and method match an entry in the configuration.

Sample configuration:

nft-api:
  tokens:
    $2y$05$ZifkrfFg2XZU2ds7Lrcl9usJVyxHro9Ezjo84OMpsBSau4pEu42eS:
      /set/inet/filter/foo4:
        - GET
        - POST
    $2y$05$ZifkrfFg2XZU2ds7Lrcl9usJVyxHro9Ezjo84OMpsBSau4pEu42eS:
      /set/inet/filter/*:
        - GET

Any elements can contain a wildcard in the form of a * character.

Generate token hashes using any bcrypt hashing tool, such as htpasswd from the apache-utils suite:

$ htpasswd -Bn x

The username (here x) is not used, ignore the relevant part before and including the colon in the output.

Deployment

The application can be served using any Python WSGI server. Easiest is to use waitress using the script found in the repository root:

./nftables-api.py

It will bind on *:9090.

Usage

Currently GET and POST methods are implemented, allowing to query or append data respectively.

All requests must contain a header X-NFT-API-Token containing a token authorized for the requested path and method. All POST requests must contain a JSON payload.

By default, the response body will be output deemed most “useful” - in case of GET requests, that is only the data found for the given query, in case of POST requests the result of the change. Optionally, a query parameter raw can be passed to retrieve a mapping containing all status information, including the raw libnftables-json(5) output, instead.

Below are examples using curl.

nftables sets

Get a set

$ curl -H 'X-NFT-API-Token: foo' localhost:9090/set/inet/filter/foo4
["192.168.0.0/24", "192.168.1.1", "192.168.3.0/24", "192.168.4.0/24", "192.168.5.0/26"]⏎

Append to a set

$ curl -H 'X-NFT-API-Token: foo' --json '{"addresses": "fe80::/64"}' localhost:9090/set/inet/filter/foo
{"status": true}⏎