Referencia de configuración

Conceptos básicos

La configuración es un archivo TOML, llamado por defecto nostrfy.toml. Créalo con init:

nostrfy --config nostrfy.toml init

Valídalo (recomendado antes de cada inicio):

nostrfy --config nostrfy.toml check

Cada comando acepta --config <path> (por defecto nostrfy.toml).

Sintaxis general:

[section]
key = "string"
key = 8080
key = [1, 2]
key = true

Secciones de configuración

Cada clave es opcional; una clave ausente usa su valor predeterminado.

Sección [relay] — identidad del relé

Detalles de claves

• private_key — la clave secreta propia del relé, usada para firmar eventos generados por el relé: metadatos de grupos NIP-29 (39000-39005) y eventos de rol/miembros NIP-43. Genérala con nostrfy genkey; mantenla en secreto. Se lee una vez al iniciar, por lo que cambiarla requiere reiniciar.
• public_url — se usa para validar etiquetas con URL de los clientes: AUTH NIP-42, vanish NIP-62 y auth de administración NIP-98. Cuando está vacía, el relé recurre a host:port, que nunca coincide con una URL real de cliente al enlazar 0.0.0.0 o 127.0.0.1 (se registra una advertencia). Configúrala siempre.
• enabled_nips frente a disabled_nips — la lista de permitidos gana: cuando enabled_nips no está vacío, solo se anuncian sus NIP y disabled_nips se ignora. Ambos requieren reinicio.
• reject_ephemeral — los kinds 20000-29999 se rechazan, pero los kinds exentos que los NIP exigen retransmitir siguen reenviándose: 22242, 27235, 28934/28935/28936, 24133, 23194/23195, 24242 y 21059. Se aplica con SIGHUP.
• enabled_git — NIP-34 opcional: acepta los kinds 1617-1633 y 30617/30618 y anuncia NIP-34. Desactivado por defecto porque los parches pueden ser grandes. Se aplica con SIGHUP.

Sección [server] — ajustes del servidor

Detalles de claves

• host — 0.0.0.0 enlaza todas las interfaces IPv4; 127.0.0.1 es solo local.
• port — 1-65535; el puerto 80 requiere root. Este único puerto sirve el relé WebSocket, el documento NIP-11, la API REST y el RPC NIP-86 juntos.
• api_host — dedica la API REST a un único nombre de host para que la API y el relé puedan compartir un puerto detrás de un proxy inverso. Fijo al iniciar — requiere reinicio.
• ws_paths — root sirve solo /, inbox-outbox sirve solo /inbox y /outbox, all sirve ambos. Fijo al iniciar — requiere reinicio.
• trusted_proxies — incluye solo las direcciones propias del proxy (loopback para nginx/Caddy en el mismo host, el rango de origen del balanceador en la nube). Con esta opción, la IP del cliente se deriva de la última entrada no confiable de X-Forwarded-For para los límites por IP, el límite de tasa, blockip y los registros. Nunca añadas una dirección accesible directamente por los clientes — podrían falsificar la cabecera y eludir los límites por IP. Fijo al iniciar — requiere reinicio.

Sección [rpc] — gestión NIP-86

El RPC NIP-86 está montado en las rutas públicas POST / del relé — no hay un puerto de gestión separado. management_token y admin_pubkey a veces aparecen bajo [server] en guías antiguas; esas grafías son alias heredados de estas claves [rpc].

Sección [limits] — límites y protecciones

Conexiones y mensajes

Suscripciones y consultas

Eventos

Alias heredados: limits.require_pow, limits.new_pubkey_min_age_secs y limits.max_indexed_words aún se aceptan como alias de relay.require_pow, relay.new_pubkey_min_age_secs y database.max_indexed_words.

API REST

Distribución en vivo

Sección [database] — base de datos

Detalles de claves

• map_size — el piso del mapa de memoria: el mapa siempre se abre al menos con este tamaño.
• max_map_size — el techo, abierto como reserva virtual dispersa: el disco físico solo crece con los datos realmente escritos. Auméntalo cuando veas database map is full.
• search_index = false — la búsqueda sigue funcionando (coincidencia de palabras completas contra el contenido) pero los escaneos son más lentos; en un VPS pequeño reduce la base de datos a la mitad. Recomendado en instancias pequeñas.
• disabled_fsync — cambia durabilidad por rendimiento: las escrituras se confirman en la caché de páginas del SO y un corte de energía puede perder las escrituras más recientes.

Sección [daemon] — demonio

Las rutas se resuelven respecto al directorio del archivo de configuración, por lo que siguen siendo válidas después de que el demonio cambie su directorio de trabajo.

Sección [access] — control de acceso

Las listas de pubkeys permitidas/denegadas no son claves de configuración — viven en la base de datos del relé (LMDB) y se gestionan en tiempo de ejecución:

nostrfy relay allow npub1...
nostrfy relay deny npub1...
nostrfy relay list

• restrict_relay = true — solo las pubkeys en lista permitida pueden publicar, mientras la lectura sigue abierta para todos (cualquier cliente aún puede suscribirse y obtener datos).
• Una pubkey denegada siempre se rechaza al publicar y nunca se sirve al leer.
• method_grants — concesiones de métodos NIP-86 para pubkeys no administradoras (pubkey → nombres de método, p. ej. un moderador con banevent y listbannedevents). Se siembran desde la configuración en la primera ejecución, luego se gestionan en tiempo de ejecución con assignmethod/unassignmethod de NIP-86 (inspeccionadas con listmethodassignees). Solo los métodos de moderación y lectura son delegables — la gestión de permisos, roles, invitaciones e identidad del relé sigue siendo solo de admin, y una pubkey baneada se rechaza incluso con concesiones. Ver la API de gestión.

Sección [blossom] — servidor de archivos Blossom

Recarga en caliente (SIGHUP)

Editar el archivo y enviar kill -HUP $(cat nostrfy.pid) recarga la configuración sin reiniciar. La mayoría de los ajustes surten efecto de inmediato; unos pocos están fijados al iniciar:

[access] no se aplica con una recarga — las listas se siembran una vez al iniciar y luego se gestionan en tiempo de ejecución vía NIP-86. El registro avisa cuando cambia un ajuste que requiere reinicio, y algunos ajustes capturados al iniciar no son comprobados por la recarga.