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. Un redémarrage répare aussi les métadonnées de groupes stockées — les événements signés par l’ancienne clé sont supprimés et l’état actuel est republié sous la nouvelle clé (l’état des groupes lui-même est restauré tel quel, pas reconstruit). L’état des rôles NIP-43 (adhésions, rôles et codes d’invitation) est réparé de la même façon.
• livekit_participants_interval_secs — fréquence (en secondes) à laquelle le relais rafraîchit les listes de participants NIP-29 kind:39004 en appelant l’API LiveKit Room Service (ListParticipants) avec les identifiants configurés. Les webhooks LiveKit envoyés à /.well-known/nip29/livekit/webhook rafraîchissent immédiatement la liste d’un groupe ; le sondage réconcilie les événements manqués. Doit être au moins 1. Figé au démarrage — 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.
• landing_page_file — par défaut, un navigateur ouvrant l’URL du relais reçoit une page leurre intégrée qui ne révèle rien sur le relais. Pointez ceci vers un fichier HTML pour servir votre propre page (règles du relais, contact, statistiques) ; le document NIP-11 et les connexions WebSocket ne sont pas affectés. Le fichier est lu à la demande et relu lorsqu’il change, donc une tâche externe peut le régénérer sans redémarrage. Il doit être un fichier régulier d’au plus 8 MiB (les liens symboliques ne sont pas suivis) ; s’il manque, la page leurre est servie. S’applique au SIGHUP.
• assets_dir — répertoire dont les fichiers sont servis sous /assets/<name> (images, CSS, JS de la page d’accueil). Seuls des noms plats en ASCII (lettres, chiffres, ., _, -) sont servis (pas de fichiers cachés, sous-répertoires ni liens symboliques) ; les extensions inconnues sont envoyées en application/octet-stream. Les fichiers sont lus à chaque requête et peuvent donc être remplacés sur place. 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.

/relay/stats ne demande aucun jeton et est lisible en cross-origin, il sert donc une vue plus étroite que le fichier de statistiques : l’espace disque libre de l’hôte et l’indicateur de disque plein, les compteurs d’échecs (db_errors, accept_errors, rebuild_failures, log_errors) et la répartition des refus de connexion par motif sont omis — ensemble, ils constitueraient un oracle de capacité de stockage pour un sondeur anonyme. Ces clés restent dans le fichier de statistiques (nostrfy stats les affiche) et dans /metrics. Notez que /metrics n’est pas authentifié non plus : isolez-le (api_host ou reverse-proxy) si les chiffres de capacité doivent rester privés.

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.