Référence de configuration

Bases

La configuration est un fichier TOML, par défaut nommé nostrfy.toml. Créez-le avec init :

nostrfy --config nostrfy.toml init

Validez-le (recommandé avant chaque démarrage) :

nostrfy --config nostrfy.toml check

Chaque commande accepte --config <path> (par défaut nostrfy.toml).

Syntaxe générale :

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

Sections de configuration

Chaque clé est optionnelle ; une clé manquante utilise sa valeur par défaut.

Section [relay] — identité du relais

Détails des clés

• private_key — clé secrète propre au relais, utilisée pour signer les événements générés par le relais : métadonnées de groupes NIP-29 (39000–39005) et événements de rôles/membres NIP-43. Générez-la avec nostrfy genkey ; gardez-la secrète. Elle est lue une fois au démarrage, donc toute modification exige un redémarrage.
• public_url — utilisée pour valider les tags porteurs d’URL des clients : AUTH NIP-42, vanish NIP-62 et auth admin NIP-98. Quand elle est vide, le relais se replie sur host:port, qui ne correspond jamais à une vraie URL client lors de la liaison à 0.0.0.0 ou 127.0.0.1 (un avertissement est journalisé). Définissez-la toujours.
• enabled_nips vs disabled_nips — la liste d’autorisation l’emporte : quand enabled_nips est non vide, seuls ses NIPs sont annoncés et disabled_nips est ignoré. Les deux exigent un redémarrage.
• reject_ephemeral — les kinds 20000–29999 sont rejetés, mais les kinds exemptés que les NIPs exigent de relayer sont toujours transmis : 22242, 27235, 28934/28935/28936, 24133, 23194/23195, 24242 et 21059. S’applique sur SIGHUP.
• enabled_git — opt-in NIP-34 : accepte les kinds 1617–1633 et 30617/30618 et annonce NIP-34. Désactivé par défaut car les charges de patch peuvent être volumineuses. S’applique sur SIGHUP.

Section [server] — paramètres serveur

Détails des clés

• host — 0.0.0.0 lie toutes les interfaces IPv4 ; 127.0.0.1 est local uniquement.
• port — 1–65535 ; le port 80 exige root. Ce port unique sert ensemble le relais WebSocket, le document NIP-11, l’API REST et le RPC NIP-86.
• api_host — dédie l’API REST à un seul nom d’hôte pour que l’API et le relais puissent partager un port derrière un reverse-proxy. Figé au démarrage — exige un redémarrage.
• ws_paths — root sert uniquement /, inbox-outbox sert uniquement /inbox et /outbox, all sert les deux. Figé au démarrage — exige un redémarrage.
• trusted_proxies — listez uniquement les propres adresses du proxy (loopback pour nginx/Caddy sur le même hôte, plage source de l’équilibreur dans le cloud). Si défini, l’IP client est dérivée de la dernière entrée X-Forwarded-For non de confiance pour les plafonds par IP, la limite de débit, blockip et les logs. N’ajoutez jamais une adresse joignable directement par les clients — ils pourraient falsifier l’en-tête et contourner les limites par IP. Figé au démarrage — exige un redémarrage.

Section [rpc] — gestion NIP-86

Le RPC NIP-86 est monté sur les routes publiques POST / du relais — il n’y a pas de port de gestion séparé. management_token et admin_pubkey apparaissent parfois sous [server] dans les anciens guides ; ces orthographes sont des alias historiques de ces clés [rpc].

Section [limits] — limites et protections

Connexions et messages

Abonnements et requêtes

Événements

Alias historiques : limits.require_pow, limits.new_pubkey_min_age_secs et limits.max_indexed_words sont toujours acceptés comme alias de relay.require_pow, relay.new_pubkey_min_age_secs et database.max_indexed_words.

API REST

Diffusion live

Section [database] — base de données

Détails des clés

• map_size — le plancher pour le memory map : la map est toujours ouverte au moins à cette taille.
• max_map_size — le plafond, ouvert comme réservation virtuelle éparse : le disque physique ne croît qu’avec les données réellement écrites. Augmentez-le en cas de database map is full.
• search_index = false — la recherche fonctionne toujours (correspondance de mots entiers dans le contenu) mais les scans sont plus lents ; sur un petit VPS cela divise la base par deux. Recommandé sur les petites instances.
• disabled_fsync — échange la durabilité contre le débit : les écritures sont validées dans le cache de pages OS et une coupure de courant peut perdre les écritures les plus récentes.

Section [daemon] — démon

Les chemins sont résolus par rapport au répertoire du fichier de configuration, donc ils restent valides après que le démon change son répertoire de travail.

Section [access] — contrôle d’accès

Les listes d’autorisation/refus de pubkeys ne sont pas des clés de config — elles vivent dans la base du relais (LMDB) et sont gérées à l’exécution :

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

• restrict_relay = true — seules les pubkeys autorisées peuvent publier, tandis que la lecture reste ouverte à tous (tout client peut toujours s’abonner et récupérer).
• Une pubkey refusée est toujours rejetée à la publication et jamais servie à la lecture.
• method_grants — octrois de méthodes NIP-86 pour les pubkeys non-admin (pubkey → noms de méthodes, p. ex. un modérateur autorisé avec banevent et listbannedevents). Initialisés depuis la config au premier lancement, puis gérés à l’exécution avec NIP-86 assignmethod/unassignmethod (inspectés avec listmethodassignees). Seules les méthodes de modération et de lecture sont octroyables — la gestion des permissions, rôles, revendications d’invitation et identité du relais reste réservée à l’admin, et une pubkey bannie est refusée même avec des octrois. Voir l' API de gestion.

Section [blossom] — serveur de fichiers Blossom

Rechargement à l’exécution (SIGHUP)

Modifier le fichier et envoyer kill -HUP $(cat nostrfy.pid) recharge la configuration sans redémarrage. La plupart des réglages prennent effet immédiatement ; quelques-uns sont figés au démarrage :

[access] n’est pas appliqué par un rechargement — les listes sont initialisées une fois au démarrage puis gérées à l’exécution via NIP-86. Le log avertit quand un réglage exigeant un redémarrage a changé, et quelques réglages capturés au démarrage ne sont pas vérifiés par le rechargement.