Publishing Services

Publish any TCP or UDP service to the machines in its compartment, without port forwarding or firewall rules.

Who Can Reach a Service

A service on the overlay is reachable from every machine whose taints are compatible with the server's, and from nowhere else. Decide which machines these should be before you publish anything.

On the instance VeilNet hosts, these are the machines you enrolled with the server's taint. On a sovereign network, they are the machines that the guardian commissioned with compatible taints.

To check, run sudo conflux peers on a client. The DATA column shows yes for each peer the client can exchange data with, and no for each peer it cannot.

Publishing from a Proxy Machine

On a proxy machine, you publish each port with a spec. A spec maps an overlay port to a backend that the machine can already reach, much like port forwarding on a router.

A spec can publish any TCP or UDP service, not only a web app. For example, 5432=127.0.0.1:5432 publishes a database, and 53/udp=127.0.0.1:53 publishes DNS. Peers reach each port at the machine's overlay IPv4 and IPv6 addresses. The host itself gets no interface.

Each connection to the overlay port becomes a new connection to the backend. The service keeps listening where it already does.

Fig. 01 — Publishing a service, two ways01 / 02

conflux proxy keeps the overlay inside the anchor. A peer connects to the overlay port, and the anchor opens a new connection to the backend you named. The service stays on loopback, and every connection reaches it from loopback.

conflux up gives the host a real interface. The service listens on that interface, and peers connect to it directly. Bind the service as usual, as Publishing from a TUN Machine describes.

0 of 3 done

01
Run conflux proxy with a spec for the port:
$ sudo conflux proxy 8080=127.0.0.1:3000
On the instance VeilNet hosts, the first machine mints a taint, as up does. To join an existing network, add its taint with --taint brhk-2mq9-tzva-6pjs-k4xe-nw7d-qf.
On a sovereign network, install the machine's manifest with conflux enrol first, and leave out --taint.

Each spec has the form OVERLAYPORT[/NETWORK]=BACKEND

Spec	Means
`8080=127.0.0.1:3000`	TCP on overlay port 8080 to 127.0.0.1:3000
`53/udp=127.0.0.1:53`	UDP on overlay port 53 to 127.0.0.1:53
`5432=[::1]:5432`	An IPv6 backend, in brackets
`80=nas.lan:8080`	A backend on another host that this machine can reach, given by name. The connection comes from this host, so the backend sees this host's address.

Specs follow these rules:

The network is tcp unless you write udp. The overlay port must be from 1 to 65535.
To publish one port on both TCP and UDP, give two specs, such as 53=… and 53/udp=…. The same port and network cannot appear twice.
The backend can be a name that does not resolve yet, or a named port. Conflux connects to it only when a peer connects.
An overlay port never clashes with a host port, because conflux binds nothing on the host. For example, 80=127.0.0.1:3000 works on a machine that already serves port 80.
Specs and flags can appear in any order on the command line.

You can also add the spec to proxies in conflux.json, and then run sudo conflux start:

/etc/conflux/conflux.json

{
  "version": 1,
  "mode": "proxy",
  "taints": ["brhk-2mq9-tzva-6pjs-k4xe-nw7d-qf"],
  "ipv4": "10.128.0.5/24",
  "proxies": ["5432=127.0.0.1:5432", "80=127.0.0.1:3000"]
}

The CLI Reference lists every field of the file.

Refused specs

Message	What to do
`conflux proxy publishes a local service on the overlay, and needs at least one spec`	You ran `conflux proxy` with nothing to publish, and it exited with status 2. Add a spec. For a machine that only routes, add `--subnet` or `--serve-exit` instead.
`"8080" is not PORT[/NETWORK]=BACKEND`	Write the backend after an `=`, as in `8080=127.0.0.1:3000`.
`"tpc" is not tcp or udp`	Write `tcp` or `udp` after the `/`.
`"70000" is not an overlay port (1-65535)`	Use a port from 1 to 65535.
`backend "localhost" is not host:port`	Give the backend a port, as in `127.0.0.1:3000`.
`overlay port 8080/tcp is given twice`	Give each combination of port and network only once.

Changing Ports at Runtime

To try a port without saving it, use the proxy command of anchorctl through conflux. The change lasts until the anchor restarts, and conflux then starts it again with the saved list.

$ sudo conflux anchorctl proxy                             # what it is serving
$ sudo conflux anchorctl proxy -add 9000=127.0.0.1:9000    # one more, until restart
$ sudo conflux anchorctl proxy -rm 9000                    # and gone again

conflux proxy -add does not work, because conflux proxy sets the mode the machine boots into. Conflux refuses it with the message "-add" is not one of conflux proxy's flags.

Publishing from a TUN Machine

On a machine that runs conflux up, the host owns the overlay addresses. To publish a service, bind it as usual. There is nothing to configure in conflux.

A service on a TUN machine follows these rules:

Bind to 0.0.0.0 or ::, or bind to the overlay address alone to accept connections only from the overlay. Peers cannot reach a service bound to 127.0.0.1.
A service that binds the overlay address at boot must start after conflux. Under systemd, add After=conflux.service. The conflux unit is Type=notify, so systemd counts it as started only once the anchor is up.
A peer that connects over IPv6 appears with its own overlay address. A peer that connects over IPv4 appears with an address in 198.18.0.0/15. Write allow-lists against IPv6 addresses, because each one is bound to a peer's identity.
Broadcast and multicast do not cross the overlay, so discovery by mDNS or SSDP does not work. Connect by address.
Peers have addresses, not names. sudo conflux peers lists their addresses. To give a peer a name, add a line to /etc/hosts.

Several Services on One Machine

On a proxy machine

Run one command with every spec in it:

$ sudo conflux proxy 5432=127.0.0.1:5432 6379=127.0.0.1:6379 80=127.0.0.1:3000

On a TUN machine

Bind each service as you would on any network. Nothing else is needed.

For the exact settings for PostgreSQL, Redis, Grafana and ten other services, see Service Recipes. Each recipe includes the settings that stop the app redirecting to localhost.