MobileMail Administrator s Guide
Prepared by: Citrix Labs Version: 1.3.1 Last Updated: June 18, 2014 Contents Introduction... 5 Installation... 6 Citrix XenApp 6.5... 6 Citrix XenDesktop 7.x... 6 Citrix XenApp 7.5... 6 Dependencies... 6 Attachment Viewers... 7 MobileMail... 7 Configuration... 8 Publishing MobileMail on XenApp 6.5... 8 Publishing MobileMail on XenApp 7.5... 15 User Profile Manager... 22 Add LocalDB directories... 22 Add LocalDB files... 24 Troubleshooting... 26 Exchange Auto-Discovery... 26 Exchange Web Services... 27 App doesn t resize properly when rotating on ios... 28 Tracing... 29 Sensitive information in trace files... 31 Caching... 31 LocalDB... 31 Page 2
Message bodies and attachments... 32 Performance... 32 Recovery... 32 Encryption... 33 Known Issues... 33 Multi-domain setups and Office 365... 33 Editing of recurring appointments... 33 Cannot edit message bodies in draft messages... 33 Links and References... 33 Page 3
Revision History Version Description Date Author 1.0 Beta build 2.5.0.1278 2013-06-17 Citrix Labs 1.1 Pre-release 2.5.1.1339 2013-09-12 Citrix Labs 1.2 Add publishing steps for XenApp 7.5 2013-03-19 Citrix Labs 1.3 New template and edits 2014-03-28 Kyara Lomer- Camarena 1.3.1 Updated known issues 2014-06-13 Citrix Labs Page 4
Introduction This admin guide describes installation (including optional components), configuration, and troubleshooting steps for MobileMail. MobileMail incorporates email, calendaring, contact, and collaboration capabilities into a single micro app that runs securely in the datacenter and is delivered to mobile devices by Citrix XenApp and XenDesktop. MobileMail tightly integrates with Microsoft Exchange and brings many enterprise communication features to any mobile device running Citrix Receiver. MobileMail enables corporate data to b e highly mobile while providing an enterprise-class security solution. The following diagram provides an overview of how MobileMail works. MobileMail communicates with the Exchange server via a secure HTTPS connection using the Exchange Web Services API. MobileMail is then presented to the user via the HDX channel that remotes the server graphics to the user s device. Exchange Server Exchange Web Services Exchange Core XenApp Server Mobile Device MobileMail Citrix Receiver Page 5
Installation The following components are required for MobileMail: 1. Citrix XenApp 6.5, Citrix XenDesktop 7.x, Citrix XenApp 7.5 2. For the best user experience, use the latest version of Citrix Receiver for Android and ios available in their respective app stores. 3. Microsoft Exchange Server running Exchange Web Services and auto-discovery Citrix XenApp 6.5 If you are using XenApp 6.5, you must install the appropriate Hotfix Rollup Pack to add support for mobilized applications. You must install HRP01 as a minimum; however, HRP02 or later is recommended: Hotfix Rollup Pack 1: http://support.citrix.com/article/ctx132122 Hotfix Rollup Pack 2: http://support.citrix.com/article/ctx136248 Hotfix Rollup Pack 3: http://support.citrix.com/article/ctx138537 Note: To run Web Interface and MobileMail on the same XenApp server, make sure that Web Interface is installed and running before you install the.net 4.0 runtime, which is a prerequisite for MobileMail. This issue is described in the knowledge base article at http://support.citrix.com/article/ctx125635. Citrix XenDesktop 7 If you are using XenDesktop 7 (7.0 or later), you do not need to install any additional hotfixes or feature packs. You can only install Hosted MobileMail on server workers in XenDesktop 7 for use with the Application Virtualization and Hosting or Hosted Shared Desktops features. Installation of Hosted MobileMail is presently not supported for delivery via VDI. Citrix XenApp 7.5 No additional hotfixes are required to run MobileMail on XenApp 7.5. Dependencies Prior to installing MobileMail, you must install the following:.net Runtime 3.5 SP1.NET Runtime 4.0, with the 4.0.3 update o Update 4.0.3 is available at http://support.microsoft.com/kb/2600211 SQL Server 2012 LocalDB (x64) Page 6
o The LocalDB install is available at http://www.microsoft.com/enau/download/details.aspx?id=29062. Click the Download button, and choose the x64 SqlLocalDB.MSI package. Refer to the following screenshot to see which package you need to select: Attachment Viewers MobileMail also supports attachment viewing for certain file formats. If you want to support viewing these attachments, you need to install the appropriate third-party programs that MobileMail will use to open these attachments. Word documents: Microsoft Word 2007, 2010, 2013 Excel spread sheets: Microsoft Excel 2007, 2010, 2013 PowerPoint presentations: Microsoft PowerPoint 2007, 2010, 2013 Installing these attachment-viewing programs is optional. If you do not install these programs, then MobileMail will continue to work but will not support opening these types of email attachments. MobileMail To install MobileMail onto your XenApp server, run the MobileMail MSI: MobileMailx64.msi You do not need to provide any configuration during the installation. Simply progress through the MSI install wizard until the install is finished. Page 7
Configuration Publishing MobileMail on XenApp 6.5 After you install MobileMail on your XenApp server, you must publish it as described below: 1. Select Publish Application in the Citrix AppCenter management console. 2. On the Name page: a. Set the Display name to an appropriate name, for example MobileMail. b. Add the special phrase keyword:mobile to the application description, as highlighted in the following screenshot: Important: This step is very important, as the mobile keyword tells Receiver to adjust the size of the session to match the size of its screen, as well as to process touch input in a way that suited for mobile-friendly apps. If you don t do this, the app may not resize properly to the full size of the screen, or you may not be able to scroll properly within the app. Page 8
3. On the Type page, keep all the default settings. Page 9
4. On the Location page, browse to the MobileMail executable. Page 10
5. On the Servers page, select the servers where you want MobileMail published. Page 11
6. On the Users page, select the users who will access MobileMail. Page 12
7. On the Shortcut presentation page, set client application folder and shortcut placement as appropriate. Page 13
8. On the Publish immediately page, select the Configure advanced application settings now option. a. Skip through the Advanced pages to the last Appearance page. Page 14
9. On the Appearance page, change the session window size to Full screen. Note: Setting the session window size to full screen ensures that the session sizes properly when you roam a session between devices with different screen sizes, such as from your phone to a tablet. If you do not change this setting, the session size could be larger than the screen size of your client device. 10. Click Finish to publish MobileMail. Publishing MobileMail on XenApp 7.5 The following steps describe how to publish MobileMail on XenApp 7.5. These steps also apply to publishing MobileMail in XenDesktop 7.x. The steps assume you already have created a delivery group into which to publish. The publishing steps are fairly typical; however, there is one nonstandard configuration step (6) to add the mobile keyword to the application. Page 15
1. From Citrix Studio, select the Delivery Group where you want to publish MobileMail, and then select Add Applications. Page 16
2. In the Create Application wizard, click Next to skip past the introduction, and then click Next to select your Delivery Group: Page 17
3. If MobileMail is already in your Master Image, then select it, and continue to step 5. Otherwise, click Add applications manually, and continue to step 4 if you are manually adding MobileMail. Page 18
4. For manual configuration, enter the information shown in the screenshot below. You may want to use the browse button to look for one of your XenApp servers and select the MobileMail.exe; this will auto-populate the dialog. 5. Configure MobileMail properties: If you manually added MobileMail, you will now be at the dialog shown previously in step 3. With MobileMail selected, you need to click on the Application Properties button. Page 19
6. In the Application Settings dialog, type keyword:mobile into the Description and keywords field, and then click OK. Page 20
7. Click Next in the Create Application dialog, and then click Finish to complete publishing. Page 21
8. You should now see MobileMail listed in your published applications as follows: User Profile Manager Hosted MobileMail uses a SQL LocalDB database to cache emails and contacts that have been downloaded from the Exchange Server. This database is stored in the user s local profile. If you are using User Profile Manager (UPM) with the recommended configuration for XenApp, then files stored in the user s local profile will be discarded on a logoff, including the LocalDB cache. This means that the user s mailbox will always sync from the Exchange Server on each startup. While this will work, the user will suffer a slow startup every time they run the app. To avoid this, it is recommended that you configure the UPM to save the files that the LocalDB uses. This ensures that on startup the app only syncs down the changes made to a user s mailbox since they last ran Hosted MobileMail. Refer to the following sections on how to configure the appropriate UPM group policies. Add LocalDB directories You need to configure UPM to add two directories that will be synced from the user s local profile. The policy to configure this is: Page 22
Citrix\Profile Management\File system\synchronization\directories to synchronize Page 23
1. Edit this policy 2. Ensure the policy is set to Enabled 3. In Options, click on the Show button next to List of directories to synchronize. 4. This will display a popup that allows you to add directories. Add the following entries: a. AppData\Local\Citrix\MobileMail b. AppData\Local\Microsoft\Microsoft SQL Server Local DB\Instances\v11.0 5. Commit the changes by clicking OK on all the popup dialogs. Add LocalDB files You also need to configure files to be synced using the following policy: Citrix\Profile Management\File system\synchronization\files to synchronize Page 24
1. Edit this policy 2. Ensure the policy is set to Enabled 3. In Options, click on the Show button next to List of files to synchronize. 4. This will display a popup that allows you to add files. Add the following entry: a. AppData\Local\Citrix\MobileMail\* 5. Commit the changes by clicking OK on all the popup dialogs. Page 25
Troubleshooting Exchange Auto-Discovery By default, MobileMail uses auto-discovery to locate an Exchange Server. Auto-discovery queries Active Directory for the location of the Exchange Auto-Discover Service. That service is then queried to determine the location of the Exchange Web Services (EWS) endpoint that MobileMail uses to talk to Exchange. If you have not properly configured auto-discovery or it is not available, MobileMail will not work without additional manual configuration. You can make MobileMail skip the use of auto-discovery by manually configuring the address of an EWS endpoint. You do this by editing the MobileMail.exe.config file using a text editor. This configuration file is located in the MobileMail installation directory. This file contains the following configuration section underneath the node: <configuration> <applicationsettings> <Citrix.GoldenGate.Properties.Settings> <setting name="defaultserverurl" serializeas="string"> <value /> </setting> Edit the value of this setting as follows: 1. Replace the <value/> tag with <value></value>. 2. Insert the address of the EWS endpoint in between the value tags. The address must include the https prefix unless the ExchangeSecureConnectionOnly setting is set to False. The address must include the EWS/Exchange.asmx suffix. The name of the Exchange Server must be its fully qualified domain name. The following example shows what the setting will look like when correctly entered: <setting name="defaultserverurl" serializeas="string"> Page 26
<value>https://exchangeserverfqdn/ews/exchange.asmx</value> </setting> <setting name="exchangesecureconnectiononly" serializeas="string"> <value>true</value> </setting> Exchange Web Services The simplest way to test whether EWS is available is to use a web browser. Enter a URL with the following format into your browser: https://exchangeserverfqdn/ews/exchange.asmx Be sure to replace ExchangeServerFQDN with the fully qualified domain name of your Exchange Server. If EWS is working correctly, your browser should load the XML definition of the Exchange Web Service. The beginning of this document should look something like the following example: Page 27
App doesn t resize properly when rotating on ios If you don t publish MobileMail correctly, the app may display in letterbox format when you rotate your device, as shown in the following screenshot: Page 28
This happens when keyword:mobile is not added to the application description when publishing the application. Refer to the publishing steps in section 0. Tracing MobileMail can output a trace file and save it in a user s profile. Errors and exceptions as well as messages describing the normal operation of MobileMail are traced when tracing is enabled. By default, the trace file is not generated. To enable tracing, edit the configuration file MobileMail.exe.config in the installation directory. This is an XML-based file that contains a range of application settings that can be edited using any text editor. There are three configuration options in the configuration file that affect tracing. They are all under the node: <configuration> <applicationsettings> <Citrix.GoldenGate.Properties.Settings> These settings are: TraceToFile: This is a Boolean setting that turns tracing on or off. Change this setting to True to enable tracing. Page 29
EnableDetailedExchangeTracing: This is a Boolean setting that enables additional tracing to log a selection of the messages that MobileMail sends to the Exchange Server. Unless the TraceToFile setting has been set to True, enabling this setting has no effect. TraceFilePath: This setting controls the location of the trace file. Generally, you should use the default value and not edit this setting. The following example shows how these three settings are defined in the XML configuration file. To change the value of any of these settings, edit the value within the <value></value> tags, and save the configuration file. You must restart MobileMail for the changes to take effect. Important: It is recommended that you save a copy of the MobileMail.exe.config configuration file prior to editing it so you can restore it if needed. <setting name="tracetofile" serializeas="string"> <value>true</value> </setting> <setting name="enabledetailedexchangetracing" serializeas="string"> <value>false</value> </setting> <setting name="tracefilepath" serializeas="string"> <value>%appdata%\citrix\mobilemail</value> </setting> Enabling detailed Exchange tracing is useful when diagnosing problems with MobileMail locating and communicating with an Exchange Server. It causes MobileMail to log the full request and reply to messages for all auto-discovery queries as well as the initial set of EWS queries MobileMail makes when it first starts. The TraceFilePath setting can contain Windows environment variables. The default setting uses %APPDATA% as the root for storing trace files. This will create the log file in a location inside a user s profile: Windows 2008 C:\Users\UserName\AppData\Roaming The default setting has a default trace file path of: Windows 2008 C:\Users\UserName\AppData\Roaming\Citrix\MobileMail\MobileMail.log If you do change the trace file path, it is recommended that you employ a user-specific path using an environment variable such as APPDATA. If you set the path to a common location for all users, such as C:\Temp, it will be difficult to determine which trace file is for which user. Also, because the tracing system tries to open the existing trace file and append to it, you can end up with the main MobileMail.log trace file containing trace from different users. Page 30
Sensitive information in trace files If you provide trace files to Citrix for diagnosis, be aware that they can contain some information you may regard as sensitive. You may want to remove this information first. When MobileMail starts, it traces the email address of the current user in the following format: Trace1: Citrix.GoldenGate.App.ctor User email: username@company.com If you have enabled the EnableDetailedExchangeTracing option, the trace messages also contain: The display name of the current user Names of servers in your environment, for example Exchange Servers and Domain Controllers Active Directory domain names Caching The purpose of this section is to give you an overview of how MobileMail caches content locally on the Citrix server using the user s profile. There are two main sets of data that MobileMail writes out: Message headers: Stored in a SQL LocalDB database Message bodies and attachments: Stored as flat files All this data is written out to the user s local profile as a mix of files and registry entries. LocalDB LocalDB stores its state in three main locations on the file system and registry: 1. AppData\Local\Microsoft\Microsoft SQL Server Local DB 2. HKCU\Software\Microsoft\Microsoft SQL Server 3. AppData\Local\Citrix\MobileMail The first directory is the default on-disk storage location for LocalDB. When a user uses LocalDB for the first time, it will create a default SQL instance under the following directory: AppData\Local\Microsoft\Microsoft SQL Server Local DB\Instances\v11.0 It also records the instances that have been created using registry entries under the location described in point No. 2 above. For example: HKCU\Software\Microsoft\Microsoft SQL Server\UserInstances\{403136B9-DA1C- 4904-BE68-7051FC8A8897} Page 31
Each instance that is created in the user s profile will be listed with a different random GUID under the UserInstances key. The MobileMail database is a member of the default instance; however, the actual database files are stored in location No. 3 so they are in the same place as the message bodies. The files are: MobileMail.MDF MobileMail_log.LDF Message bodies and attachments Cached messages have their body and attachments written out as flat files to disk. They can be found at: AppData\Local\Citrix\MobileMail\Cache Each message will have its own unique directory with a GUID-like name, such as: 0xDD3B66F70x4F69EA040x512E5C390xA0BEE0430x1DA351470x259925B70xCDBDB7DF Performance For optimal performance, you want the content cached in the user s local profile to be available in subsequent logons. This will improve startup time and minimize load on the Exchange Server because MobileMail will resume syncing from its last sync point. This issue is particularly relevant when you have published MobileMail on multiple servers because your users can end up with multiple caches in their local profiles on different servers. To avoid this duplication and resyncing of the cache, you can use Citrix User Profile Manager to persist and restore users local profiles (with appropriate configuration as described in section 0). Recovery MobileMail applies multiple levels of recovery to its persistent state to keep it consistent and avoid failures. This ensures that if any state is missing because of accidental deletion or improper syncing of a user s profile, the app will start up and run correctly. 1. Missing LocalDB instance: At startup, MobileMail will query the user s registry to discover what SQL instances should exist on disk. It will then check that the expected directory for each instance exists to ensure it is available. If it finds an instance missing from the disk, it will delete the associated registry entry. This allows MobileMail to re-create a new SQL instance on the fly and resync the user s mailbox. 2. Missing MobileMail database: LocalDB tracks the MobileMail database using the default instance. If for some reason the actual database files in AppData\Local\Citrix\MobileMail get deleted, then LocalDB would be unable to connect to the app database. So at startup, MobileMail will check if Page 32
the database files are missing. If they are missing, then MobileMail will drop the database from the default instance, re-create it, and resync the user s mailbox. 3. Missing body: When users open messages that have been previously cached, MobileMail will look for the cached body on disk. If the body is missing, MobileMail will redownload that message from the Exchange Server. Encryption The bodies and attachments of messages are stored as flat files, so it is easy for someone with admin access to a Citrix server to browse other users messages. For this reason, the primary cache directory (AppData\Local\Citrix\MobileMail) is encrypted using EFS. This ensures that only the rightful owner can open both the message headers stored in the LocalDB database and the bodies/attachments. Known Issues Multi-domain setups and Office 365 MobileMail only supports integrated authentication using the current identity of the user of the XenApp session. This means that if your Exchange server is hosted under a different domain and requires an additional login using different credentials, then MobileMail will not be able to connect to it. E.g. this is common in multi-domain setups or when using hosted Exchange via Office 365. Editing of recurring appointments Editing of recurring appointments is currently not supported. Cannot edit message bodies in draft messages MobileMail currently can only edit the bodies of drafts that were created in MobileMail. If you open a draft that was created in Microsoft Outlook, you will not be able to make any edits to the existing body. You can only add text above the existing body. Links and References 1. Hosted MobileMail Website (https://www.citrix.com/go/hosted-mobilemail.html) 2. Hosted MobileMail Forum (http://discussions.citrix.com/forum/1077-hosted-mobilemail/) Page 33