Skip to main content

Documentação – Comandos Cloudflared | Servidor

  • Documentação – Comandos Cloudflared | Servidor

Nota: muitos desses comandos dependem de ter o cert.pem (feito com cloudflared tunnel login) ou de um tunnel token — se der erro de “origin cert” primeiro rode cloudflared tunnel login. ([Cloudflare Docs][1])

Autenticação / certificados

# Abre o browser para autenticar sua conta e gerar cert.pem (salva em ~/.cloudflared/)
cloudflared tunnel login

Quando usar: primeira vez que configura cloudflared no host ou quando faltar cert.pem. ([Cloudflare Docs][2])

Criar / listar / inspecionar / remover túneis (lifecycle)

# Criar um túnel (gera credencial JSON para rodar o túnel)
cloudflared tunnel create <NOME_DO_TUNEL>

# Listar túneis registrados na conta
cloudflared tunnel list

# Exibir informações detalhadas de um túnel (connectors, estado, id)
cloudflared tunnel info <NOME_OU_UUID>

# Remover / deletar um túnel (não deleta se houver conexões ativas)
cloudflared tunnel delete <NOME_OU_UUID>

# Forçar remoção mesmo se houver conexões (cuidado)
cloudflared tunnel delete -f <NOME_OU_UUID>

# Se houver conexões "zumbis" ou falha ao deletar, limpar conexões
cloudflared tunnel cleanup <NOME_OU_UUID>

O delete normalmente recusa se houver conexões ativas — use -f com cuidado; cleanup remove conexões pendentes que impedem operações. ([fig.io][3])

Tokens / credenciais para execução remota / instalação

# Gerar/pegar token para usar em instalação remota / serviço (obtido via API/dashboard)
# (Ex.: para usar com `service install` - ver docs do seu fluxo)
cloudflared tunnel token <NOME_OU_UUID>   # (nem sempre disponível em todas as versões; ver docs)

Também é comum usar o endpoint API do Zero Trust para obter tokens se estiver a criar túneis via API. ([Cloudflare Docs][4])

Rotas / DNS / load balancer / IP routing

# Criar CNAME DNS que aponta hostname para o túnel (gera registro do tipo CNAME -> <UUID>.cfargotunnel.com)
cloudflared tunnel route dns <NOME_OU_UUID> <hostname.example.com>

# Ver/editar rotas LB / ip / outras (subcomandos)
cloudflared tunnel route lb ...
cloudflared tunnel route ip ...

Para expor host pelo túnel normalmente cria-se o registro DNS (CNAME para <UUID>.cfargotunnel.com) ou usa-se as rotas via dashboard/CLI. ([Cloudflare Docs][5])

Rodar o túnel (localmente) — debug / em foreground

# Roda o túnel em foreground (útil para testes). Substitua pelo nome/UUID do túnel.
cloudflared tunnel run <NOME_OU_UUID>

# Rodar com nível de log debug para troubleshooting
cloudflared tunnel run <NOME_OU_UUID> --loglevel debug

# Rodar com um arquivo de configuração específico
cloudflared tunnel --config /path/to/config.yml run <NOME_OU_UUID>

run cria a conexão entre seu host e a edge da Cloudflare — observe logs para erros de auth, upstream unreachable, TLS, etc. ([fig.io][6])

Instalar como serviço / iniciar automático

# No Linux (instala/integra com systemd — varia com versão/platform; alguns guias usam: cloudflared --config ~/.cloudflared/config.yml service install)
sudo cloudflared service install <TUNNEL_TOKEN>   # quando estiver usando token-based install
# Ou (guia alternativo)
sudo cloudflared --config /etc/cloudflared/config.yml service install

# Gerenciar service (systemd)
sudo systemctl start cloudflared
sudo systemctl enable cloudflared
sudo systemctl status cloudflared
sudo systemctl stop cloudflared

Recomenda-se rodar cloudflared como serviço para garantir disponibilidade. A forma exata do service install depende se você instalou via package ou binário e se usa token/arquivo de config. ([Cloudflare Docs][7])

Comandos de manutenção / atualização / remoção

# Atualizar o binário (se instalado via service install)
sudo cloudflared update        # disponível quando instalado dessa forma

# Desinstalar serviço / uninstall launch agent (mac/windows varia)
cloudflared service uninstall   # macOS / launch agent variant
cloudflared.exe service uninstall  # Windows variant

cloudflared update existe em instalações que usam o instalador/service oficial; para pacotes gerenciados (apt, rpm, homebrew) atualize pelo package manager. ([docs.pi-hole.net][8])

Diagnóstico útil (logs, permissões, rede)

# Verificar se cert.pem existe (origincert)
ls -l ~/.cloudflared/
ls -l /etc/cloudflared/

# Logs systemd (Linux)
sudo journalctl -u cloudflared -n 200 --no-pager
sudo journalctl -u cloudflared -f

# Logs do container (se usar Docker)
docker ps --filter "name=cloudflared"
docker logs -f <CONTAINER_ID_OU_NOME>

# Testar serviço local que o túnel expõe
ss -tlnp | grep :<PORTA>
curl -v -H "Host: <hostname.example.com>" http://127.0.0.1:<PORTA>/

Muitos erros comuns estão relacionados a cert.pem ausente, permissões incorretas, firewall/egress bloqueado, ou serviço local indisponível. ([Cloudflare Docs][1])

Exemplos rápidos (workflow típico)

  1. Autenticar / obter cert:
cloudflared tunnel login
  1. Criar túnel:
cloudflared tunnel create my-tunnel
# saída inclui UUID e caminho do arquivo credentials (ex: ~/.cloudflared/<UUID>.json)
  1. Criar rota DNS:
cloudflared tunnel route dns my-tunnel app.minhaempresa.com
  1. Executar localmente (teste):
cloudflared tunnel run my-tunnel --loglevel debug
  1. Instalar como serviço (opcional):
sudo cloudflared service install <TUNNEL_TOKEN>
sudo systemctl enable --now cloudflared

(ou use cloudflared --config ~/.cloudflared/config.yml service install dependendo de como você configurou). ([Cloudflare Docs][2])

Observações / boas práticas

  • Sempre proteja ~/.cloudflared/*.json e cert.pem (permissões 600).
  • Se o tunnel for gerenciado por service, coloque cert.pem/credenciais em /etc/cloudflared/ com dono adequado para o usuário do serviço.
  • Ao deletar um túnel, cheque se há registros DNS que podem conflitar ao recriar um túnel com o mesmo hostname. ([Cloudflare Docs][5])