Un peer de anclaje mantiene tus logs disponibles mientras tus propios
dispositivos están desconectados. Guarda el texto cifrado y nunca recibe
las claves para leerlo. Esta guía compila el comando kolo-pin, lo ejecuta
en un VPS con Linux y ancla en él un log desde el ordenador de un
propietario. Consulta kolo-pin para ver la
biblioteca.
La guía usa 203.0.113.10 como dirección IPv4 pública del VPS. Usa en su
lugar la dirección de tu servidor.
1Compila el binario
En tu ordenador, dentro de la carpeta del código fuente de kolo-pin, compila un binario 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-pinGo no imprime nada y deja un archivo llamado kolo-pin. No necesita ningún
otro archivo en el servidor.
2Cópialo al VPS
Copia el binario a tu servidor:
scp kolo-pin user@203.0.113.10:Después, en el servidor, ponlo donde systemd pueda ejecutarlo:
sudo install -m 0755 kolo-pin /usr/local/bin/kolo-pin3Crea un usuario y una carpeta de datos
En el servidor, crea un usuario sin privilegios y una carpeta de datos privada para él:
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-pinLa carpeta tiene que ser privada (modo 0700). kolo-pin rechaza una a la que
otros puedan acceder, y guarda en ella su clave (identity.key, modo 0600)
y su almacén (store/).
4Imprime la clave del peer de anclaje
Los propietarios ponen esta clave en sus capacidades. La primera ejecución la crea, y no cambia entre reinicios:
sudo -u kolo-pin kolo-pin id -data /var/lib/kolo-pinImprime la clave pública en hexadecimal. La tuya será distinta:
d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a5Pruébalo antes por loopback
Solo con -data, kolo-pin escucha en 127.0.0.1:7450 y nadie de fuera del
servidor puede alcanzarlo. Arráncalo en primer plano:
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pinImprime tres líneas y sigue en marcha:
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=100000000000En una segunda sesión SSH en el servidor, pregunta al endpoint de salud:
curl http://127.0.0.1:7451/healthzokLa línea metrics es el endpoint de Prometheus, GET /metrics en
127.0.0.1:7452. Monitorizar un peer de anclaje
lo explica.
Pulsa Ctrl-C en la primera sesión. kolo-pin cierra su almacén, imprime
msg=stopped y sale con el código 0.
6Elige los flags
Cada flag tiene una variable de entorno, y un flag tiene prioridad sobre su variable:
| Flag | Entorno | Por defecto | Significado |
|---|---|---|---|
-data | KOLO_PIN_DATA | obligatorio | carpeta de datos: identity.key y el almacén |
-listen | KOLO_PIN_LISTEN | 127.0.0.1:7450 | dirección UDP para las conexiones de kolo-secure, IPv4 |
-max-bytes | KOLO_PIN_MAX_BYTES | 100GB | máximo de bytes guardados para todos los propietarios juntos; B, KB, MB, GB, TB, KiB, MiB, GiB, TiB |
-owners | KOLO_PIN_OWNERS | vacío | claves de propietario en hexadecimal, separadas por comas, que se aceptan; vacío acepta a cualquier propietario y registra una advertencia al arrancar |
-max-owners | KOLO_PIN_MAX_OWNERS | 100000 | máximo de registros de propietario guardados, uno por clave de propietario vista alguna vez; un propietario nuevo por encima del límite se rechaza (ErrOwnerLimit) |
-max-conns | KOLO_PIN_MAX_CONNS | 100 | máximo de conexiones a la vez, en handshake o abiertas; de 1 a 10000 |
-max-conns-per-ip | KOLO_PIN_MAX_CONNS_PER_IP | 4 | máximo de conexiones desde una misma dirección de origen, como mucho -max-conns; súbelo para propietarios detrás de un mismo NAT |
-add-timeout | KOLO_PIN_ADD_TIMEOUT | ninguno | máximo de tiempo que puede gastar un add, como 10m; pasado ese tiempo el add se rechaza como ocupado y se conserva lo guardado |
-health | KOLO_PIN_HEALTH | 127.0.0.1:7451 | dirección TCP de GET /healthz, u off |
-metrics | KOLO_PIN_METRICS | 127.0.0.1:7452 | dirección TCP de GET /metrics, u off |
-log-format | KOLO_PIN_LOG_FORMAT | text | text o json, en stderr |
-log-level | KOLO_PIN_LOG_LEVEL | info | debug, info, warn o error |
Elige -max-bytes según la RAM del servidor, además de su disco. Un log
abierto ocupa unos 250 bytes de memoria por entrada y lee los textos
cifrados del disco, y kolo-pin mantiene hasta 64 logs abiertos. Ese límite
cuenta logs, no entradas, así que en el peor caso 64 logs abiertos que
llenan -max-bytes con las entradas más pequeñas ocupan en memoria unas
0,42 veces -max-bytes: unos 40 GB con el valor por defecto de 100GB.
Cualquier peer que conozca sus claves de propietario e IDs de log puede
hacer que kolo-pin los abra.
Para que los propietarios puedan alcanzarlo, escucha en todas las direcciones IPv4 del servidor:
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pin -listen 0.0.0.0:7450O solo en la dirección pública del servidor:
sudo -u kolo-pin kolo-pin run -data /var/lib/kolo-pin -listen 203.0.113.10:7450Kolo solo usa IPv4. Una dirección IPv6, incluida la forma v4-mapped, se rechaza:
kolo-pin: address "[::1]:7450": IPv6 is not supported, use IPv4Un flag incorrecto sale con el código 2, también una dirección no válida en
-listen, -health o -metrics. Un fallo al arrancar, como un puerto ya
en uso, sale con el código 1. Si quitas a un propietario de -owners,
kolo-pin borra sus logs en el siguiente arranque y registra dropped con
el motivo owner not accepted.
7Abre el puerto UDP 7450
kolo-secure funciona sobre QUIC, que usa UDP, así que las reglas de TCP no sirven. Abre el puerto UDP 7450 para IPv4 en el cortafuegos del servidor, y en el cortafuegos de tu proveedor si tiene uno. Con ufw:
sudo ufw allow 7450/udpCon firewalld:
sudo firewall-cmd --permanent --add-port=7450/udp
sudo firewall-cmd --reloadDeja cerrados el puerto de salud 7451 y el de métricas 7452. Los dos solo responden en 127.0.0.1 y deben seguir siendo privados.
8Ejecútalo con systemd
Crea /etc/systemd/system/kolo-pin.service en el servidor. La
configuración va en variables de entorno:
[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 evita que systemd lo reinicie después de un
flag incorrecto. Añade Environment=KOLO_PIN_OWNERS=... con las claves de
tus propietarios para reservar el peer para ellos. Después, arráncalo y
sigue sus logs:
sudo systemctl daemon-reload
sudo systemctl enable --now kolo-pin
journalctl -u kolo-pin -fDeberías ver las líneas health, metrics y serving del paso 5, con addr igual a
la dirección en la que escuchas. systemctl stop kolo-pin envía SIGTERM, y
kolo-pin se detiene de forma limpia.
9Comprueba su salud
En el servidor:
curl http://127.0.0.1:7451/healthzokDesde tu ordenador, llega a él por un túnel SSH en lugar de abrir el puerto:
ssh -L 7451:127.0.0.1:7451 user@203.0.113.10Con el túnel abierto, pregúntale desde un segundo terminal de tu ordenador:
curl http://127.0.0.1:7451/healthzcurl.exe http://127.0.0.1:7451/healthzcurl http://127.0.0.1:7451/healthzResponde ok con el estado 200 mientras el peer está en marcha.
El endpoint de métricas del puerto 7452 funciona igual, con
ssh -L 7452:127.0.0.1:7452. Mantenlo también en local, y consulta
Monitorizar un peer de anclaje para
recoger sus métricas con Prometheus y configurar alertas.
10Da a los propietarios la clave y la dirección
Un propietario necesita dos cosas. La primera es la clave del paso 4:
sudo -u kolo-pin kolo-pin id -data /var/lib/kolo-pinLa segunda es la dirección: la dirección IPv4 pública del servidor y el
puerto UDP en el que escuchas, aquí 203.0.113.10:7450. Envía las dos al
propietario por un medio de confianza, porque un propietario que recibe una
clave equivocada no puede alcanzar el peer.
11Ancla un log desde el ordenador de un propietario
En el ordenador del propietario, dentro de un módulo de Go que requiera kolo-pin, kolo-id y kolo-store, este programa escribe un log pequeño, firma una capacidad para el peer de anclaje y le añade el log. Recibe como argumentos la clave y la dirección del peer de anclaje.
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))
}Ejecútalo con la clave y la dirección de tu peer de anclaje:
go run . d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a 203.0.113.10:7450Imprime la clave del propietario y después lo que tiene el peer de anclaje. Tus claves y tu ID de log serán distintos:
owner a8ad43ab31caffbc78a3ea089e39e493a0f0c82da7e8cfeb58c16a5cd7245380
pinned log 9b42c4ca: 4 entries, 2896 of 100000000 bytes used
status: 4 entries, kept until 2026-12-12Y el peer de anclaje registra la petición en sus logs:
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 ejecución se hizo por loopback, así que addr es 127.0.0.1; en un
VPS es la dirección IP y el puerto del propietario.
Vuelve a llamar a pin.Add después de añadir entradas o de borrar alguna;
así se pone al día el peer de anclaje. Este ejemplo crea una clave de
propietario nueva en cada ejecución, así que un peer con -owners
configurado la rechaza con pin: not authorized. Una aplicación real
guarda su clave de propietario con kolo-id, y el
operador incluye esa clave en la lista.
Qué ve el peer de anclaje
Ve qué claves de propietario e IDs de log aloja, cuántas entradas tienen y
cuánto ocupan, los registros firmados, cuándo crece cada log, cuándo se
borra algo de él o cuándo se hace pull de él y, en cada petición, la clave,
la dirección IP y los tiempos de quien la hace. Sus logs muestran parte de
esto, como en la línea pinned de arriba.
Nunca recibe una clave de entrada ni ningún texto en claro, así que no
puede leer las entradas. Cualquiera que conozca una clave de propietario y
un ID de log puede hacer pull del texto cifrado y de los registros desde
él, o pedir un rango de entradas con Fetch de kolo-sync, y saber los
mismos metadatos. Ninguna respuesta suya lleva una clave.
Límites y sus errores
Hay dos límites, cada uno con su propio error, y los dos se comprueban antes de guardar nada:
- La cuota del propietario que indica la capacidad (
Quota, 0 para ninguna). Si se supera,Adddevuelvepin: owner quota exceeded(ErrQuotaExceeded). - El total del peer para todos los propietarios (
-max-bytes, 100GB por defecto). Si se supera,Adddevuelvepin: pinning peer disk full(ErrDiskFull).
No se expulsa nada para hacer sitio, y los borrados siempre pasan. Los
bytes se cuentan como claves y valores guardados, no como bloques de disco,
así que deja espacio libre en el disco por encima de -max-bytes.
Una entrada tiene que caber en un mensaje de kolo-sync de 4 MiB como
máximo, con su registro y la sobrecarga del cifrado, o Add devuelve
pin: too large (ErrTooLarge). Una entrada de 4 MiB exactos ya es
demasiado grande, así que divide los archivos grandes en varias entradas.
Cuando una capacidad caduca (se comprueba cada minuto), o el propietario envía una nota de revocación, el peer de anclaje borra todos los logs de ese propietario.
El borrado es de mejor esfuerzo
El peer de anclaje aplica las marcas de borrado nuevas de un propietario
en el siguiente Add, a medida que kolo-sync se las entrega, y elimina sus
textos cifrados en esa misma escritura. Un peer
que no sigue el protocolo conserva lo que tiene, y los bloques antiguos del
disco pueden contener todavía bytes borrados. Como el peer de anclaje nunca
tuvo las claves de las entradas, de todos modos no podía leerlas. Consulta
Borrado.
Qué no se ha probado
Todas las ejecuciones de esta guía se hicieron en un solo ordenador, en
127.0.0.1: la compilación, kolo-pin id, kolo-pin run, los endpoints de
salud y de métricas y el programa del propietario. No se han probado un VPS real, un
NAT real, la unidad de systemd, los comandos del cortafuegos, los
comandos de Windows.
Siguientes pasos
- Lee la página de kolo-pin: su API, sus límites y sus errores.
- Vigílalo con Prometheus: Monitorizar un peer de anclaje.
- Guarda cada log en más de un peer de anclaje: Cómo elegir peers de anclaje.
- Consulta Réplicas para ver cómo se comprueba una copia de un log.