wiki:Servicos/Z-Push/InstalacaoServidor

Version 35 (modified by emersonfaria, 13 years ago) (diff)

--

Instalação do Servidor Z-Push

Pré-Requisitos:

  • O Z-Push deve ser instalado num servidor que tenha acesso lógico ao Servidor Expresso.
  • Deve existir uma regra no pg_hba.conf do PostgreSQL do Expresso, permitindo conexões vindas do servidor Z-Push;
  • Ambos servidores (PostgreSQL e Z-Push) devem estar sincronizados com algum servidor de hora;
  • Os seguintes pacotes devem estar instalados:
    • apache2
    • php5 (no mínimo a versão 5.2.6)
    • php5-imap
    • php5-pgsql
    • php5-ldap
    • postfix
    • html2text
  • É necessário que os protocolos IMAP e SMTP do servidor Expresso, estejam habilitados;
  • É necessário que o servidor do Z-Push tenha permissão de relay no servidor Expresso;
  • As seguintes portas precisam estar abertas (verificar regras de firewall) para o Z-Push acessar os servidores:
    • Servidor SMTP(S): 25 e/ou 465;
    • Servidor IMAP(S): 143 e/ou 993;
    • Banco de dados (postgreSQL): 5432;
    • Servidor LDAP: 389.

Instalação:

1) Faça o download da versão 1.4.3 do Z-Push no site  http://z-push.sourceforge.net/soswp/ e copie para a pasta raiz do Apache Web Server (Geralmente /var/www).
2) Sobrescreva com os arquivos customizados  http://trac.expressolivre.org/browser/contrib/z-push.
3) Mova o arquivo html2text, obtido no passo anterior, para a pasta /usr/local/bin/. Use o comando chmod para atribuir direitos de execução. Esse executável foi compilado em um servidor Debian 32 bits, para S.O. de 64 bits recomenda-se compilar o código fonte que pode ser obtido no site  http://www.mbayer.de/html2text/.
4) Configure os parâmetros IMAP_SERVER e IMAP_PORT no arquivo config.php.
5) Configure os parâmetros ANONYMOUS_BIND, LDAP_BIND_USER, LDAP_BIND_PASSWORD, LDAP_HOST, LDAP_PORT, LDAP_SEARCH_BASE e LDAP_SEARCH_FILTER no arquivo config.php.
6) Configure a conexão com o banco de dados no arquivo dbconnect.php que se encontra na pasta include.
7) Configure o Postfix (main.cf?), para que utilize o serviço de SMTP do Expresso.
8) Crie arquivo de debug:

touch /var/www/z-push/debug.txt

9) Crie um Alias no apache do z-push:

Alias /Microsoft-Server-ActiveSync /var/www/z-push/index.php

Dica: Caso seja usado um proxy para fazer redirecionamento de url, também deve ser incluída a regra:
"https://expresso.seu_dominio.gov.br/Microsoft-Server-ActiveSync" para: "https://ip_do_zpush/z-push/index.php"

10) Insira no arquivo php.ini:

php_flag magic_quotes_gpc off
php_flag register_globals off
php_flag magic_quotes_runtime off
php_flag short_open_tag on

11) Configure permissões:

chmod 755 /var/www/z-push/state
chown -R www-data. /var/www/z-push/
chmod 777 /var/www/z-push/debug.txt

12) Reinicie os serviços:

/etc/init.d/apache2 restart
/etc/init.d/postfix restart

13) Crie, no banco de dados do Expresso, o usuário zpush?.

14) Crie, no banco de dados do Expresso, as triggers do Z-Push?.

15) Agende, diariamente, a execução do seguinte script para excluir os arquivos da pasta state que não foram modificados nos últimos 4 meses.

#!/bin/sh
find /var/www/z-push/state/ -type f -mtime +120 -exec rm \{\} \;

Administração:

  • Arquivos de Logs:

/var/www/z-push/debug.txt
/var/www/z-push/trace-<LOGIN_USUARIO>.txt
/var/log/apache2/ssl_access.log
/var/log/apache2/access.log
/var/log/apache2/error.log

  • Nível de Debug:

