# ACME Fornece recuperação automática de certificados usando o [protocolo ACME](https://datatracker.ietf.org/doc/html/rfc8555). Ao [compilar a partir do código-fonte](https://pt.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), o módulo não é compilado por padrão; ele deve ser habilitado com a [opção de compilação](https://pt.angie.software//angie/docs/installation/sourcebuild.md#configure) `--with-http_acme_module`. Em pacotes e imagens de [nossos repositórios](https://pt.angie.software//angie/docs/installation/index.md#install-packages), o módulo está incluído na compilação. ## Exemplo de Configuração Exemplos de configuração e instruções de instalação podem ser encontrados na seção [Configuração ACME](https://pt.angie.software//angie/docs/configuration/acme.md#acme-config). ## Diretivas ### acme | [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme` name; | |-------------------------------------------------------------------------------------------|----------------| | Padrão | — | | [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | server | Para todos os domínios especificados nas diretivas [server_name](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#server-name) em todos os blocos [server](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#server) que referenciam o [cliente ACME](#acme-client) com o name fornecido, um único certificado será obtido; se a configuração `server_name` mudar, o certificado será renovado para refletir as mudanças. Cada vez que o Angie inicia, novos certificados são solicitados para todos os domínios que não possuem um certificado válido. Possíveis razões incluem expiração do certificado, arquivos ausentes ou ilegíveis, e mudanças nas configurações do certificado. #### NOTE Esta diretiva controla apenas quais nomes de domínio são incluídos nas solicitações de certificado; ela não afeta onde o certificado pode ser usado. Qualquer bloco `server` pode referenciar o certificado através da variável [$acme_cert_](#v-acme-cert-name), independentemente de o bloco conter ou não uma diretiva `acme`. Remover `acme` de um bloco `server` simplesmente exclui os valores de [server_name](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#server-name) desse bloco das futuras solicitações de certificado, mas não impede que o bloco use o certificado. #### NOTE Atualmente, domínios especificados com expressões regulares não são suportados e serão ignorados. Domínios curinga são suportados apenas com `challenge=dns` em `acme_client`. Esta diretiva pode ser especificada múltiplas vezes para carregar certificados de diferentes tipos, por exemplo RSA e ECDSA: ```nginx server { listen 443 ssl; server_name example.com www.example.com; ssl_certificate $acme_cert_rsa; ssl_certificate_key $acme_cert_key_rsa; ssl_certificate $acme_cert_ecdsa; ssl_certificate_key $acme_cert_key_ecdsa; acme rsa; acme ecdsa; } ``` ### acme_client | [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_client` name uri [`enabled=``on` | `off`] [`key_type=`type] [`key_bits=`number] [`email=`email] [`max_cert_size=`number] [`renew_before_expiry=`time] [`renew_on_load`] [`retry_after_error=`off|time] [`challenge=``dns` | `http` | `alpn`] [`account_key=`file]; | |-------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Padrão | — | | [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Define um cliente ACME com um name globalmente único. Ele deve ser válido para um diretório, é uma string com variáveis, e será usado sem distinção entre maiúsculas e minúsculas. O segundo parâmetro obrigatório é o uri do diretório ACME. Por exemplo, o URI do diretório ACME do Let's Encrypt é [especificado](https://letsencrypt.org/getting-started/) como [https://acme-v02.api.letsencrypt.org/directory](https://acme-v02.api.letsencrypt.org/directory). #### NOTE O módulo ACME adiciona um `location @acme` nomeado ao contexto do [cliente](#acme-client), que pode ser usado para configurar solicitações ao diretório ACME; por padrão, este `location` contém uma diretiva [proxy_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) com o uri do diretório, ao qual outras configurações do módulo [Proxy](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) podem ser adicionadas. Para que esta diretiva funcione, um [resolver](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#resolver) deve ser configurado no mesmo contexto. #### NOTE Para fins de teste, as autoridades certificadoras geralmente fornecem ambientes de teste separados. Por exemplo, o [ambiente de teste do Let's Encrypt](https://letsencrypt.org/docs/staging-environment/) é [https://acme-staging-v02.api.letsencrypt.org/directory](https://acme-staging-v02.api.letsencrypt.org/directory). | `enabled` | Habilita ou desabilita a renovação de certificados para o cliente;
isso é útil, por exemplo, para suspender temporariamente
sem remover o cliente da configuração.

Padrão: `on`. | |-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `key_type` | O tipo de algoritmo de chave privada para o certificado.
Valores válidos: `rsa`, `ecdsa`.

