Módulos nativos (para programadores)

A utilização normal não requer módulos. Este guia destina-se a programadores e administradores que pretendem expandir o serviço Windows ou Linux através de bibliotecas nativas. Os módulos são executados dentro do serviço, com as permissões deste. Instale apenas código de confiança e mantenha os ficheiros dos módulos, dependências e configurações sob propriedade de um administrador.

Carregar módulos

O serviço lê os ficheiros *.conf no diretório modules.d junto do ficheiro de configuração. As localizações predefinidas são as seguintes.

Sistema operativo	Localização das configurações dos módulos	Formato da biblioteca
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

Em cada ficheiro, escreva o caminho absoluto de uma biblioteca por linha. Por exemplo, /etc/mudfish-dns/modules.d/10-policy.conf pode conter:

/usr/lib/mudfish-dns/modules/policy.so

Os ficheiros são lidos por ordem de nome e as linhas de cada ficheiro pela sua ordem. As linhas vazias e as que começam por # são ignoradas. Não coloque os caminhos entre aspas nem utilize variáveis de ambiente ou comentários no fim da linha: estas expressões não são interpretadas. No Windows, escreva também o caminho absoluto completo, incluindo os espaços que contenha.

Depois de adicionar, alterar ou remover um módulo, reinicie o serviço. No Linux, utilize o comando seguinte.

sudo systemctl restart mudfish-dns.service

No Windows, reinicie o serviço Mudfish DNS na gestão de serviços. As opções Iniciar DNS, Parar DNS e Aplicar configurações da aplicação não recarregam os módulos. O serviço não inicia se não conseguir ler o ficheiro de configuração, se um caminho for inválido ou se ocorrer um erro de carregamento ou inicialização. É permitido que o diretório de módulos não exista ou esteja vazio.

Durante o desenvolvimento, pode repetir o argumento --module para carregar bibliotecas pela ordem dos argumentos. Isto substitui o carregamento automático de modules.d. --config FILE também altera a localização do diretório de módulos junto do ficheiro de configuração. --restore-dns efetua a recuperação sem carregar módulos.

Implementar hooks

Leia Cabeçalho mudfish_dns_module.h ou descarregue mudfish_dns_module.h. Este cabeçalho define as estruturas, hooks, ações e regras de validade dos dados utilizados pelos módulos. Este guia utiliza C ABI v2. Exporte mudfish_dns_module_init_v2() e, antes de preencher os hooks, verifique MUDFISH_DNS_MODULE_ABI_V2 e o tamanho da estrutura recebida. Devolva 0 se a inicialização tiver sucesso.

Hook	Momento da chamada
on_dns_query	Depois de aceitar a consulta analisada, antes de consultar a cache ou a encaminhar.
on_dns_response	Depois de selecionar a resposta, antes de a guardar em cache ou devolver ao cliente. As respostas em cache também passam por este hook.
on_web_hello	Depois da inspeção inicial de HTTP Host/TLS SNI, antes de estabelecer a ligação ou processar os dados iniciais.
on_web_data	Depois de ler dados subsequentes do cliente ou dados do servidor, antes de os encaminhar.

Ações DNS

Os hooks DNS v2 devolvem 0 em caso de sucesso e definem result->action.

Ação	Efeito
MUDFISH_DNS_CONTINUE	Continua para o módulo seguinte e o processamento normal.
MUDFISH_DNS_ALLOW	Termina a cadeia de hooks atual e continua a consulta DNS normal ou devolve a resposta selecionada.
MUDFISH_DNS_BLOCK	Devolve REFUSED.
MUDFISH_DNS_DROP	Descarta a consulta sem enviar uma resposta DNS.
MUDFISH_DNS_ANSWER	Gera uma resposta com os endereços IPv4/IPv6 e o TTL fornecidos.
MUDFISH_DNS_REPLACE	Utiliza uma resposta DNS completa, em formato de rede, fornecida pelo módulo.

Não devolva diretamente constantes de ação a partir dos hooks DNS v2. Se a função devolver um valor diferente de 0 ou o resultado for inválido, ocorre SERVFAIL. ALLOW termina apenas a cadeia de hooks atual e não contorna regras de domínios, permissões de métodos de comunicação ou verificações de certificados. Exceto DROP, os resultados das consultas também passam pelos hooks de resposta.

Os hooks Web devolvem diretamente MUDFISH_DNS_CONTINUE ou MUDFISH_DNS_REJECT. Rejeitar um pedido Web termina a ligação. Para utilizar hooks Web, a proteção Web tem de estar ativada. Não é disponibilizado conteúdo HTTPS desencriptado.

Buffers, threads e cache

Os eventos e buffers de entrada são só de leitura e válidos apenas durante a execução do callback. As respostas de substituição devem utilizar memória pertencente ao módulo e manter-se válidas até ao próximo callback desse módulo ou ao seu encerramento. Não devolva memória da pilha nem ponteiros emprestados pelo evento. O ID DNS, o opcode e a pergunta da resposta de substituição devem corresponder à consulta original. Os callbacks de uma instância são executados sequencialmente, mas podem ser chamados por threads diferentes. Mantenha os callbacks curtos e não propague exceções através da fronteira ABI.

Os resultados gerados, substituídos, bloqueados ou descartados não são guardados na cache do anfitrião. Substituir uma resposta em cache não altera a entrada original. O anfitrião limpa o sinalizador AD das respostas de substituição e não efetua validação DNSSEC nem novas assinaturas. Os módulos que alteram dados assinados devem tratar as assinaturas invalidadas.

Exemplos e cabeçalho

As páginas abaixo contêm o código completo dos exemplos e o cabeçalho necessário. Não precisa de descarregar separadamente o código-fonte do Mudfish DNS.

Ficheiro	Conteúdo
policy.c — exemplo de política DNS	Permitir, bloquear e descartar consultas DNS, gerar respostas IP e alterar endereços e TTL das respostas. Inclui comandos de compilação e teste no Linux.
mudfish_dns_module.h — cabeçalho de módulos	Declarações ABI, assinaturas de hooks, constantes de ação e regras de propriedade dos buffers.

Antes de compilar, descarregue policy.c e mudfish_dns_module.h para o mesmo diretório. O comando de compilação do exemplo gera uma biblioteca Linux .so.