API server

The API server is a daemon implemented using Go and listens on TCP port 9311.

This component is used to send command from UI to Redis, using HTTP Rest API and Redis Pub/Sub protocol.

API server

API Paths

APIs are documented using a swagger.json file. To browse all existing APIs, use the Swagger UI.

API flow:

authenticate the user using the login API
extract the JWT token from the login API response
use the token to execute all next API calls

Authentication:

curl -X 'POST' \
  'http://localhost:9311/api/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "password": "Nethesis,12345"}' | jq

Response, note the JWT token saved inside the token field:

{
  "code": 200,
  "expire": "2022-02-01T13:54:50Z",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY3Rpb25zIjpbXSwiZXhwIjoxNjQzNzIzNjkwLCJpZCI6ImFkbWluIiwib3JpZ19pYXQiOjE2NDMxMTg4OTAsInJvbGUiOiIifQ.BzzmleO6ln40DQUZr4FUyFTFEle6PkK-ar-vqwXJ5uo"
}

Use the obtained JWT token to list configured nodes:

curl -X 'GET' \
  'http://localhost:9311/api/nodes' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY3Rpb25zIjpbXSwiZXhwIjoxNjQzNzIzNjkwLCJpZCI6ImFkbWluIiwib3JpZ19pYXQiOjE2NDMxMTg4OTAsInJvbGUiOiIifQ.BzzmleO6ln40DQUZr4FUyFTFEle6PkK-ar-vqwXJ5uo"

Response:

{
  "code": 200,
  "data": {
    "list": [
      "1"
    ],
    "queue": "node/*"
  },
  "message": "success"
}

You can also use the shortcut command called api-cli. Usage example:

# api-cli list-actions
node/1/get-node-status
...

Network access control

The API server enforces source-IP restrictions at login time and on every authenticated request.

Agent credentials

Credentials belonging to the internal agents — cluster, node/*, and module/* — are always restricted to the loopback addresses (127.0.0.1, ::1) and the cluster VPN network (stored in the Redis key cluster/network). Login attempts from any other source IP are rejected with HTTP 401, and requests carrying a JWT obtained with agent credentials are rejected with HTTP 403 when the source IP is outside those networks. This rule is unconditional and cannot be changed per-user.

User accounts

Regular user accounts (e.g. admin) can optionally be given an allowed_networks restriction through the cluster/add-user and cluster/alter-user actions. When the list is non-empty, login attempts from IPs that do not match any entry are rejected with HTTP 401, and requests carrying a JWT are rejected with HTTP 403. An empty allowed_networks list means no IP restriction.

Audit log

Every request made to the server, using its APIs or WebSocket, is logged inside an audit db. The audit db is store in a file using a SQLite database schema. Each record is composed by:

ID: the unique id of the record, autoincrement
User: the name of the user that made the specific action
Action: the name of the action made by the user
Data: the payload of the action (if present)
Timestamp: the time when the specific action is executed

Audit database is saved inside AUDIT_FILE variable, default path is /var/lib/nethserver/api-server/audit.db.

The audit logs can be access using the audit API or directly from command line. Example:

sqlite3 /var/lib/nethserver/api-server/audit.db "SELECT * FROM audit LIMIT 10;" ".exit"

api-cli

You can also use the shortcut command called api-cli. Usage example:

# api-cli login
username: admin
password:

If authentication is successful the login subcommand stores a JWT token in $XDG_RUNTIME_DIR/.api-cli.cache. With such token the run subcommand sends API calls to api-server. To destroy the token run

api-cli logout

If the token is missing api-cli tries to talk directly with Redis. In any case to run an action use the run subcommand, e.g.:

api-cli run list-actions

Shell auto-complete is available. It is possible to type TAB key to automatically complete the action name:

api-cli run <TAB><TAB>