Referência de configuração

Conceitos básicos

A configuração é um arquivo TOML, por padrão chamado nostrfy.toml. Crie-o com init:

nostrfy --config nostrfy.toml init

Valide-o (recomendado antes de cada inicialização):

nostrfy --config nostrfy.toml check

Cada comando aceita --config <path> (padrão nostrfy.toml).

Sintaxe geral:

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

Seções de configuração

Cada chave é opcional; uma chave ausente usa seu valor padrão.

Seção [relay] — identidade do relay

Detalhes das chaves

• private_key — a chave secreta própria do relay, usada para assinar eventos gerados pelo relay: metadados de grupos NIP-29 (39000-39005) e eventos de função/membros NIP-43. Gere com nostrfy genkey; mantenha-a em segredo. Ela é lida uma vez na inicialização, portanto alterá-la exige reiniciar.
• public_url — usada para validar tags com URL dos clientes: AUTH NIP-42, vanish NIP-62 e auth de admin NIP-98. Quando vazia, o relay recorre a host:port, que nunca corresponde a uma URL real de cliente ao vincular 0.0.0.0 ou 127.0.0.1 (um aviso é registrado). Defina-a sempre.
• enabled_nips vs disabled_nips — a lista de permissão vence: quando enabled_nips não está vazio, apenas seus NIPs são anunciados e disabled_nips é ignorado. Ambos exigem reiniciar.
• reject_ephemeral — os kinds 20000-29999 são rejeitados, mas os kinds isentos que os NIPs exigem retransmitir ainda são encaminhados: 22242, 27235, 28934/28935/28936, 24133, 23194/23195, 24242 e 21059. Aplica-se com SIGHUP.
• enabled_git — NIP-34 opcional: aceita os kinds 1617-1633 e 30617/30618 e anuncia NIP-34. Desligado por padrão porque cargas de patch podem ser grandes. Aplica-se com SIGHUP.

Seção [server] — configurações do servidor

Detalhes das chaves

• host — 0.0.0.0 vincula todas as interfaces IPv4; 127.0.0.1 é somente local.
• port — 1-65535; a porta 80 exige root. Esta única porta serve o relay WebSocket, o documento NIP-11, a API REST e o RPC NIP-86 juntos.
• api_host — dedica a API REST a um único nome de host para que a API e o relay possam compartilhar uma porta atrás de um proxy reverso. Fixo na inicialização — exige reiniciar.
• ws_paths — root serve apenas /, inbox-outbox serve apenas /inbox e /outbox, all serve ambos. Fixo na inicialização — exige reiniciar.
• trusted_proxies — liste apenas os endereços próprios do proxy (loopback para nginx/Caddy no mesmo host, o intervalo de origem do balanceador na nuvem). Com ele definido, o IP do cliente é derivado da última entrada não confiável de X-Forwarded-For para os limites por IP, o limite de taxa, blockip e os logs. Nunca adicione um endereço que os clientes possam alcançar diretamente — eles poderiam falsificar o cabeçalho e contornar os limites por IP. Fixo na inicialização — exige reiniciar.

Seção [rpc] — gerenciamento NIP-86

O RPC NIP-86 é montado nas rotas públicas POST / do relay — não há porta de gerenciamento separada. management_token e admin_pubkey às vezes aparecem sob [server] em guias antigos; essas grafias são apelidos legados destas chaves [rpc].

Seção [limits] — limites e proteções

Conexões e mensagens

Assinaturas e consultas

Eventos

Apelidos legados: limits.require_pow, limits.new_pubkey_min_age_secs e limits.max_indexed_words ainda são aceitos como apelidos de relay.require_pow, relay.new_pubkey_min_age_secs e database.max_indexed_words.

API REST

Distribuição ao vivo

Seção [database] — banco de dados

Detalhes das chaves

• map_size — o mínimo do mapa de memória: o mapa é sempre aberto com pelo menos este tamanho.
• max_map_size — o máximo, aberto como reserva virtual esparsa: o disco físico só cresce com os dados realmente gravados. Aumente-o quando vir database map is full.
• search_index = false — a pesquisa continua funcionando (correspondência de palavras inteiras contra o conteúdo) mas as varreduras ficam mais lentas; em um VPS pequeno isso reduz o banco de dados pela metade. Recomendado em instâncias pequenas.
• disabled_fsync — troca durabilidade por taxa de transferência: as gravações são confirmadas no cache de páginas do SO e uma queda de energia pode perder as gravações mais recentes.

Seção [daemon] — daemon

Os caminhos são resolvidos em relação ao diretório do arquivo de configuração, portanto permanecem válidos depois que o daemon muda seu diretório de trabalho.

Seção [access] — controle de acesso

As listas de pubkeys permitidas/negadas não são chaves de configuração — elas vivem no banco de dados do relay (LMDB) e são gerenciadas em tempo de execução:

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

• restrict_relay = true — somente as pubkeys na lista de permissão podem publicar, enquanto a leitura permanece aberta a todos (qualquer cliente ainda pode assinar e buscar dados).
• Uma pubkey negada é sempre rejeitada ao publicar e nunca é servida ao ler.
• method_grants — concessões de métodos NIP-86 para pubkeys não admin (pubkey → nomes de método, ex. um moderador com banevent e listbannedevents). Semeadas a partir da configuração na primeira execução, depois gerenciadas em tempo de execução com assignmethod/unassignmethod do NIP-86 (inspecionadas com listmethodassignees). Somente métodos de moderação e leitura podem ser concedidos — o gerenciamento de permissões, funções, convites e identidade do relay permanece somente admin, e uma pubkey banida é recusada mesmo com concessões. Veja a API de gerenciamento.

Seção [blossom] — servidor de arquivos Blossom

Recarga a quente (SIGHUP)

Editar o arquivo e enviar kill -HUP $(cat nostrfy.pid) recarrega a configuração sem reiniciar. A maioria das configurações tem efeito imediato; algumas são fixas na inicialização:

[access] não é aplicado por recarga — as listas são semeadas uma vez na inicialização e depois gerenciadas em tempo de execução via NIP-86. O log avisa quando uma configuração que exige reiniciar muda, e algumas configurações capturadas na inicialização não são verificadas pela recarga.