Networking and Remote Access

How the panel is connected to networks, and how another computer reaches the machine API over HTTPS with Basic Auth.

Panel network overview

Interface or port	Configuration
Ethernet ports	Not managed by NetworkManager, so it never touches the EtherCAT port. The backend brings every en* and eth* interface up and uses the first one that answers EtherCAT frames as the bus.
Wi-Fi	Managed by NetworkManager. Use it to connect the panel to the company network.
TCP 443	Open. Caddy serves HTTPS with Basic Auth and forwards to the backend.
TCP 3001	The backend's REST and Socket.IO port. It listens on all interfaces, but the firewall blocks it, so only the panel itself reaches it.
UDP 53, 67, 69	Open in the firewall (DNS, DHCP, TFTP). The panel's configuration sets up no service for them.

The settings are in nixos/os/configuration.nix; see NixOS.

flowchart LR
    PC["Computer in the<br/>company network"]:::hardware
    WiFi["<a href='https://github.com/qitechgmbh/control/blob/jse-control-v2/nixos/os/configuration.nix'>Wi-Fi, NetworkManager</a>"]:::hardware
    Caddy["<a href='https://github.com/qitechgmbh/control/blob/jse-control-v2/nixos/os/configuration.nix'>Caddy on :443<br/>HTTPS and Basic Auth</a>"]:::control
    Backend["<a href='https://github.com/qitechgmbh/control/blob/jse-control-v2/qitech_control/src/api/server.rs'>Backend on :3001</a>"]:::control
    App["<a href='https://github.com/qitechgmbh/control/tree/jse-control-v2/electron'>Electron app on the panel</a>"]:::frontend
    Bus["EtherCAT port"]:::hardware
    Terminals["Machine terminals"]:::hardware

    PC --> WiFi --> Caddy --> Backend
    App --> Backend
    Backend --> Bus --> Terminals

    classDef frontend fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef control fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef framework fill:#fef3c7,stroke:#b45309,color:#78350f
    classDef lib fill:#ede9fe,stroke:#6d28d9,color:#4c1d95
    classDef hardware fill:#f1f5f9,stroke:#475569,color:#0f172a

Loading

Wi-Fi

The panel runs a GNOME desktop with NetworkManager. Connect it to a Wi-Fi network through the GNOME network settings:

Watch on YouTube

To find the panel's IP address, open a terminal on the panel and run:

hostname -I

Reaching the API from another computer

From another computer, use https://<PANEL_IP> instead of http://localhost:3001. Caddy checks Basic Auth on every request, Socket.IO connections included, and forwards it to the backend. The routes and events are described in API.

curl -k -u machine:<PASSWORD> \
  -X POST https://<PANEL_IP>/api/v1/machine/mutate \
  -H 'Content-Type: application/json' \
  -d '{"machine_identification_unique":{"machine_identification":{"vendor":1,"machine":6},"serial":1},"data":{"SetTargetDiameter":1.75}}'

-k skips the certificate check; trust the panel's root certificate instead, see below. A Socket.IO client connects to https://<PANEL_IP>/main or https://<PANEL_IP>/machine/... and sends an Authorization: Basic ... header, for example with the extraHeaders option of socket.io-client in Node.js.

HTTPS and Basic Auth

Caddy is configured in nixos/os/configuration.nix:

Setting	Effect
virtualHosts.":443"	Listens for HTTPS on port 443, for any host name or IP
tls internal { on_demand }	Issues certificates from Caddy's own local certificate authority when a client connects
import /var/lib/caddy/auth_snippet.conf	Loads the Basic Auth credentials from this file
import machine_basic_auth	Requires the credentials on every request
reverse_proxy localhost:3001	Forwards requests to the backend

Set the credentials

The credentials live in /var/lib/caddy/auth_snippet.conf on the panel, which defines the snippet machine_basic_auth with a user name and a password hash. Caddy's configuration imports this file, so create it before using HTTPS. The file is outside the control checkout, so updates keep it. To create or change the credentials, open a terminal on the panel and run these commands in bash:

PASSWORD=$(head -c 18 /dev/urandom | base64)
echo "user: machine  password: $PASSWORD"
HASH=$(caddy hash-password --plaintext "$PASSWORD")
printf '(machine_basic_auth) {\n    basic_auth {\n        machine %s\n    }\n}\n' "$HASH" \
  | sudo tee /var/lib/caddy/auth_snippet.conf > /dev/null
sudo chown caddy:caddy /var/lib/caddy/auth_snippet.conf
sudo chmod 600 /var/lib/caddy/auth_snippet.conf
sudo systemctl restart caddy.service

Write down the printed password; only its hash is stored. Run the commands again to set a new password.

Self-signed certificate

Browsers, curl and HTTPS libraries don't trust Caddy's local certificate authority by default. Either skip the check (curl -k), or install the panel's root certificate as a trusted root on the client. On the panel it's at:

/var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt

Copy it to the client, for example with a USB stick, and add it as a trusted root certificate as described in the client operating system's documentation.

Firewall

Port	Status
TCP 443	Open (Caddy)
UDP 53, 67, 69	Open
Everything else, including TCP 3001	Closed

The rules are networking.firewall.allowedTCPPorts and networking.firewall.allowedUDPPorts in nixos/os/configuration.nix.

Open port 3001 without HTTPS

Only do this in an isolated network or behind your own reverse proxy with authentication: port 3001 has no authentication.

1. On the panel, edit the configuration in the control checkout that the panel was installed from:

   cd /home/qitech/control
   sudo nano nixos/os/configuration.nix

2. Change networking.firewall.allowedTCPPorts = [ 443 ]; to networking.firewall.allowedTCPPorts = [ 443 3001 ];.

3. Rebuild the system with the panel's install script. It reboots the panel when it's done:

   ./nixos-install.sh

4. After the reboot, check that the backend listens:

   systemctl status qitech-control-server --no-pager
   ss -ltnp | grep 3001

5. From another computer, the API is now at http://<PANEL_IP>:3001, for example /api/v1/machine/mutate.

An update from Setup → Update checks out the new version with git checkout -f, which discards this edit. Repeat it after every update.