Installation

Installing Conflux

Conflux is the command-line tool that runs an anchor on your machine. Each build is a single binary of about 50 MB. It contains anchord and anchorctl, the anchor binaries for its platform.

The installation steps are the same on every platform.

You can keep the downloaded binary anywhere. The boot service runs as root, so conflux registers its own copy in a directory that only root can change. The up, proxy, install and start commands make this copy, and uninstall removes it.

Two Ways to Join

A credential admits a machine to its realm. How you get one depends on the network you join:

• The instance VeilNet hosts is for trials and personal use. A machine enrols itself there.
• A sovereign network belongs to an organisation, which runs it with its guardian. The guardian commissions the machine, and you install the file it hands over.

After that, every command is the same on both.

Joining the Instance VeilNet Hosts

The first time you run conflux up, it enrols the machine with the instance VeilNet hosts at https://api.veilnet.com.au. The machine gets its own identity and credential, and every later run reuses them. conflux proxy enrols in the same way. To choose between the two, see Proxy and TUN Modes.

Machines exchange data only when their taints are compatible. The first machine mints a taint, and you pass it to every other machine.

To run up from a script, pass both flags. --taint chooses the compartment, and --ipv4 or --no-ipv4 answers the only question that up asks. Without a terminal and without either IPv4 flag, conflux exits with status 1:

conflux: this machine has not been given an IPv4 yet and there is no terminal to ask at: pass --ipv4 ADDRESS or --no-ipv4

Conflux asks the IPv4 question only once in a machine's life, and it keeps the answer, even a blank one. A later up without the flag leaves the address unchanged.

Choosing the IPv4 address

Conflux treats the address you give as follows:

• Conflux advertises a private address, and peers reach the machine at it. Give a different address to each machine that peers must reach on its own.
• Conflux sends traffic from a public address but never advertises it.
• A prefix length, as in 10.128.0.7/24, routes the rest of that range to the peers whose addresses fall inside it.
• A blank answer is valid and common. The machine still reaches IPv4 peers, and peers reach it at its IPv6 address.
• Conflux refuses addresses in 198.18.0.0/15, because anchor uses that range for IPv4 peers. It also refuses IPv6, loopback, link-local, multicast and broadcast addresses, and a range that covers the whole internet, such as 0.0.0.0/0.
• To send internet traffic over the overlay, use an exit node with --use-exit instead.

Joining a Sovereign Network

On a sovereign network, machines do not enrol themselves. An operator commissions each machine in the guardian console and chooses its realm, its taints and, optionally, its IPv4 address.

The operator then hands you one file, the machine's manifest. It holds the machine's identity, its credential and the bootstrap nodes it starts from. conflux enrol installs the manifest, and conflux up starts the machine.

These flags change how enrol installs a manifest:

enrol checks everything before it writes anything, and it never replaces an installed credential. To replace one, run sudo conflux uninstall first.

If the manifest commissions the machine as an exit node, enrol shows an exit row, and the hint becomes Next: sudo conflux up --serve-exit. Conflux serves an exit only when you pass that flag.

enrol copies the allocated IPv4 address and any telemetry export settings into the configuration once. After that, you can change them like any other setting. To learn how the machine renews through the guardian, see Credentials and Renewal.

Boot Service

When a machine joins, conflux registers a boot service. The machine then comes back after a reboot without any command from you.

At every start, the service renews the credential if more than two thirds of its life has passed, and then starts the anchor. If the anchor stops, the service starts it again.

The service retries a failed start, waiting up to 30 seconds between attempts. It gives up after three attempts, with exit status 70, when retrying cannot help:

• Conflux refuses the configuration.
• The configuration asks for taints that the credential does not grant.
• The credential has expired and cannot be renewed.

If there is nothing to start at all, the service exits with status 78.

To check the service, look at the service row of sudo conflux status. On Linux, a healthy machine shows active (systemd: conflux.service, enabled at boot). For the other states, see Service and Logs.

Stopping and removing

down and start stop and start the anchor now. install and uninstall register and remove the boot service, and uninstall also deletes the identity.

To stop the anchor and keep everything else, run down:

$ sudo conflux down
Stopped. The boot service is still registered and the configuration is intact,
so the next reboot brings this machine back exactly as it was.

  conflux start      start it again now
  conflux uninstall  remove it permanently

The CLI Reference lists every file conflux keeps.