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 withkolo-nodebelow. - This computer only.
-localkeeps 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.-localtogether with-bootstrapis 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.
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.
- 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.
- Two examples connect directly when they can. The entry node only helps them meet and carries none of their data.
- 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.
- 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.
| Server | Command | Default port | Used by |
|---|---|---|---|
| Entry node | kolo-node run | UDP 7447 | every example |
| Relay | kolo-node relay | UDP 7448 (-listen) | Kolo Chat, Kolo Share and Kolo Meet, when you list one |
| Pin | kolo-pin run | UDP 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:
go install github.com/ciranda-dev/kolo-node/cmd/kolo-node@v0.1.0Install kolo-pin, for a pin:
go install github.com/ciranda-dev/kolo-pin/cmd/kolo-pin@v0.1.0Both 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:
kolo-node run -listen 0.0.0.0:7447 -identity "$HOME/kolo-node/node.key" -firstA second entry node, on another host, joins the first with -bootstrap,
so the network stays up when one of them stops:
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:
sudo ufw allow 7447/udpFrom each computer that will run an example, check that the node answers. It
prints ok 203.0.113.10:7447:
kolo-node check 203.0.113.10:7447The 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.
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.
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:
sudo ufw allow 7448/udpFrom each computer, check that the relay answers with that key. It prints
ok relay 203.0.113.10:7448@<relay-key> and reserves nothing:
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:
kolo-pin run -data "$HOME/kolo-pin" -listen 0.0.0.0:7450 -max-bytes 100GBPrint its public key, which goes after the @ in the examples' pin list:
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:
sudo ufw allow 7450/udpTo 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:
-relaytakes a comma-separated list and can be repeated.-relay-filereads 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_RELAYSandKOLO_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:
./bin/kolo-chat -bootstrap 203.0.113.10:7447 -relay 203.0.113.10:7448@<relay-key>Kolo Share:
./bin/kolo-share -bootstrap 203.0.113.10:7447 -relay 203.0.113.10:7448@<relay-key>Kolo Meet:
./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 itsConn()is a*kolorelay.ConnwhoseRelayPublicKey()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
- Built with Kolo: what each example needs.
- Run a pinning peer on a VPS: the pin under systemd, step by step.
- kolo-node, kolo-relay and kolo-pin: every flag and limit.