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:

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

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 }

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

Reboots, reconnects, power and latency

If it goes wrong

You seeMeaning and fix
A session opens and closes at once, and nfltr up on the gateway logs that the service is downThe 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 3The gateway publishes no such service: check the service name, and that nfltr up runs on the gateway with this config.
nfltr cat pipe exits 10Your machine's organisation certificate has none of the service's allow_group: groups.
nfltr cat pipe exits 2Your machine has no certificate for the relay: enrol it with nfltr config login.

Next