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.