Para aumentar o nível de debug do arquivo /var/www/z-push/debug.txt, definir a constante WBXML_DEBUG como “true” no arquivo /var/www/z-push/wbxml.php. (este nível de debug detalhado aumenta muito o tamanho dos arquivos de log além de aumentar o tempo de sincronização dos dispositivos móveis, não sendo recomendado a sua utilização por padrão)

  • Trace Detalhado:

Como o debug original do Z-Push mistura informações de todos usuários, foi criado o trace por usuário para auxiliar na solução de bugs. O trace também gera um log mais detalhado que o debug.

O trace detalhado pode ser habilitado no arquivo /var/www/z-push/config.php. Ele é habilitado por login, no parâmetro TRACE_UID, e por tipo(ALL, IMAP, CALENDAR ou CONTACTS), no parâmetro TRACE_TYPE, e gera um arquivo de saída chamado /var/www/z-push/trace-<LOGIN_USUARIO>.txt . É recomendado que o trace detalhado só fique habilitado quando necessário, caso contrário atribua o valor false(sem aspas) ao parâmetro TRACE_UID.

Para que o trace tenha um grande número de detalhes, deve-se atribuir true para a constante WBXML_DEBUG no arquivo /var/www/z-push/wbxml.php. Evite deixar essa opção habilitada mais tempo que o necessário, para não sobrecarregar o servidor.

Para que o arquivo de Trace não fique muito grande, no Exchange ActiveSync do celular, desative a sincronização automática(PUSH) e em seguida sincronize uma vez para que o servidor do Z-Push entenda que a sincronização automática foi desativada.

A cada sincronização, novos dados são adicionados ao arquivo de Trace do usuário. Para iniciar um trace zerado, basta apagar o arquivo antes de sincronizar.

Alguns problemas podem ser solucionados pesquisando pela palavra ERRO nas linhas que tem a string [TRACE], enquanto outros precisam ser inferidos através da análise do trace, do código-fonte, do S.O., do banco de dados, do PHP, do IMAP e do SMTP.

Para facilitar o entendimento do conteúdo do trace, é recomendado ter uma noção do funcionamento do protocolo  Exchange ActiveSync. O protocolo tem um conjunto pré-definido de comandos que são enviados pelos celulares e respondidos pelo servidor.

Segue exemplo de sequência de comandos do protocolo ActiveSync quando o celular acabou de ser configurado para uma primeira sincronização:

1) O celular envia o comando "Options request" e o servidor responde quais comandos o celular pode utilizar durante a sincronização.
2) O celular envia o comando "FolderSync" solicitando a sincronização de pastas(pastas de e-mail, pasta de contatos denominada "root" e pasta de calendário denominada "calendar") e o servidor retorna a lista de pastas(Found n folder changes).
3) Para cada pasta configurada para sincronizar seus itens, o celular envia o comando "Sync" e o servidor responde com a chave única(SyncKey) que será usada nas sincronizações desta pasta.
4) O celular envia o comando "GetItemEstimate" e o servidor responde quantos itens(Found n message changes) serão sincronizados em cada pasta.
5) Para cada pasta, o celular envia o comando "Sync" para sincronizar seus itens.

5.1) Se existem mudanças de itens feitas no celular, elas são enviadas e processadas pelo servidor(Processed n incoming changes).
5.2) Se existem mudanças de itens feitas no servidor(Found n message changes) , elas são enviadas para o celular.

O usuário é autenticado sempre que o celular envia um comando para o servidor.


EXEMPLO DE DEPURAÇÃO DE BUGS 01:

Suponha que uma das mensagens de e-mail, com data de dois dias atrás, não está aparecendo no celular do usuário com login “testeexpresso”. O filtro do celular está configurado para mostrar e-mails das duas últimas semanas. Para depurar esse problema, podemos fazer o seguinte:

