Testing and troubleshooting Secure Mail
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
You can use Endpoint Management Analyzer to conduct Secure Mail autodiscovery service checks. It guides you in downloading the Endpoint Management Exchange ActiveSync Test application. The Mail test option checks basic connection settings to the mail server. The tool also helps you troubleshoot the ActiveSync servers for their readiness to be deployed within an Endpoint Management environment. For details, see Endpoint Management Analyzer Tool.
The Mail test option in the Analyzer 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), Citrix 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.
The Mail Test App, MailTest.ipa, is deprecated. Instead, access the same functionality in Endpoint Management Analyzer.
Prerequisites for testing
- Ensure that the Network Access policy is not blocked.
- Set the Block Email Compose policy to Off.
Using Secure Mail logs to troubleshoot connection issues
To obtain Secure Mail logs, do the following.
Go to Secure Hub > Help > Report Issue.
Select Secure Mail from the list of apps.
An email addressed to your organization help desk opens.
Fill in the subject line and body with a few words describing your issue.
Select the time when it happened.
Change log settings only if your support team has instructed you to do so.
The completed message opens with zipped log files attached.
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 Endpoint Management compatibility.
- CtxLog_VPNConfig.xml (iOS) and VpnConfig.xml (Android)
The VPN configuration logs are provided for Secure Hub only. Check the Citrix ADC version
ServerBuildVersion to ensure the latest Citrix ADC release is in use. Check the
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 the values for the
- 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 Citrix 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 Citrix Gateway to Endpoint Management succeeded (and thus can validate the STA ticket), do the following: 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 Endpoint Management:
- Getting STA Ticket.
- Got STA Ticket response.
- STA Ticket – Success obtaining STA ticket for App – Secure Mail.
During enrollment, Secure Hub sends a request to Endpoint Management for a STA ticket. Endpoint Management sends the STA ticket to the device, where it is stored and added to the Endpoint Management STA ticket list.
To determine if Endpoint Management issued a STA ticket to a user, check the UserAuditLogFile.log, included in the 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
Device: Mozilla/5.0 (iPad; CPU OS 8_1_2 like macOS)
Result: Successfully generated STA ticket for user ‘user2’ for app ‘Secure Mail’
To check the communication from Citrix 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 Citrix 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 Citrix Gateway and the mail server. If the OWA page opens, you know that Citrix 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.
To obtain crash logs from a device for Secure Mail for iOS
- On your iOS device, go to Settings > Privacy > Analytics > Analytics Data.
- In the Data list, click the name of the app and the relevant time stamp. The logs appear.
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 Under the Hood: Exchange ActiveSync Mailbox Log Analysis TechNet blog post.
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.
If the mailbox size exceeds 18,000 messages or 600 MB in total size, email sync can slow down.
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.
To prevent unlimited sync as an option for users, set the Max sync interval app policy to a value other than All.
It is not recommended to set All as the Default sync interval for users.