Product Documentation

Logging Administrative Changes to a XenApp Farm

Apr 29, 2015

The Configuration Logging feature allows you to keep track of administrative changes made to your server farm environment. By generating the reports that this feature makes available, you can determine what changes were made to your server farm, when they were made, and which administrators made them. This is especially useful when multiple administrators are modifying the configuration of your server farm. It also facilitates the identification and, if necessary, reversion of administrative changes that may be causing problems for the server farm.

When this feature is enabled for a licensed server farm, administrative changes initiated from the following components lead to the creation of log entries in a central Configuration Logging database:
  • Delivery Services Console
  • some command-line utilities
  • tools custom built with SDKs
Before you enable the Configuration Logging feature:
  • Determine the level of security and control you need over the configuration logs. This determines if you need to set up additional database user accounts and if you want to make XenApp administrators enter credentials before clearing logs.
  • Determine how strictly you want to log tasks; for example, if you want to log administrative tasks and if you want to allow administrators to make changes to a farm if the task cannot be logged (for example, if the database is disconnected).
  • Determine if you want to allow administrators to be able to clear configuration logs and if you want them to have to supply credentials for this purpose. This requires the permission to Edit Configuration Logging settings.
Important: To securely store the credentials used for accessing the Configuration Logging database, you can enable the IMA encryption feature when you deploy your server farm. After this is enabled, however, you cannot disable it without losing the data it encrypted. Citrix recommends that you configure IMA encryption before the Configuration Logging feature is configured and used.
To enable the Configuration Logging feature:
  • Set up the Configuration Logging database
  • Define the Configuration Logging database access permissions
  • Configure the Configuration Logging database connection
  • Set the Configuration Logging properties
  • Delegate administrative permissions, as needed

The Configuration Logging feature, after it is properly enabled, runs in the background as administrative changes trigger entries in the Configuration Logging database. The only activities that are initiated by the user are generating reports, clearing the Configuration Logging database, and displaying the Configuration Logging properties.

To generate a configuration logging report, use the PowerShell command Get-CtxConfigurationLogReport. For more information, see help for Get-CtxConfigurationLogReport or Windows PowerShell with Common Commands.

Setting up the Configuration Logging Database

The Configuration Logging feature supports Microsoft SQL Server and Oracle databases; for information about supported versions, see CTX114501.

The Configuration Logging database must be set up before Configuration Logging can be enabled. Only one Configuration Logging database is supported per server farm, regardless of how many domains are in the farm. When the Configuration Logging database is set up, you also must ensure that the appropriate database permissions are provided for XenApp so that it can create the database tables and stored procedures (preceded by “CtxLog_AdminTask_”) needed for Configuration Logging. Do this by creating a database user who has “ddl_admin” or “db_owner” permissions for SQL Server, or a user who has the "connect" and "resource" roles and "unlimited tablespace" system privilege for Oracle. This is used to provide XenApp full access to the Configuration Logging data.

The Configuration Logging feature does not allow you to use a blank password to connect to the Configuration Logging database.

Each server in the server farm must have access to the Configuration Logging database.

Considerations for SQL Server

Only one server farm is supported per Configuration Logging database. To store Configuration Logging information for a second farm, create a second Configuration Logging database.

When using Windows Integrated Authentication, only fully qualified domain logons are valid. Local user account credentials will fail to authenticate on the database server that hosts the Configuration Logging database.

Ensure that all Citrix administrators accessing the same farm are configured to use the same default schema. The database user who will create the Configuration Logging tables and stored procedures must be the owner of the default schema. If you are using dbo as the default schema, the database user must have db_owner permissions. If you are using ddl_admin as the default schema, the database user must have ddl_admin permissions.

See the SQL Server documentation for information about managing and using schemas.

Considerations for Oracle

