# Exportar contatos do Horde de toda a revenda antes da remoção

Um loop no shell do WHM resolve dezenas de cPanels enquanto o webmail resolve um. Com pasta por domínio, log por conta e conferência de contagem antes da entrega.

> use o script oficial `export_horde_contacts_to_vcf` do cPanel por SSH como root, em um loop sobre `/var/cpanel/users`, gravando um .vcf por domínio fora do public_html e conferindo cada arquivo com `grep -c 'BEGIN:VCARD'`.

João Rizzon · 2026-10-31 · Revenda

---

Quem administra uma revenda não tem como abrir o webmail de cada conta, clicar em Contatos, clicar em Exportar, salvar o arquivo, repetir. Com dezenas de cPanels e várias caixas por cPanel, o caminho pelo navegador deixa de ser um procedimento e vira um turno inteiro de trabalho perdido. O caminho pelo servidor resolve o mesmo problema com um loop e termina com uma pasta por domínio, pronta para entregar.

Este guia se apoia na [documentação oficial do cPanel sobre o script `export_horde_contacts_to_vcf`](https://docs.cpanel.net/whm/scripts/the-export_horde_contacts_to_vcf-script/). Não há medição nossa aqui: é procedimento, organização e tratamento de erro.

## Contatos dá para automatizar, agenda não

Seja honesto com o escopo antes de prometer prazo ao cliente. Os dois itens não têm o mesmo nível de suporte oficial.

**Contatos (.vcf)**: o cPanel publica um script de servidor, o `export_horde_contacts_to_vcf`, documentado em WHM > Scripts. É a ferramenta oficial para tirar os contatos do Horde e gravá-los como vCard. É isso que permite o processamento em lote a partir do shell do root.

**Agenda (.ics)**: não existe, na documentação de scripts do cPanel, um equivalente oficial para calendários. Quem disser que existe um `export_horde_calendar_to_ics` está inventando. Então a agenda segue por um dos dois caminhos: exportação manual pelo webmail enquanto o Horde ainda estiver instalado, ou assinatura/sincronização via CalDAV antes do desligamento. Trate a agenda como item manual no seu plano e cobre o tempo dela separadamente.

Essa distinção muda a conversa com o cliente. Contatos: lote, rápido, você entrega. Agenda: caso a caso, só para quem usava calendário de verdade, e há gente que nunca criou um evento.

## O que confirmar antes de abrir o terminal

Checklist curto. Se qualquer item falhar, pare e resolva antes, porque rodar o loop pela metade gera pasta incompleta e você não vai saber quais contas ficaram de fora.

- Acesso **root por SSH** ao servidor. Em revenda sem root, o procedimento em lote não se aplica: fale com quem opera o servidor.
- **Horde ainda instalado e com os dados presentes.** Depois que o recurso sai do servidor, os dados podem ir junto. A janela é definida pelo fornecedor, não por você.
- **Espaço em disco** em uma partição que não seja a dos sites, para a pasta de saída.
- Uma **lista fechada de cPanels** da sua revenda, não "todos os usuários do servidor", se o servidor for compartilhado com outras contas.
- **Backup antes.** Exportação não é backup, mas um snapshot do estado atual evita discussão depois.

### Confirmar se o script existe e quais opções sua versão aceita

A documentação do cPanel descreve o script e seu uso. As opções exatas podem variar conforme a versão instalada, então leia o que o seu servidor diz antes de escrever o loop:

```bash
ls -l /usr/local/cpanel/scripts/export_horde_contacts_to_vcf
/usr/local/cpanel/scripts/export_horde_contacts_to_vcf --help
```

Se o arquivo não existir, a versão instalada não tem o script e o resto deste procedimento não se aplica. Nesse caso, resta o caminho pelo webmail, conta a conta.

## Levantar quais cPanels ainda têm dados do Horde

Não rode a exportação às cegas. Primeiro saiba quantos cPanels você vai percorrer, porque esse número é o que entra no seu orçamento de tempo e na mensagem ao cliente.

A lista de usuários cPanel do servidor fica em `/var/cpanel/users`, um arquivo por conta:

```bash
ls /var/cpanel/users | wc -l
mkdir -p /root/horde-export
chmod 700 /root/horde-export
ls /var/cpanel/users | sort > /root/horde-export/contas.txt
```

Se você atende só parte das contas do servidor, edite `contas.txt` à mão e trabalhe a partir dele. É melhor uma lista explícita do que um `ls` que amanhã devolve conta nova.

De cada conta você vai precisar, no fim, do domínio principal para nomear a pasta de saída. O arquivo de usuário traz isso:

```bash
grep -m1 '^DNS=' /var/cpanel/users/usuario
```

Guarde esse mapeamento usuário/domínio agora. Na hora de entregar, ninguém do lado do cliente sabe o que é `usuar12`, mas todo mundo reconhece `clinicaexemplo.com.br` (exemplo fictício).

## Rodar a exportação em lote

### Criar a estrutura de saída fora do public_html

Uma pasta por domínio, fora do `public_html` de qualquer site. A raiz `/root/horde-export` já foi criada no inventário, e repetir os comandos abaixo não causa efeito colateral. Nunca grave vCard dentro de pasta servida pela web: contato de cliente é dado pessoal e um arquivo `.vcf` exposto é um incidente de LGPD, não um detalhe.

```bash
mkdir -p /root/horde-export
chmod 700 /root/horde-export
```

### Chamar o script por conta, com log e código de retorno

O padrão do loop é sempre o mesmo: ler a lista, criar a pasta do domínio, chamar o script, registrar saída e código de retorno. A forma de passar a conta ao script é a única parte que você precisa confirmar: use o que o `--help` do seu servidor mostrar, porque o exemplo abaixo é ilustrativo.

```bash
while read -r user; do
  dom=$(grep -m1 '^DNS=' "/var/cpanel/users/$user" | cut -d= -f2)
  out="/root/horde-export/${dom:-$user}"
  mkdir -p "$out"
  echo "=== $user ($dom) ===" >> /root/horde-export/export.log
  # linha abaixo: exemplo ilustrativo de sintaxe, não copiada da documentação.
  # Confirme no --help como a conta deve ser informada neste servidor.
  /usr/local/cpanel/scripts/export_horde_contacts_to_vcf "$user" \
    >> /root/horde-export/export.log 2>&1 < /dev/null
  echo "rc=$? user=$user" >> /root/horde-export/export.log
done < /root/horde-export/contas.txt
```

Três coisas importam nesse bloco. A primeira é o `2>&1`: erro silencioso é o que faz você entregar pasta vazia e descobrir pelo cliente. A segunda é o `rc=`, o código de retorno por conta. No fim, `grep -v 'rc=0' /root/horde-export/export.log` devolve exatamente a lista do que precisa de atenção manual. A terceira é o `< /dev/null`: sem ele, o script herda o stdin do `while` e pode consumir linhas de `contas.txt`, pulando contas sem avisar. É a falha mais chata de diagnosticar aqui, porque o log parece correto e só a contagem final denuncia.

### Descobrir onde os .vcf foram gravados

O script informa na saída onde gravou cada arquivo. Leia o log em vez de supor um caminho. Se os `.vcf` saírem no home da conta, recolha-os para a pasta do domínio:

```bash
find /home/usuario -maxdepth 3 -name '*.vcf' -newermt '-1 hour' -ls
```

O `-newermt` evita que você recolha vCard antigo que o próprio usuário deixou no home anos atrás.

### Testar em uma conta antes de soltar o loop

Escolha um cPanel pequeno, rode o procedimento inteiro nele, confira a contagem, abra o arquivo no Google Contatos. Só depois solte o loop na lista completa. Testar em um é barato; refazer trinta é caro.

## Contar vCards para saber se a exportação valeu

Um arquivo `.vcf` é texto. Cada contato começa com uma linha `BEGIN:VCARD`. Então contar contatos é contar essas linhas:

```bash
grep -c 'BEGIN:VCARD' /root/horde-export/clinicaexemplo.com.br/contatos.vcf
```

Para a revenda inteira, de uma vez:

```bash
find /root/horde-export -name '*.vcf' -print0 \
  | xargs -0 grep -cH 'BEGIN:VCARD'
```

O `-H` força o caminho no início de cada linha, inclusive quando o lote tem um arquivo só (sem ele, o `grep` imprime apenas o número e você perde a referência). A saída vem no formato `caminho:número`. Arquivo com `:0` é exportação vazia, e vazio pode significar duas coisas bem diferentes: a conta realmente não tinha contatos, ou a exportação falhou. Confirme com o cliente antes de dar como concluído. Uma pergunta objetiva basta: "o endereço X tinha contatos salvos no catálogo do webmail?".

Esse número também é o seu comprovante de entrega. Se o cliente diz que tinha cerca de 300 contatos e o arquivo tem 312, está resolvido. Se tem 4, alguém estava usando outro catálogo, outra conta, ou o catálogo compartilhado.

## Seis erros que aparecem nesse procedimento e a saída de cada um

| Sintoma | Causa provável | O que fazer |
|---|---|---||
| Script não existe em `/usr/local/cpanel/scripts/` | Versão do cPanel sem o script ou Horde já removido | Exportar pelo webmail, conta a conta, enquanto houver interface |
| `rc` diferente de 0 para uma conta | Conta sem dados do Horde, ou dados corrompidos | Separar a conta para tratamento manual; não refazer o lote inteiro |
| `.vcf` gerado com 0 ocorrências de `BEGIN:VCARD` | Catálogo vazio ou contatos em outro endereço de e-mail | Confirmar com o cliente qual caixa tinha o catálogo |
| Acentos virando `Ã§`, `Ã£` | Divergência de codificação entre arquivo e leitor | Verificar com `file -i` e converter com `iconv` |
| Google Contatos importa, mas sem telefone | Campos do vCard não mapeados na importação | Conferir um contato na origem e um no destino antes de apagar algo |
| Pasta de saída dentro de `public_html` | Erro de caminho no loop | Mover imediatamente, revisar acesso, tratar como exposição de dados |

### Por que o acento quebra e como corrigir com iconv

É o erro que mais gera retrabalho porque só aparece depois da importação, quando o cliente abre a agenda e vê `JoÃ£o`. Verifique o que o arquivo é de fato:

```bash
file -i /root/horde-export/clinicaexemplo.com.br/contatos.vcf
```

Se vier `iso-8859-1` e o destino esperar UTF-8:

```bash
iconv -f ISO-8859-1 -t UTF-8 contatos.vcf -o contatos-utf8.vcf
grep -c 'BEGIN:VCARD' contatos-utf8.vcf
```

Repita o `grep -c` depois da conversão. Conversão que perde linha é conversão que perdeu contato.

## O que entregar ao cliente, e por qual canal

O arquivo `.vcf` importa direto no Google Contatos (Importar > Selecionar arquivo) e no Roundcube (Contatos > Importar). Não peça ao cliente para abrir o arquivo em editor de texto, não mande por canal público e prefira um link temporário com expiração a anexo em e-mail que vai ficar na caixa dele para sempre.

O que entregar por domínio:

- O `.vcf` de cada caixa que tinha contatos, com o nome do endereço no arquivo.
- A contagem de contatos de cada arquivo, em uma linha.
- A lista das caixas que não tinham contato nenhum, para o cliente confirmar.
- O `.ics` das agendas, quando houver, exportado manualmente pelo webmail.

### Texto pronto para avisar o cliente da desativação

Ajuste o nome e a data e mande como está:

> **** O webmail Horde vai ser desativado pelo fornecedor e, com ele, saem o catálogo de contatos e a agenda que ficavam guardados lá. Seus e-mails não são afetados: eles continuam na sua caixa normalmente. Vamos exportar os contatos de todas as suas contas até [data] e enviar um arquivo por endereço, pronto para importar no Google Contatos ou no novo webmail. Se você usa a agenda do webmail, nos avise até [data], porque esse item é exportado caixa a caixa. Depois da desativação não é possível recuperar.

### Checklist para repetir o procedimento em outro servidor

- Confirmar root por SSH e presença do script.
- Montar `contas.txt` com os cPanels que são seus.
- Criar `/root/horde-export` com permissão 700.
- Rodar em uma conta de teste e validar a importação no destino.
- Rodar o loop com log e código de retorno por conta.
- `grep -v 'rc=0'` no log e tratar as exceções à mão.
- Contar `BEGIN:VCARD` em todos os arquivos.
- Conferir codificação e converter o que precisar.
- Exportar as agendas das contas que usam calendário.
- Entregar por domínio, com a contagem, e guardar o log do lote.

Uma observação que vai contra o volume de trabalho: antes de rodar tudo, pergunte aos clientes quem usava o catálogo do webmail. Muita gente salva contato no celular e nunca tocou nessa tela. A lista de contas que realmente precisam de exportação costuma ser menor que a lista de contas existentes, e o lote fica mais rápido de conferir. O que não dá para fazer é descobrir isso depois que o recurso saiu do servidor.

