OX6:MailNotify Bundle

Open-Xchange Mail Push

Beginning with the 6.16 release, there's a new bundle handling external notifications of new mail to send push requests to mobile devices.

Description

This Bundle is currently only able to cooperate with the mail notification functionality of cyrus-imapd, but this will change in a way, that future versions will be configurable on what kind of notification protocol is required.

At the moment, this bundle listens on the address and port as configured in /opt/open-xchange/etc/groupware/push_mailnotify.properties accepting UDP datagrams following the format as used in the cyrus notifyd:

notifyd/notifyd.c:
method NUL class NUL priority NUL user NUL mailbox NUL nopt NUL N(option NUL) message NUL

and the only information which is currently being evaluated is the fourth one, the username.

Install on OX AppSuite

Debian GNU/Linux 11.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/stable/DebianBullseye/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/stable/updates/DebianBullseye/ /

and run

$ apt-get update
$ apt-get install open-xchange-push-mailnotify

Debian GNU/Linux 12.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/stable/DebianBookworm/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/stable/updates/DebianBookworm/ /

and run

$ apt-get update
$ apt-get install open-xchange-push-mailnotify

Configuration

On the server running cyrus, add the following to /etc/imapd.conf:

mailnotifier: log

In /etc/cyrus.conf take care, that cyrus own notifyd is NOT in use. If it is not commented, either do that or remove it completely.

Example:

 # this is only necessary if using notifications
 #  notify       cmd="notifyd" listen="/var/lib/imap/socket/notify" proto="udp" prefork=1

Install the program socat. Socat is a Multipurpose relay (see http://www.dest-unreach.org/socat/) which must be used to relay the udb datagrams from the unix domain socket to the open-xchange push bundle.

To redirect the notifications to the open-xchange server, socat must be started like this:

socat -u -4 UNIX-RECV:/var/lib/imap/socket/notify,unlink-early,perm-early=777,type=2 \
         UDP-SENDTO:<YOUROXIP>:<YOURPUSHPORT>

To debug whether cyrus sends messages, you might want to add debugging to socat:

socat -d -d -d -D -v -u -4 UNIX-RECV:/var/lib/imap/socket/notify,unlink-early,perm-early=777,type=2 \
         UDP-SENDTO:<YOUROXIP>:<YOURPUSHPORT>

Example Initscript for Debian

The following initscript can be used to start the socat tunnel on debian. A file /etc/default/ox-push can be created to define parameters such as DAEMON_ARGS.

After copying the script to /etc/init.d/ox-push do the following:

$ chmod 755 /etc/init.d/ox-push
$ update-rc.d ox-push defaults

#! /bin/sh
### BEGIN INIT INFO
# Provides:          ox-push
# Required-Start:    $local_fs $remote_fs open-xchange-groupware
# Required-Stop:     $local_fs $remote_fs
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: UDP Tunnel for Open-Xchange mail push
# Description:       Tunnel UDP Datagrams from cyrus notify unix socket
#                    to Open-Xchange Mail Push bundle
### END INIT INFO

# Author: Carsten Hoeger <choeger at open-xchange.com>

# Do NOT "set -e"

# PATH should only include /usr/* if it runs after the mountnfs.sh script
PATH=/sbin:/usr/sbin:/bin:/usr/bin
DESC="Open-Xchange Push Tunnel"
NAME=socat
DAEMON=/usr/bin/$NAME
DAEMON_ARGS="-u -4 UNIX-RECV:/var/lib/imap/socket/notify,unlink-early,perm-early=777,type=2 UDP-SENDTO:localhost:23420"
PIDFILE=/var/run/$NAME.pid
SCRIPTNAME=/etc/init.d/$NAME

# Exit if the package is not installed
[ -x "$DAEMON" ] || exit 0

# Read configuration variable file if it is present
[ -r /etc/default/$NAME ] && . /etc/default/$NAME

# Load the VERBOSE setting and other rcS variables
. /lib/init/vars.sh

# Define LSB log_* functions.
# Depend on lsb-base (>= 3.0-6) to ensure that this file is present.
. /lib/lsb/init-functions

#
# Function that starts the daemon/service
#
do_start()
{
	# Return
	#   0 if daemon has been started
	#   1 if daemon was already running
	#   2 if daemon could not be started
	start-stop-daemon --start -b --quiet -m --pidfile $PIDFILE --exec $DAEMON --test > /dev/null \
		|| return 1
	start-stop-daemon --start -b --quiet -m --pidfile $PIDFILE --exec $DAEMON -- \
		$DAEMON_ARGS \
		|| return 2
	# Add code here, if necessary, that waits for the process to be ready
	# to handle requests from services started subsequently which depend
	# on this one.  As a last resort, sleep for some time.
}

#
# Function that stops the daemon/service
#
do_stop()
{
	# Return
	#   0 if daemon has been stopped
	#   1 if daemon was already stopped
	#   2 if daemon could not be stopped
	#   other if a failure occurred
	start-stop-daemon --stop --quiet --retry=TERM/30/KILL/5 --pidfile $PIDFILE --name $NAME
	RETVAL="$?"
	[ "$RETVAL" = 2 ] && return 2
	# Many daemons don't delete their pidfiles when they exit.
	rm -f $PIDFILE
	return "$RETVAL"
}


case "$1" in
  start)
	[ "$VERBOSE" != no ] && log_daemon_msg "Starting $DESC" "$NAME"
	do_start
	case "$?" in
		0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
		2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
	esac
	;;
  stop)
	[ "$VERBOSE" != no ] && log_daemon_msg "Stopping $DESC" "$NAME"
	do_stop
	case "$?" in
		0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
		2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
	esac
	;;
  restart|force-reload)
	#
	# If the "reload" option is implemented then remove the
	# 'force-reload' alias
	#
	log_daemon_msg "Restarting $DESC" "$NAME"
	do_stop
	case "$?" in
	  0|1)
		do_start
		case "$?" in
			0) log_end_msg 0 ;;
			1) log_end_msg 1 ;; # Old process is still running
			*) log_end_msg 1 ;; # Failed to start
		esac
		;;
	  *)
	  	# Failed to stop
		log_end_msg 1
		;;
	esac
	;;
  *)
	echo "Usage: $SCRIPTNAME {start|stop|restart|force-reload}" >&2
	exit 3
	;;
esac

: