kolo docsbeta

Rode um peer de fixação em uma VPS

Um guia passo a passo. Compile o binário da kolo-pin, rode o binário em um servidor Linux com systemd e fixe nele um log a partir do computador de um dono.

Nesta página

Um peer de fixação mantém os seus logs disponíveis enquanto os seus próprios dispositivos estão offline. Ele guarda o texto cifrado e nunca recebe as chaves para lê-lo. Este guia compila o comando kolo-pin, roda o comando em uma VPS Linux e fixa nele um log a partir do computador de um dono. Veja kolo-pin para conhecer a biblioteca.

O guia usa 203.0.113.10 como o endereço IPv4 público da VPS. Use o endereço do seu próprio servidor no lugar dele.

1Compile o binário

No seu computador, na pasta do código-fonte da kolo-pin, compile um binário estático para Linux:

bash
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o kolo-pin ./cmd/kolo-pin

O Go não imprime nada e deixa um arquivo chamado kolo-pin. Ele não precisa de nenhum outro arquivo no servidor.

2Copie o binário para a VPS

Copie o binário para o seu servidor:

Terminal
scp kolo-pin user@203.0.113.10:

Depois, no servidor, coloque o binário em um lugar onde o systemd consiga rodá-lo:

bash
sudo install -m 0755 kolo-pin /usr/local/bin/kolo-pin

3Crie um usuário e uma pasta de dados

No servidor, crie um usuário sem privilégios e uma pasta de dados privada para ele:

bash
sudo useradd --system --home-dir /var/lib/kolo-pin --shell /usr/sbin/nologin kolo-pin
sudo install -d -m 0700 -o kolo-pin -g kolo-pin /var/lib/kolo-pin

A pasta precisa ser privada (modo 0700). A kolo-pin recusa uma pasta que outros possam acessar, e guarda nela a sua chave (identity.key, modo 0600) e o seu store (store/).

4Imprima a chave do peer de fixação

Os donos colocam essa chave nas suas capabilities. A primeira execução cria a chave, e ela continua a mesma entre reinícios:

bash
sudo -u kolo-pin kolo-pin id -data /var/lib/kolo-pin

Ele imprime a chave pública em hex. A sua vai ser diferente:

Texto
d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a

5Teste primeiro no loopback

Só com -data, a kolo-pin escuta em 127.0.0.1:7450, e ninguém de fora do servidor consegue alcançá-la. Inicie em primeiro plano:

bash
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pin

Ela imprime três linhas e continua rodando:

Texto
time=2026-11-12T08:16:33.990+07:00 level=INFO msg=health addr=127.0.0.1:7451
time=2026-11-12T08:16:33.990+07:00 level=INFO msg=metrics addr=127.0.0.1:7452
time=2026-11-12T08:16:34.041+07:00 level=INFO msg=serving key=d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a addr=127.0.0.1:7450 owners=0 used=0 max-bytes=100000000000

Em uma segunda sessão SSH no servidor, consulte o endpoint de health:

bash
curl http://127.0.0.1:7451/healthz
Texto
ok

A linha metrics é o endpoint do Prometheus, GET /metrics em 127.0.0.1:7452. Monitorar um peer de fixação explica como usá-lo.

Aperte Ctrl-C na primeira sessão. A kolo-pin fecha o seu store, imprime msg=stopped e sai com o código 0.

6Escolha as flags

Cada flag tem uma variável de ambiente, e a flag vale mais que a variável:

