Pular para o conteúdo principal
Versão: 0.4 · atual

Configurar nomes e TLS

Guia de instruçõesRevisado em 11 de outubro de 2026
Aplica-se a:Excubius 0.4Funções: Instalador (administrador do Linux), Superadministrador
PlanosFree · Core · Pro · EnterpriseImplantaçãoAuto-hospedado

O seu servidor do Excubius responde a um nome principal e a qualquer quantidade de aliases e serve HTTPS em um de seis modos, de um certificado do Let's Encrypt a um gateway que encerra o TLS na frente dele. As respostas do instalador definem os primeiros valores. Depois disso, você os altera no console, e a alteração entra em vigor em até um minuto, sem reinicialização. Este guia mostra como escolhê-los e alterá-los.

Antes de começar​

  • Para alterar os nomes e o TLS no console, você precisa da função Super admin (Superadministrador).
  • Para trabalhar a partir do servidor, você precisa de acesso SSH e de sudo, para agir como a conta de serviço (excubius por padrão).
  • Crie primeiro os registros DNS. Cada nome deve ser resolvido para o servidor, ou para o gateway na frente dele, a partir de onde as pessoas usarão o Excubius.

Os três tipos de nome​

NomeO que é
Primary nameO nome do host no endereço público, por exemplo monitoring.ciguapa.example. Os links que o Excubius envia, nas mensagens do Slack e nos itens do Jira, usam esse nome. A entrada sempre acontece nele: uma pessoa que abre um alias é enviada ao nome principal para entrar
AliasesOutros nomes que as pessoas podem abrir, por exemplo monitoring.areito.example em um domínio que você controla quando a zona DNS do cliente está fora do seu alcance. O servidor responde a todos eles
Names in the certificateOs nomes para os quais um certificado é solicitado. Todos os nomes por padrão, e os novos aliases entram automaticamente. Desmarque um nome que um certificado não pode cobrir, por exemplo um cujo DNS você não controla

Um servidor tem no máximo 100 nomes no total.

aviso

Os endereços de redirecionamento registrados para a entrada com o Microsoft Entra ID e o Google começam com o nome principal. Quando você alterar o nome principal, atualize-os primeiro; consulte Configurar provedores de entrada.

Escolher um modo​

Modo no consoleResposta do instaladorUse quando
Let's Encrypt over HTTPletsencryptTodos os nomes do certificado estão no DNS público apontando para este servidor e a porta 80 está acessível pela internet, diretamente ou encaminhada por um NAT ou gateway
Let's Encrypt over DNSletsencrypt-dnsVocê tem credenciais de API para a zona DNS dos nomes. O servidor não precisa estar acessível pela internet, por isso esta é a escolha habitual para um servidor acessado por VPN
Self-signedselfsignedEm qualquer lugar. Os navegadores exibem avisos até que as pessoas confiem no certificado nos computadores e telefones delas
Your own certificatecustomA sua organização emite certificados. Você cola a cadeia e a chave e as substitui antes que expirem
Gateway in frontgatewayUm balanceador de carga ou proxy reverso, como o Azure Application Gateway ou o Front Door, encerra o TLS e encaminha HTTP simples. O cabeçalho X-Forwarded-Proto dele é respeitado
Plain HTTPlaterUm primeiro teste ou uma rede em que você confia totalmente. Nada é criptografado

Alterar os nomes ou o modo no console​

  1. Abra Settings e selecione Server and certificates. Você também pode chegar lá por Settings › Instance, com Server names and HTTPS.
  2. Em Names, verifique o Primary name. Para adicionar um alias, digite-o e selecione Add; para remover um, selecione Remove ao lado dele.
  3. Em HTTPS, escolha o modo e preencha o que ele pede. As seções abaixo descrevem cada um.
  4. Em Names in the certificate, desmarque qualquer nome que um certificado não possa cobrir.
  5. Selecione Apply. A página mostra Saved. The certificate service is applying it.

Em Current certificate, você vê o que está sendo servido: o emissor, os nomes, Valid until, a Last attempt com o resultado dela e a Next check. Se uma tentativa falhar, What went wrong explica o motivo.

Cada alteração é verificada antes de ser salva e é registrada no log de auditoria.

Let's Encrypt por HTTP​

Digite o E-mail for the Let's Encrypt account. Antes de aplicar, verifique se todos os nomes do certificado são resolvidos publicamente para o servidor e se a porta 80 está aberta a partir da internet. Um nome que não pode ser público, como um endereço IP ou um nome terminado em .local, .internal ou .corp, é recusado: desmarque-o ou use um certificado autoassinado.

