Product Documentation

Installing Device Manager

Mar 19, 2014

Before installing Device Manager, ensure that the following prerequisites are in place.

  • Do not enable the Web Server (IIS) role on the server on which you plan to install Device Manager. If this role is already enabled, remove the role before installing Device Manager.
  • Install the following Java components on the server on which you plan to install Device Manager.
    • Java Standard Edition 7 Development Kit (minimum version 1.7.0_11)
    • Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7

    To support enrollment of iOS devices, the restricted strength JCE components included in the JDK must be replaced with the unlimited strength files. To do this, copy the unlimited strength JCE files local_policy.jar and US_export_policy.jar to the \jre\lib\security\ directory of the JDK, overwriting the existing files. For more information see the readme file for the JDK, which is available at http://www.oracle.com/technetwork/java/javase/terms/readme/index.html.

  • The Device Manager repository requires a Microsoft SQL Server database. Ensure that you have access to a service account on the database server that has administrator rights to SQL Server, including Creator, Owner, and Read/Write permissions.
  • Ensure that the Windows service accounts for Device Manager and the database have local administrator permissions for the server on which Device Manager is installed. Note that domain membership is not required for the Device Manager server.
  • Create an external DNS record for the Device Manager server, such as mobile.yourcompany.com.

Choosing Device Manager Components to Install

If you are installing Device Manager on your computer for the first time, select Full install. When you select this option, the following components are installed:

  • The Device Manager server
  • The Device Manager repository database (PostgreSQL) as well as the database and requisite tables
  • The integrated web application server hosting the Device Manager server
Note: If you install an Application Server prior to installing Device Manager, remove the Application Server before installing Device Manager.

Installing Databases

Device Manager includes the PostgreSQL database server installation. If you installed a SQL database server on your computer or another server, clear the PostgreSQL check box in the list of components during the installation wizard. The install type switches automatically to Custom. When using Microsoft SQL Server, refer to the Microsoft installation instructions. If you do not clear the check box, the PostgreSQL installation wizard appears with configuration instructions.

If you install PostgreSQL, an installation wizard appears. The installation program automatically selects all of the default PostgreSQL options required to install an Device Manager server. However, you can check additional options you want to install. You can also change the installation location with the Browse button.

During installation of PostgreSQL, define the service account that runs the PostgreSQL server. The Service name, Account name, and Account domain fields are already completed. You need to enter a password for the service account.

If the user account does not exist, you receive a prompt to confirm creation of the account. In addition, if the password you choose is not a strong password, you are prompted to replace the password with a strong password. Click No in the message dialog box to keep the password you originally entered.

Installing License Files

After you configure the PostgreSQL database, you can then install licenses. If you are using a different SQL database and did not install PostgreSQL, after choosing the initial components and installation location, you install the licenses.

Running the Device Manager Installation Wizard

Before you install Device Manager, make sure you do the following:

Caution: Using Registry Editor incorrectly can cause serious problems that may require you to reinstall your operating system. Citrix cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk.

The setup wizard includes several discrete tasks. You need to complete the all of the tasks in this topic in consecutive order to complete the entire wizard. The installation tasks include:

  • Device Manager components
  • Installation location
  • Microsoft SQL Server database installation
  • Database cluster settings
  • Licenses
  • Device Manager and database communication
  • Crystal Reports keycode
  • HTTP and HTTPS connectors
  • Root and server certificates
  • Apple Push Notification Service (APNS) certificates
  • Remote support settings
  • Active Directory service account for managing users

To select Device Manager components

After you download the software package to your computer, navigate to the folder and then double-click the Device Manager executable installation file to start the Setup Wizard.

When the wizard starts, you set the language and then read and accept the End User License Agreement. After these two steps, on the Choose Components page, click to clear Database server to disable installation of the PostgreSQL database.

Important: Citrix recommends that you use Microsoft SQL Server instead of the PostgreSQL database that comes with Device Manager. The PostgreSQL database should be used for demonstration purposes only.

After you select your components, on the Choose Install Location page, leave the default install location and then click Install. Citrix recommends that you use the default location to install Device Manager.

To install the license on Device Manager

