`), permitindo que uma segunda implantação do conector compartilhe uma instância sem conflitar com os usuários da primeira. |
| `--ch-admin-password-stdin` | Lê a senha de administrador do ClickHouse do stdin quando o provisionamento SQL exige uma; em execuções no terminal, a senha é solicitada. |
### Flags de assinatura (somente na fase 1)
| Flag | Descrição |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--no-auto-sign` | Apenas na fase: ignora a assinatura automática da CSR pelo endpoint de inscrição, para fluxos de assinatura isolados da internet ou fora de banda. |
| `--sign-endpoint ` | Substitui o endpoint de assinatura de inscrição (padrão: derivado do endpoint do pacote com a inserção do rótulo DNS `enroll`). Deve ser uma URL HTTPS. |
### Flags exclusivas do Kubernetes
Válidas apenas com `--target helm`.
| Flag | Descrição |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--target-namespace ` | Espaço de nomes em que o Chart do Helm é instalado e seus Secrets são criados (padrão: `clicklink`; solicitado no terminal). |
| `--instance-namespace ` | Espaço de nomes da instância ClickHouse de destino; inicializa a detecção de Service nativo e os prompts da instância. |
| `--storage-class ` | StorageClass do volume de estado do solucionador de problemas (padrão: a StorageClass padrão do cluster; solicitada ou obrigatória quando o cluster não define nenhuma). |
| `--values ` | Caminho da sobreposição de values preparada (padrão: `clicklink-values.yaml`). |
| `--chart [` | Chart do Helm a implantar: um nome resolvido em `--chart-repo` ou uma referência direta `oci://`, URL ou local para instalações espelhadas (padrão: `clicklink-connector`). |
| `--chart-repo ` | Repositório Helm em que o nome do Chart do Helm é resolvido (padrão: `https://releases.clicklink.clickhouse.com/charts`); ignorado para referências diretas em `--chart`. |
| `--chart-version ` | Versão do Chart do Helm a implantar (padrão: a versão de lançamento deste binário). |
| `--ch-pod ][` | Pod do Kubernetes do ClickHouse para as etapas de provisionamento no pod, como nome ou seletor de rótulo `k=v` (padrão: um pod em execução que dá suporte ao Service de cada instância). |
| `--api-private-ca` | O endpoint da API usa um certificado emitido pela CA do pacote de registro: prepara `api.tls.caFile` apontando para a cadeia de CAs montada, em vez das raízes do sistema. |
]
### Flags exclusivas para VM
Válidas apenas com `--target systemd`.
| Flag | Descrição |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `--server ` | URL do servidor da API do Kubernetes para o qual os pacotes de acesso apontam (padrão: kubeconfig deste host; caso contrário, será solicitado). |
| `--ca-data ` | `certificate-authority-data` em Base64 para `--server` (padrão: kubeconfig deste host; caso contrário, será solicitado). |
### Conflitos de flags
* `--handoff`, `--enroll` e `--signed-cert` são mutuamente exclusivos; exatamente um é obrigatório.
* As flags exclusivas do Kubernetes são rejeitadas, a menos que `--target helm` seja usado; `--server` e `--ca-data` são rejeitados com `--target helm` (o fluxo do Helm lê o kubeconfig da estação de trabalho).
* `--no-auto-sign` e `--sign-endpoint` são mutuamente exclusivos, e ambos (além de `--api-private-ca`) são rejeitados com `--signed-cert`.
* `--operators` e `--no-gateway` são mutuamente exclusivos.
* `--skip-provision` rejeita `--ch-pod`, `--ch-user-suffix`, `--server`, `--ca-data` e `--ch-admin-password-stdin` (nada é provisionado).
## clicklink clctl preflight
Executa o conjunto de verificações do conector, agrupadas por categoria: configuração, arquivos, rede, clickhouse, systemd, acesso, disco e redação. Cada verificação informa aprovação, aviso, falha ou ignorada. O código de saída 0 indica que todas as verificações foram aprovadas (os avisos não bloqueiam); o código de saída 2 indica que uma ou mais verificações falharam.
Por padrão, o comando é executado localmente. Com `--k8s-namespace`, ele executa o binário do conector no pod por meio de `kubectl exec` e gera o relatório localmente (as verificações de systemd são sempre ignoradas em pods). Com as [flags do canal remoto](#channel-flags), ele executa o binário instalado em uma VM remota.
| Flag | Descrição |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `--config ` | Caminho para o arquivo de configuração do conector; em um destino remoto, o caminho nesse host. |
| `--output `, `-o` | Formato de saída: `text` (padrão) ou `json`. |
| `--timeout ` | Tempo limite geral para todas as verificações (padrão: `30s`). |
| `--skip-systemd` | Ignora verificações do estado da unidade do systemd (hosts que não usam systemd). |
| `--k8s-namespace ` | Espaço de nomes do Chart do Helm do conector; executa o preflight no pod do conector por meio de `kubectl exec`. |
| `--k8s-component ` | Pod do conector no qual executar: `scraper` (padrão) ou `troubleshooter`. |
| `--k8s-pod [` | Nome do pod ou substituição do seletor de rótulo `k=v` (padrão: os rótulos de componente do Chart do Helm). |
| `--k8s-container ` | Contêiner no qual executar o comando `exec` (padrão: o nome do componente). |
As flags `--k8s-*` e as flags do canal remoto são mutuamente exclusivas; escolha um destino.
]
## clicklink clctl troubleshoot session
Habilita, desabilita e inspeciona a sessão de suporte: o período limitado durante o qual o solucionador de problemas aceita comandos. Quando não há sessão ativa, o daemon recusa todos os comandos, mesmo que o WebSocket esteja conectado. Consulte [sessões de suporte](/docs/pt-BR/products/bring-your-own-cloud/connector/support-sessions).
Os comandos operam em um de dois modos:
* **Arquivo local** (padrão): lê e grava o arquivo de estado da sessão no host em que o solucionador de problemas é executado (o padrão é `/var/lib/clicklink/session.json`).
* **Gateway**: com `--gateway-url`, obtém um token de ID OIDC e, a partir da sua estação de trabalho, chama o gateway de sessão do solucionador de problemas.
### Flags compartilhadas
| Flag | Descrição |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--session-file ` | Caminho do arquivo de estado da sessão (o padrão é `/var/lib/clicklink/session.json`). |
| `--config ` | Arquivo de configuração do conector; determina o caminho do arquivo de sessão a partir da seção `troubleshooter`. |
| `--gateway-url ` | URL base do gateway de sessão. Quando definida, o comando obtém um token Bearer OIDC e chama o gateway em vez de acessar o arquivo de estado local. Mutuamente exclusiva com `--session-file` e `--config`. |
| `--gateway-audience ` | Claim de audiência ao qual o token OIDC está vinculado (o padrão é `clicklink-clctl`, que corresponde ao padrão do próprio gateway). Defina-a apenas se a audiência do gateway tiver sido reconfigurada. |
| `--gateway-issuer ` | Emissor OIDC que o gateway valida. Se estiver vazio, seleciona o fluxo do Google; defina-o junto com `--oidc-client-id` para executar o fluxo de código do dispositivo em um provedor de identidade diferente do Google. |
| `--oidc-client-id ` | ID de cliente OIDC público para o fluxo de código do dispositivo, registrado em `--gateway-issuer` com a concessão de dispositivo habilitada. |
| `--token-file ` | Arquivo que contém um token de ID OIDC pré-gerado, usado como token Bearer e que ignora os demais provedores de token. |
| `--gateway-ca ` | Bundle de CA que verifica o certificado do gateway (certificado fornecido por você). Quando não definido, é usado um certificado fixado via `gateway trust`; um gateway autossinado sem fixação falha de modo seguro. |
### habilitar sessão
| Flag | Descrição |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--duration ` | Por quanto tempo a sessão permanece ativa (padrão: `4h`; máximo: `24h`). |
| `--reason ` | Motivo opcional em texto livre registrado com a sessão (até 256 caracteres). |
| `--user ` | Identidade do operador a ser registrada no modo de arquivo local; por padrão, usa `$SUDO_USER` ou `$USER`. No modo gateway, o e-mail atestado pelo token é a fonte autorizada. |
A habilitação falha se já houver uma sessão ativa; primeiro, desabilite-a ou aguarde a expiração.
### desativar sessão
Desativa a sessão imediatamente. Não tem efeito quando não há nenhuma sessão ativa.
### status da sessão
Mostra se a sessão está ativa, quem a habilitou e quando expira. `--output` (`-o`) seleciona `table` (padrão) ou `json`.
No Kubernetes, acesse o gateway por meio de um redirecionamento de porta:
```bash theme={null}
kubectl -n port-forward \
statefulset/clicklink-connector-troubleshooter 8443:8443
clicklink clctl troubleshoot session enable \
--gateway-url http://localhost:8443 \
--duration 1h --reason "support ticket 1234"
```
## clicklink clctl troubleshoot gateway trust
Em uma VM, o gateway de sessão usa um certificado TLS autossinado. Este comando registra a impressão digital SHA-256 do certificado em `~/.clicklink/clctl.yaml` para que os comandos `session` possam verificá-lo; se uma impressão digital fixada deixar de corresponder, a operação falhará de forma segura. A confiança é estabelecida fora de banda de uma destas duas formas:
* Com as [flags do canal remoto](#channel-flags), o certificado é lido diretamente da VM pelo canal já autenticado e fixado.
* Sem um canal, passe `--gateway-fingerprint` com o valor SHA-256 registrado pelo conector ao gerar o certificado; o certificado obtido só será fixado se corresponder. A omissão da flag exibe a impressão digital apresentada sem fixar nada.
| Flag | Descrição |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--gateway-url ` | URL base do gateway no qual confiar (obrigatória), por exemplo, `https://:8443`. |
| `--gateway-fingerprint ` | Impressão digital SHA-256 esperada do log do conector, verificada antes da fixação. Dois-pontos e diferenças entre maiúsculas e minúsculas são ignorados. |
| `--remote-cert-file ` | Caminho do certificado do gateway na VM, lido pelo canal (padrão: `/var/lib/clicklink/gateway/tls/server.crt`). |
```bash theme={null}
clicklink clctl troubleshoot gateway trust \
--gateway-url https://:8443 \
--gateway-fingerprint
```
No Kubernetes, o pinning não é usado: exponha o gateway por meio de uma Entrada com um certificado emitido por uma CA ou use o redirecionamento de porta.
## clicklink clctl troubleshoot audit tail
Exibe as últimas entradas do log de auditoria do solucionador de problemas: JSON delimitado por quebras de linha, uma entrada para cada comando que o daemon aceitou ou bloqueou. O comando abre o log em modo somente leitura e nunca o modifica.
| Flag | Descrição |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| `--lines `, `-n` | Número de entradas finais a exibir (padrão: 50). |
| `--path ` | Caminho para o arquivo de log de auditoria (padrão: `/var/log/clicklink/troubleshoot-audit.log`). |
A imagem de runtime do conector não inclui um shell; portanto, no Kubernetes, este comando é o leitor compatível:
```bash theme={null}
kubectl -n exec -- \
/clicklink clctl troubleshoot audit tail
```
## Provisionamento de acesso
`clicklink clctl scraper access provision` e `clicklink clctl troubleshoot access provision` criam e, com `--force`, rotacionam o pacote de acesso por instância de um componente: o usuário do ClickHouse com acesso somente leitura e suas permissões, além da ServiceAccount do Kubernetes, RBAC e token usados pelo componente. `init` executa essa operação inline durante a instalação; os comandos standalone permitem reexecutá-la e rotacionar credenciais.
| Flag | Descrição |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--instance ` | Nome da instância na configuração (obrigatório). |
| `--server ` | URL do servidor da API do Kubernetes (obrigatório). |
| `--ca-data ` | Certificado da CA do cluster em Base64 para o kubeconfig gerado. |
| `--config ` | Arquivo de configuração do conector do qual a instância será lida. |
| `--target ` | `systemd` (padrão: envia o pacote para uma VM por um canal remoto ou o gera localmente com `--provider local`) ou `helm` (envia o pacote como um Secret do Kubernetes para o Chart do Helm). |
| `--target-namespace ` | Espaço de nomes em que o Secret do pacote será criado (obrigatório com `--target helm`). |
| `--instance-namespace ` | (`--target helm`) Espaço de nomes da instância ClickHouse de destino. |
| `--force` | Sobrescreve um pacote existente: usado para reexecução e rotação de credenciais. |
| `--secret-name ` | Substitui o nome do Secret do pacote (padrão `clicklink-connector--access-`). |
| `--output-dir ` | (`--target helm` ou `--provider local`) Diretório raiz em que o pacote será criado. |
| `--ch-admin-user ` | Usuário administrador do ClickHouse para aplicar permissões (padrão `default`). |
| `--ch-admin-password-stdin` | Lê a senha do administrador do ClickHouse de stdin. |
| `--ch-user-suffix ` | Sufixo opcional para o nome de usuário provisionado do ClickHouse. |
| `--ch-user-via ` | Como o usuário do ClickHouse é provisionado: `sql` (padrão; aplica as permissões geradas como `--ch-admin-user`) ou `cr` (grava o usuário no recurso personalizado da instância, para instâncias gerenciadas por operador sem administrador com acesso SQL). |
| `--apply-ch-grants` | (`--target helm`) Aplica as permissões geradas dentro do pod via `kubectl exec`, em vez de deixá-las para você aplicar. |
| `--ch-pod [`, `--ch-pod-namespace `, `--ch-container ` | (`--target helm` com `--apply-ch-grants` ou `--ch-user-via cr`) Seleciona o pod do Kubernetes do ClickHouse e o contêiner no qual executar o comando. |
| `--token-duration ` | Ciclo de vida do token da ServiceAccount (padrão `2160h`, 90 dias; o EKS limita as concessões a 24 horas). |
| `--skip-restart` | Não reinicia o componente após o provisionamento. |
| `--dry-run` | Exibe o plano e encerra; não realiza gravações no Kubernetes, em canais remotos ou no ClickHouse. |
Rotacione as credenciais de uma instância para um componente:
```bash theme={null}
clicklink clctl scraper access provision --target helm \
--target-namespace \
--instance --instance-namespace \
--server \
--apply-ch-grants --ch-pod --ch-pod-namespace \
--force
```
]
## Flags de canal remoto
`preflight`, `gateway trust` e `access provision` aceitam um conjunto compartilhado de flags que define como acessar uma VM de destino:
| Flag | Descrição |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--provider ` | Canal de execução: `ssh`, `aws` (SSM) ou `gcp` (IAP) para VMs remotas, ou `local` quando executado na própria VM de destino. É inferido pelas flags específicas de cada provedor quando não definido explicitamente; `local` nunca é inferido. |
| `--ssh-host `, `--ssh-user `, `--ssh-port `, `--ssh-identity-file ` | Detalhes da conexão SSH (`--provider ssh`); usuário, porta e chave assumem como padrão as configurações de SSH. |
| `--instance-id `, `--region `, `--profile ` | Instância EC2, região e perfil de configuração compartilhada para SSM (`--provider aws`). |
| `--project `, `--zone `, `--instance-name ` | Projeto, zona e instância para tunelamento via IAP (`--provider gcp`). |