When Secure Mail isn’t working properly, connection issues are typically the cause. This article describes how to avoid connection issues. If issues occur, this article describes to troubleshoot the issues.
Testing ActiveSync connections, user authentication, and APNs configuration
The Mail Test App helps you verify that ActiveSync is ready for deployment in a XenMobile environment. The app also verifies that your environment meets the system requirements for Secure Mail push notifications. The Mail Test App verifies the following.
- iOS and Android device connections with Microsoft Exchange or IBM Traveler servers.
- User authentication.
- Push notification configuration for iOS, including Exchange Server, Exchange Web Services (EWS), NetScaler Gateway, APNs certificates, and Secure Mail.
For information about configuring push notifications, see Push Notifications for Secure Mail for iOS.
The tool provides a comprehensive list of recommendations for correcting issues.
Installing the Mail Test App
The Mail Test App, MailTest.ipa, is available for download from http://support.citrix.com/article/CTX141685.
The Mail Test App supports environments configured with client certificate authentication. To install, you wrap MailTest.ipa with the MDX Toolkit and then add the app to XenMobile.
To uninstall the Mail Test App
- Press and hold the Mail Test App icon on your home screen until the icon begins to move back and forth.
- Tap the X in the upper left corner of the icon.
- When prompted, tap Delete.
Mail Test App Logs
The Mail Test App writes all logs to /documents/citrixlogs/ on a device. If you wrap Mail Test App, the app generates two files: CtxLog_AppInfo.txt and CtxLog_AppPolicies.xml. Use the Send Log command in Mail Test App to email all log files.
Testing with the Mail Test App
Prerequisites for testing:
- Ensure that the Network Access policy is not blocked.
- Set the Block Email Compose policy to Off.
To set up a test
- On the device where you installed the Mail Test App, open the tool.
2. To add the server you are testing, tap Add new server. Specify any of the following to connect to a server:
- FQDN (subdomain.example.com)
- IP address (10.20.30.40)
- Email address (name@example.com)
- For a cluster configuration, add all the servers including the load balancing server. Tap Next to add more servers or tap Dismiss to continue with the next step. To delete an added server, swipe left on its name and tap Delete.
3. Enter the following items for the account to be used to test the connection. To enter an item, tap the field, type the value, and then tap Next.
- Username: Specify either the userPrincipalName (UPN) or sAMAccountName attribute.
- Domain: Provide the user domain. If you are using an internal domain for the Traveler server, you can leave Domain blank.
- Password: Specify the user password.
- To enable Accept All Certificates, set it to On.
- By default, the Client OS is set to Auto Detect.
- To change the OS, Version, or Device Type, select them from the provided lists.
- To add a Version or Device Type, tap its label, tap + and then enter the information as shown in the following example. When you are finished, tap <. To return to the main screen, tap < again.
4. To change the number of times the test runs, tap Repeat Count and then tap a value.
5. To run the test, tap Diagnose in top right corner.
Test results appear as shown in the following example:
The following example shows how issues are reported.
The following example shows how the tool notifies you that Secure Mail successfully received a test push notification.
If there are issues during the test, the results appear as shown in the following example:
6. For a detailed list of ActiveSync policies, tap Send Logs and then tap Send.
7. To reset the test, tap Reset on the main screen. A reset performs the following actions:
- Deletes all Server names.
- Clears all Credentials.
- Sets Accept All Certificates to Off.
- Sets Client Settings to Auto Detect.
- Sets Repeat Count to 1.
Using Secure Mail logs to troubleshoot connection issues
All XenMobile Apps generate several logs to assist with troubleshooting. To obtain Secure Mail logs, do the following.
1. Go to Secure Hub > Help > Report Issue.
2. Select Secure Mail from the list of apps.
An email addressed to your organization help desk opens.
3. Fill in the subject line and body with a few words describing your issue.
4. Select the time when it happened.
5. Change log settings only if your support team has instructed you to do so.
6. Click Send.
The completed message opens with zipped log files attached.
7. Click Send again.
The zip files sent include the following logs:
- CtxLog_AppInfo.txt (iOS), Device_And_AppInfo.txt (Android), logx.txt and WH_logx.txt (Windows Phone)
App info logs include information about the device and app. Verify that the hardware model and platform version in use are supported. Verify that the versions of Secure Mail and MDX Toolkit in use are the latest and are compatible. For details, see System Requirements for Secure Mail and XenMobile compatibility.
- CtxLog_VPNConfig.xml (iOS) and VpnConfig.xml (Android)
The VPN configuration logs are provided for Secure Hub only. Check the NetScaler version (<ServerBuildVersion>) to ensure the latest NetScaler release is in use. Check the <SplitDNS> and <SplitTunnel> settings as follows:
- If Split DNS is set to Remote, Local, or Both, verify that you are correctly resolving the mail server FQDN through DNS. (Split DNS is available for Secure Hub on Android.)
- If Split Tunnel is set to On, ensure that mail server is listed as one of the Internet apps accessible on the backend.
- CtxLog_AppPolicies.xml (iOS), Policy.xml (Android and Windows Phone)
The policies logs provide the values of all MDX policies applied to Secure Mail as of the time you obtained the log. For connection issues, verify that the values for the <BackgroundServices> and <BackgroundServicesGateway> policies.
- Diagnostic logs (in the diagnostics folder)
For initial configurations of Secure Mail, the most common issue is “Your Company Network Is Not Currently Available.” To use the diagnostic logs to troubleshoot connection issues, do the following.
The key columns in the diagnostic logs are Timestamp, Message Class, and Message. When an error message appears in Secure Mail, make note of the time so you can quickly locate related log entries in the Timestamp column.
To determine whether the connection from the device to NetScaler Gateway succeeded: Review the AG Tunneler entries. The following messages indicate successful connection:
- AG policy Intercepting FQDN:443 for STA tunneling
- New TCP proxy connection to (null):443 established
To determine whether the connection from NetScaler Gateway to XenMobile succeeded (and thus can validate the STA ticket), go to the Secure Hub diagnostic log and review the INFO (4) entries under Message Class, for the time the device was enrolled. The following messages indicate that Secure Hub obtained a STA ticket from XenMobile:
- Getting STA Ticket
- Got STA Ticket response
- STA Ticket – Success obtaining STA ticket for App — Secure Mail
Note
During enrollment, Secure Hub sends a request to the XenMobile server for a STA ticket. The XenMobile server sends the STA ticket to the device, where it is stored and added to the XenMobile server STA ticket list.
To determine if XenMobile Server issued a STA ticket to a user, check the UserAuditLogFile.log, included in the XenMobile support bundle. It lists for each ticket, the issue time, user name, user devices, and result. For example:
Time: 2015-06-30T 12:26:34.771-0700
User: user2
Device: Mozilla/5.0 (iPad; CPU OS 8_1_2 like Mac OS X)
Result: Successfully generated STA ticket for user ‘user2’ for app ‘Secure Mail’
To check the communication from NetScaler Gateway to the mail server: Check if DNS and networking are configured correctly. To do so, use Secure Web to access Outlook Web Access (OWA). Like Secure Mail, Secure Web can use a micro VPN tunnel to establish a connection to NetScaler Gateway. Secure Web acts as a proxy to the internal or external resource the app is accessing. Usually and particularly in an Exchange environment, OWA is hosted on the mail server.
To test the configuration, open Secure Web and enter the FQDN of the OWA page. That request takes the same route and DNS resolution as communication between NetScaler Gateway and the mail server. If the OWA page opens, you know that NetScaler Gateway is communicating with the mail server.
If the preceding checks indicate successful communications, you know that the issue isn’t with your Citrix setup. Instead, the issue is with the Exchange or Traveler servers.
You can collect information for your Exchange or Traveler server administrators. First check for HTTP issues on the Exchange or Traveler servers by searching the Secure Mail diagnostic log for the word Error. If the errors include HTTP codes and you have multiple Exchange or Traveler servers, investigate each server. Exchange and Traveler have HTTP logs that show HTTP requests and responses from client devices. The log for Exchange is C:\inetpub\LogFiles\W3SVC1\U_EX*.log. The log for Traveler is IBM_TECHNICAL_SUPPORT > HTTHR*.log.
Troubleshooting issues with Email, Contacts, or Calendar
You can troubleshoot Secure Mail issues, such as an email or emails stuck in drafts, missing contacts, or calendar items out-of-sync. To troubleshoot these issues, use Exchange ActiveSync mailbox logs. The logs show incoming requests sent by the devices and the outgoing responses from the mail server.
For more details, see these TechNet blog posts:
Unlimited sync best practices
When users set their sync mail period to All, they have unlimited sync. With unlimited sync, the assumption is that users manage their mailbox size, which is the Inbox and all synced subfolders. Here are a few points to keep in mind for best performance.
1. If the mailbox size exceeds 18,000 messages or 600 MB in total size, email sync can slow down.
2. It is not recommended to enable Load Attachments on WiFi with unlimited sync. This option can cause the mail size to bloat quickly on the device.
3. To prevent unlimited sync as an option for users, set the Max sync interval app policy to a value other than All.
4. It is not recommended to set All as the Default sync interval for users.