O kolo-node é um comando, não um pacote Go. Ele roda um servidor da kolo-dht em uma porta UDP: responde a consultas da DHT, guarda anúncios de topic assinados e repassa pedidos de conexão para que os peers consigam fazer hole punch através dos seus NATs. Ele não carrega dados de aplicação. O kolo-node relay roda, em vez disso, um servidor da kolo-relay, para peers que não conseguem se conectar diretamente; ele copia o tráfego cifrado deles, que não consegue ler. Ele guarda a sua chave da kolo-id em um arquivo, encerra de forma limpa com SIGINT e SIGTERM, e registra alguns eventos estruturados com slog. Rode algumas instâncias em hosts diferentes e passe os endereços delas para os peers.
Instalação
go install github.com/ciranda-dev/kolo-node/cmd/kolo-node@latestCompila sem cgo; CGO_ENABLED=0 gera um binário estático.
Início rápido
Inicie uma rede nova no loopback: o seu primeiro nó, com -first (ainda sem nós de entrada) e a chave em um novo diretório temporário:
dir=$(mktemp -d)
kolo-node run -listen 127.0.0.1:7447 -identity "$dir/state/node.key" -firstVerifique o nó a partir de um segundo terminal. O comando imprime ok 127.0.0.1:7447:
kolo-node check 127.0.0.1:7447Um peer faz bootstrap a partir do nó passando o endereço dele para (*kolodht.Node).Bootstrap. Este programa recebe os endereços como argumentos, por exemplo go run . 127.0.0.1:7447:
package main
import (
"context"
"fmt"
"log"
"net/netip"
"os"
"time"
kolodht "github.com/ciranda-dev/kolo-dht"
koloid "github.com/ciranda-dev/kolo-id"
)
func main() {
if len(os.Args) < 2 {
log.Fatal("usage: join IP:PORT...")
}
var servers []netip.AddrPort
for _, a := range os.Args[1:] {
ap, err := netip.ParseAddrPort(a)
if err != nil {
log.Fatal(err)
}
servers = append(servers, ap)
}
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
id, err := koloid.Generate()
if err != nil {
log.Fatal(err)
}
n, err := kolodht.New(ctx, "127.0.0.1:0", id, nil)
if err != nil {
log.Fatal(err)
}
defer n.Close()
if err := n.Bootstrap(ctx, servers); err != nil {
log.Fatal(err)
}
fmt.Println("joined:", n.Stats().Servers, "servers in the routing table")
}O programa imprime quantos servidores estão na tabela de roteamento do cliente. Outro kolo-node entra com -bootstrap, uma lista de entradas host:port (endereços IPv4 ou nomes DNS), com -bootstrap-file, um arquivo com uma entrada por linha, ou com os dois:
kolo-node run -listen 127.0.0.1:7448 -identity "$dir/state2/node.key" -bootstrap 127.0.0.1:7447Pare um nó com Ctrl-C: ele registra stopping, uma última linha de stats e stopped, e sai com 0. Iniciar o nó de novo com o mesmo -identity mantém a mesma chave.
Sem -bootstrap, -bootstrap-file, a variável de ambiente KOLO_BOOTSTRAP nem -first, run sai com 2, então uma lista deixada vazia por engano nunca inicia um nó solitário. O kolo-node não traz nenhuma lista de nós públicos; veja Redes públicas e privadas.
Referência da API
A referência da API é gerada a partir do código Go e está em inglês.
Command kolo-node runs a kolo-dht bootstrap server or a kolo-relay; see the README for its commands, flags and config file.
Comando
usage:
kolo-node run -identity FILE [flags] run a kolo-dht bootstrap server
kolo-node relay -identity FILE -listen ADDR [flags]
run a kolo-relay server
kolo-node check [-timeout 5s] [-relay HOST:PORT@KEY] [-relay-file FILE] [HOST:PORT...]
check that kolo-dht servers and kolo-relays answer from here
kolo-node version print the version
Run "kolo-node run -h" or "kolo-node relay -h" for their flags.kolo-node run
Usage of kolo-node run:
-bootstrap host:port
comma-separated host:port list of entry nodes, repeatable
-bootstrap-file file
file of entry nodes, one host:port per line, repeatable
-config file
JSON config file; flags set on the command line override it
-dht-max-inflight int
kolodht.Config.MaxInflight; 0 means the kolo-dht default
-dht-max-records int
kolodht.Config.MaxRecords; 0 means the kolo-dht default
-dht-max-records-per-ip int
kolodht.Config.MaxRecordsPerIP; 0 means the kolo-dht default
-dht-max-records-per-topic int
kolodht.Config.MaxRecordsPerTopic; 0 means the kolo-dht default
-dht-max-relays int
kolodht.Config.MaxRelays; 0 means the kolo-dht default
-dht-max-requests int
kolodht.Config.MaxRequests; 0 means the kolo-dht default
-dht-max-requests-per-ip int
kolodht.Config.MaxRequestsPerIP; 0 means the kolo-dht default
-dht-max-requests-per-prefix int
kolodht.Config.MaxRequestsPerPrefix; 0 means the kolo-dht default
-dht-punch-timeout duration
kolodht.Config.PunchTimeout; 0 means the kolo-dht default
-dht-request-timeout duration
kolodht.Config.RequestTimeout; 0 means the kolo-dht default
-first
start a new network: no entry nodes yet
-identity file
key file, created on the first run (required)
-listen address
IPv4 UDP address to listen on (default ":7447")
-log-addrs
log full peer addresses instead of their /24
-log-format format
log format: text or json (default "text")
-log-level level
log level: info, warn or error (default "info")
-stats-interval duration
interval between stats events, 1s to 24h (default 5m0s)kolo-node relay
Usage of kolo-node relay:
-allow-file file
file of the hex keys that may reserve, one per line; without it any key may
-config file
JSON config file; flags set on the command line override it
-identity file
key file of the relay, created on the first run (required)
-listen address
IPv4 UDP address to listen on (required)
-log-format format
log format: text or json (default "text")
-log-level level
log level: info, warn or error (default "info")
-relay-connect-timeout duration
kolorelay.ServerConfig.ConnectTimeout; 0 means the kolo-relay default
-relay-control-timeout duration
kolorelay.ServerConfig.ControlTimeout; 0 means the kolo-relay default
-relay-flush-interval duration
kolorelay.ServerConfig.FlushInterval; 0 means the kolo-relay default
-relay-max-conns int
the listener's kolo-transport MaxConns; 0 means 128, kolo-relay's listener default
-relay-max-conns-per-ip int
the listener's kolo-transport MaxConnsPerIP; 0 means 4, kolo-relay's listener default
-relay-max-reservations int
kolorelay.ServerConfig.MaxReservations; 0 means the kolo-relay default
-relay-max-session-bytes int
kolorelay.ServerConfig.MaxSessionBytes; 0 means the kolo-relay default
-relay-max-session-duration duration
kolorelay.ServerConfig.MaxSessionDuration; 0 means the kolo-relay default
-relay-max-sessions int
kolorelay.ServerConfig.MaxSessions; 0 means the kolo-relay default
-relay-max-sessions-per-peer int
kolorelay.ServerConfig.MaxSessionsPerPeer; 0 means the kolo-relay default
-relay-max-sessions-per-target int
kolorelay.ServerConfig.MaxSessionsPerTarget; 0 means the kolo-relay default
-relay-rate-burst int
kolorelay.ServerConfig.RateBurst; 0 means the kolo-relay default
-relay-rate-bytes int
kolorelay.ServerConfig.RateBytes, per second; 0 means the kolo-relay default
-relay-reservation-lifetime duration
kolorelay.ServerConfig.ReservationLifetime; 0 means the kolo-relay default
-relay-session-idle-timeout duration
kolorelay.ServerConfig.SessionIdleTimeout; 0 means the kolo-relay defaultkolo-node a
kolonode: unknown command "a"
usage:
kolo-node run -identity FILE [flags] run a kolo-dht bootstrap server
kolo-node relay -identity FILE -listen ADDR [flags]
run a kolo-relay server
kolo-node check [-timeout 5s] [-relay HOST:PORT@KEY] [-relay-file FILE] [HOST:PORT...]
check that kolo-dht servers and kolo-relays answer from here
kolo-node version print the version
Run "kolo-node run -h" or "kolo-node relay -h" for their flags.kolo-node check
usage: kolo-node check [-timeout 5s] [-relay HOST:PORT@KEY] [-relay-file FILE] [HOST:PORT...]
-relay host:port@key
comma-separated host:port@key list of kolo-relays, repeatable
-relay-file file
file of kolo-relays, one host:port@key per line, repeatable
-timeout duration
time allowed per address, 1s to 60s (default 5s)kolo-node that
kolonode: unknown command "that"
usage:
kolo-node run -identity FILE [flags] run a kolo-dht bootstrap server
kolo-node relay -identity FILE -listen ADDR [flags]
run a kolo-relay server
kolo-node check [-timeout 5s] [-relay HOST:PORT@KEY] [-relay-file FILE] [HOST:PORT...]
check that kolo-dht servers and kolo-relays answer from here
kolo-node version print the version
Run "kolo-node run -h" or "kolo-node relay -h" for their flags.Bom saber
Redes públicas e privadas
Uma rede é o conjunto de servidores da kolo-dht que se conhecem entre si, e um nó pertence à rede dos nós de entrada a partir dos quais faz bootstrap. O kolo-node não traz nenhuma lista de nós de entrada, e run precisa de uma destas:
-bootstrap host:port,...: nós de entrada separados por vírgulas; a flag pode ser repetida.-bootstrap-file caminho: um arquivo de texto com nós de entrada, umhost:portpor linha.#inicia um comentário até o fim da linha; linhas em branco são ignoradas; um BOM UTF-8 e finais de linha CRLF são aceitos. Só um arquivo regular de no máximo 64 KiB é lido: um diretório, um dispositivo ou um FIFO são recusados antes de serem abertos. A flag pode ser repetida e se soma a-bootstrap: primeiro as entradas de-bootstrap, depois as de cada arquivo em ordem, sem duplicatas, no máximo 16 no total.KOLO_BOOTSTRAP=host:port,...: só é lida quando nem-bootstrapnem-bootstrap-fileestão definidos (na linha de comando ou no arquivo de configuração, mesmo com uma lista vazia) e-firstnão está definido. UmaKOLO_BOOTSTRAPdefinida que não é lida registra o avisoKOLO_BOOTSTRAP ignored.-first: inicia uma rede nova, ainda sem nós de entrada. Não pode ser combinada com-bootstrapnem com-bootstrap-file.
Sem nenhuma delas, ou só com listas vazias, run sai com 2: uma lista deixada vazia por engano nunca inicia um nó solitário, e uma flag ou uma chave definida com uma lista vazia nunca recorre a KOLO_BOOTSTRAP. Um caminho relativo de -bootstrap-file, também no arquivo de configuração, é relativo ao diretório de trabalho do kolo-node, não ao arquivo de configuração; unidades do systemd devem usar caminhos absolutos. Cada elemento do array de configuração é uma entrada: um elemento com vírgula é recusado. O evento de log network informa o mode (first ou join), as entries listadas e, com join, de onde vieram (from: -bootstrap, -bootstrap-file ou KOLO_BOOTSTRAP).
Uma entrada é um endereço IPv4 ou um nome DNS, com uma porta de 1 a 65535. IPv6 em qualquer forma, incluindo IPv4-mapped, é recusado. Um arquivo de bootstrap:
# entry nodes of our network
203.0.113.10:7447
node2.example.org:7447 # resolved to IPv4 at each attemptUma rede pública é aquela cujos operadores publicam seus nós de entrada; os membros os listam. Uma rede privada roda os seus: inicie o primeiro nó com -first, os outros com -bootstrap (ou um arquivo) apontando para ele, e dê aos membros só esses endereços. Rode pelo menos dois nós de entrada em hosts que fiquem no ar, com a porta UDP aberta. Dois nós de uma rede privada no loopback:
dir=$(mktemp -d)
kolo-node run -listen 127.0.0.1:7447 -identity "$dir/a/node.key" -first
kolo-node run -listen 127.0.0.1:7448 -identity "$dir/b/node.key" -bootstrap 127.0.0.1:7447O que ela é: separação por topologia. Um servidor da kolo-dht só conhece outros servidores pelos servidores que consulta e pelos que lhe enviam requisições, então duas redes com nós de entrada diferentes nunca veem os servidores, os registros nem os peers uma da outra.
O que ela não é: controle de acesso. A lista não é um segredo. Quem descobrir um endereço de entrada pode fazer bootstrap a partir dele, buscar topics e anunciar neles, e um nó que lista nós de entrada de duas redes as junta. Decida quem pode se conectar com as chaves da kolo-secure e o Allow da kolo-swarm, admita membros com a kolo-invite e confie só em registros assinados.
run sem nós de entrada e sem -first sai com 2, então uma lista deixada vazia por engano nunca inicia um nó solitário; o mesmo vale para -bootstrap, -bootstrap-file ou a chave de configuração deles definidos com uma lista vazia. Dê ao primeiro nó -first, ou "first": true no arquivo de configuração, e a todos os outros nós -bootstrap, -bootstrap-file ou KOLO_BOOTSTRAP.
Rodar um relay
O kolo-node relay roda uma kolo-relay: peers que não conseguem se conectar diretamente, como dois computadores atrás de firewalls que só deixam passar tráfego de saída, fazem uma reserva nele e se encontram por ele. Cada lado roda a sua própria conexão kolo-secure através do relay, então ele copia bytes que não consegue ler. A kolo-swarm o usa quando a sua Config.Relays o lista. Um relay tem o próprio arquivo de chave e a própria porta UDP; um processo é um relay. No loopback, com a chave em um diretório temporário novo:
dir=$(mktemp -d)
kolo-node relay -listen 127.0.0.1:7448 -identity "$dir/relay/relay.key"Ele registra identity com a sua key e started com o seu addr. Os peers o listam como host:port@key, por exemplo 203.0.113.20:7448@<key> com a chave registrada. Confira em um segundo terminal com kolo-node check -relay 127.0.0.1:7448@<key>, que imprime ok relay 127.0.0.1:7448@<key>: o check pede ao relay uma chave aleatória com uma identidade nova, o que prova o endereço, a chave e o protocolo dele sem reservar nada.
Sem -allow-file o relay é aberto: qualquer chave pode fazer uma reserva e ser alcançada, às custas do operador, e 16 endereços conseguem ocupar as suas 64 reservas padrão, a 4 conexões por endereço; ele registra o aviso open relay. Com -allow-file path, só as chaves do arquivo podem fazer reserva: uma chave por linha, com 64 caracteres hexadecimais, comentários com #, linhas em branco ignoradas, um arquivo regular de no máximo 64 KiB, lido na inicialização. Um arquivo sem nenhuma chave é recusado. O check recebe relays de -relay (separados por vírgulas, repetível), de -relay-file (um por linha) ou de KOLO_RELAYS, no máximo 16 no total. Para os comandos de uma rede inteira, veja Rode a sua própria infraestrutura.
Rodar em uma VPS
Para rodar em uma VPS Linux com systemd (o README tem todos os passos):
- Instale a unit
deploy/kolo-node.service. Ela roda como um usuário de sistema estático comStateDirectoryMode=0700, que é obrigatório: a kolo-id recusa um diretório de chave que outros possam ler ou que seja um symlink. - O arquivo de configuração
/etc/kolo-node/config.jsonnão guarda nenhum segredo (modo 0644). Liste os outros nós de entrada da sua rede embootstrap, ou em um arquivo indicado porbootstrap-file. Usar a mesma lista em todos os nós é válido: um nó ignora o próprio endereço. O primeiro nó de uma rede nova ainda não tem lista: dê a ele"first": trueem vez debootstrap. - Aumente
net.core.rmem_maxenet.core.wmem_maxpara 7500000, para que o socket UDP receba os buffers que pede. - Abra a porta UDP 7447 no firewall do host e no firewall do provedor. Bloqueie novas entradas IPv6 e conecte-se ao host por IPv4.
- A unit define
MemoryMax=512MeGOMEMLIMIT=480MiB. O pior caso de heap ativo é de cerca de 416 MiB (um armazenamento de registros cheio mais as 16 conexões do listener que recusa). Aumente os dois junto com os limites de registros. - A saída 2 não reinicia o serviço (
RestartPreventExitStatus=2); as outras falhas reiniciam depois de 5s. RestrictAddressFamilies=AF_INET AF_UNIXtambém bloqueia DNS sobre IPv6, então em um host cujos servidores de nomes são todos IPv6, use IPs literais em-bootstrapou um resolvedor IPv4.- Verifique a porta a partir de outro computador com
kolo-node check 203.0.113.10:7447, em que203.0.113.10representa o endereço público.
Limites
- Só IPv4. Um endereço IPv6 em
-listen,-bootstrap,-bootstrap-file,KOLO_BOOTSTRAP,-relay,-relay-file,KOLO_RELAYSoucheck, incluindo as formas IPv4-mapped, é um erro de configuração (saída 2), e os nomes só são resolvidos para endereços IPv4. -listen::7447por padrão.-config: um único objeto JSON de no máximo 64 KiB. As chaves precisam bater exatamente e aparecer uma só vez; uma chave desconhecida, repetida ou com maiúsculas e minúsculas diferentes,null, um número que não seja inteiro ou qualquer coisa depois do objeto é um erro. As durações são strings como"30s".-bootstrap: entradashost:portseparadas por vírgulas (endereços IPv4 ou nomes DNS), repetível. Junto com-bootstrap-fileeKOLO_BOOTSTRAP, no máximo 16 entradas distintas no total. Um nome gera no máximo 8 endereços, e há no máximo 64 endereços de bootstrap no total. Cada nome é resolvido em até 5s, em paralelo, e depoisBootstraptem 30s.-bootstrap-file: um arquivo de texto de no máximo 64 KiB, umhost:portpor linha, repetível (no arquivo de configuração, um array de caminhos). 16 entradas da forma mais longa (um nome de 253 bytes, dois-pontos e uma porta de 5 dígitos) ocupam cerca de 4 KiB, e o resto deixa espaço para comentários.-first: falso por padrão; verdadeiro significa sem nós de entrada, e é recusado junto com-bootstrapou-bootstrap-file.KOLO_BOOTSTRAP: não definida por padrão; como-bootstrap, só é lida quando-bootstrap,-bootstrap-file(mesmo com uma lista vazia) e-firstestão todos sem definição.-stats-interval: 5m, de 1s a 24h (288 linhas por dia com o padrão).-log-formatétextoujson;-log-leveléinfo,warnouerror.- As flags
-dht-definem limites da kolo-dht. Deixadas em 0, cada uma assume o padrão da kolo-dht, e a kolo-dht verifica a faixa:-dht-max-records: 65536, de 16 a 1.000.000. Um armazenamento cheio ocupa cerca de 710 bytes de heap por registro, 44 MiB com o padrão.-dht-max-records-per-topic: 512, de 1 a 65536.-dht-max-records-per-ip: 256, de 1 a 65536.-dht-max-inflight: 160, de 8 a 4096, e no mínimo 75 com-bootstrap.-dht-max-relays: 64, de 1 a 4096.-dht-max-requests-per-ip: 50 por segundo, de 1 a 10.000.-dht-max-requests-per-prefix: 200 por segundo, ou-dht-max-requests-per-ip, se for maior, até 100.000.-dht-max-requests: 10.000 por segundo, ou o limite por prefixo, se for maior, até 1.000.000.-dht-request-timeout: 1s, de 100ms a 10s.-dht-punch-timeout: 45s, de 1s a 2m.
- Enquanto não tiver entrado na rede, o nó tenta de novo depois de 1 minuto, dobrando a espera a cada falha até 5 minutos. Depois de entrar, ele resolve os nomes e faz bootstrap de novo a cada 5 minutos enquanto a sua tabela tiver menos de 20 servidores.
- O encerramento tem 10s, e depois o processo sai com 1. Um segundo sinal durante o encerramento termina o processo na hora.
- Todas as conexões de entrada da kolo-secure são recusadas. O listener que recusa tem limite de 16 conexões, 16 pendentes, 1 conexão de saída, 1 stream de entrada e janelas de recepção de 64 KiB por stream e por conexão.
check: de 1 a 16 endereços,-timeoutde 5s por endereço, de 1s a 1m. Cada requisição espera no máximo metade de-timeout.check -relay,-relay-fileeKOLO_RELAYS: no máximo 16 relays distintos no total; uma chave em dois endereços ou um endereço com duas chaves sai com 2.relay -listenerelay -identitysão obrigatórios; nenhuma porta é atribuída à kolo-relay, então escolha uma.relay -allow-file: nenhum por padrão (um relay aberto), um arquivo de texto de no máximo 64 KiB com pelo menos uma chave.- As flags
-relay-definem limites da kolo-relay. Deixada em 0, cada uma fica com o padrão da kolo-relay, e a kolo-relay confere a faixa:-relay-max-reservations: 64, de 1 a 100000.-relay-max-sessions: 16, de 1 a 10000.-relay-max-sessions-per-peer: 4 e-relay-max-sessions-per-target: 8, ou-relay-max-sessions, se for menor.-relay-reservation-lifetimee-relay-max-session-duration: 1h, de 1s a 24h.-relay-max-session-bytes: 1 GiB em cada sentido, de 64 KiB a 1 TiB.-relay-session-idle-timeout: 60s, de 1s a 10m.-relay-connect-timeoute-relay-control-timeout: 15s, de 1s a 60s.-relay-rate-bytes: 1 MiB por segundo por conexão de cliente, de 16 KiB a 1 GiB.-relay-rate-burst: 256 KiB, de 16 KiB a 64 MiB.-relay-flush-interval: 1ms, de 100µs a 100ms.-relay-max-conns: 128, de 1 a 10000, e-relay-max-conns-per-ip: 4, ou-relay-max-conns, se for menor: os limites do listener. O limite de memória do listener sobe para (-relay-max-conns+ 1) × 256 KiB de janela de recepção quando isso passa de 1 GiB, cerca de 2,4 GiB com 10000.
Segurança
- Os logs nunca contêm a seed, o conteúdo de pacotes, topics, chaves de registros nem o endereço de um peer além da sua /24, a não ser que
-log-addrsesteja definido. Nada é registrado por pacote, então uma enxurrada de tráfego não consegue encher o disco. - Um nome DNS em
-bootstrapsó leva a endereços públicos, ou a endereços no escopo do endereço de escuta, então quem controla o nome não consegue apontar o nó para uma rede privada. Os endereços literais são usados do jeito que foram configurados. - O caminho do arquivo de configuração precisa apontar para um arquivo regular antes de ser aberto, então um dispositivo nunca é aberto.
- O arquivo de chave só é criado depois que o socket está aberto, então um erro de configuração ou de escuta não deixa nada no disco.
- O
relaynão registra nenhum endereço de peer nem nenhuma chave dos seus clientes. O que um relay ainda consegue saber está na página da kolo-relay. - O
runnunca leva tráfego de aplicação: o repasse é o comando separadorelay, com a própria chave e a própria porta.
Limites conhecidos
- A kolo-dht v0.1.x deriva o ID de DHT de um servidor a partir do seu IP e de uma escolha aleatória feita a cada início, e os seus PINGs não são autenticados. Assim, a chave estável identifica o nó do operador, mas nenhum peer a verifica.
- Não há endpoint HTTP. A saúde do nó aparece no evento
stats, e a alcançabilidade é testada de fora comkolo-node check, que usa o caminho UDP real. - O kolo-node é experimental. A linha de comando e o arquivo de configuração podem mudar antes da v1.0.0.
Erros
Este pacote não exporta variáveis de erro.
O kolo-node informa os erros por eventos de log e códigos de saída: 0 depois de SIGINT ou SIGTERM, quando tudo foi fechado; 1 se a identidade ou o socket não puderem ser configurados, ou se o encerramento falhar ou passar de 10s; 2 para um comando, uma flag, um arquivo de configuração ou um limite da kolo-dht inválido, para a falta de nós de entrada sem -first, e para um arquivo de chave ou um diretório de chave que a kolo-id recusa. check imprime ok ADDRESS ou failed ADDRESS: reason para cada endereço, depois ok relay ADDRESS@KEY ou failed relay ADDRESS@KEY: reason para cada relay, e só sai com 0 se todos os servidores e relays responderam.
Referências
- RFC 1123, Requirements for Internet Hosts - Application and Support (Internet Standard, October 1989).
- Usa: a verificação da sintaxe dos nomes de host (seção 2.1).