kolo docsbeta

Run your own infrastructure

Copy-paste commands to run your own entry node, relay and pin, and to point the Kolo examples at them. There is no public relay and no public pin.

On this page

Kolo examples need no server of yours to start: by default they join the public network. You run servers yourself for your own network, for a relay or for a pin. An entry node is the address every example contacts first to find the others. A relay carries a connection between two computers that cannot connect directly. A pin keeps an encrypted copy of a log for people who are offline. This page has the commands for each one, and the flags that point the examples at them.

An example has three network modes:

  • Public network (default). With no flag, the example uses the two public entry nodes that Ciranda runs, built into the libraries. Two people on different networks find each other with no setup. It is free, with no uptime guarantee while Kolo is a beta.
  • Your own network. -bootstrap host:port[,host:port] uses the entry nodes you list, alone: the public ones are not touched. Run them with kolo-node below.
  • This computer only. -local keeps everything on 127.0.0.1: the first window runs an entry node and the others join it. Kolo Share, Kolo Meet and Kolo Board have it; Kolo Chat has no local mode, and its own network is -bootstrap. -local together with -bootstrap is an error.

If the public network cannot be reached at start, the example shows an error that names these three options; it never falls back to another network.

There is no public relay and no public pin, and no example defaults to one. Both stay optional (-relay, -pin) and you run your own. A relay matters only behind strict NATs, where two computers cannot connect directly.

All steps

The servers you run

You run these for your own network. There is no public relay and no public pin; the public entry nodes are Ciranda's and are the default.

  1. With -bootstrap, an example uses the address of your entry node, alone, and finds the other examples on its topic through it. With no flag it uses the public entry nodes.
  2. Two examples connect directly when they can. The entry node only helps them meet and carries none of their data.
  3. When the direct connection fails, two examples meet through a relay that both list with -relay host:port@key. The relay copies encrypted bytes it cannot read.
  4. Kolo Chat also keeps an encrypted copy of each member's log on a pin. An example reaches the pin directly, never through a relay, so the pin needs an address every member reaches.
ServerCommandDefault portUsed by
Entry nodekolo-node runUDP 7447every example
Relaykolo-node relayUDP 7448 (-listen)Kolo Chat, Kolo Share and Kolo Meet, when you list one
Pinkolo-pin runUDP 7450 (-listen)Kolo Chat

The commands below use 203.0.113.10 as the address of your server. Use its real public IPv4 address, or a name that resolves to it. Kolo is IPv4 only. Open each UDP port you use in the host's firewall and in the provider's firewall.

Install the commands

Install kolo-node, which runs entry nodes and relays:

Terminal
go install github.com/ciranda-dev/kolo-node/cmd/kolo-node@v0.1.0

Install kolo-pin, for a pin:

Terminal
go install github.com/ciranda-dev/kolo-pin/cmd/kolo-pin@v0.1.0

Both are Go only, with no cgo, and go install puts them in $(go env GOPATH)/bin, which must be on your PATH.

Run an entry node

The first entry node of your network starts with -first, since there are no entry nodes yet. It creates its key file with mode 0600 on the first run and keeps it for the next runs:

Terminal
kolo-node run -listen 0.0.0.0:7447 -identity "$HOME/kolo-node/node.key" -first

A second entry node, on another host, joins the first with -bootstrap, so the network stays up when one of them stops:

Terminal
kolo-node run -listen 0.0.0.0:7447 -identity "$HOME/kolo-node/node.key" -bootstrap 203.0.113.10:7447

-bootstrap takes a comma-separated list and can be repeated, -bootstrap-file reads one host:port per line, and KOLO_BOOTSTRAP is read only when neither is set; at most 16 entries in all. Without any of them and without -first, run exits with code 2, so a list left empty by mistake never starts a lone node.

Open its port. With ufw:

Terminal
sudo ufw allow 7447/udp

From each computer that will run an example, check that the node answers. It prints ok 203.0.113.10:7447:

Terminal
kolo-node check 203.0.113.10:7447

The list of entry nodes is not a secret and not access control: anyone who knows one address can join that network. See kolo-node for the config file, the systemd unit and the limits.

Run a relay

A relay has its own key file and its own UDP port. It logs its key as key in its identity line when it starts: that is the <relay-key> below, 64 hex characters.

Terminal
kolo-node relay -listen 0.0.0.0:7448 -identity "$HOME/kolo-node/relay.key"

