Riferimento di configurazione

Nozioni di base

La configurazione è un file TOML, per impostazione predefinita chiamato nostrfy.toml. Crealo con init:

nostrfy --config nostrfy.toml init

Convalidalo (consigliato prima di ogni avvio):

nostrfy --config nostrfy.toml check

Ogni comando accetta --config <path> (predefinito nostrfy.toml).

Sintassi generale:

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

Sezioni di configurazione

Ogni chiave è facoltativa; una chiave mancante usa il suo valore predefinito.

Sezione [relay] — identità del relay

Dettagli delle chiavi

• private_key — la chiave segreta propria del relay, usata per firmare eventi generati dal relay: metadati dei gruppi NIP-29 (39000-39005) ed eventi di ruolo/membri NIP-43. Generala con nostrfy genkey; tienila segreta. Viene letta una volta all’avvio, quindi modificarla richiede un riavvio.
• public_url — usata per convalidare i tag con URL dai client: AUTH NIP-42, vanish NIP-62 e auth admin NIP-98. Quando è vuota, il relay ripiega su host:port, che non corrisponde mai a una URL reale del client quando si usa il binding 0.0.0.0 o 127.0.0.1 (viene registrato un avviso). Impostala sempre.
• enabled_nips vs disabled_nips — l’allowlist vince: quando enabled_nips non è vuoto, vengono annunciati solo i suoi NIP e disabled_nips viene ignorato. Entrambi richiedono un riavvio.
• reject_ephemeral — i kind 20000-29999 vengono rifiutati, ma i kind esenti che i NIP richiedono di inoltrare vengono comunque inoltrati: 22242, 27235, 28934/28935/28936, 24133, 23194/23195, 24242 e 21059. Si applica con SIGHUP.
• enabled_git — NIP-34 facoltativo: accetta i kind 1617-1633 e 30617/30618 e annuncia NIP-34. Disattivato per impostazione predefinita perché i payload delle patch possono essere grandi. Si applica con SIGHUP.

Sezione [server] — impostazioni del server

Dettagli delle chiavi

• host — 0.0.0.0 collega tutte le interfacce IPv4; 127.0.0.1 è solo locale.
• port — 1-65535; la porta 80 richiede root. Questa singola porta serve insieme il relay WebSocket, il documento NIP-11, l’API REST e l’RPC NIP-86.
• api_host — dedica l’API REST a un singolo hostname così API e relay possono condividere una porta dietro un reverse proxy. Fisso all’avvio — richiede un riavvio.
• ws_paths — root serve solo /, inbox-outbox serve solo /inbox e /outbox, all serve entrambi. Fisso all’avvio — richiede un riavvio.
• trusted_proxies — elenca solo gli indirizzi propri del proxy (loopback per nginx/Caddy sullo stesso host, l’intervallo di origine del bilanciatore nel cloud). Se impostato, l’IP del client è derivato dall’ultima voce non attendibile di X-Forwarded-For per i limiti per IP, il rate limit, blockip e i log. Non aggiungere mai un indirizzo raggiungibile direttamente dai client — potrebbero falsificare l’header e aggirare i limiti per IP. Fisso all’avvio — richiede un riavvio.

Sezione [rpc] — gestione NIP-86

L’RPC NIP-86 è montato sulle route pubbliche POST / del relay — non esiste una porta di gestione separata. management_token e admin_pubkey a volte compaiono sotto [server] nelle vecchie guide; quelle grafie sono alias legacy di queste chiavi [rpc].

Sezione [limits] — limiti e protezioni

Connessioni e messaggi

Sottoscrizioni e query

Eventi

Alias legacy: limits.require_pow, limits.new_pubkey_min_age_secs e limits.max_indexed_words sono ancora accettati come alias di relay.require_pow, relay.new_pubkey_min_age_secs e database.max_indexed_words.

API REST

Fan-out live

Sezione [database] — database

Dettagli delle chiavi

• map_size — la base della mappa di memoria: la mappa viene sempre aperta almeno con questa dimensione.
• max_map_size — il tetto, aperto come prenotazione virtuale sparsa: il disco fisico cresce solo con i dati effettivamente scritti. Aumentalo quando vedi database map is full.
• search_index = false — la ricerca funziona ancora (corrispondenza di parole intere contro il contenuto) ma le scansioni sono più lente; su un piccolo VPS dimezza il database. Consigliato su istanze piccole.
• disabled_fsync — scambia durabilità per throughput: le scritture vengono confermate nella page cache del SO e una perdita di alimentazione può perdere le scritture più recenti.

Sezione [daemon] — demone

I percorsi sono risolti rispetto alla directory del file di configurazione, quindi restano validi dopo che il demone cambia la sua directory di lavoro.

Sezione [access] — controllo degli accessi

Gli elenchi allow/deny delle pubkey non sono chiavi di configurazione — vivono nel database del relay (LMDB) e sono gestiti a runtime:

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

• restrict_relay = true — solo le pubkey in allowlist possono pubblicare, mentre la lettura resta aperta a tutti (qualsiasi client può ancora sottoscrivere e recuperare dati).
• Una pubkey negata viene sempre rifiutata in pubblicazione e mai servita in lettura.
• method_grants — concessioni di metodi NIP-86 per pubkey non admin (pubkey → nomi di metodo, es. un moderatore con banevent e listbannedevents). Inizializzate dalla configurazione alla prima esecuzione, poi gestite a runtime con assignmethod/unassignmethod di NIP-86 (ispezionate con listmethodassignees). Solo i metodi di moderazione e lettura sono delegabili — la gestione di permessi, ruoli, inviti e identità del relay resta solo admin, e una pubkey bannata viene rifiutata anche con concessioni. Vedi l'API di gestione.

Sezione [blossom] — server di file Blossom

Ricarica a runtime (SIGHUP)

Modificare il file e inviare kill -HUP $(cat nostrfy.pid) ricarica la configurazione senza riavvio. La maggior parte delle impostazioni ha effetto immediato; alcune sono fisse all’avvio:

[access] non viene applicato da una ricarica — gli elenchi vengono inizializzati una volta all’avvio e poi gestiti a runtime via NIP-86. Il log avvisa quando cambia un’impostazione che richiede il riavvio, e alcune impostazioni acquisite all’avvio non sono verificate dalla ricarica.