Only one farm is supported per schema. To store Configuration Logging information for a second farm in the same database instance, use a different schema. Tables and stored procedures are created in the schema associated with the user who initially configured the Configuration Logging feature. For information about managing and using a different schema, see the Oracle documentation.

Important: To use an Oracle database for configuration logging, the 32-bit Oracle client must be installed on the Delivery Services Console.

Before running the Delivery Services Console, update the Oracle tnsnames.ora client file to include the connectivity information needed to access the available databases.

Defining Database Permissions for Configuration Logging

The first time the Configuration Logging feature is enabled, it connects to the Configuration Logging database and discovers that the database schema does not exist. XenApp then creates the database schema, tables, and stored procedures. To create a database schema, XenApp needs full access to the database. After the database schema is created, full access is no longer necessary and you have the option of creating additional users with fewer permissions.

The following table lists the minimum permissions required to perform the Configuration Logging tasks.
Configuration Logging task Database permissions needed

To create log entries in the database tables

  • INSERT for the database tables
  • EXECUTE for the stored procedures
  • SELECT
    • SQL Server: for sysobjects and sysusers
    • Oracle: for sys.all_objects, and for sequence objects and the "create session" system privilege

To clear the log

  • DELETE/INSERT for the database tables
  • EXECUTE for the GetFarmData stored procedure
  • SELECT
    • SQL Server: for sysobjects and sysusers
    • Oracle: for sys.all_objects, and for sequence objects and the "create session" system privilege

To create a report

  • EXECUTE for the Configuration Logging stored procedures
  • SELECT
    • SQL Sever: for sysobjects and sysusers
    • Oracle: for sys.all_objects, and for sequence objects and the "create session" system privilege

The Configuration Logging components must have access to the GetFarmData stored procedure to find out if a Configuration Logging database is associated with a farm. If you do not have permission to execute an existing GetFarmData stored procedure, this farm is invisible to the Configuration Logging components.

Considerations for SQL Server

Before you configure the Configuration Logging database connection, grant EXECUTE permission to the sp_databases system stored procedure to list the databases on the database server.

The authentication mode must be the same for the database user who creates log entries in the database tables and the database user who clears the log.

To configure the connection to the Configuration Logging database

After the Configuration Logging database is set up by your database administrator and the appropriate database credentials are provided to XenApp, use the Configuration Logging Database wizard to configure the connection to the database.

  1. From the Delivery Services Console, select a farm.
  2. From the Action menu, select Farm properties.
  3. Click Configuration Logging.
  4. Click Configure Database. The wizard opens.
  5. Select the connection type (SQL Server or Oracle). For SQL Server, use the drop-down list to select a SQL Server; for Oracle, select a net service name (from the Oracle tnsnames.ora client file). You can also type the entry.
  6. (SQL Server only). Select an authentication mode: Windows integrated security (recommended) or SQL Server authentication.
  7. Enter a valid user name and password for the database. Credentials are always required (even if you are using Windows Integrated Authentication with SQL Server). The credentials are stored using the IMA encryption feature. Each server that creates log entries uses the credentials to connect to the Configuration Logging database.
  8. (SQL Server only). Select or type the name of the database.
  9. Configure connection options and connection pooling options. You can use the default values for these settings. (For SQL Server, the possible exception is Use encryption. For security reasons, the default value is Yes; however, if the database server to which you are connecting does not support encryption, the connection will fail. Click Test Database Connection on the summary page to check for encryption support.)
  10. Click Test Database Connection. A display indicates whether or not the connection established successfully.

After you configure the connection to the Configuration Logging database, you cannot set the database back to None. To stop logging, clear the Log administrative tasks to Configuration Logging database check box in the Configuration Logging dialog box.

To set Configuration Logging properties

Before you set Configuration Logging properties, configure the database and the connection to the database. Otherwise, the Configuration Logging property fields are not active.