Without -allow-file the relay is open: any key may hold a place (a reservation) there, and it logs the warning open relay. With -allow-file, only the keys in the file may hold a place: one key per line, as 64 hex characters, # comments allowed. Each example prints its own key in the terminal, in its kolo-id line. Any key can still connect through the relay to an example that holds a place there.

Terminal
kolo-node relay -listen 0.0.0.0:7448 -identity "$HOME/kolo-node/relay.key" -allow-file "$HOME/kolo-node/allow.txt"

An allow list cannot name a key made for one pairing code or one call. So with -allow-file, a Kolo Share pairing code never waits at the relay, and the relay of a Kolo Meet call cannot hold a place there: a guest who cannot reach the host directly needs a relay without an allow list.

Open its port. With ufw:

Terminal
sudo ufw allow 7448/udp

From each computer, check that the relay answers with that key. It prints ok relay 203.0.113.10:7448@<relay-key> and reserves nothing:

Terminal
kolo-node check -relay 203.0.113.10:7448@<relay-key>

The relay's limits (places, sessions, bytes, rate) are -relay-* flags; see kolo-node and kolo-relay.

Run a pin

Only Kolo Chat uses a pin, and it is optional. It keeps an encrypted copy of each member's log and never gets the keys to read it. Start it with a private data folder and a size limit:

Terminal
kolo-pin run -data "$HOME/kolo-pin" -listen 0.0.0.0:7450 -max-bytes 100GB

Print its public key, which goes after the @ in the examples' pin list:

Terminal
kolo-pin id -data "$HOME/kolo-pin"

The data folder is created with mode 0700 and the key file with 0600. To accept only your people, add -owners with the key of every member, comma separated.

A pin is reached directly, never through a relay: it needs an address that every member reaches, a public IPv4 address or a router that forwards UDP port 7450 to it. Open its port. With ufw:

Terminal
sudo ufw allow 7450/udp

To run it under systemd and watch it, see Run a pinning peer on a VPS.

Point the examples at them

Every example takes your own entry nodes with -bootstrap host:port; without it, the example uses the public network. Relays are given as host:port@key, the key as 64 hex characters:

  • -relay takes a comma-separated list and can be repeated.
  • -relay-file reads a file of relays, one per line, # comments allowed.
  • Each example has its own environment variable, read only when neither flag is given: KOLO_CHAT_RELAYS, KOLO_SHARE_RELAYS and KOLO_MEET_RELAYS.
  • At most 16 relays in all. One key at two addresses, or one address with two keys, is refused.

Two computers meet through a relay only when both list it, so give every example the same relay. Kolo Chat:

Terminal
./bin/kolo-chat -bootstrap 203.0.113.10:7447 -relay 203.0.113.10:7448@<relay-key>

Kolo Share:

Terminal
./bin/kolo-share -bootstrap 203.0.113.10:7447 -relay 203.0.113.10:7448@<relay-key>

Kolo Meet:

Terminal
./bin/kolo-meet -bootstrap 203.0.113.10:7447 -relay 203.0.113.10:7448@<relay-key>

Kolo Chat's pin list is -pin IP:PORT@KEY or KOLO_CHAT_PIN, set by the person who starts the conversation; the invite carries it to everyone who joins. The invite does not carry the relays. What each example needs is in Built with Kolo.

Which connection am I on?

Direct first, relay as a fallback. With relays listed, kolo-swarm first tries a direct connection, with the hole punching of kolo-dht, and tries the relays only after that failed. A first contact can take up to 3 times 45 seconds when punches start but never connect, then up to 60 seconds for each relay tried. A peer that needed a relay before is dialed directly and through the relays at once next time, and a direct connection that works replaces the relayed one.

To see which one you are on:

  • In Go, Peer.Direct() is false for a peer reached through a relay, and its Conn() is a *kolorelay.Conn whose RelayPublicKey() names the relay. See kolo-swarm.
  • Kolo Meet marks a person reached through a relay with "via relay" on their tile.
  • Kolo Chat and Kolo Share show each relay and its state in Settings.

What the operator of a relay can see, in the words of kolo-relay's README:

What the relay learns: both keys of every session, both clients' addresses, which keys hold reservations, when sessions start and end, and the sizes and timing of the inner packets. It cannot read or change them, and it can always drop, delay or end them.

The two peers run their own kolo-secure connection through the relay, so it forwards packets of a session it is not part of. kolo-node relay logs no peer address and no key of its clients. An entry node carries no application data at all. See Relay.

Next steps