kolo docsbeta

Rode a sua própria infraestrutura

Comandos para copiar e colar que rodam o seu próprio nó de entrada, relay e pin, e que apontam os exemplos do Kolo para eles. Não existe relay público nem pin público.

Nesta página

Os exemplos do Kolo não precisam de nenhum servidor seu para começar: por padrão entram na rede pública. Você roda servidores por conta própria para a sua rede, para um relay ou para um pin. Um nó de entrada é o endereço que todo exemplo procura primeiro para encontrar os outros. Um relay leva uma conexão entre dois computadores que não conseguem se conectar diretamente. Um pin guarda uma cópia cifrada de um log para quem está offline. Esta página traz os comandos de cada um, e as flags que apontam os exemplos para eles.

Um exemplo tem três modos de rede:

  • Rede pública (padrão). Sem nenhuma flag, o exemplo usa os dois nós de entrada públicos que a Ciranda mantém no ar, embutidos nas bibliotecas. Duas pessoas em redes diferentes se encontram sem configurar nada. É de graça e sem garantia de disponibilidade enquanto o Kolo for uma beta.
  • A sua própria rede. -bootstrap host:port[,host:port] usa só os nós de entrada que você lista: os públicos não são tocados. Você os roda com o kolo-node, mais abaixo.
  • Só este computador. -local mantém tudo em 127.0.0.1: a primeira janela roda um nó de entrada e as outras entram nele. O Kolo Share, o Kolo Meet e o Kolo Board têm essa opção; o Kolo Chat não tem modo local, e a sua própria rede é -bootstrap. -local junto com -bootstrap é um erro.

Se a rede pública não puder ser alcançada na partida, o exemplo mostra um erro que nomeia essas três opções; ele nunca recorre a outra rede por conta própria.

Não existe relay público nem pin público, e nenhum exemplo usa um por padrão. Os dois continuam opcionais (-relay, -pin) e você roda os seus. Um relay só importa atrás de NATs restritivos, onde dois computadores não conseguem se conectar diretamente.

Todos os passos

Os servidores que você roda

Você roda estes para a sua própria rede. Não existe relay público nem pin público; os nós de entrada públicos são da Ciranda e são o padrão.

  1. Com -bootstrap, um exemplo usa só o endereço do seu nó de entrada e encontra por ele os outros exemplos do seu topic. Sem nenhuma flag usa os nós de entrada públicos.
  2. Dois exemplos se conectam diretamente quando conseguem. O nó de entrada só ajuda os dois a se encontrarem e não carrega nenhum dado deles.
  3. Quando a conexão direta falha, dois exemplos se encontram por um relay que os dois informam com -relay host:port@key. O relay copia bytes cifrados que não consegue ler.
  4. O Kolo Chat também guarda num pin uma cópia cifrada do log de cada membro. Um exemplo chega ao pin diretamente, nunca por um relay, então o pin precisa de um endereço que todos os membros alcancem.
ServidorComandoPorta padrãoUsado por
Nó de entradakolo-node runUDP 7447todos os exemplos
Relaykolo-node relayUDP 7448 (-listen)Kolo Chat, Kolo Share e Kolo Meet, quando você informa um
Pinkolo-pin runUDP 7450 (-listen)Kolo Chat

Os comandos abaixo usam 203.0.113.10 como endereço do seu servidor. Use o endereço IPv4 público real dele, ou um nome que resolva para ele. O Kolo é só IPv4. Abra cada porta UDP que você usar no firewall da máquina e no firewall do provedor.

Instale os comandos

Instale a kolo-node, que roda nós de entrada e relays:

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

Instale a kolo-pin, para um pin:

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

As duas são só Go, sem cgo, e o go install coloca os comandos em $(go env GOPATH)/bin, que precisa estar no seu PATH.

Rode um nó de entrada

O primeiro nó de entrada da sua rede começa com -first, já que ainda não existe nenhum nó de entrada. Ele cria o arquivo de chave com modo 0600 na primeira execução e o mantém nas seguintes:

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

Um segundo nó de entrada, em outra máquina, entra pelo primeiro com -bootstrap, para que a rede continue no ar quando um deles parar:

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

-bootstrap aceita uma lista separada por vírgulas e pode se repetir, -bootstrap-file lê um host:port por linha, e KOLO_BOOTSTRAP só é lido quando nenhum dos dois está definido; no máximo 16 entradas no total. Sem nenhum deles e sem -first, o run sai com código 2, então uma lista deixada vazia por engano nunca inicia um nó sozinho.

Abra a porta dele. Com ufw:

Terminal
sudo ufw allow 7447/udp

Em cada computador que vai rodar um exemplo, confira se o nó responde. Ele imprime ok 203.0.113.10:7447:

Terminal
kolo-node check 203.0.113.10:7447

A lista de nós de entrada não é um segredo nem controle de acesso: quem conhece um endereço pode entrar naquela rede. Veja kolo-node para o arquivo de configuração, a unidade do systemd e os limites.

Rode um relay

