blog
Revenda

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.

JR · · 8 min de leitura · 1 tabela · 10 blocos de código

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
  1. Contatos dá para automatizar, agenda não
  2. O que confirmar antes de abrir o terminal
  3. Levantar quais cPanels ainda têm dados do Horde
  4. Rodar a exportação em lote
  5. Contar vCards para saber se a exportação valeu
  6. Seis erros que aparecem nesse procedimento e a saída de cada um
  7. 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.

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:

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

  1. Confirmar root por SSH e presença do script.
  2. Montar contas.txt com os cPanels que são seus.
  3. Criar /root/horde-export com permissão 700.
  4. Rodar em uma conta de teste e validar a importação no destino.
  5. Rodar o loop com log e código de retorno por conta.
  6. grep -v 'rc=0' no log e tratar as exceções à mão.
  7. Contar BEGIN:VCARD em todos os arquivos.
  8. Conferir codificação e converter o que precisar.
  9. Exportar as agendas das contas que usam calendário.
  10. 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

  1. Documentação oficial (cpanel) — The export_horde_contacts_to_vcf Script. Consultado em 2026-10-13.
Leia também