Mobil . Administrator s Guide Citrix Systems, Inc. All rights reserved.

Transcription

1 Mobil Administrator s Guide

2 Prepared by: Citrix Labs Version: Last Updated: June 18, 2014 Contents Introduction... 5 Installation... 6 Citrix XenApp Citrix XenDesktop 7.x... 6 Citrix XenApp Dependencies... 6 Attachment Viewers... 7 Mobil Configuration... 8 Publishing Mobil on XenApp Publishing Mobil on XenApp User Profile Manager Add LocalDB directories Add LocalDB files Troubleshooting Exchange Auto-Discovery Exchange Web Services App doesn t resize properly when rotating on ios Tracing Sensitive information in trace files Caching LocalDB Page 2

3 Message bodies and attachments Performance Recovery Encryption Known Issues Multi-domain setups and Office Editing of recurring appointments Cannot edit message bodies in draft messages Links and References Page 3

4 Revision History Version Description Date Author 1.0 Beta build Citrix Labs 1.1 Pre-release Citrix Labs 1.2 Add publishing steps for XenApp Citrix Labs 1.3 New template and edits Kyara Lomer- Camarena Updated known issues Citrix Labs Page 4

5 Introduction This admin guide describes installation (including optional components), configuration, and troubleshooting steps for Mobil . Mobil incorporates , 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. Mobil tightly integrates with Microsoft Exchange and brings many enterprise communication features to any mobile device running Citrix Receiver. Mobil enables corporate data to b e highly mobile while providing an enterprise-class security solution. The following diagram provides an overview of how Mobil works. Mobil communicates with the Exchange server via a secure HTTPS connection using the Exchange Web Services API. Mobil 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 Mobil Citrix Receiver Page 5

6 Installation The following components are required for Mobil 1. Citrix XenApp 6.5, Citrix XenDesktop 7.x, Citrix XenApp 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: Hotfix Rollup Pack 2: Hotfix Rollup Pack 3: Note: To run Web Interface and Mobil 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 Mobil . This issue is described in the knowledge base article at 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 Mobil on server workers in XenDesktop 7 for use with the Application Virtualization and Hosting or Hosted Shared Desktops features. Installation of Hosted Mobil is presently not supported for delivery via VDI. Citrix XenApp 7.5 No additional hotfixes are required to run Mobil on XenApp 7.5. Dependencies Prior to installing Mobil , you must install the following:.net Runtime 3.5 SP1.NET Runtime 4.0, with the update o Update is available at SQL Server 2012 LocalDB (x64) Page 6

7 o The LocalDB install is available at 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 Mobil 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 Mobil 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 Mobil will continue to work but will not support opening these types of attachments. Mobil To install Mobil onto your XenApp server, run the Mobil MSI: Mobil x64.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

8 Configuration Publishing Mobil on XenApp 6.5 After you install Mobil 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 Mobil . 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

9 3. On the Type page, keep all the default settings. Page 9

10 4. On the Location page, browse to the Mobil executable. Page 10

11 5. On the Servers page, select the servers where you want Mobil published. Page 11

12 6. On the Users page, select the users who will access Mobil . Page 12

13 7. On the Shortcut presentation page, set client application folder and shortcut placement as appropriate. Page 13

14 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

15 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 Mobil . Publishing Mobil on XenApp 7.5 The following steps describe how to publish Mobil on XenApp 7.5. These steps also apply to publishing Mobil 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

16 1. From Citrix Studio, select the Delivery Group where you want to publish Mobil , and then select Add Applications. Page 16

17 2. In the Create Application wizard, click Next to skip past the introduction, and then click Next to select your Delivery Group: Page 17

18 3. If Mobil 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 Mobil . Page 18

19 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 Mobil .exe; this will auto-populate the dialog. 5. Configure Mobil properties: If you manually added Mobil , you will now be at the dialog shown previously in step 3. With Mobil selected, you need to click on the Application Properties button. Page 19

20 6. In the Application Settings dialog, type keyword:mobile into the Description and keywords field, and then click OK. Page 20

21 7. Click Next in the Create Application dialog, and then click Finish to complete publishing. Page 21

22 8. You should now see Mobil listed in your published applications as follows: User Profile Manager Hosted Mobil uses a SQL LocalDB database to cache s 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 Mobil . 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

23 Citrix\Profile Management\File system\synchronization\directories to synchronize Page 23

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 directories to synchronize. 4. This will display a popup that allows you to add directories. Add the following entries: a. AppData\Local\Citrix\Mobil b. AppData\Local\Microsoft\Microsoft SQL Server Local DB\Instances\v 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

25 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\Mobil \* 5. Commit the changes by clicking OK on all the popup dialogs. Page 25

26 Troubleshooting Exchange Auto-Discovery By default, Mobil 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 Mobil uses to talk to Exchange. If you have not properly configured auto-discovery or it is not available, Mobil will not work without additional manual configuration. You can make Mobil skip the use of auto-discovery by manually configuring the address of an EWS endpoint. You do this by editing the Mobil .exe.config file using a text editor. This configuration file is located in the Mobil 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

27 <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: 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

28 App doesn t resize properly when rotating on ios If you don t publish Mobil correctly, the app may display in letterbox format when you rotate your device, as shown in the following screenshot: Page 28

29 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 Mobil 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 Mobil are traced when tracing is enabled. By default, the trace file is not generated. To enable tracing, edit the configuration file Mobil .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

30 EnableDetailedExchangeTracing: This is a Boolean setting that enables additional tracing to log a selection of the messages that Mobil 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 Mobil for the changes to take effect. Important: It is recommended that you save a copy of the Mobil .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\mobil </value> </setting> Enabling detailed Exchange tracing is useful when diagnosing problems with Mobil locating and communicating with an Exchange Server. It causes Mobil to log the full request and reply to messages for all auto-discovery queries as well as the initial set of EWS queries Mobil 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\Mobil \Mobil .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 Mobil .log trace file containing trace from different users. Page 30

31 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 Mobil starts, it traces the address of the current user in the following format: Trace1: Citrix.GoldenGate.App.ctor User 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 Mobil caches content locally on the Citrix server using the user s profile. There are two main sets of data that Mobil 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\Mobil 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 BE FC8A8897} Page 31

32 Each instance that is created in the user s profile will be listed with a different random GUID under the UserInstances key. The Mobil 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: Mobil .MDF Mobil _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\Mobil \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 Mobil will resume syncing from its last sync point. This issue is particularly relevant when you have published Mobil 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 Mobil 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, Mobil 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 Mobil to re-create a new SQL instance on the fly and resync the user s mailbox. 2. Missing Mobil database: LocalDB tracks the Mobil database using the default instance. If for some reason the actual database files in AppData\Local\Citrix\Mobil get deleted, then LocalDB would be unable to connect to the app database. So at startup, Mobil will check if Page 32

33 the database files are missing. If they are missing, then Mobil 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, Mobil will look for the cached body on disk. If the body is missing, Mobil 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\Mobil ) 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 Mobil 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 Mobil 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 Mobil currently can only edit the bodies of drafts that were created in Mobil . 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 Mobil Website ( 2. Hosted Mobil Forum ( Page 33