Full Citrix administrators can edit the Configuration Logging settings and clear the log, or they can authorize other administrators to perform these tasks by assigning them the delegated administration Edit Configuration Logging Settings permission. Without this permission, ordinary administrators cannot perform these functions.

  1. From the Delivery Services Console, select a farm.
  2. From the Action menu, select Farm properties.
  3. Click Configuration Logging.
  4. To enable Configuration Logging, select the Log administrative tasks to Configuration Logging database check box. If you want administrators to be able to make changes to the server farm when log entries cannot be saved to the Configuration Logging database, select the Allow changes to the farm when logging database is disconnected check box.
  5. To prompt administrators to enter their credentials before clearing the log, select the Require administrators to enter database credentials before clearing the log check box.

Clearing Entries from the Configuration Logging Database

It may become necessary to clear the entries in the Configuration Logging database if the population of the tables becomes too large.

To manage which database users can clear the configuration log, Citrix recommends that you enable the Require administrators to enter database credentials before clearing the log check box in the Configuration Logging properties. Anyone attempting to clear the log is prompted for database credentials.

The credentials must correspond to the authentication mode you selected when you connected to the database initially. Specifically:
  • For SQL authentication, credentials with permissions for the Configuration Logging database on the SQL server are required
  • For Windows Integrated authentication, XenApp impersonates the database user when it connects to the SQL database, so credentials for the Windows user account are required

Use one of the following methods to clear log entries from the Configuration Logging database:

  • From the Delivery Services Console, expand the farm node and select History. Select Clear history in the Actions pane or the Action menu.
  • Use the PowerShell command Clear-XAConfigurationLog. For more information, see help for Clear-XAConfigurationLog or Windows PowerShell with Common Commands.

Encrypting Configuration Logging Data

Independent Management Architecture (IMA) is the underlying architecture used in XenApp for configuring, monitoring, and operating all XenApp functions. The IMA data store stores all XenApp configurations.

IMA encryption protects administrative data used by Configuration Logging. This information is stored in the IMA data store. For IT environments with heightened security requirements, using IMA encryption provides a higher degree of security for Configuration Logging. One example would include environments that require strict separation of duties or where the Citrix Administrator should not have direct access to the Configuration Logging database.

IMA encryption is a farm-wide setting that applies to all servers in the farm after encryption is enabled. Consequently, to use IMA encryption, you must enable it on all servers in the farm. IMA encryption has the following components:
Component Description
CTXKEYTOOL Also known as the IMA encryption utility, CTXKEYTOOL is a command-line utility you use to manage IMA encryption and generate key files. CTXKEYTOOL is in the Support folder of the XenApp media.
Key file The key file contains the encryption key used to encrypt sensitive IMA data. You create the key file using CTXKEYTOOL. To preserve the integrity of the encryption, Citrix recommends that you keep the key file in a secure location and that you do not freely distribute it.
Key The same valid IMA encryption key must be loaded on all servers in the farm if IMA encryption is enabled. After copying the key file to a server, you load the key by using CTXKEYTOOL.
Configuring IMA encryption includes the following tasks:
  • On the first server in a farm (that is, the server on which you create the farm during XenApp configuration), generate a key file, load the key, and enable it
  • Make the key file accessible to other servers in the farm or put it on a shared network location
  • Load the key onto other servers in the farm (that is, the servers that join the farm during configuration)

Citrix recommends that if you are enabling IMA encryption in environments that have multiple farms, you give the key for each farm a different name.

Storing CTXKEYTOOL Locally

  1. Copy the CTXKEYTOOL.exe file from the Support folder of XenApp media to your local computer.
  2. Create a folder named Resource at the same level in your directory structure as the CTXKEYTOOL file.
  3. Copy the entire Support\Resource\en folder to the new Resource folder.

You can store the CTXKEYTOOL.exe file and the Resource\en folder anywhere on your computer, provided you maintain the same relative directory structure used on the media.

To generate a key and enable IMA encryption on the first server in a farm

