IoT Device Management

Q: How do I name devices when they are imaged identically?

Leave --name off and each machine joins under its own hostname, which for field equipment is usually already the serial number or the location. One systemd unit with --name %H then images every device identically.

Summary

Put every machine in the field on one fleet, under its own name and one shared token. Open the ports each one serves from the dashboard, write a grant for the people and systems that need them, and reach a port with localport access <device-address> -L <local>:<device-port>. No inbound ports, no VPN, no static IPs.

You have equipment in the field: sensors, cameras, Raspberry Pis, industrial controllers. Each runs a local service, each sits behind NAT or a firewall you do not administer, and you need to reach one of them by name from your office or your monitoring system.

A Localport fleet gives every machine an address of its own behind one tunnel and one token. You decide which ports each machine serves, and every caller presents a certificate before anything answers.

What the finished setup looks like#

plc-01-plant.eu.localport.dev      tcp 502     Modbus, line 7
cam-01-plant.eu.localport.dev      tcp 554     RTSP, entrance
gw-01-plant.eu.localport.dev       tcp 22 · http 80    gateway and its web UI

Each machine dials out and holds the connection open. Nothing on your side listens for inbound connections, and none of these addresses answers a browser or a port scan. An engineer reaches one by forwarding the port they need:

localport access plc-01-plant.eu.localport.dev -L 5020:502

Their Modbus client then connects to 127.0.0.1:5020.

Put the first device on a fleet#

1. Create the fleet#

Create it in the dashboard under Remote Access. It gives you one token, shared by every machine, and a subdomain the device addresses are built from. Fleets are on the Pro and Enterprise plans, see pricing.

2. Install the agent on each machine#

curl -fsSL https://localport.io/install.sh | sh

The same command installs and upgrades in place. Details and offline installs are on Installation.

3. Connect the machine as a device#

localport connect --token FLEET_TOKEN --region eu --noui

With no --name, the machine joins under its own hostname, which is usually what you want for equipment named by serial or location. Pass --name plc-01 to choose. --noui prints plain log lines instead of the live display, the form to use under a service manager.

The device appears on the fleet's Devices tab as soon as it connects, serving nothing.

4. Open the ports it serves#

On the Devices tab, choose Edit from the device's menu and add each port, with tcp or http beside it. tcp carries Modbus, MQTT, RTSP, SSH and anything else built on TCP. http carries a web UI and additionally counts requests and response classes in the access log.

A device serves the list you give it and nothing else. The agent asks for no ports of its own, so a machine in the field cannot expose something you did not open, and a port you remove closes the connections already using it.

5. Say who may reach it#

On the fleet's Access tab, write a grant naming an identity and the devices it reaches. Name machines with a shared prefix and one grant on plc* covers every controller you deploy afterwards. See Grants and Access.

Keep it running across reboots#

Field equipment needs the agent started at boot and restarted if it stops. The agent repository ships a hardened systemd unit, deploy/localport.service, which keeps the token out of the command line by loading it from a file readable only by the service user.

For a device, the line to change is ExecStart=:

ExecStart=/usr/local/bin/localport connect --name %H --noui

%H expands to the machine's hostname, so one unit file images every device identically. The token comes from LOCALPORT_TOKEN_FILE, which the unit points at systemd's LoadCredential= path.

sudo useradd --system --no-create-home --shell /usr/sbin/nologin localport
sudo install -d -m 0700 -o localport -g localport /etc/localport
printf '%s' 'tok_...' | sudo tee /etc/localport/token >/dev/null
sudo chmod 0600 /etc/localport/token
sudo cp localport.service /etc/systemd/system/
sudo systemctl enable --now localport

The launchd and Windows equivalents are on Installation.

Equipment that cannot run an agent#

A PLC, a label printer or an IP camera usually runs no software of yours. Run the agent on one machine that reaches them over the local network and give each piece of equipment its own device entry, with host pointing at its LAN address:

version: 1

