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.

Resposta curta: 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'`.
Neste artigo
- Contatos dá para automatizar, agenda não
- O que confirmar antes de abrir o terminal
- Levantar quais cPanels ainda têm dados do Horde
- Rodar a exportação em lote
- Contar vCards para saber se a exportação valeu
- Seis erros que aparecem nesse procedimento e a saída de cada um
- O que entregar ao cliente, e por qual canal
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. 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:
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:
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:
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.
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.
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:
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:
grep -c 'BEGIN:VCARD' /root/horde-export/clinicaexemplo.com.br/contatos.vcf
Para a revenda inteira, de uma vez:
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:
file -i /root/horde-export/clinicaexemplo.com.br/contatos.vcf
Se vier iso-8859-1 e o destino esperar UTF-8:
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
.vcfde 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
.icsdas 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á:
Checklist para repetir o procedimento em outro servidor
- Confirmar root por SSH e presença do script.
- Montar
contas.txtcom os cPanels que são seus. - Criar
/root/horde-exportcom 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:VCARDem 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.
Referências
- Documentação oficial (cpanel) — The export_horde_contacts_to_vcf Script. Consultado em 2026-10-13.