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:
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o kolo-pin ./cmd/kolo-pin$env:CGO_ENABLED="0"; $env:GOOS="linux"; $env:GOARCH="amd64"
go build -trimpath -o kolo-pin ./cmd/kolo-pinCGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o kolo-pin ./cmd/kolo-pinO 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:
scp kolo-pin user@203.0.113.10:Depois, no servidor, coloque o binário em um lugar onde o systemd consiga rodá-lo:
sudo install -m 0755 kolo-pin /usr/local/bin/kolo-pin3Crie 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:
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-pinA 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:
sudo -u kolo-pin kolo-pin id -data /var/lib/kolo-pinEle imprime a chave pública em hex. A sua vai ser diferente:
d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a5Teste 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:
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pinEla imprime três linhas e continua rodando:
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=100000000000Em uma segunda sessão SSH no servidor, consulte o endpoint de health:
curl http://127.0.0.1:7451/healthzokA 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:
| Flag | Ambiente | Padrão | Significado |
|---|---|---|---|
-data | KOLO_PIN_DATA | obrigatório | pasta de dados: identity.key e o store |
-listen | KOLO_PIN_LISTEN | 127.0.0.1:7450 | endereço UDP para as conexões da kolo-secure, IPv4 |
-max-bytes | KOLO_PIN_MAX_BYTES | 100GB | máximo de bytes guardados para todos os donos juntos; B, KB, MB, GB, TB, KiB, MiB, GiB, TiB |
-owners | KOLO_PIN_OWNERS | vazio | chaves de dono em hex, separadas por vírgula, a aceitar; vazio aceita qualquer dono e registra um aviso ao iniciar |
-max-owners | KOLO_PIN_MAX_OWNERS | 100000 | máximo de registros de dono guardados, um por chave de dono já vista; um dono novo além do limite é recusado (ErrOwnerLimit) |
-max-conns | KOLO_PIN_MAX_CONNS | 100 | máximo de conexões ao mesmo tempo, em handshake ou abertas; de 1 a 10000 |
-max-conns-per-ip | KOLO_PIN_MAX_CONNS_PER_IP | 4 | má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-timeout | KOLO_PIN_ADD_TIMEOUT | nenhum | máximo de tempo que um add pode gastar, como 10m; passado esse tempo o add é recusado como ocupado e o que foi guardado é mantido |
-health | KOLO_PIN_HEALTH | 127.0.0.1:7451 | endereço TCP de GET /healthz, ou off |
-metrics | KOLO_PIN_METRICS | 127.0.0.1:7452 | endereço TCP de GET /metrics, ou off |
-log-format | KOLO_PIN_LOG_FORMAT | text | text ou json, no stderr |
-log-level | KOLO_PIN_LOG_LEVEL | info | debug, 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:
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pin -listen 0.0.0.0:7450Ou só no endereço público do servidor:
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pin -listen 203.0.113.10:7450O Kolo só aceita IPv4. Um endereço IPv6, incluindo a forma v4-mapped, é recusado:
kolo-pin: address "[::1]:7450": IPv6 is not supported, use IPv4Uma 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:
sudo ufw allow 7450/udpCom firewalld:
sudo firewall-cmd --permanent --add-port=7450/udp
sudo firewall-cmd --reloadDeixe 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:
[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.targetRestartPreventExitStatus=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:
sudo systemctl daemon-reload
sudo systemctl enable --now kolo-pin
journalctl -u kolo-pin -fVocê 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:
curl http://127.0.0.1:7451/healthzokNo seu computador, acesse o endpoint por um túnel SSH em vez de abrir a porta:
ssh -L 7451:127.0.0.1:7451 user@203.0.113.10Com o túnel aberto, consulte o endpoint de um segundo terminal no seu computador:
curl http://127.0.0.1:7451/healthzcurl.exe http://127.0.0.1:7451/healthzcurl http://127.0.0.1:7451/healthzEle 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:
sudo -u kolo-pin kolo-pin id -data /var/lib/kolo-pinA 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.
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:
go run . d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a 203.0.113.10:7450Ele 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:
owner a8ad43ab31caffbc78a3ea089e39e493a0f0c82da7e8cfeb58c16a5cd7245380
pinned log 9b42c4ca: 4 entries, 2896 of 100000000 bytes used
status: 4 entries, kept until 2026-12-12E o peer de fixação registra a requisição no log:
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=2896Esta 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,Addretornapin: owner quota exceeded(ErrQuotaExceeded). - O total do peer para todos os donos (
-max-bytes, 100GB por padrão). Além dele,Addretornapin: 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
- Leia a página da kolo-pin: a API, os limites e os erros dela.
- Acompanhe o peer com o Prometheus: Monitorar um peer de fixação.
- Mantenha cada log em mais de um peer de fixação: Como escolher peers de fixação.
- Veja Réplicas para saber como uma cópia de um log é verificada.