Proxy and TUN Modes

Conflux runs a machine in one of two modes: conflux up gives the host a network interface, and conflux proxy publishes chosen ports without one.

The Two Modes

Both modes run an anchor and connect the machine to its realm. They differ in what the host gets, and so in how programs on the machine use the overlay.

TUN mode

conflux up runs in TUN mode. It creates a network interface on the host, and the host owns the overlay addresses. Every program on the machine, from ping and ssh to a browser, can use the overlay without changes.

To publish a service in TUN mode, bind it as you would on any network. The interface is anchor0 on Linux and Windows, utunN on macOS and tunN on the BSDs. The system chooses the number.

Proxy mode

conflux proxy runs in userspace mode. It creates no interface, and nothing on the host can see the overlay addresses. Peers reach only the ports you publish, and the anchor passes each connection to a backend that the machine can reach.

Proxy mode is not an HTTP proxy. It publishes any TCP or UDP service, such as a database, DNS, SSH or a message broker. Each published port answers at the machine's overlay IPv4 address and at its IPv6 address, as on a VPN.

A proxy machine can still act as a subnet router or exit node. The anchor forwards that traffic from its own process, so the destination sees this host's address. The anchor needs no privilege, and you need root only to register the boot service.

Fig. 01 — What each mode gives the host

With conflux up, the host owns the overlay addresses on anchor0, and every program on the host can use them. With conflux proxy, the anchor owns the overlay addresses itself, IPv4 as well as IPv6, and no interface appears on the host. Peers reach only the TCP and UDP ports you publish, and the anchor opens a new connection to the backend for each one.

Quick Start uses up, which suits a laptop. A server that only publishes ports can run proxy instead, and then nothing changes on the host.

Comparing the Modes

The two modes compare as follows:

	conflux up	conflux proxy
What the host gets	A TUN interface for ping, ssh and every other program	Nothing
What the realm gets	This machine, at an overlay address	The services you name, at overlay ports, and any subnet or exit it routes
Privilege	Root, CAP_NET_ADMIN, or Administrator	Root only to register the boot service
An IPv4 address	Yes, on the host's interface	Yes, inside the anchor. Peers reach published ports at it, as on a VPN
Protocols	Anything bound on the interface	Any TCP or UDP service. Name its port, and add /udp for UDP
Can connect out as a client	Yes	No. There is no interface to connect from
Act as a subnet router	Yes. The host forwards	Yes. The anchor forwards from its own process
Serve or use an exit node	Yes	Yes. Using one covers only the anchor's own traffic
Run over an uplink	Yes	Yes
wintun.dll on Windows	Needed	Not needed
`mode` row in `conflux status`	`tun — interface anchor0`	`proxy — userspace, no host interface`

Choosing a Mode

Choose the mode by what the machine does:

Choose up for any machine that connects out, such as a laptop, a workstation, a jump host or an application server that calls a database on another machine. A client always runs up.
Choose proxy for a machine that only offers services, or where CAP_NET_ADMIN is not available, such as a container, a CI runner or a locked-down host. Proxy mode changes nothing on the host.
Either mode can act as a subnet router or exit node, and can reach the realm over the host's network or over a serial cable.

The mode decides what the machine gets from the realm. The medium decides how the anchor reaches the realm. By default the medium is the host's IP network, but it can also be a serial cable that you name with --uplink.

The two choices are independent, so all four combinations work. Uplinks run on Linux, macOS and the BSDs:

	Over the host's network	Over a cable
`up`	`sudo conflux up`	`sudo conflux up --uplink /dev/ttyUSB0:115200`
`proxy`	`sudo conflux proxy 8080=127.0.0.1:3000`	`sudo conflux proxy 8080=127.0.0.1:3000 --uplink /dev/ttyS1`

To publish from each mode, see Publishing Services. To set up the cable, see Serial Uplink.

Switching Modes

To switch modes, run the other command. Conflux replaces the current mode and tells you that it has done so.

0 of 3 done

$ sudo conflux proxy 8080=127.0.0.1:3000
conflux: this machine was running in TUN mode with interface anchor0.
  Userspace mode replaces that: one daemon holds one anchor, and an anchor with
  a host interface cannot also serve a reverse proxy -- with a TUN the kernel owns
  the overlay address, so a service binds it directly and needs no proxy.

A switch keeps the identity, so the machine keeps its AnchorID and overlay address. It also keeps every setting that both modes use: the subnets, the exit settings, the IPv4 address, the taints, the uplink, the starting peers, the port and low-latency mode.

Switching to up clears the proxy specs, because only proxy mode serves them. To turn routing off in either mode, pass --no-subnet, --no-serve-exit or --no-use-exit.