User:Grawlinson/z-push
Wikipedia:Z-Push is a FOSS implementation of the Wikipedia:Exchange ActiveSync protocol which is used to synchronize email, personal contacts and other items between a central server and a mobile device. Devices supported are Windows Mobile, Android, iPhone, and Nokia. With Z-Push any groupware can be connected and synced with these devices.
Prerequisites
Z-Push requires several components:[1]
- A web server: Apache HTTP Server, nginx or lighttpd
- PHP with additional modules
- (optional) database: MariaDB/MySQL, PostgreSQL, SQLite or Open Database Connectivity
These will be configured in #PHP setup.
Make sure the required components are installed before proceeding.
Installation
Install the z-pushAUR package, and additional components depending on your needs: (*TODO*: backends, ipc, and other packages).
Configuration
Backends
Inter Process Communication (IPC)
State Directory
Log Directory
Hosting
Web Server
Depending on which web server you are using, further setup is required, indicated below.
/usr/share/doc/z-push
.Apache
If you have not already, install Apache HTTP Server and install and enable Apache's PHP module
Copy the Apache configuration file to the configuration directory:
# cp /usr/share/doc/z-push/apache2/z-push.conf /etc/httpd/conf/extra
Modify the file according to your preferences. By default it includes an alias for /Microsoft-Server-ActiveSync
pointing to /usr/share/z-push/index.php
.
And include it in /etc/httpd/conf/httpd.conf
:
Include conf/extra/z-push.conf
Ensure that the root location of your Z-Push installation (e.g., /usr/share/z-push
) is accessible by the webserver's user http
.
Now restart Apache (httpd.service
).
lighttpd
Enable lighttpd#FastCGI, e.g. by adding server.modules += ( "mod_fastcgi" )
to /etc/lighttpd/lighttpd.conf
.
Copy the lighttpd configuration file to the configuration directory:
# cp /usr/share/doc/z-push/lighttpd/z-push.conf /etc/lighttpd
Modify the file according to your preferences.
nginx
Make sure #php-fpm has been configured correctly.
Create a server block and add the content according to the documentation.
nginx.conf
upstream php-handler { server unix:///run/php-fpm/php-fpm.sock; } server { # ... root /usr/share/z-push; # php-fpm configuration include fastcgi.conf; fastcgi_index index.php; fastcgi_param PHP_FLAG "magic_quotes_gpc=off \n register_globals=off \n magic_quotes_runtime=off \n short_open_tag=on"; fastcgi_param PHP_VALUE "post_max_size=20M \n upload_max_filesize=20M \n max_execution_time=3660"; fastcgi_read_timeout 3660; # Z-Push Ping might run 3600s, but to be safe location /Microsoft-Server-ActiveSync/ { alias /usr/share/z-push/index.php; access_log /var/log/nginx/z-push-access.log; error_log /var/log/nginx/z-push-error.log; # Attachments ca 15MB max (since binary data needs to be base64 encoded in mine, which results in in about 33% overhead) client_max_body_size 20m; client_body_buffer_size 128k; }
See nginx#FastCGI for more information on using FastCGI with nginx.
php-fpm
php-fpm is PHP's FastCGI implementation. It can be used by web servers that support the protocol.
Add an additional pool that runs as the z-push
user/group:
/etc/php/php-fpm.d/z-push.conf
[z-push] user = z-push group = z-push ; should be accessible by your web server listen.owner = http listen.group = http listen = /run/php-fpm/z-push.sock ; note: pm* parameters should also be tweaked depending on hardware capabilities ; uncomment environment variables env[PATH] = /usr/local/bin:/usr/bin:/bin env[TMP] = /tmp ; additonal parameters as per upstream documentation ; minimum of 128M required php_admin_value[memory_limit] = 128M ; increase/decrease based on e-mail attachment size limit php_admin_value[upload_max_filesize] = 20M php_admin_value[post_max_size] = 20M ; limit filesystem access php_admin_value[open_basedir] = ${open_basedir}:/usr/share/z-push:/etc/z-push:/var/lib/z-push:/var/log/z-push:/etc/mime.types:/usr/share/awl/inc ; change to server timezone php_admin_value[date.timezone] = Etc/UTC ; other settings php_admin_value[max_execution_time] = 3660 php_admin_flag[magic_quotes_gcp] = off php_admin_flag[register_globals] = off php_admin_flag[magic_quotes_runtime] = off php_admin_flag[short_open_tag] = on
The php-fpm service runs with the system mounted as read-only for hardening purposes, so it is necessary to explicitly grant write permissions on the appropriate paths.
Create an override.conf
for php-fpm
:
# systemctl edit php-fpm.service
Add and save following content.
/etc/systemd/system/php-fpm.service.d/override.conf
[Service] # Data directory ReadWritePaths=/var/lib/z-push # Log directory ReadWritePaths=/var/log/z-push
Enable and start the php-fpm
service.
fail2ban
In order for fail2ban to effectively catch the failed login attempts, LOGAUTHFAIL
configuration parameter must be enabled in /etc/z-push/z-push.conf.php
.
/etc/fail2ban/filter.d/z-push.conf
[INCLUDES] before = common.conf [Definition] failregex = IP: <HOST> failed to authenticate user ignoreregex =
/etc/fail2ban/jail.d/z-push.conf
[z-push] enabled = true port = http,https filter = z-push logpath = /var/log/z-push/z-push-error.log
Troubleshooting
Most problems will be caused by incorrect web server settings. To test whether the web server setup is working correctly, you can simply type the Z-Push URL in your browser, to see if the web server is correctly redirecting your request to Z-Push. You can simply use: https://your.server.tld/Microsoft-Server-ActiveSync
If correctly configured, you should see a username/password request and when you specify a valid username and password, you should see a Z-Push information page, saying that this kind of request is not supported. Without authentication credentials Z-Push displays general information.
If not then check your web server settings and error logs.
Increase log verbosity for debugging
/etc/z-push/z-push.conf.php
$specialLogUsers = array("user1", "user2", "user3");
LOGLEVEL_DEBUG
and LOGLEVEL_WBXML
Z-Push will be quite talkative, so it is advisable to use log-rotate on the log file. Or better yet, revert back to LOGLEVEL_WARN
once debugging is complete.If you have other synchronisation problems, you can increase the LOGLEVEL
parameter in /etc/z-push/z-push.conf.php
e.g. to LOGLEVEL_DEBUG
or LOGLEVEL_WBXML
. The log file will then collect detailed debug information from your synchronisation.
Repeated incorrect password messages
If a password contains characters which are encoded differently in ISO-8859-1 and Windows-1252 encodings (e.g. "§") the login might fail with Z-Push but it works fine with the WebApp/Webaccess. The solution is to add setlocale(LC_CTYPE, "en_US.UTF-8");
to /etc/z-push/z-push.conf.php
.