FlagAmbientePadrãoSignificado
-dataKOLO_PIN_DATAobrigatóriopasta de dados: identity.key e o store
-listenKOLO_PIN_LISTEN127.0.0.1:7450endereço UDP para as conexões da kolo-secure, IPv4
-max-bytesKOLO_PIN_MAX_BYTES100GBmáximo de bytes guardados para todos os donos juntos; B, KB, MB, GB, TB, KiB, MiB, GiB, TiB
-ownersKOLO_PIN_OWNERSvaziochaves de dono em hex, separadas por vírgula, a aceitar; vazio aceita qualquer dono e registra um aviso ao iniciar
-max-ownersKOLO_PIN_MAX_OWNERS100000máximo de registros de dono guardados, um por chave de dono já vista; um dono novo além do limite é recusado (ErrOwnerLimit)
-max-connsKOLO_PIN_MAX_CONNS100máximo de conexões ao mesmo tempo, em handshake ou abertas; de 1 a 10000
-max-conns-per-ipKOLO_PIN_MAX_CONNS_PER_IP4máximo de conexões de um mesmo endereço de origem, no máximo -max-conns; aumente para donos atrás de um mesmo NAT
-add-timeoutKOLO_PIN_ADD_TIMEOUTnenhummáximo de tempo que um add pode gastar, como 10m; passado esse tempo o add é recusado como ocupado e o que foi guardado é mantido
-healthKOLO_PIN_HEALTH127.0.0.1:7451endereço TCP de GET /healthz, ou off
-metricsKOLO_PIN_METRICS127.0.0.1:7452endereço TCP de GET /metrics, ou off
-log-formatKOLO_PIN_LOG_FORMATtexttext ou json, no stderr
-log-levelKOLO_PIN_LOG_LEVELinfodebug, info, warn ou error

Escolha -max-bytes pela RAM do servidor, além do disco. Um log aberto ocupa cerca de 250 bytes de memória por entrada e lê os textos cifrados do disco, e a kolo-pin mantém até 64 logs abertos. Esse limite conta logs, não entradas, então no pior caso 64 logs abertos que enchem -max-bytes com as menores entradas ocupam na memória cerca de 0,42 vez -max-bytes: cerca de 40 GB com o padrão de 100GB. Qualquer peer que conheça as chaves de dono e os IDs de log deles pode fazer a kolo-pin abri-los.

Para que os donos consigam alcançá-la, escute em todos os endereços IPv4 do servidor:

bash
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pin -listen 0.0.0.0:7450

Ou só no endereço público do servidor:

bash
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pin -listen 203.0.113.10:7450

O Kolo só aceita IPv4. Um endereço IPv6, incluindo a forma v4-mapped, é recusado:

Texto
kolo-pin: address "[::1]:7450": IPv6 is not supported, use IPv4

Uma flag inválida sai com o código 2, inclusive um endereço inválido em -listen, -health ou -metrics. Uma falha ao iniciar, como uma porta já em uso, sai com o código 1. Se você tirar um dono de -owners, a kolo-pin apaga os logs dele no próximo início e registra dropped com o motivo owner not accepted.

7Abra a porta UDP 7450

A kolo-secure roda sobre QUIC, que é UDP, então regras de TCP não ajudam. Abra a porta UDP 7450 para IPv4 no firewall do servidor, e no firewall do seu provedor, se ele tiver um. Com ufw:

bash
sudo ufw allow 7450/udp

Com firewalld:

bash
sudo firewall-cmd --permanent --add-port=7450/udp
sudo firewall-cmd --reload

Deixe a porta de health 7451 e a porta de métricas 7452 fechadas. As duas só respondem em 127.0.0.1 e devem continuar privadas.

8Rode com systemd

Crie /etc/systemd/system/kolo-pin.service no servidor. As configurações ficam em variáveis de ambiente:

/etc/systemd/system/kolo-pin.service
[Unit]
Description=kolo-pin pinning peer
After=network-online.target
Wants=network-online.target

[Service]
Type=exec
ExecStart=/usr/local/bin/kolo-pin run
Environment=KOLO_PIN_DATA=/var/lib/kolo-pin
Environment=KOLO_PIN_LISTEN=0.0.0.0:7450
Environment=KOLO_PIN_MAX_BYTES=100GB
Environment=KOLO_PIN_METRICS=127.0.0.1:7452
Restart=on-failure
RestartSec=5s
RestartPreventExitStatus=2
User=kolo-pin
Group=kolo-pin
UMask=0077
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/lib/kolo-pin
RestrictAddressFamilies=AF_INET AF_UNIX

[Install]
WantedBy=multi-user.target