Let's Encrypt por DNS​

  1. Digite o E-mail for the Let's Encrypt account.

  2. Escolha o DNS provider da zona dos nomes. Para um provedor que não está na lista, escolha Other (acme.sh dnsapi id) e digite o id dnsapi dele no acme.sh.

  3. Em API credentials, digite os valores que o provedor lê. O console os lista para cada provedor:

    Provedorid dnsapiVariáveis
    Cloudflaredns_cfCF_Token, CF_Account_ID
    DreamHostdns_dreamhostDH_API_KEY
    Azure DNSdns_azureAZUREDNS_SUBSCRIPTIONID, AZUREDNS_TENANTID, AZUREDNS_APPID, AZUREDNS_CLIENTSECRET
    Amazon Route 53dns_awsAWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
    GoDaddydns_gdGD_Key, GD_Secret
    DigitalOceandns_dgonDO_API_KEY
    Gandidns_gandi_livednsGANDI_LIVEDNS_TOKEN
    Hetznerdns_hetznercloudHETZNER_TOKEN
    IONOSdns_ionosIONOS_PREFIX, IONOS_SECRET
    Linode (Akamai)dns_linode_v4LINODE_V4_API_KEY
    Namecheapdns_namecheapNAMECHEAP_USERNAME, NAMECHEAP_API_KEY, NAMECHEAP_SOURCEIP
    OVHclouddns_ovhOVH_END_POINT, OVH_AK, OVH_AS, OVH_CK
    Porkbundns_porkbunPORKBUN_API_KEY, PORKBUN_SECRET_API_KEY
  4. Se quiser, defina Let's Encrypt server como Staging para ensaiar sem atingir os limites de taxa do Let's Encrypt. Os certificados de staging não são confiáveis para os navegadores; volte para Production quando funcionar.

Os valores das credenciais são somente gravação: eles são armazenados criptografados e nunca mais são exibidos. Para manter um valor armazenado ao editar as configurações, deixe o campo dele vazio.

Autoassinado​

Não há nada a digitar. O certificado é válido por 825 dias e é renovado da mesma forma que os outros. Para eliminar os avisos do navegador, selecione Download the certificate e instale-o como confiável nos computadores e telefones que usam o servidor.

Seu próprio certificado​

Cole a Certificate chain no formato PEM, com o certificado do servidor primeiro, e a Private key no formato PEM, sem frase secreta. A chave deve ser RSA de 2048 bits ou mais, ou ECDSA. O console recusa um certificado expirado, que não cobre os nomes do servidor ou cuja chave não corresponde. Substitua os dois antes que o certificado expire; o Excubius não o renova para você.

Gateway na frente​

Não há nada a digitar. Configure o gateway para encaminhar HTTP simples para a porta 80 do servidor e enviar o cabeçalho X-Forwarded-Proto.

Renovação​

A renovação é automática para os certificados do Let's Encrypt e autoassinados. O serviço de certificados verifica o certificado ativo todos os dias e o renova quando restam 30 dias ou menos. Não há temporizador a configurar no servidor.

  • Uma tentativa com falha nunca remove o que funciona. O certificado anterior, ou o HTTP simples, continua sendo servido; o erro aparece na página com o horário da próxima tentativa, após 15 minutos e depois dobrando até um dia.
  • Uma alteração das configurações é tentada imediatamente.
  • Renew now solicita um novo certificado imediatamente.
  • Use self-signed now muda para um certificado autoassinado, a forma rápida de ter HTTPS enquanto o Let's Encrypt ainda não pode funcionar.

Os cookies de sessão são marcados como Secure sempre que uma solicitação chega por HTTPS, por isso a mudança de modo não exige reinicialização. Deixe COOKIE_SECURE vazio no arquivo de configuração; ele apenas força o comportamento em um sentido ou no outro.

Os endereços /healthz e /heartbeat respondem por HTTP simples em todos os modos, de modo que um monitor externo continua funcionando enquanto você altera o TLS.

Alterar o TLS a partir do servidor​

Quando o console estiver fora de alcance, por exemplo porque o certificado está com problema e o navegador recusa a página, altere as mesmas configurações a partir do servidor. O script passa pelas mesmas verificações e pelo mesmo log de auditoria que o console.

  1. Conecte-se por SSH e assuma a conta de serviço:

    sudo -iu excubius
  2. Exiba as configurações e o certificado atuais:

    /opt/excubius/current/scripts/enable-tls.sh --status
  3. Altere o que for necessário. Por exemplo, mude para um certificado autoassinado:

    /opt/excubius/current/scripts/enable-tls.sh --mode selfsigned

    Ou use o Let's Encrypt por DNS com o Cloudflare, com dois nomes e um certificado apenas para o segundo. As credenciais são lidas como linhas KEY=VALUE da entrada padrão:

    /opt/excubius/current/scripts/enable-tls.sh --mode letsencrypt-dns \
    --email ops@areito.example --dns-provider dns_cf \
    --names "monitoring.ciguapa.example monitoring.areito.example" \
    --cert-names monitoring.areito.example < credentials.txt
  4. Para renovar imediatamente, execute enable-tls.sh --renew.

Substitua /opt/excubius se você escolheu outro diretório de instalação. Execute enable-tls.sh --help para ver todas as opções, incluindo --staging e --production. Um certificado próprio só pode ser carregado pelo console.

Alterar as respostas com o instalador​

sudo ./install.sh --reconfigure faz todas as perguntas novamente. As respostas de TLS que você der nesse momento são aplicadas à plataforma em execução, como se você as tivesse alterado no console.