Skip to content

Latest commit

 

History

History
753 lines (493 loc) · 30.3 KB

ng-mobile.adoc

File metadata and controls

753 lines (493 loc) · 30.3 KB
Raw

Mobile NG

Enable Mobile NG Synchronization for a COS

By enabling Mobile NG for a all users in a Class of Service, you authorize all users in that COS to use all the mobile functions of Mobile NG.

How to Enable Mobile NG for all Users in a Class Of Service

From the Administration Console

To enable Mobile NG for all users in a COS from the Administration Console:

  • Open the Zimbra Administration Console.

  • Double-click the Class Of Service you want to edit (on the left, under Configuration → Class of Service).

  • Click the Mobile tab.

  • Check the Enable mobile synchronization button.

From the Zimbra CLI

To enable Mobile NG for all users in a COS from the CLI:

  • As the 'zimbra' user run: zmprov mc COSName zimbraFeatureMobileSyncEnabled TRUE

How to Disable Mobile NG for all Users in a Class Of Service

From the Administration Console

To disable Mobile NG for all users in a COS from the Administration Console:

  • Open the Zimbra Administration Console.

  • Double-click the Class Of Service you want to edit (on the left, under Configuration → Class of Service).

  • Click the Mobile tab and uncheck the Enable mobile synchronization button.

From the Zimbra CLI

To disable Mobile NG for all users in a COS from the CLI:

  • As the 'zimbra' user run: zmprov mc COSName zimbraFeatureMobileSyncEnabled FALSE

Note about Settings Hierarchy

COS-level settings are overridden by user-level settings.

Enable Mobile NG for a Single User

By enabling the Mobile NG Module for a single user you authorize a single user to use all the mobile functions of the Mobile NG Module.

How to Enable Mobile NG for a Single User

From the Zimbra Administration Console

To enable Mobile NG for a single user from the Administration Console:

  • Open the Zimbra Administration Console.

  • Double-click the user you want to edit (on the left, under Manage → Accounts).

  • Click the Mobile tab.

  • Check Enable mobile synchronization.

From the Zimbra CLI

To enable Mobile NG for a single user from the CLI:

  • As the 'zimbra' user run: zmprov ma user@domain.tld zimbraFeatureMobileSyncEnabled TRUE

How to Disable Mobile NG for a Single User

From the Zimbra Administration Console

To disable Mobile NG for a single user from the CLI:

  • Open the Zimbra Administration Console.

  • Double-click the user you want to edit (on the left, under Manage → Accounts).

  • Click the Mobile NG tab and uncheck Enable mobile synchronization.

From the Zimbra CLI

To disable Mobile NG for a single user from the CLI:

  • As the 'zimbra' user run: zmprov ma user@domain.tld zimbraFeatureMobileSyncEnabled FALSE

Note about Settings Hierarchy

User-level settings override COS-level settings.

The Mobile Password Feature

Mobile Passwords and You

The Mobile Password feature allows to set an additional password for an account to be used for Exchange ActiveSync authentications only.

The main benefits of using this feature are:

  • Enforce set-and-forget safe passwords, regardless of any other password policy, so that you won’t need to change the password saved on all mobile devices synchronized with an account should this account’s Zimbra password change.

  • Avoid the real password to be disclosed in case of unauthorized access to the device/client.

A Mobile Password will not be valid for Webmail/POP3/IMAP/SMTP logins, and the account password will not be valid for mobile logins.

Data Storage

Both Mobile Passwords and QR Code data is saved in a local HSQL database.

All passwords, tokens and sensitive information are stored in hashed form using the SHA256 algorithm using auto-generated keys and no credential or sensitive information is ever stored cleartext.

How to Set a Mobile Password for a Mailbox

versions up to 8.8.15 patch15 versions up to 9.0.0 patch8

  • Open the Zimbra Administration Console.

  • Right-click the user for which you want to set a Mobile Password and select Edit.

  • In the Mobile tab within the user’s settings, check the Enable mobile password checkbox.

  • Enter the desired password in the Mobile password field and enter it again in the Confirm mobile password field. You can also choose to generate a random mobile password by clicking btn:[Generate random password].

  • btn:[Save].

