Reach a Small Device Through a Gateway
Reach a microcontroller's web page, a sensor's TCP socket or a PLC's UDP port from anywhere, with nothing installed on the device. A small Linux machine on the same network runs nfltr up and publishes each device port you name; clients reach it by name or over a capability address, end to end encrypted to that machine.
Goal
From a laptop anywhere, read the web page of a device at 192.168.1.50 on a home or factory LAN, talk to its raw TCP socket, and send it UDP datagrams, without changing the device's firmware and without opening a port on the router.
Why the device does not run nfltr
An ESP32 has about 520 KB of RAM and a few MB of flash; many sensors and PLCs have less, or run firmware you cannot change. nfltr needs a full operating system: it speaks TLS 1.3 to the relay, holds a machine certificate it renews every day, and keeps the relay's session protocol with its flow control and reconnects. So the device stays as it is, and a machine next to it does that work:
- The gateway is any Linux machine on the device's network: a Raspberry Pi, a router that runs Linux (OpenWrt), a NAS, an industrial PC. It dials out to the relay and opens a connection to the device only when a client opens a session.
- The device keeps speaking its own protocol (HTTP, MQTT, Modbus TCP, CoAP, a raw socket) on the LAN. Nothing on it changes.
End-to-end encryption ends at the gateway. Between the gateway and the device the traffic is whatever the device speaks, on your LAN, as it is today.
Prerequisites
- A gateway on the device's LAN with the
nfltrCLI, enrolled in your account withnfltr config login. - Your laptop with the
nfltrCLI, enrolled the same way. - For services by name with end-to-end encryption: both machines in an organisation (
nfltr org join), the gateway in a group such asdevicesand the laptop in a group such asops. For the capability address (step 4) no organisation is needed.
1. Check the gateway can reach the device
On the gateway, check each port you want to publish:
$ nc -vz 192.168.1.50 80
Connection to 192.168.1.50 80 port [tcp/http] succeeded!
Give the device a fixed address (a DHCP reservation on the router), so the gateway's config keeps pointing at it after a reboot.
2. Publish the device's ports on the gateway
gateway.yaml on the gateway, one service per device port. forward: is the device's LAN address and port; the gateway dials only the targets in this file:
agent: plant
services:
ui: { tcp: 80, forward: "192.168.1.50:80", e2ee: true, allow_group: [ops] }
sensor: { tcp: 7, forward: "192.168.1.50:7", e2ee: true, allow_group: [ops] }
coap: { udp: 5683, forward: "192.168.1.50:5683", e2ee: true, allow_group: [ops] }
ui-link: { tcp: 80, forward: "192.168.1.50:80", address: true }
uiis the device's web page or REST API,sensora raw TCP socket (MQTT on 1883 and Modbus TCP on 502 are the same shape),coapa UDP port.e2ee: trueandallow_group: [ops]make each session end to end encrypted between the client and the gateway, admitted only for machines whose organisation certificate names groupops. The relay carries the bytes and cannot read them.ui-linkis the same web page under a capability address (step 4).
Start it, and keep it running with a service manager (a systemd unit, or the router's init system):
$ nfltr up -c gateway.yaml
Clients name these services gw.plant/ui, gw.plant/sensor and gw.plant/coap: the gateway's machine name (gw here), the agent, the service.
3. Connect from the laptop
A single session on stdin and stdout, for a script or a quick check:
$ printf 'GET / HTTP/1.0\r\n\r\n' | nfltr cat pipe gw.plant/ui
HTTP/1.0 200 OK
Content-Type: application/json
...
{"device":"esp32-demo","temp_c":21.5}
A local port whose every connection is one session, for a browser or any TCP client:
$ nfltr cat forward gw.plant/ui --listen 127.0.0.1:8080
Then open http://127.0.0.1:8080/. The raw socket is the same with its own local port (nfltr cat forward gw.plant/sensor --listen 127.0.0.1:7000). A UDP port takes --udp and a datagram listener:
$ nfltr cat forward --udp gw.plant/coap --listen udp:127.0.0.1:5683
To start a set of these together, put them in the connect: section of an nfltr up config on the laptop:
connect:
ui: { target: gw.plant/ui, listen: "127.0.0.1:8080" }
sensor: { target: gw.plant/sensor, listen: "127.0.0.1:7000" }
coap: { target: gw.plant/coap, listen: "udp:127.0.0.1:5683" }
4. Without an organisation: a capability address
address: true serves ui-link under an nf1… address: whoever holds the address opens the service, end to end encrypted, with no account on the client. nfltr up prints the address once, when it is made, and keeps it in an owner-only file beside the gateway's nfltr config, so restarts keep it. Copy it to the laptop over a channel you trust, into a file only you can read (chmod 600 ui.addr), then:
$ nfltr cat forward --address-file ui.addr --listen 127.0.0.1:8080
The address is a password for that one service: anyone who has it reaches the device's web page. Use it for a single person or tool, and delete the address's key file on the gateway (then restart nfltr up) to replace it; holders of the old address are refused from then on.
Who can reach the device
- Only the ports you declare. A port of the device that is not a service in
gateway.yamlis not reachable through the gateway:nfltr cat pipeto an unpublished service exits 3. There is no subnet routing and no proxy; each target is named on the gateway. - Only the groups you name.
allow_group:admits machines by the group in their organisation certificate. A machine of another group is refused (exit 10), a machine with no certificate too (exit 2). Revoking a machine in the organisation reaches every gateway; see organisations. - Only the holders of an address. An
nf1…address is a capability: give one per person or tool, and replace it when it leaks. - The device's own LAN exposure. The gateway does not protect the device from other machines on the same LAN. Where the device or the switch can filter, allow only the gateway's address to the device's ports, and put the device and its gateway on their own VLAN in a factory network. Many small devices have no authentication of their own: everything that reaches the gateway's services reaches them.
Reboots, reconnects, power and latency
- The device reboots. The gateway opens a new connection to the device for each session, so nothing has to be restarted: while the device is down, a session opens and then closes at once (or
nfltr upreports the service down), and the next session after it is back works. - The gateway reboots or loses its uplink.
nfltr upreconnects to the relay by itself; the services' names and the capability address stay the same. Run it under a service manager so it starts at boot. Clients'nfltr cat forwardports stay open meanwhile and serve again when the gateway is back. - Power. The device stays as it is, so its power budget does not change; the gateway holds one connection to the relay, idle between sessions. A Raspberry Pi or a router that is on anyway is enough.
- Latency. A session adds the path to the relay and back to the round trip of each request. That suits web pages, REST, MQTT and polling (Modbus reads every second or slower). It is not for hard real-time control loops: keep those on the LAN.
If it goes wrong
| You see | Meaning and fix |
|---|---|
A session opens and closes at once, and nfltr up on the gateway logs that the service is down | The gateway cannot connect to the device. From the gateway, nc -vz 192.168.1.50 80; check the device is on and its address did not change. |
nfltr cat pipe exits 3 | The gateway publishes no such service: check the service name, and that nfltr up runs on the gateway with this config. |
nfltr cat pipe exits 10 | Your machine's organisation certificate has none of the service's allow_group: groups. |
nfltr cat pipe exits 2 | Your machine has no certificate for the relay: enrol it with nfltr config login. |