kolo docsbeta

Ejecuta un peer de anclaje en un VPS

Una guía paso a paso. Compila el binario de kolo-pin, ejecútalo en un servidor Linux con systemd y ancla en él un log desde el ordenador de un propietario.

En esta página

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:

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

Go 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:

Terminal
scp kolo-pin user@203.0.113.10:

Después, en el servidor, ponlo donde systemd pueda ejecutarlo:

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

3Crea un usuario y una carpeta de datos

En el servidor, crea un usuario sin privilegios y una carpeta de datos privada para él:

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

La 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:

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

Imprime la clave pública en hexadecimal. La tuya será distinta:

Texto
d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a

5Prué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:

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

Imprime tres líneas y sigue en marcha:

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

En una segunda sesión SSH en el servidor, pregunta al endpoint de salud:

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

La 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:

FlagEntornoPor defectoSignificado
-dataKOLO_PIN_DATAobligatoriocarpeta de datos: identity.key y el almacén
-listenKOLO_PIN_LISTEN127.0.0.1:7450dirección UDP para las conexiones de kolo-secure, IPv4
-max-bytesKOLO_PIN_MAX_BYTES100GBmáximo de bytes guardados para todos los propietarios juntos; B, KB, MB, GB, TB, KiB, MiB, GiB, TiB
-ownersKOLO_PIN_OWNERSvacíoclaves de propietario en hexadecimal, separadas por comas, que se aceptan; vacío acepta a cualquier propietario y registra una advertencia al arrancar
-max-ownersKOLO_PIN_MAX_OWNERS100000má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-connsKOLO_PIN_MAX_CONNS100máximo de conexiones a la vez, en handshake o abiertas; de 1 a 10000
-max-conns-per-ipKOLO_PIN_MAX_CONNS_PER_IP4má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-timeoutKOLO_PIN_ADD_TIMEOUTningunomáximo de tiempo que puede gastar un add, como 10m; pasado ese tiempo el add se rechaza como ocupado y se conserva lo guardado
-healthKOLO_PIN_HEALTH127.0.0.1:7451dirección TCP de GET /healthz, u off
-metricsKOLO_PIN_METRICS127.0.0.1:7452dirección TCP de GET /metrics, u off
-log-formatKOLO_PIN_LOG_FORMATtexttext o json, en stderr
-log-levelKOLO_PIN_LOG_LEVELinfodebug, 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:

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

O solo en la dirección pública del servidor:

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

Kolo solo usa IPv4. Una dirección IPv6, incluida la forma v4-mapped, se rechaza:

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

Un 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:

bash
sudo ufw allow 7450/udp

Con firewalld:

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

Deja 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:

/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 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:

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

Deberí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:

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

Desde tu ordenador, llega a él por un túnel SSH en lugar de abrir el puerto:

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

Con el túnel abierto, pregúntale desde un segundo terminal de tu ordenador:

bash
curl http://127.0.0.1:7451/healthz

Responde 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:

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

La 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.

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))
}

Ejecútalo con la clave y la dirección de tu peer de anclaje:

Terminal
go run . d7fcc0e2d91c96ab1bf7bafa3b24be08ac9ad96de6bfc683df5b290051a1b79a 203.0.113.10:7450

Imprime la clave del propietario y después lo que tiene el peer de anclaje. Tus claves y tu ID de log serán distintos:

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

Y el peer de anclaje registra la petición en sus logs:

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 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, Add devuelve pin: owner quota exceeded (ErrQuotaExceeded).
  • El total del peer para todos los propietarios (-max-bytes, 100GB por defecto). Si se supera, Add devuelve pin: 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