Zimbra 8.8.15 patch 16+ Zimbra 9.0.0 patch9+ (Classic UI) Starting from Zimbra 8.8.15p16 and 9.0.0p9, Mobile Passwords are now managed by the user via the new Auth Zimlet, which can be installed by running zxsuite auth doDeployAuthZimlet.

Tip
 This new Mobile Password management system allows the user to set multiple independent Mobile Passwords for an account, to be used with different devices.

Once the Zimlet is deployed and enabled, the user can create a new Mobile Password following this steps:

  • Open the Zextras Auth Zimlet and click on "New Password";

  • Enter an easy to remember identifier for the password in the "Password Label" field and select "Text code" as the Password Type;

  • Click "Next";

  • The new Mobile Password will be displayed;

Warning
 Mobile Passwords are randomly generated and cannot be displayed again after the creation is complete.

  • Click on "Done" to close the Zextras Auth window. An entry for the new Mobile Password is now visible in the "Active Passwords" list of the Zextras Auth Zimlet.

Admins can also create a Mobile Password from the CLI, use the zxsuite auth credential command with the following attributes:

  • password: enter the password you wish to set as the Mobile Password

  • label: enter the label for the Mobile Password

  • service: use eas to set a Mobile Password

E.g. To add the gn89hg95hvmn59..] Mobile Password to the john.doe@domain.com account, labeled as "Personal Phone", run:

zxsuite auth credential add john.doe@domain.com password "gn89hg95hvmn59..]" label "Personal Phone" service eas

The system will confirm the success of the operation and display all the password’s information:

Credential correctly added

        values
            generated                                               0
            created                                                 1603120995372
            label                                                   Personal Phone
            id                                                      Fr2jM
            services

                    service                                                         EAS
            hash                                                    +Crk6YcPL7IapCg6xfT6oXWP977uTeZdJTVQDQZd+Io=
            enabled                                                 true
            algorithm                                               SHA256
        text_data
            auth_method                                             password
            password                                                gn89hg95hvmn59..]
            user                                                    john.doe@domain.com

List existing Mobile Passwords

Any user can see the list of active Mobile Passwords in the Zextras Auth Zimlet. Each entry of the list displays the label of the password, its status, the service it is valid for and its creation date.

Specifically, all passwords valid for the "EAS" service are Mobile Passwords.

System Administrators, on the other hand, can view an extended list of all credentials, including Mobile Passwords,

Editing a Mobile Password

While a Mobile Password itself cannot be edited, the System Administrator can edit its label and properties using the zxsuite auth credential update command

Application Password (QR Code)

The Auth Zimlet can speed up and manage Application logins, such as those for the Drive and Team/Connect apps made by Zextras.

This is achieved through the creation of a QR Code in the Zimbra WebClient, which the user can then scan from the App’s login page to log in.

Warning
 QR Codes are a one-time credential only, meaning that once generated it will grant access to the app until the relevant credential itself is deleted from the account. Once generated, the QR Code can only be viewed once.

QR Code Requirements

The QR Code Application Password feature requires the following properties to be set at domain level in order to be functional:

  • zimbraPublicServiceHostname

  • zimbraPublicServicePort

  • zimbraPublicServiceProtocol

Should one or more of the properties be unset, a notification will be delivered to the Admin reporting the affected domains and their missing properties.

Creating a new QR Code Credential

While, as all credentials, QR Codes can be created from both the Zextras Auth Zimlet and Zextras CLI, only the former allows the user to use the QR code itself so the latter will not be taken into consideration in this guide.

Creating a QR Code Credential from the Zextras Auth Zimlet

To create a new QR Code, open the Auth Zimlet and click on "New Password";:

  • Enter an easy to remember identifier for the password in the "Password Label" field and select "QR code" as the Password Type;

  • Click "Next";

  • The new QR Code will be displayed;

Warning
 QR Codes are randomly generated and cannot be displayed again after the creation is complete.

  • Click on "Done" to close the Auth Zimlet. An entry for the new QR Code is now visible in the "Active Passwords" list of the Auth Zimlet.