Padrão: `ecdsa`. | | `key_bits` | Número de bits na chave do certificado.
Padrão: 256 para `ecdsa`, 2048 para `rsa`. | | `email` | Endereço de email opcional para feedback;
usado ao criar uma conta no servidor da CA. | | `max_cert_size` | Especifica o tamanho máximo permitido de um novo arquivo de certificado em bytes
para reservar espaço para o novo certificado na memória compartilhada;
quanto mais domínios o certificado for solicitado,
mais espaço será necessário.
Este parâmetro não limita o tamanho das respostas do servidor ACME;
use [acme_max_response_size](#acme-max-response-size) para isso.

Se o parâmetro não for definido, o Angie calcula um tamanho aproximado
com base na lista de domínios configurada e o usa para alocação
de memória compartilhada.

Se um certificado já existir na inicialização mas seu tamanho exceder o
valor `max_cert_size`, o valor `max_cert_size` é
aumentado dinamicamente para corresponder ao tamanho do arquivo de certificado
existente.

Se o tamanho de um certificado obtido durante a renovação
exceder `max_cert_size`,
o processo de renovação falhará com um erro.

Padrão: calculado automaticamente. | | `renew_before_expiry` | [Tempo](https://pt.angie.software//angie/docs/configuration/configfile.md#syntax) antes da expiração do certificado
quando a renovação deve começar.

Padrão: `30d`. | | `renew_on_load` | Especifica que o certificado deve ser renovado forçadamente
cada vez que a configuração for carregada. | | `retry_after_error` | [Tempo](https://pt.angie.software//angie/docs/configuration/configfile.md#syntax) para aguardar antes de tentar novamente
se a recuperação do certificado falhar.
Se definido como `off`,
o cliente não tentará obter o certificado novamente após um erro.

Padrão: `2h`. | | `challenge` | Especifica o tipo de verificação para o cliente ACME.
Valores válidos: `dns`, `http`, `alpn`.

O valor `alpn` habilita a validação [TLS-ALPN-01](https://datatracker.ietf.org/doc/rfc8737/) e requer
que o Angie seja compilado com OpenSSL que suporte ALPN
(não suportado com compilações BoringSSL ou AWS-LC).

Padrão: `http`. | | `account_key` | Especifica o caminho completo para um arquivo contendo uma chave em formato PEM.
Isso é útil se você quiser usar uma chave de conta existente
em vez de geração automática,
ou se precisar usar uma chave para múltiplos clientes ACME.

Tipos de chave suportados:

- Chaves RSA com comprimentos que são múltiplos de 8, variando de 2048 a 8192 bits.
- Chaves ECDSA com comprimentos de 256, 384 ou 521 bits.

Ao especificar o parâmetro `account_key`,
certifique-se de que o arquivo de chave realmente existe.
Se o arquivo estiver ausente,
o Angie tentará criá-lo no caminho especificado.

Note que as chaves para clientes ACME são criadas na ordem
em que os clientes correspondentes são mencionados na configuração
nas diretivas [acme_client](#acme-client), [acme](#id1) ou [acme_hook](#acme-hook).
Portanto, se um cliente deve usar uma chave
criada para outro,
esse outro cliente deve aparecer antes na configuração.

Além disso, as chaves são criadas apenas para clientes
que têm o parâmetro `enabled=on` definido. | ### acme_max_response_size | [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_max_response_size` size; | |-------------------------------------------------------------------------------------------|----------------------------------| | Padrão | `acme_max_response_size 32k;` | | [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Limita o tamanho máximo do corpo de uma resposta do servidor ACME. Se uma resposta exceder este limite, a solicitação falhará com um erro. Aumente o valor se você ver erros como `too big subrequest response while sending to client`. ### acme_client_path | [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_client_path` path; | |-------------------------------------------------------------------------------------------|----------------------------| | Padrão | — | | [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Substitui o path para o diretório de armazenamento de certificados e chaves, definido durante a compilação usando o [parâmetro de compilação](https://pt.angie.software//angie/docs/installation/sourcebuild.md#configure) `--http-acme-client-path`. ### acme_dns_port | [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_dns_port` port | ip[:port] | [ip6][:port]; | |-------------------------------------------------------------------------------------------|----------------------------------------------------| | Padrão | `acme_dns_port 53;` | | [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Especifica a porta que o módulo usa para lidar com consultas DNS do servidor ACME sobre UDP. O número da porta deve estar no intervalo de 1 a 65535. Especificar um endereço IP junto com uma porta opcional também é suportado. Tanto endereços IPv4 na forma `ip:port` quanto endereços IPv6 na forma `[ip6]:port` podem ser usados: ```nginx acme_dns_port 8053; acme_dns_port 127.0.0.1; acme_dns_port [::1]; ``` Para usar o número de porta 1024 ou inferior, o Angie deve executar com privilégios de [superusuário](https://pt.angie.software//angie/docs/configuration/modules/core.md#user). ### acme_http_port | [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_http_port` port | ip[:port] | [ip6][:port]; | |-------------------------------------------------------------------------------------------|-----------------------------------------------------| | Padrão | `acme_http_port 80;` | | [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | http | Especifica a porta que o módulo usa para lidar com solicitações de desafio ACME HTTP. O número da porta deve estar no intervalo de 1 a 65535. Especificar um endereço IP junto com uma porta opcional também é suportado. Tanto endereços IPv4 na forma `ip:port` quanto endereços IPv6 na forma `[ip6]:port` podem ser usados: ```nginx acme_http_port 8080; acme_http_port 127.0.0.1; acme_http_port [::1]; ``` Se nenhum servidor estiver configurado para escutar no endereço e porta especificados, o módulo cria um listener dedicado para desafios HTTP. Para usar o número de porta 1024 ou inferior, o Angie deve executar com privilégios de [superusuário](https://pt.angie.software//angie/docs/configuration/modules/core.md#user). ### acme_hook | [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_hook` name [uri]; | |-------------------------------------------------------------------------------------------|---------------------------| | Padrão | — | | [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile) | location | Habilita a validação de domínio baseada em hooks para o [cliente ACME](#acme-client) especificado por name. Quando a emissão ou renovação de certificado requer verificação de domínio, o Angie gera uma solicitação interna para o `location` nomeado onde esta diretiva está colocada. Como a solicitação é tratada depende inteiramente das outras diretivas configuradas no mesmo `location`, como [fastcgi_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass), [proxy_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), ou qualquer outro manipulador de solicitações. | name | O nome do [cliente ACME](#acme-client)
para o qual este hook trata a verificação de domínio. | |--------|------------------------------------------------------------------------------------------------------------| | uri | Uma string com variáveis;
especifica a URI de solicitação para chamadas de hook.

Padrão: `/`. | Por exemplo, a seguinte configuração passa os valores das [variáveis de hook](#http-acme-variables) para uma aplicação FastCGI através da URI de solicitação: ```nginx acme_hook example uri=/acme_hook/$acme_hook_name?domain=$acme_hook_domain&key=$acme_hook_keyauth; fastcgi_param REQUEST_URI $request_uri; fastcgi_pass ...; ``` ## Variáveis Integradas ### `$acme_cert_` Conteúdo do último arquivo de certificado (se houver) obtido pelo cliente com este name. ### `$acme_cert_key_` Conteúdo do arquivo de chave do certificado usado pelo cliente com este name. #### NOTE O arquivo de certificado está disponível apenas se o cliente ACME tiver obtido pelo menos um certificado, mas o arquivo de chave está disponível imediatamente após a inicialização. ### `$acme_hook_challenge` O tipo de desafio. Valores possíveis: `dns`, `http`, `alpn`. ### `$acme_hook_client` O nome do cliente ACME que inicia a solicitação. ### `$acme_hook_domain` O domínio sendo verificado. Se for um domínio curinga, será passado sem o prefixo `*.`. ### `$acme_hook_keyauth` A string de autorização: - Para desafio DNS, é usada como o valor do registro TXT, cujo nome é formado como `_acme-challenge. + $acme_hook_domain + .`. - Para desafio HTTP, esta string deve ser usada como o conteúdo da resposta solicitada pelo servidor ACME. ### `$acme_hook_name` O nome do hook. Para diferentes tipos de desafio, pode ter diferentes valores e significados: | Valor | Significado para desafio DNS | Significado para desafio HTTP | |----------------------------|-----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------| | `add` (hook de adição) | O registro TXT correspondente deve ser adicionado à configuração DNS. | Uma resposta à solicitação HTTP correspondente deve ser preparada. | | `remove` (hook de remoção) | O registro TXT pode ser removido da configuração DNS. | Esta solicitação HTTP não é mais relevante;
o arquivo criado anteriormente com a string de autorização pode ser removido. | ### `$acme_hook_token` O token de verificação. Para desafio HTTP, é usado como o nome do arquivo solicitado: `/.well-known/acme-challenge/` + `$acme_hook_token`.