RestartPreventExitStatus=2 impede o systemd de reiniciar o serviço depois de uma flag inválida. Adicione Environment=KOLO_PIN_OWNERS=... com as chaves dos seus donos para manter o peer só para eles. Depois inicie o serviço e acompanhe os logs:

bash
sudo systemctl daemon-reload
sudo systemctl enable --now kolo-pin
journalctl -u kolo-pin -f

Você deve ver as linhas health, metrics e serving do passo 5, com addr igual ao endereço em que você escuta. systemctl stop kolo-pin envia SIGTERM, e a kolo-pin para de forma limpa.

9Confira a saúde do serviço

No servidor:

bash
curl http://127.0.0.1:7451/healthz
Texto
ok

No seu computador, acesse o endpoint por um túnel SSH em vez de abrir a porta:

Terminal
ssh -L 7451:127.0.0.1:7451 user@203.0.113.10

Com o túnel aberto, consulte o endpoint de um segundo terminal no seu computador:

bash
curl http://127.0.0.1:7451/healthz

Ele responde ok com status 200 enquanto o peer está rodando.

O endpoint de métricas na porta 7452 funciona do mesmo jeito, com ssh -L 7452:127.0.0.1:7452. Mantenha-o local também, e veja Monitorar um peer de fixação para coletar as métricas com o Prometheus e configurar alertas.

10Passe a chave e o endereço para os donos

Um dono precisa de duas coisas. A primeira é a chave do passo 4:

bash
sudo -u kolo-pin kolo-pin id -data /var/lib/kolo-pin

A segunda é o endereço: o endereço IPv4 público do servidor e a porta UDP em que você escuta, aqui 203.0.113.10:7450. Envie os dois ao dono por um meio em que você confia, porque um dono que recebe uma chave errada não consegue alcançar o peer.

11Fixe um log a partir do computador de um dono

No computador do dono, em um módulo Go que depende da kolo-pin, da kolo-id e da kolo-store, este programa escreve um log pequeno, assina uma capability para o peer de fixação e adiciona o log a ele. Ele recebe a chave e o endereço do peer de fixação como argumentos.

main.go
package main

import (
	"context"
	"crypto/ed25519"
	"encoding/hex"
	"fmt"
	"log"
	"os"
	"time"

	koloid "github.com/ciranda-dev/kolo-id"
	"github.com/ciranda-dev/kolo-pin"
	kolostore "github.com/ciranda-dev/kolo-store"
)

func main() {
	if len(os.Args) != 3 {
		log.Fatal("usage: owner PEER-KEY IP:PORT")
	}
	key, err := hex.DecodeString(os.Args[1])
	if err != nil || len(key) != ed25519.PublicKeySize {
		log.Fatal("PEER-KEY must be 64 hex digits")
	}
	peer := pin.Peer{ID: key, Addr: os.Args[2]}
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	owner, err := koloid.Generate() // in memory only, a new owner each run
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("owner %x\n", owner.PublicKey())
	st := kolostore.New(kolostore.NewMemory())
	defer st.Close()
	l, err := st.Create(owner)
	if err != nil {
		log.Fatal(err)
	}
	for _, v := range []string{"hello", "from", "my", "laptop"} {
		if _, err := l.Append([]byte(v)); err != nil {
			log.Fatal(err)
		}
	}

	capability, err := pin.Issue(owner, pin.Capability{
		Peer:    peer.ID,
		Expires: time.Now().Add(30 * 24 * time.Hour),
		Quota:   100_000_000,
	})
	if err != nil {
		log.Fatal(err)
	}
	info, err := pin.Add(ctx, owner, peer, l, capability)
	if err != nil {
		log.Fatal(err)
	}
	logID := l.ID()
	fmt.Printf("pinned log %x: %d entries, %d of %d bytes used\n", logID[:4], info.Entries, info.Used, info.Quota)

	info, err = pin.Status(ctx, owner, peer, logID)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("status: %d entries, kept until %s\n", info.Entries, info.Expires.Format(time.DateOnly))
}