Before enabling IMA encryption on the first server in the XenApp farm (that is, the server on which you created the farm), install and configure XenApp, and restart the server.

  1. On the server where you created the XenApp farm, run CTXKEYTOOL with the generate option, specifying the full UNC or absolute path (including the file name of the key you want to generate) to the location where you want to store the file key.

    Citrix suggests naming the key after the farm on which it will be used; for example, farmakey.ctx. Citrix also suggests saving the key to a folder that uses the name of your farm; for example, Farm A Key.

    If the key file generates successfully, the message “Key successfully generated" appears.

  2. To obtain the key from the file and put it in the correct location on the server, run CTXKEYTOOL with the load option on the server on which you want to add the key, specifying the full UNC or absolute path (including the key file name) to the location where you stored the key file. If the key loaded successfully, the message “Key successfully loaded” appears.
  3. Run CTXKEYTOOL with the newkey option to use the currently loaded key and enable the key. If IMA encryption is enabled successfully, the message “The key for this farm has been replaced. IMA Encryption is enabled for this farm” appears.

Storing the Key File on a Shared Network Location

If you choose to store the key on a shared network location, Citrix recommends the following:
  • Give the folder a meaningful name that specifies the name of the farm for which the key was created. This is important in situations when you follow the Citrix best practice recommendation of creating a unique key for the farm.
  • Ensure that the account you use to generate the key is the same as the account that will be used to configure all the servers in the farm. You must use the same account for both tasks.
  1. When you generate the key file, save it to a local directory (as you normally would).
  2. After enabling IMA encryption on the server where you generated the key, copy the key file to the shared network location.
  3. Grant Read/Execute access to the key file for each server that will be joining the farm, and to the administrator performing the installation.

To load a key on servers that join the farm

Before enabling IMA encryption on servers you are joining to a XenApp farm, install and configure XenApp, but do not restart the server.

  1. If you do not have the key file on a shared network location, load the key file to the server.
  2. To obtain the key from the file and put it in the correct location on the server, run CTXKEYTOOL with the load option, specifying the full UNC or absolute path (including the key file name) to the location where you stored the key file. If the key loaded successfully, the message “Key successfully loaded” appears. You do not need to enable IMA encryption on this server, because you already enabled it on the first server in the farm
  3. Restart the server.

Repeat this procedure on all servers you configure to join the farm.

Changing Farms

If you move a server that has IMA encryption to a farm that has IMA encryption enabled, run CTXKEYTOOL with the load option (specifying the key that was generated for the new farm) on that server is configured but before it is restarted.

If you move a server that has IMA encryption enabled to a farm that does not have IMA encryption enabled, IMA encryption is disabled automatically on the server being moved.

Managing IMA Encryption

IMA encryption includes other features that you can use as needed:

  • Citrix strongly recommends backing up the farm key to a safe, secondary location, such as a CD, immediately after you generate a key. You can create a copy of the key file when you create it, or you can back up the farm key by running CTXKEYTOOL with the backup option.
  • You can recreate a key file that you accidentally deleted, lost, or overwrote. All servers in the same farm use the same key, so you can obtain a key from another server on the farm; however, XenApp does not allow you to access keys. You must recreate the entire key file by running CTXKEYTOOL with the backup option on any server in the farm that has the key and is functioning properly.
  • You can disable IMA encryption by running CTXKEYTOOL with the disable option. Because IMA encryption is a farm-wide feature, disabling it on one server disables the feature on all servers.

    If you disable IMA encryption, to access the Configuration Logging database, you must reenter the password for the Configuration Logging database. In addition, no configuration information is logged until you reenter your database credentials.

    To reenable IMA encryption after you disabled it, run CTXKEYTOOL with the enable option. After enabling IMA encryption, Citrix recommends that you run CTXKEYTOOL with the query option to verify that IMA encryption is enabled.

For more information about CTXKEYTOOL, see the XenApp Command Reference documentation.