1) Seguindo instruções descritas no tópico “Configuração e uso do Trace”, ative o trace de IMAP para o usuário “testeexpresso”;
2) Inicie uma sincronização, para criar o arquivo /var/www/z-push/trace-testeexpresso.txt;
3) Como somente um e-mail, dentre vários, não está sendo sincronizado, provavelmente o problema está somente neste e-mail. Talvez ele esteja com o cabeçalho mal formatado ou está correto e o Z-Push não esta conseguindo reconhecer. Vamos analisar o arquivo de trace;
4) No início do arquivo de trace, aparece o comando “Options request” que tem como finalidade apenas informar ao celular, quais comandos do ActiveSync são suportados pelo servidor. A maioria dos problemas não tem nada a ver com isso, inclusive o nosso;
5) Em seguida, vem o comando “FolderSync”, o qual tem como objetivo sincronizar as pastas(não o conteúdo das pastas) do servidor com o celular. Aqui precisamos verificar se a pasta INBOX, onde está armazenado o e-mail, é listada;
6) O próximo comando é o “GetItemEstimate” que lê as mensagens do servidor IMAP e retorna a quantidade de e-mails que precisam ser sincronizados, levando em conta o filtro de período. Aqui observamos que o nosso e-mail não está aparecendo. Agora precisamos saber porque o servidor IMAP não retorna o e-mail para o Z-Push. Como não está aparecendo nenhuma mensagem de erro no trace, vamos verificar o que tem diferente nesse e-mail em relação aos que estão funcionando;
7) Exportando o e-mail a partir da interface do Expresso, verificamos que o valor do campo date que aparece em seu cabeçalho é anterior ao período filtrado, isso nos indica que o Z-Push está agindo corretamente não sincronizando esse e-mail. Analisando o funcionamento da Importação de mensagens no Expresso, verificamos que a data que aparece na interface do Expresso é a que o e-mail foi importado e não a que está no servidor IMAP. Assim, concluímos que o problema é devido ao comportamento da rotina de importação de e-mails do Expresso. Possíveis soluções para este problema seriam o Expresso apresentar em sua interface a data armazenada no IMAP ou alterar a data armazenada no IMAP para a data da importação.


EXEMPLO DE DEPURAÇÃO DE BUGS 02:

Suponha que um evento de calendário criado no Expresso não está sendo sincronizado com o Celular do usuário com login “testeexpresso”. Veja a seguir como foi rastreado este problema:

1) Seguindo instruções descritas no tópico “Configuração e uso do Trace”, ative o trace de CALENDAR para o usuário “testeexpresso”;
2) Inicie uma sincronização, para criar um novo arquivo /var/www/z-push/trace-testeexpresso.txt;
3) No início do arquivo de trace, aparece o comando “Options request” que tem como finalidade apenas informar ao celular, quais comandos do ActiveSync são suportados pelo servidor. A maioria dos problemas não tem nada a ver com isso, inclusive o nosso;
4) Em seguida, vem o comando “FolderSync”, o qual tem como objetivo sincronizar as pastas(não o conteúdo das pastas) do servidor com o celular. Aqui verificamos se a pasta “Calendar”, onde é armazenado todos eventos de calendário, foi sincronizada. No arquivo de trace isso é indicado atráves da string “Sync folder:Calendar” ;
5) O próximo comando é o “GetItemEstimate” que lê os eventos de calendário do Banco de Dados e retorna a quantidade de eventos que serão sincronizados, levando em conta o filtro de período. Conforme pode ser visto nas seguintes linhas de Trace, aparece um erro indicando que o valor 10095 do campo reference é inválido. Quando o valor do campo reference é diferente de zero, significa que o evento é do tipo único, filho de um evento recursivo. O trace detectou a inconsistência porque não existe um evento recursivo com chave primária igual a 10095, logo o evento filho é órfão. Como existe uma inconsistência no Banco de Dados, o campo reference precisa ser atualizado para o valor zero ou esse evento precisa ser excluído:

05/12/11 11:01:33 [11155] [testeexpresso] [TRACE] CalendarExpresso::GetMessageList-> ERRO: Evento com campo reference inválido (cal_id: 11329, title: teste, reference: 10095, last_update: 13/04/2011 16:11:28, last_update_timestamp: 1302721888214, datetime: 09/12/2010 10:00:00, datetime_timestamp: 1291896000, cal_type: E)

Os exemplos apresentados não pretendem esgotar os inúmeros caminhos que a depuração pode seguir, mas sim dar uma ideia inicial de como a depuração é feita.