First pass at EAS' best practices for SOGo

Documentation/SOGoInstallationGuide.asciidoc

@@ -2354,8 +2354,8 @@ easier. These GUI utilities can make use of templates to create and
 pre-configure typical user accounts or any standardized LDAP record,
 along with the correct object classes, fields and default values.
 
-Microsoft ActiveSync
---------------------
+Microsoft Enterprise ActiveSync
+-------------------------------
 
 SOGo supports the Microsoft ActiveSync protocol.
 
@@ -2469,6 +2469,83 @@ and send an email to iplicreq@microsoft.com
 Inverse inc. provides this software for free, but is not responsible for
 anything related to its usage.
 
+Microsoft Enterprise ActiveSync Tuning
+--------------------------------------
+
+First of all, it is important to know that most EAS devices will keep
+HTTP connections open to SOGo (and thus, Apache) for a long time. This
+is required for "push" to work properly. Connections can stay open for
+up to one hour, or 3600 seconds.
+
+The first parameter to check is related to Apache's proxying to
+SOGo:
+
+----
+ProxyPass /Microsoft-Server-ActiveSync \
+ http://127.0.0.1:20000/SOGo/Microsoft-Server-ActiveSync \
+ retry=60 connectiontimeout=5 timeout=360
+----
+
+The above line sets a timeout for up to 360 seconds, or 6 minutes. If
+you want to let EAS clients keep their HTTP connections open for up
+to an hour, you must change the timeout parameter and set it to 3600.
+
+If you change this value, the WOWatchDogRequestTimeout parameter must be changed
+accordingly in SOGo's configuration file (/etc/sogo/sogo.conf). By default,
+a SOGo child process is allowed to handle a request that can take up
+to 10 minutes before it gets killed by its parent process. When using
+EAS "push", the client expects to keep its connection open for up to one
+hour - so the WOWatchDogRequestTimeout, which is set in minutes,
+must be adjusted accordingly.
+
+EAS clients will keep HTTP connections open for a long time
+during these two EAS commands: Ping and Sync. By default, SOGo will prevent
+EAS clients from keeping connections for a long time. This is to avoid the
+situation where all SOGo child processes would be monopolized by EAS clients -
+rendering the SOGo web interface or DAV interface unavailable. The
+default SOGo behavior is thus similar to disable EAS push entirely.
+
+Two SOGo configuration parameters are available to modify this behavior:
+SOGoMaximumPingInterval (set by default to 10 seconds) and
+SOGoMaximumSyncInterval (set by default to 30 seconds). If you want
+connection to stay open for up to one hour, you should set these
+slightly under 3600 seconds (say 3540 - or 59 minutes). During a
+long-lived HTTP connection, the SOGo child process will perform
+internal polling to detect changes and return them to the EAS client
+if any changes are found. The parameter used to control this
+is SOGoInternalSyncInterval. By default, polling is done every 10
+seconds. This might generate too much load on large-scale system.
+
+The last configuration parameter to adjust is WOWorkersCount - which sets the
+number of SOGo child process that will be used to handle requests.
+You should have at least one child per EAS device configured to use
+"push". You must also have more children than you have EAS devices
+configured to use "push" - in order to handle normal SOGo requests to
+its Web or DAV interfaces.
+
+Here are some usage examples for EAS devices using "push". In all
+cases, the Apache timeout is set to 3600 and the
+WOWatchDogRequestTimeout parameter is set to 60.
+
+Example 1 - 100 users, 10 EAS devices:
+
+----
+WOWorkersCount = 15;
+SOGoMaximumPingInterval = 3540;
+SOGoMaximumSyncInterval = 3540;
+SOGoInternalSyncInterval = 30;
+----
+
+Example 2 - 1000 users, 100 EAS devices:
+
+----
+WOWorkersCount = 120;
+SOGoMaximumPingInterval = 3540;
+SOGoMaximumSyncInterval = 3540;
+SOGoInternalSyncInterval = 60;
+----
+
+
 Using SOGo
 ----------
 

NEWS

@@ -7,6 +7,7 @@ New features
 Enhancements
  - added support for email categories using EAS (#2995)
  - now possible to always send vacation messages (#2332)
+ - added EAS best practices to the documentation
 
 Bug fixes
  - (regression) fixed sending a message when mail module is not active (#3088)