User:Grawlinson/z-push

From ArchWiki
Warning: This entire page is incomplete. Here be dragons.

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]


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

Warning: It is recommended to use HTTPS instead of plain HTTP, see Apache HTTP Server#TLS, Lighttpd#Enabling_https_via_SSL or Nginx#TLS for examples and implement this in the examples given below.

Depending on which web server you are using, further setup is required, indicated below.

Tip: Configuration snippets for Apache, lighttpd and nginx are included in /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

Warning: This setting will set Z-Push to log the detailed information for every user on the system. You can set a different log level for particular users by adding them comma separated to $specialLogUsers in /etc/z-push/z-push.conf.php $specialLogUsers = array("user1", "user2", "user3");
Note: Be aware that if you are using 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.

See also

General

Documentation