Device Manager requires a license. For more information about licenses for Device Manager, see Obtaining and Installing Licenses. You upload the .crt license file from your computer. When the upload is complete, the license details appear in the XenMobile Device Manager License dialog box.

Device Manager License Information

To test the connection to the database from Device Manager

You need to configure the Device Manager settings to connect to your database. In the Configure database connection dialog box, you select the SQL Server database. You provide the database name or use the default value. You need to complete the following information, as shown in the following figure:

  • In Host name or IP address, enter the fully qualified domain name (FQDN) or IP address of SQL Server.
  • In Port, enter the port number. The default port number for SQL Server is 1433.
  • In User name, enter a user name for the database.
  • In Password, enter the password to connect to the SQL Server database.
  • In Database name, enter the database name or leave the default value.
Configuring the connection between Device Manager and the database

After you configure the database connection, you then enter the keycode for Crystal Reports.

To configure and register Crystal Reports

With Crystal Reports, you can process the mobile device connection and session logs to generate activity reports online by using the Device Manager web console, or offline from the Device Manager repository database. The reports include a watermark with registration information. To remove the watermark, you need a Crystal Reports Developer Edition license and a keycode for the product. If you did not enter a license serial number during installation, you can define it later by following these steps:
  1. Open the crconfig.xml configuration file located at in the Device Manager setup folder, which is typically %systemroot%\Program Files\Xenmobile\tomcat\webapps\Device Manager\WEBINF\classes\crconfig.xml on a Windows Server.
  2. Add your serial number by editing the <keycode></keycode> element. For example, if your serial number is XXXX-YYYY-ZZZZ, modify the line as follows:

    <keycode>XXXX-YYYY-ZZZZ</keycode>

On the Crystal Report Java Reporting Components configuration page, to leave a watermark on the reports, leave the keycode blank. Or, to remove the watermark, enter your keycode for the product.

Crystal Reports keycode

To configure the server connectors

When you configure the connection between the Device Manager agent and the Device Manager server, you can configure the following connectors, which require the same information but serve different purposes:

  • If you manage IOS devices, select Enable iOS. When you select the checkbox, the authentication code appears automatically. In Authentication code for applications/tunnels, enter a prefix that Device Manager uses to create authentication keys used by the software. Use a simple alphanumeric word or passphrase. Use mixed case, numbers, and letters only. Then, record this value for use later when you configure the system.
    Important: You can only select Enable iOS during installation. If you do not select this option and you want to enable the mode in the future, you must reinstall the application server.
  • HTTP connector that allows insecure connections over port 80. You can configure this connector if NetScaler Gateway is installed between the Device Manager server and mobile devices.

    HTTP connector

  • HTTPS connector for secure connections over port 443 with a certificate.

    HTTPS connector

  • HTTPS connector that allows secure connections over port 8443 for device enrollment.

    Connector for device enrollment

When you configure connectors, you set the following parameters:

  • Protocol for secure and insecure connections (HTTP or HTTPS).
  • IP addresses.
  • Port settings for the connector. To allow connections over HTTPS and that use certificates for authentication, you use port 443. For secure connections without certificates, use port 8443. For insecure connections use port 80.
  • Maximum concurrent connections defines the total amount of user connections that are allowed for each connector.

To configure root and server certificates in Device Manager

Device Manager supports root, server, and APNS certificates. Root certificates enable Device Manager to communicate with other XenMobile components. Server certificates enable secure communication between Device Manager and devices.

The installation wizard prompts you to install a root certificate from a Certificate Authority (CA) first and then the server certificate. For each certificate, you provide the following information:

  • Keystore file path is the certificate location on your computer. Do not change the default path. The server configuration provides the file path automatically.
  • Keystore password and Confirm keystore password is for the private key. Enter the private password used for each component of the local CA. Although you can use the same password for each CA keystore component, Citrix recommends using separate passwords for the root, server, device, and Web Service certificates. Passwords must have at least eight characters, and can consist of alphanumeric and ASCII symbol values. Passwords are case sensitive.
  • Organizational unit is an optional parameter. Enter a value typically given to the entity or group that has management authority over the certificate.
  • Organization is an optional parameter. Enter a value typically given to the entity or organization that is the parent that owns the certificate and its rights.

