The controller (server) is a set of containers that allow the admin to remotely manage multiple NethSecurity installations (firewalls).
Firewalls can register to the server using ns-plug client. Upon registration the server will:
- create a VPN configuration which is sent back to the firewall
- create a route inside the proxy to access the firewall Luci RPC
- store credentials to access the remote firewall
You can install it on NS8.
Otherwise, first make sure to have podman installed on your server. Containers should run under non-root users, but first you need to configure the tun device and the user.
As root, execute:
useradd -m controller
loginctl enable-linger controller
ip tuntap add dev tunsec mod tun
ip addr add 172.21.0.1/16 dev tunsec
ip link set dev tunsec up
Then change to non-root user, clone this repository and execute:
su - controller
./start.sh
The server will be available at http://<fqdn>:8080/ui.
General workflow:
- Access the controller and add a new machine using the
addAPI below. This will generate a join code containing the FQDN of the controller, a registration token, and the unit UUID. - Connect the NethSecurity unit and register the machine using the join code.
- Return to the controller and manage the unit.
- The UI retrieves a token for the NethSecurity unit:
curl http://localhost:8080/api/servers/login/clientX - THe UI Uses the token to invoke Luci APIs:
curl http://localhost:8080/clientX/cgi-bin/luci/rpc/...
The controller is composed by 4 services:
- nethsec-vpn: OpenVPN server, it authenticates the machines and create routes for the proxy, it listens on port 1194
- nethsec-proxy: traefik forwards requests to the connected machines using the machine name as path prefix, it listens on port 8181
- nethsec-api: REST API python server to manage nethsec-vpn clients, it listens on port 5000
- nethsec-ui: lighttpd instance serving static UI files, it listens on port 3000
The following environment variables can be used to configure the containers:
FQDN: default is the container/pod hostnameOVPN_NETWORK: OpenVPN network, default is172.21.0.0OVPN_NETMASK: OpenVPN netmask, default is255.255.0.0OVPN_CN: OpenVPN certificate CN, default isnethsecOVPN_UDP_PORT: OpenVPN UDP port, default is1194OVPN_TUN: OpenVPN tun device name, default istunsecUI_PORT: UI listening port, default is3000UI_BIND_IP: UI binding IP, default is0.0.0.0API_PORT: API server listening port, default is5000API_BIND_IP: API server listening IP, default is127.0.0.1API_USER: controller admin user, default isadminAPI_PASSWORD: controller admin password, it must be passed as SHA56SUM, default isadminAPI_SECRET: JWT secret tokenAPI_DEBUG: enable debug logging and CORS if set to1, default is0API_SESSION_DURATION: JWT session duration in seconds, default is 7 daysPROXY_PORT: proxy listening port, default is8080PROXY_BIND_IP: proxy binding IP, default is0.0.0.0
Manage server registrations using the REST API server. Request should be sent to the proxy server.
Almost all APIs are authenticated using JWT.
Authentication work-flow:
- send user name and password to
/loginAPI - retrieve authorization tokens:
access_token: it's the token used to executed all APIs, it expires after an hourrefresh_token: this token can be used only to call the/refreshAPI and request a newaccess_token, it expires afterAPI_SESSION_DURATIONseconds (default to 7 days)
- invoke other APIs by setting the header
Authorization: Bearer <access_token>"
Unauthenticated APIs:
/login: execute the login and retrieve the tokens/register: invoked by firewalls to register themselves, this API should be always invoked using a valid HTTPS endpoint to ensure the identity of the server
See the API documentation for more details.
Requirements:
To build the image, use:
./build.sh
To load the UI from a local dir, use:
./start.sh <ui_path>
Every time a commit us pushed to the master, a GitHub actions will automatically build new images.