Um relay tem o próprio arquivo de chave e a própria porta UDP. Ao iniciar, ele registra a sua chave como key na linha identity: essa é a <relay-key> abaixo, com 64 caracteres hexadecimais.

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

Sem -allow-file o relay é aberto: qualquer chave pode ocupar um lugar (uma reserva) nele, e ele registra o aviso open relay. Com -allow-file, só as chaves do arquivo podem ocupar um lugar: uma chave por linha, com 64 caracteres hexadecimais, e comentários com #. Cada exemplo imprime a própria chave no terminal, na linha kolo-id. Qualquer chave ainda pode se conectar pelo relay a um exemplo que ocupa um lugar nele.

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

Uma lista de permissões não consegue nomear uma chave criada para um único código de pareamento ou para uma única chamada. Por isso, com -allow-file, um código de pareamento do Kolo Share nunca espera no relay, e o relay de uma chamada do Kolo Meet não consegue ocupar um lugar nele: um convidado que não alcança o anfitrião diretamente precisa de um relay sem lista de permissões.

Abra a porta dele. Com ufw:

Terminal
sudo ufw allow 7448/udp

Em cada computador, confira se o relay responde com essa chave. Ele imprime ok relay 203.0.113.10:7448@<relay-key> e não reserva nada:

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

Os limites do relay (lugares, sessões, bytes, taxa) são as flags -relay-*; veja kolo-node e kolo-relay.

Rode um pin

Só o Kolo Chat usa um pin, e ele é opcional. Ele guarda uma cópia cifrada do log de cada membro e nunca recebe as chaves para lê-la. Inicie o pin com uma pasta de dados privada e um limite de tamanho:

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

Imprima a chave pública dele, que vai depois do @ na lista de pins dos exemplos:

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

A pasta de dados é criada com modo 0700 e o arquivo de chave com 0600. Para aceitar só a sua gente, acrescente -owners com a chave de cada membro, separadas por vírgulas.

Um pin é alcançado diretamente, nunca por um relay: ele precisa de um endereço que todos os membros alcancem, um endereço IPv4 público ou um roteador que encaminhe a porta UDP 7450 para ele. Abra a porta dele. Com ufw:

Terminal
sudo ufw allow 7450/udp

Para rodar o pin com systemd e acompanhá-lo, veja Rode um peer de fixação em uma VPS.

Aponte os exemplos para eles

Todo exemplo recebe os seus próprios nós de entrada com -bootstrap host:port; sem ele, o exemplo usa a rede pública. Os relays são informados como host:port@key, com a chave em 64 caracteres hexadecimais:

  • -relay aceita uma lista separada por vírgulas e pode se repetir.
  • -relay-file lê um arquivo de relays, um por linha, com comentários com #.
  • Cada exemplo tem a sua própria variável de ambiente, lida só quando nenhuma das duas flags é dada: KOLO_CHAT_RELAYS, KOLO_SHARE_RELAYS e KOLO_MEET_RELAYS.
  • No máximo 16 relays no total. Uma chave em dois endereços, ou um endereço com duas chaves, é recusado.

Dois computadores só se encontram por um relay quando os dois o têm na lista, então dê a todos os exemplos o mesmo 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>

A lista de pins do Kolo Chat é -pin IP:PORT@KEY ou KOLO_CHAT_PIN, definida por quem inicia a conversa; o convite a leva a todos que entram. O convite não leva os relays. O que cada exemplo precisa está em Feito com Kolo.

Em qual conexão eu estou?

Primeiro a direta, o relay como alternativa. Com relays na lista, a kolo-swarm tenta primeiro uma conexão direta, com o hole punching da kolo-dht, e só tenta os relays depois que ela falhou. Um primeiro contato pode levar até 3 vezes 45 segundos quando os punches começam mas nunca conectam, e depois até 60 segundos para cada relay tentado. Um peer que precisou de um relay antes é discado diretamente e pelos relays ao mesmo tempo na vez seguinte, e uma conexão direta que funciona substitui a que passa pelo relay.

Para ver em qual delas você está:

  • Em Go, Peer.Direct() é falso para um peer alcançado por um relay, e o Conn() dele é um *kolorelay.Conn cujo RelayPublicKey() nomeia o relay. Veja kolo-swarm.
  • O Kolo Meet marca uma pessoa alcançada por um relay com "via relay" no quadro dela.
  • O Kolo Chat e o Kolo Share mostram cada relay e o estado dele nas configurações.

O que o operador de um relay consegue ver, nas palavras do README da kolo-relay:

O que o relay fica sabendo: as duas chaves de cada sessão, os endereços dos dois clientes, quais chaves têm reservas, quando as sessões começam e terminam, e o tamanho e o ritmo dos pacotes internos. Ele não consegue ler nem alterar esses pacotes, e sempre pode descartá-los, atrasá-los ou encerrá-los.

Os dois peers rodam a própria conexão kolo-secure através do relay, então ele repassa pacotes de uma sessão da qual não faz parte. O kolo-node relay não registra nenhum endereço de peer nem nenhuma chave dos seus clientes. Um nó de entrada não leva nenhum dado de aplicação. Veja Relay.

Próximos passos