Mobile Device Management a.k.a. Mobile Provisioning

What is Mobile Device Management?

Mobile Device Management (MDM - also known as provisioning) allows an administrator to define a set of rules and security settings that are applied Over The Air to one or more mobile devices, ranging from PIN policies to Allowed/Blocked app lists and including one time commands, such as the remote wipe of the entire device.

MDM effectively allows administrators to limit and restrict the use of corporate mobile devices to avoid risky or improper behaviors.

MDM is also a priceless aid for Bring Your Own Device corporate policies, allowing users to connect their personal mobile devices to the corporate servers, while minimizing the risk of security breaches.

Provisioning Features Available on Your Client

Not all provisioning features are available on all clients.

Network NG and MDM

Network NG features advanced MDM features through the Exchange ActiveSync protocol version 14+.

Mobile policies can be enabled at COS and mailbox levels, allowing both a quick 'one-for-many' setup and user-based customized management. In both cases, Mobile Management Options are available in the Mobile tab.

Provisioning Options

The following provisioning options are available:

  • Enable Mobile Device Management: Enable or disable the use of mobile policies for the current user/COS.

  • Allow non-provisionable devices: Allow the user to synchronize any device that does not support provisioning.

  • Allow partial policy enforcement on device: Allow the user to synchronize any device that does not support one or more applicable policies.

Tip
 By default, MDM is disabled in NG MobileSync. To enable navigate to Network Modules NG → Mobile → Advanced Settings and check the “Enable Mobile Device Management” option

Enforceable Policies

Enforceable Policies are available right below the Mobile Devices list, grouped in the following categories:

  • Sync Settings: Set synchronization spans and limits.

  • Device Settings: Enable or disable device features such as camera, WiFi, removable storage or Bluetooth.

  • Device Security Settings: Force an unlock code and define the minimum requirements for the code itself.

  • Device Applications: Enable or disable standard device applications such as the Browser and POP/IMAP client or unsigned apps.

Two lists are also available for application whitelist/blacklist management:

  • Approved Applications: A customizable list of approved applications.

  • Blocked Applications: A customizable list of blocked applications that won’t be usable on the device.

Mobile Password

While conceptually similar, the mobile password feature is not part of Mobile Device Management and can be used with any version of the EAS protocol.

SyncStates

Mobile NG and the SyncState

The SyncState (short for Synchronization Status) is a set of information kept on the server about the synchronization with a mobile device. Each time a device establishes a connection with Mobile NG, the following steps take place:

  • 1. The device requests a folderSync operation to synchronize the local Folders with the ones on the server.

    One SyncKey per local folder is sent (or a single SyncKey set to '0' if this is the first connection between the device and the server)   

  • 2. The server replies with a list of available folders.

    One SyncKey per folder is sent by the server.

  • 3. Then, the device requests an itemSync operation to synchronize all due items.

    The server stores the items synchronized in the SyncState.

  • 4. After completing the itemSync operation, the device sends a 'ping' command to keep the connection alive.

    Step 4 is repeated as long as no changes happen to the synchronized account.

Every time a new item is stored on the mailbox or an old item is modified, the server notifies the availability to the device, which closes the active connection (the one kept alive by the ping command) and repeats steps 3 and 4.

The SyncState is the combination of the SyncKeys saved on step 2 and the itemIds saved on step 3. It’s saved by the server per the userId/deviceId unique pair.

Sync Request

The Sync Request is the actual synchronization process, started by either Mobile NG or by the client. During a sync request, any change in the mailbox that happened since the last request is synchronized to the device and vice versa.

A sync request is issued when:

  • The SyncState changes.

  • A sync is forced client-side.

  • The current ping expires and a new one is sent by the device (the keepalive duration is defined by the client).

Managing the SyncStates

Via the Administration Zimlet

Mobile NG provides two options in the Administration Zimlet to manage the SyncStates of synchronized mobile devices:

  • Reset Device: Resets the device’s SyncState for a single account, forcing a full re-synchronization the next time the device connects to the server.

  • Wipe Device: Removes all the device’s SyncState and history from the server. Useful when a mobile device is not used anymore or is assigned to a different employee in the same company.