Rode o programa com a chave e o endereço do seu peer de fixação:

Terminal
go run . d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a 203.0.113.10:7450

Ele imprime a chave do dono e depois o que o peer de fixação guarda. As suas chaves e o seu ID de log vão ser diferentes:

Texto
owner a8ad43ab31caffbc78a3ea089e39e493a0f0c82da7e8cfeb58c16a5cd7245380
pinned log 9b42c4ca: 4 entries, 2896 of 100000000 bytes used
status: 4 entries, kept until 2026-12-12

E o peer de fixação registra a requisição no log:

Texto
time=2026-11-12T08:16:36.111+07:00 level=INFO msg=pinned op=add peer=a8ad43ab31caffbc78a3ea089e39e493a0f0c82da7e8cfeb58c16a5cd7245380 addr=127.0.0.1:52160 log=9b42c4caad2d363f2ce04dc7e8934f05c4abb44be9ba8b029cd8e67358c5b8e1 entries=4 used=2896

Esta execução foi no loopback, então addr é 127.0.0.1; em uma VPS, é o endereço IP e a porta do dono.

Chame pin.Add de novo depois de novas entradas ou exclusões; é assim que o peer de fixação se atualiza. Este exemplo cria uma chave de dono nova a cada execução, então um peer com -owners definido a recusa com pin: not authorized. Uma aplicação real guarda a sua chave de dono com a kolo-id, e o operador lista essa chave.

O que o peer de fixação vê

Ele vê quais chaves de dono e IDs de log ele hospeda, quantas entradas eles têm e os seus tamanhos, os registros assinados, quando cada log cresce, tem algo excluído ou é puxado, e, em cada requisição, a chave, o endereço IP e os tempos de quem fez a requisição. Os logs dele mostram parte disso, como na linha pinned acima.

Ele nunca recebe uma chave de entrada nem nenhum texto em claro, então não consegue ler as entradas. Qualquer um que conheça uma chave de dono e um ID de log pode puxar dele o texto cifrado e os registros, ou pedir um intervalo de entradas com Fetch da kolo-sync, e ficar sabendo dos mesmos metadados. Nenhuma resposta dele leva uma chave.

Limites e os seus erros

Dois limites, cada um com o seu próprio erro, os dois verificados antes de qualquer coisa ser guardada:

  • A cota do dono que vem na capability (Quota, 0 para nenhuma). Além dela, Add retorna pin: owner quota exceeded (ErrQuotaExceeded).
  • O total do peer para todos os donos (-max-bytes, 100GB por padrão). Além dele, Add retorna pin: pinning peer disk full (ErrDiskFull).

Nada é removido para abrir espaço, e as exclusões sempre passam. Os bytes são contados como chaves e valores guardados, não como blocos de disco, então deixe espaço livre no disco acima de -max-bytes.

Uma entrada precisa caber em uma única mensagem da kolo-sync de no máximo 4 MiB, com o seu registro e o custo extra da criptografia, senão Add retorna pin: too large (ErrTooLarge). Uma entrada de exatamente 4 MiB já é grande demais, então divida arquivos grandes em várias entradas.

Quando uma capability expira (isso é verificado a cada minuto), ou o dono envia uma nota de revogação, o peer de fixação exclui todos os logs desse dono.

A exclusão é de melhor esforço

O peer de fixação aplica os novos marcadores de exclusão de um dono no próximo Add, conforme a kolo-sync os entrega, e descarta os textos cifrados deles nessa mesma gravação. Um peer que não segue o protocolo guarda o que tem, e blocos de disco antigos ainda podem conter bytes excluídos. Como o peer de fixação nunca teve as chaves das entradas, ele não conseguiria ler essas entradas de qualquer forma. Veja Exclusão.

O que não foi testado

Todas as execuções por trás deste guia foram em um único computador, em 127.0.0.1: a compilação, kolo-pin id, kolo-pin run, os endpoints de health e de métricas e o programa do dono. Uma VPS real, um NAT real, a unit do systemd, os comandos de firewall, os comandos do Windows não foram testados.

Próximos passos