# `runner service`

Instala e gerencia o serviço systemd do runner (scheduler, webhook e API remota). Todos os subcomandos de mutação exigem root e systemd.

Com -o json, um erro vira UM objeto {"error":"<codigo>","message":"..."} no stdout, com exit diferente de zero. O texto humano de expose, unexpose e uninstall vai para o stderr. Veja a tabela de códigos.

# Autenticação da API

Por padrão a API autentica com o header X-API-Key e uma chave rk_... (entregue em /opt/runner/service-api-key, modo 600). Para usar um header próprio:

# o segredo vem por stdin: nunca na linha de comando
runner service config --auth-header X-Meu-Header --secret-stdin < /caminho/segredo

O segredo fica em /opt/runner/service-auth.secret (modo 600, dono root, arquivo comum). O service.yml guarda só o nome do header e a impressão digital (12 hex). A API não sobe se o arquivo sumir, tiver outra permissão ou divergir da impressão. A resposta 401 é a mesma nos dois modos e não revela o header esperado.

Ao entrar no modo header, a rk_ é zerada: api.api_key fica vazio no service.yml e /opt/runner/service-api-key é apagado. O status passa a trazer key_configured: false.

# Restrição por IP

runner service config --ip-permitidos 192.0.2.10/32,198.51.100.0/24
runner service config --limpar-ip-permitidos
runner service config --ip-permitidos 192.0.2.10 --atras-de-proxy cloudflare

service expose aceita --ip-permitidos e --atras-de-proxy. Com a API exposta, config --ip-permitidos reescreve a rota runner-api.yml: o vpn-only@file sai da rota e a faixa da VPN entra na lista (a combinação seria E, não OU). Ao limpar, ele volta. API exposta por versão anterior à 2.175.0 pede reexpor_necessario: rode expose de novo.

Fora da lista, a resposta é 403 com ip_nao_permitido. A verificação roda antes da autenticação. O mTLS não pode ser combinado com a lista (ip_permitidos_com_mtls).

O IP do client só vem do X-Forwarded-For quando a conexão chega de um proxy confiável (trusted_proxies). Um par de fora é sempre julgado pelo próprio IP.

Downgrade: com --ip-permitidos ativo, rode runner service config --limpar-ip-permitidos ANTES de voltar para versão < 2.175.0; senão a API fica sem filtro de IP e sem VPN. No modo header, a versão antiga recusa subir (api_key_ausente); rode --auth-padrao antes se for usar a API nela.

# Status em JSON

runner -o json service status traz o bloco api:

{
  "enabled": true, "bind": "127.0.0.1", "port": 9090, "mtls": false,
  "exposed": true, "domain": "runner.exemplo.com", "key_configured": false,
  "auth": {"modo": "header", "header": "X-Meu-Header", "fingerprint": "3f9a1c2b7d4e"},
  "expose": {"domain": "runner.exemplo.com", "vpn_only": true, "hooks_publicos": false, "middlewares": []},
  "ip_permitidos": {
    "cidrs": ["192.0.2.10/32"], "incluir_vpn": true, "faixa_vpn": ["10.0.1.0/24"],
    "proxy": "cloudflare", "cloudflare_faixas_data": "2026-10-29"
  }
}

• auth.modo é api_key ou header. No modo api_key, header é X-API-Key. O fingerprint é null se não há chave.
• ip_permitidos só aparece quando configurado. Traz aviso_modo_host: true com o Traefik em modo host e sem trusted_proxies, e aviso quando as faixas embutidas da Cloudflare têm mais de 180 dias.
• expose só aparece com a API exposta. Se ela foi exposta por versão anterior à 2.175.0, sem o registro gravado, traz só domain e "vpn_only": null.
• Sem service.yml: {"installed": false, ...} com exit 0.

# Códigos de erro

Na API HTTP, a recusa por IP responde 403 com ip_nao_permitido ou ip_nao_determinado.

# Veja também

• Checklist de hardening
• `runner serve`
• `runner traefik`