Via the CLI

To manage the SyncStates of synchronized mobile devices via the CLI, use one of the following commands:

The doRemoveDevice command
Syntax:
   zxsuite mobile doRemoveDevice {account} {device_id}

PARAMETER LIST

NAME            TYPE
account(M)      Account Name
device_id(M)    String

(M) == mandatory parameter, (O) == optional parameter

Usage example:

zxsuite mobile doRemoveDevice john@example.com Appl79032X2WA4S
Removes John's Appl79032X2WA4S device SyncState
The doResetAccount command
Syntax:
   zxsuite mobile doResetAccount {account}

PARAMETER LIST

NAME          TYPE
account(M)    Account Name

(M) == mandatory parameter, (O) == optional parameter

Usage example:

zxsuite mobile doResetAccount john@example.com
Resets all the device states for John's account
The doResetDevice command
Syntax:
   zxsuite mobile doResetDevice {account} [attr1 value1 [attr2 value2...

PARAMETER LIST

NAME            TYPE            DEFAULT
account(M)      Account Name
device_id(O)    String          all

(M) == mandatory parameter, (O) == optional parameter

Usage example:

zxsuite mobile doResetDevice john@example.com Appl79032X2WA4S
Resets John's Appl79032X2WA4S device SyncState

Advanced Settings

Mobile NG DoS Filter

Mobile NG includes a dedicated DoS Filter component to improve both security and stability. The filter will kick in whenever a device exceeds the chosen connection rate over time and will "jail" the device for a set period of time, refusing any connections from it.

This improves both security, helping to prevent Denial of Service attacks, and stability by blocking clients that are performing too many requests due to bugs or malfunctioning saving resources for all other clients.

Warning
 The Mobile DoS filter is disabled by default, and can be enabled as needed via CLI.

Configuration

The Mobile DoS Filter is entirely configured via CLI, using the following NG attributes:

  • mobileAntiDosServiceEnabled: enable the Mobile DoS Filter service. Default false;

  • mobileAntiDosServiceJailDuration: duration (in milliseconds) of synchronization "jail". Default 600000;

  • mobileAntiDosServiceTimeWindow interval of time to calculate the connection ratio. The jail is triggered if a device sends more than mobileAntiDosServiceMaxRequests requests in this time window. Default 30000ms;

  • mobileAntiDosServiceMaxRequests maximum number of requests received within mobileAntiDosServiceTimeWindow milliseconds). Default 150;

All attributes are set at global level with zxsuite config global set|get|clear. Specific info for each property can be obtained via zxsuite config info attribute [propertyname].

How Mobile DoS Filter works

When the anti-dos service is running and mobileAntiDosMaxRequests is greater than 0, the system stores in memory the timestamp of the last mobileAntiDosMaxRequests requests. If the maximum number of request timestamps has been stored and all stored requests are within the time window, all new requests from this device/account are dropped for mobileAntiDosJailDuration milliseconds.

When the rate has been exceeded, a warning is sent via email to admin and added to server notifications.

Note
 Issuing the command zxsuite mobile doRestartService anti-dos will reset all jails and counters.

Mobile NG Performance Tuning

Mobile NG provides three useful options to fine-tune Mobile NG according to system performance.

Performance Tuning Settings

Available Settings

  • Notifications Latency (ZxMobile_NotificationsLatency): The seconds of delay between an event on the server and its notification to the mobile device.

  • Use Instant Notifications (ZxMobile_UseInstantNotficiations): Enable/Disable instant notifications. Overrides Notifications Latency if true.

  • Max Ping Heartbeat (ZxMobile_MaxPingHeartbeat): Maximum interval between 'ping' commands.

All settings can be edited in the Administration Zimlet or via CLI using the setProperty command.

When to Edit the Performance Tuning Settings

Default settings should be optimal for most situations. If you experience one or more of the problems below, please apply the proper solution.

Problem Solution

High system load

Disable instant notifications

High system load after disabling instant notifications

Raise notification latency

Mobile users experience high network usage

Disable instant notifications and tweak notifications latency

Devices can connect but sessions are interrupted frequently

Adjust Max Ping Heartbeat according to your network configuration

Items are synchronized from server-to-device with an excessive delay

Lower notification latency or enable instant notifications

Shared Folders

Shared Folders and You (and Your Mobile)

With Network NG, it’s possible to synchronize folders that are not owned by the user itself to mobile devices. This applies to all item types available through the Exchange ActiveSync protocol, so you’ll be able to sync any shared email folder, address book, calendar or task list to mobile devices.

Specific features available on mobile devices might differ, based on the client in use.

Warning
 Not all clients support the synchronization of multiple address books, calendars or task lists via Exchange ActiveSync.

How to Sync a Shared Folder to Your Mobile Devices

To allow a higher level of control over synchronization, users are allowed to choose which shared folders are to be synchronized with their mobile devices.

Enable Mobile Synchronization for a Folder

To enable mobile synchronization for a shared folder:

  • Log in to the {product-short} {web-client}.

  • Right-click the shared folder you want to sync.

  • Select Folder Sync Settings in the drop-down menu.

  • Check the Enable synchronization for this folder checkbox.

  • Press OK.

The new folder will be synchronized to any mobile device connected to the account.

Restrictions

The following restrictions apply to shared folder synchronization:

  • It’s not possible to sync a mountpoint referring to a full account share.

  • It’s not possible to sync a subfolder of a shared folder, as doing so would return an incomplete folder tree.

  • It’s not possible to sync a read-only share, as the Exchange ActiveSync protocol does not envision the concept of a read-only resource. Synchronizing a read-only folder will cause severe inconsistencies between the client and the server, along with many errors.

EAS Filters

In the EAS protocol, the protocol version used for the synchronization is defined during the initial handshake and never changed. The server presents a list of all available protocol versions and the client chooses one among that list.

EAS filters are a way to limit the EAS version available to a subset of users or clients to ensure that the proper version is used.

Multiple EAS filters can be set up and will be evaluated in sequential order (see the getAllEASFilters and doMoveEASFilter commands below).

Anatomy of an EAS Filter

An EAS filter is composed of 5 parts:

  • Type: Defines the type of filter rule.

  • Parameter: The filtering identifier (e.g. device brand or email address).

  • Mode: Defines whether the software will limit the available versions or provide a fixed list.

  • easversions field: Contains the protocol versions enforced by the filter.

  • Blocking boolean value: Defines whether other filters are executed once the current one is successfully matched.

Managing EAS Filters

EAS filters are managed through the CLI using the following four dedicated commands.

zxsuite mobile getAllEASFilters

This command lists all existing filters.

Sample Output:

        filters

                ID                                                          0
                mode                                                        fixed
                rule                                                        [type = or; rules = [[type = contains; rule = outlook/] OR [type = contains; rule = microsoft.outlook]]
                easversions                                                 14.0
                blocking                                                    true

                ID                                                          1
                mode                                                        limit
                rule                                                        [type = contains; rule = samsung]
                easversions                                                 2.5
                blocking                                                    false

                ID                                                          2
                mode                                                        limit
                rule                                                        [type = always]
                easversions                                                 14.1
                blocking                                                    false

zxsuite mobile doAddEASFilter

This command adds a new EAS filter.

zxsuite mobile doAddEASFilter

Syntax:
   zxsuite mobile doAddEASFilter {and|or|regex|contains|account} {text|people@example.com|account=example@ff.com,contains=android} {add|subtract|fixed|limit} {easversions} [attr1 value1 [attr2 value2...]]

PARAMETER LIST

NAME              TYPE               EXPECTED VALUES
type(M)           Multiple choice    and|or|regex|contains|account
parameter(M)      String             text|people@example.com|account=example@ff.com,contains=android
mode(M)           Multiple choice    add|subtract|fixed|limit
easversions(M)    String[,..]
blocking(O)       Boolean            true|false

(M) == mandatory parameter, (O) == optional parameter

Usage example:

zxsuite mobile doAddEASFilter contains android fixed 2.5,12.0,14.1
Adds a protocol filter that will restrict the pool of available EAS versions to 2.5, 12.0 and 14.1 if the user agent name
contains the string 'android'.

zxsuite mobile doAddEASFilter and account=user@example.com,contains=android fixed 14.1 blocking true
Adds a protocol filter that will restrict the pool of available EAS versions to 14.1 if the user agent name
contains the string 'android' only for user@example.com. No more EAS filters will be evaluated after this one due to the 'blocking' directive.

zxsuite mobile doDeleteEASFilter

This command deletes an existing EAS Filter.

zxsuite mobile doDeleteEASFilter
command doDeleteEASFilter requires more parameters

Syntax:
   zxsuite mobile doDeleteEASFilter {id}

PARAMETER LIST

NAME     TYPE
id(M)    Integer

(M) == mandatory parameter, (O) == optional parameter

Usage example:

zxsuite mobile doDeleteEASFilter 2
Removes the filter with id = 2.
To show a list of the filters, use the
	zxsuite mobile getAllEASFilters
command.

zxsuite mobile doMoveEASFilter

This command is used to move EAS filters to a different position in the filter queue.

zxsuite mobile doMoveEASFilter
command doMoveEASFilter requires more parameters

Syntax:
   zxsuite mobile doMoveEASFilter {from} {to}

PARAMETER LIST

NAME       TYPE
from(M)    Integer
to(M)      Integer

(M) == mandatory parameter, (O) == optional parameter

Usage example:

zxsuite mobile doMoveEASFilter 0 5
Moves the filter with id = 0 to the position 5.
To show a list of the filters, use the
	zxsuite mobile getAllEASFilters
command.

Mobile Account Loggers

Mobile account loggers are dedicated loggers that can output the entirety of a user’s EAS logs into a dedicated logfile, with a different verbosity than the one of the sync.log. This allows for quicker troubleshooting.

When creating an account logger, the following parameters must be specified:

  • The target account.

  • The log_level (verbosity) of the log.

  • The dedicated log_file.

  • The window_size to enforce on all devices synchronizing with the account while the logger is running.

Warning
 Account loggers are removed automatically when the mailboxd is stopped or restarted and do not usually survive a mailboxd crash. Log files won’t be affected.

Account Logger Management

Account loggers can only be managed via the CLI through the following commands:

zxsuite mobile doAddAccountLogger

zxsuite mobile doAddAccountLogger
command doAddAccountLogger requires more parameters

Syntax:
   zxsuite mobile doAddAccountLogger {account} {debug|info|warn|err|crit} {log_file} [attr1 value1 [attr2 value2...]]

PARAMETER LIST

NAME              TYPE               EXPECTED VALUES
account(M)        Account Name
log_level(M)      Multiple choice    debug|info|warn|err|crit
log_file(M)       Path
window_size(O)    Integer            a value > 0

(M) == mandatory parameter, (O) == optional parameter

Usage example:

zxsuite mobile doaddaccountlogger john@example.com info /tmp/john_logger
Creates an info account logger for john's account to file /tmp/john_logger

zxsuite mobile doaddaccountlogger john@example.com info /tmp/john_logger window_size 1
Creates an info account logger for john's account to file /tmp/john_logger with window size set to 1.

zxsuite mobile doRemoveLogger

zxsuite mobile doRemoveLogger
command doRemoveLogger requires more parameters

Syntax:
   zxsuite mobile doRemoveLogger {logger_id|"all_loggers"}

PARAMETER LIST

NAME            TYPE               EXPECTED VALUES
logger_id(M)    Multiple choice    logger_id|"all_loggers"

(M) == mandatory parameter, (O) == optional parameter

Usage example:

zxsuite mobile doremovelogger 5
Removes the account logger with ID = 5

zxsuite mobile getAccountLoggers

Sample output:

zxsuite mobile getAccountLoggers

        loggers

                id                                                          7
                level                                                       DEBUG
                name                                                        AccountLogger
                description                                                 Logging account user@domain.com using level debug, log file /tmp/user.log
                remove command                                              zxsuite mobile doRemoveLogger 7