For root certificates, you need to provide the common name for the CA that issued the root certificate. Leave the default name to associate it with the creation of the CA component and certificate. If you change this field, your devices may not receive the proper chain of certificates and will not be able to enroll.

Note: The root certificate is used to issue and sign certificates for intermediate server and client-device certificates. The root certificate is also used to regenerate intermediate certificates in the event of compromise. You can install root certificates in the operating system as a trusted CA root certificate.
Configuring Root Certificates in Device Manager

For secure server certificates, you need to include the IP address or FQDN that is in the certificate. Users connect by using the IP address or FQDN contained within the certificate.

Server certificate

To install an APNS certificate in Device Manager

To allow users to connect from iOS devices, you must install an APNS certificate from Apple. When you install the certificate on Device Manager, you enter the associated private key password used to generate the original Certificate Signing Request (CSR) in the field in Private key password.

In Certificate file path, specify the file system location of a pre-authenticated APNS certificate file that you download and convert to PKCS#12 format from the Apple iOS Developer for Enterprise portal.

Note: APNS certificates are provisioned by Apple, Inc. To obtain an APNS certificate, sign in to the Apple Push Certificates Portal. When you log on, you can compare the information on the Apple web site with the values shown in the following figure:

Installing the APNS Certificate in Device Manager

Allowing Remote Support to Connect to Mobile Devices

On the Configure tunnel port(s) used by remote support page, define the port range used by remote support for Android and Windows Mobile devices. The default is port 8081.

Defining the tunneling port

To designate the Device Manager administrator

To connect to the Device Manager web console, you need to configure an account with the administrator role.

On the Extended management of the users page, you enter the administrator's name and password. After you enter the values, you can check the user name in Active Directory.

Configuring an administrative account

After you configure the administrator user and password, you can finish the installation wizard.

After you finish the wizard, you should do the following:

Configuring Active Directory on Device Manager

You use Active Directory with Device Manager to manage groups of users, not individual user accounts. Device Manager supports the following sources of user account information:

  • LDAP directory. You can configure Device Manager to read an LDAP-compliant directory, such as Active Directory to import groups, user accounts, and related properties.
  • Manual entry. You can use group maintenance forms in Device Manager to quickly create user accounts.
  • Provisioning file. You can develop a file outside of Device Manager containing user accounts and properties and then import the file. Device Manager automatically creates objects and sets properties values.

You can perform the following actions in Device Manager for LDAP connections:

  • Create a new LDAP connection.
  • Edit an existing connection.
  • Set the default LDAP connection.
  • Activate or deactivate an LDAP connection.

When you create a new LDAP connection, you configure the LDAP directory settings and then you import a signed secure certificate. When you define the connection parameters, you need to grant the following rights to the Search User service account:

READALLUSERINFORMATION

READALLNETWORKPERSON

Note: In the Lockout Limit field, the default is set to zero. However, Citrix recommends using a higher value, as well as a value that is slightly lower than the lockout limit set on your LDAP server. For example, if your LDAP server is configured to a limit of five attempts before lockout, Citrix suggests that you enter a 3 or 4 in this field.

You can also map the LDAP directory attributes to the Device Manager Repository database. If you do not modify the default settings, Device Manager binds automatically to the LDAP directory. You can specify the base DN that defines the LDAP directory groups that are imported to Device Manager.

Installing Patches for Device Manager

If a patch has been issued to resolve a problem that applies to your situation and Device Manager implementation, you may download one or more appropriate patches for your system.

Patches follow the naming convention of 'a_patch_###_xxxx.jar' where ### signs are the version release number for Device Manager and xxxx refers to the patch number.

To install the patch, copy the file 'a_patch_###_xxxx.jar' to the following directory %systemroot%\Program Files (x86)\Zenprise\ZenpriseDevice Manager\tomcat\webapps\zdm\WEB-INF\lib or the directory in which you installed Device Manager.

After you copy the file to the directory, restart the Device Manager service.

Upgrading Device Manager