fleets:
  - token: ${LOCALPORT_TOKEN:?set LOCALPORT_TOKEN}
    devices:
      - name: gw-01
      - name: plc-01
        host: 192.168.10.21
      - name: cam-01
        host: 192.168.10.22

localport connect --config /etc/localport/localport.yaml

One agent process serves all three, each holding its own connection and carrying its own address. The ports stay in the dashboard, so host takes an address with no scheme and no port. The full schema is on Configuration.

Reaching devices from a monitoring system#

The machine doing the monitoring needs a credential of its own. Redeem a setup key once during provisioning and the agent renews from then on, with no long-lived secret left behind:

localport setup lps_YOUR_SETUP_KEY
localport access cam-01-plant.eu.localport.dev -L 8554:554

Repeat -L for each port, and add a second localport access for each device. All of one device's forwards travel over a single mutual-TLS connection. See Setup Keys, and Configuration for running several devices' forwards from one file.

A device's address is built from its name, so it survives reboots, IP changes and a night offline. There are no ports to track and no address for your dashboards to chase.

Control which machines can join#

Auto-join sits on the Devices toolbar. While it is on, any agent presenting the fleet token under a new name joins the fleet and appears in the list, serving nothing until you open a port on it.

Turn it off once your fleet is deployed and the fleet admits only names already on the roster. An unknown name is refused outright and that agent stops instead of retrying, which is the setting to use when the token is baked into an image.

Use Create device to add a name before the hardware ships. Open its ports and write its grant straight away, and the machine is authorised before its first connection.

What protects a device#

No inbound ports. Every connection is outbound from the device, so no firewall rule, static IP or port forward is needed.
A certificate on every caller. A fleet answers nothing without one, and the check cannot be turned off. See Remote Access.
Grants, not addresses. Knowing a device's address gets nobody in. An identity reaches what a grant names, and narrowing a grant cuts the connections it covered immediately.
Ports you author centrally. A device serves what the dashboard says and nothing more.
A full audit trail. Every access session is recorded with the identity, the device, the port and the outcome. No request path, header or body is captured anywhere. See Access Log.

Frequently asked questions#

Do the devices need a static IP, a port forward or a VPN?

No. Each agent makes an outbound connection and traffic arrives back down it. A controller behind NAT, behind carrier-grade NAT, or on a plant network whose firewall you do not administer works the same as a machine with a public address.

How do I reach equipment that cannot run any software?

Run the agent on one machine on the same network and give each piece of equipment its own device entry with host pointing at its LAN address. A PLC, a printer or a camera then carries its own Localport address without anything being installed on it, and its ports are opened in the dashboard like any other device's.

Does a device keep its address after a reboot or a week offline?

Yes. The address is built from the device's name, so it survives reboots, IP changes and long outages. Nothing in your monitoring configuration has to follow a port.

Can I open a device in a browser?

No. A device answers nothing without a client certificate, so there is no URL to open. Forward the port first with localport access <device-address> -L 8080:80, then open http://localhost:8080.

How do I name devices when they are imaged identically?

Leave --name off and each machine joins under its own hostname, which for field equipment is usually already the serial number or the location. One systemd unit with --name %H then images every device identically.

Can one machine serve Modbus and a web UI?

Yes. Protocol is chosen per port, so one device can serve port 502 as tcp and port 80 as http. A device can hold up to 32 ports, and one localport access command can forward several of them at once.

How do I stop one device being reachable?

Close its ports, narrow the grants that name it, or remove the device. Each takes effect at once and cuts the connections it covers. Rotating the fleet token is not the lever, since every machine on the fleet shares it.

What stops an agent in the field from exposing more than I intended?

The ports come from the dashboard. The agent asks for none of its own and serves the list it is given, so somebody with access to a device in a cabinet cannot publish a port you did not open.

How many devices can one fleet hold?

The ceiling comes from your plan, and the Devices tab tells you when you reach it. See pricing.