You upgrade the Device Manager server through an in-place upgrade process. The XenMobile Device Manager Setup wizard updates your existing Device Manager installation and database in one step.

XenMobile 8.7 supports direct upgrades from XenMobile 8.6 and XenMobile 8.5. To upgrade from earlier versions of XenMobile and Zenprise, you must first upgrade to XenMobile 8.5.

  1. Before starting the upgrade, back up the Device Manager database and core application directories.

    For details, see To perform a full manual backup of Device Manager server.

  2. Ensure that you are running Java Standard Edition 7 Development Kit (minimum version 1.7.0_11) and Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7 on your Device Manager server.

    For details, see Device Manager System Requirements.

  3. Run the Device Manager installation file as an administrator and then follow the instructions in the XenMobile Device Manager Setup wizard.
  4. If you plan to deploy Samsung for Enterprise (SAFE) and Samsung KNOX policies to compatible devices, you must manually create the configuration to generate the Samsung Enterprise License Management (ELM) key.

Backing Up and Restoring Device Manager

Backing up your Device Manger server installation and core application file system directory is crucial to a good disaster recovery or business continuity plan. This section describes backing up and restoring Device Manager.

You can back up Device Manager by using the following methods:

  • Stop all services and then make a copy of the entire application directory on the server.
  • Copy the application directories required for restoration and also perform a native SQL database server backup by using the PostgreSQL utility called pgAdmin. You can also use Microsoft SQL Server Management Studio for your version of Microsoft SQL Server.

If you want to restore Device Manager, you also use pgAdmin or Microsoft SQL Server Management Studio.

To perform a full manual backup of Device Manager server

To back up a default installation of the Device Manager server, you stop all services and make a copy of the entire application directory on the server.

  1. From the Services utility on the Device Manager server, stop the XenMobile Device Manager and the XenMobile Device Manager Database - PostgreSQL 8.3 services. MS SQL database installations should follow the best practices used for the particular type of SQL server installation. Online and offline backups are acceptable as long as the backup database and transaction logs are maintained together for restoration.
  2. Back up the XenMobile Device Manager database and application environment. Make a full directory copy of the Device Manager application directory typically located at C:\Program Files (x86)\Citrix\XenMobile Device Manager
  3. Save the full directory copy to a safe external location, such as tape backup or external media storage system. This full directory backup contains the Database, Application, PKI configuration and certificates, and all configuration and log files.

To perform a directory and native SQL backup of Device Manager server

Another method of backup for Device Manager server is to copy the application directories required for restoration and also perform a native SQL database server backup by using the default PostgreSQL utility pgAdmin. For a Microsoft SQL Server database installation, use the Microsoft SQL Server Management Studio application and follow the instructions provided by Microsoft or your database administrator to back up your database according to your needs. The following steps will guide you through the process using the default PostgreSQL pgAdmin III utility only.

  1. From the Services utility on the Device Manager server, stop the XenMobile Device Manager service.
  2. Start the pgAdmin III utility fromStart > All Programs > PostgreSQL 8.3.
  3. Enter the password for the default Postgre administrator account for the database. The password was recorded during installation.
  4. Expand the Databases branch of the servers tree in the pgAdmin utility, right-click the xdm database object and then select Backup.
  5. Enter a directory location and new file name for the backup file and then click OK.
  6. When finished, click Done. The resulting backup file is saved to your predetermined location for archival and retrieval when a database restore is necessary.
  7. Next, while the Device Manager service is stopped, back up at least the following directories within the main application folder:
    • C:\Program Files (x86)\Citrix\XenMobile Device Manager\tomcat\conf
    • C:\Program Files (x86)\Citrix\XenMobile Device Manager\tomcat\webapps\zdm\WEB-INF
  8. Verify that the directory has a complete copy of the Tomcat configuration and PKI certificates. These files are located under the parent directory: C:\Program Files (x86)\Citrix\XenMobile Device Manager\tomcat\conf
  9. Verify that the backup directory also contains the license file normally found at: C:\Program Files (x86)\Citrix\XenMobile Device Manager\tomcat\webapps\zdm\WEB-INF
The Device Manager application and database environment is now fully backed up and can be restored to the same or different system host.