This section includes information about:
You can use the Caching page to manage various caches maintained by the Identity Manager User Application. The User Application employs these caches to store reusable, temporary data on the application server so it can optimize performance.
You have the ability to control these caches when necessary by flushing their contents and changing their configuration settings.
The caches are named according to the subsystems that use them in the Identity Manager User Application. Normally, you don’t need to flush them yourself, because the User Application does that automatically based on how frequently their data is used or when the source data changes. However, if you have a specific need, you can manually flush selected caches or all caches.
Go to the Caching page:
In the
section of the page, use the drop-down list to select a particular cache to flush (or select ):The list of available caches is dynamic; it changes depending on what data is cached at the moment.
Click
.The User Application’s directory abstraction layer also has a cache. The DirectoryAbstractLayerDefinitions cache stores abstraction layer definitions on the application server to optimize performance for all data model operations.
In a typical situation, the User Application automatically keeps the DirectoryAbstractLayerDefinitions cache synchronized with the abstraction layer definitions stored in the Identity Vault. But, if necessary, you can manually flush the DirectoryAbstractLayerDefinitions cache as described in Flushing caches to force the latest definitions to be loaded from the Identity Vault.
For more information on the User Application’s directory abstraction layer, see the Identity Manager User Application: Design Guide.
Cache flushing is supported in both clustered and non-clustered application server environments. If your application server is part of a cluster and you manually flush a cache, that cache is automatically flushed on every server in the cluster.
You can use the Caching page to display and change cache configuration settings for a clustered or non-clustered application server environment. Your changes are saved immediately, but they don’t take effect until the next User Application restart.
HINT:To restart the User Application, you can reboot the application server; redeploy the application (if the WAR has been changed in some way); or force the application to restart (as described in your application server’s documentation).
In the Identity Manager User Application, caching is implemented via JBoss Cache. JBoss Cache is an open source caching architecture that’s included with the JBoss Application Server but also runs on other application servers.
To learn more about JBoss Cache, go to www.jboss.org/products/jbosscache.
Two levels of settings are available for controlling cache configuration: global, and local. Use these settings to customize the caching behavior of the Identity Manager User Application. Table 5-1 describes the cache configuration settings.
Table 5-1 Cache Configuration Settings
You should think of global settings as the default values for every application server that uses a particular instance of the User Application driver. When you change a global setting, you are affecting each of those servers (at the next User Application restart), except for those cases where an individual server specifies a local override.
The Caching page displays the current cache settings (from the latest User Application restart). It also displays the corresponding global and local values of those settings, and lets you change them (for use at the next User Application restart).
The global settings always have values. The local settings are optional.
These cache settings apply to both clustered and non-clustered application servers.
To configure basic cache settings:
Go to the Caching page.
In the
section of the page, specify global or local values for the following settings, as appropriate:
Setting |
What to do |
---|---|
t |
Specify the time interval (in milliseconds) that the cache waits for a lock to be acquired on an object. You might want to increase this setting if the User Application gets a lot of lock timeout exceptions in the application log. The default is 15000 ms. |
|
Specify the time interval (in seconds) that the cache eviction policy waits before waking up to do the following:
|
|
Specify the classname for the cache eviction policy that you want to use. The default is the LRU eviction policy that JBoss Cache provides: org.jboss.cache.eviction.LRUPolicy If appropriate, you can change this to another eviction policy that JBoss Cache supports. To learn about supported eviction policies, go to www.jboss.org/products/jbosscache. |
|
Specify the maximum number of nodes allowed in the cache. For no limit, specify: 0 You can customize this setting for some cache holders. See Customizable Cache Holders. |
|
Specify the time to idle (in seconds) before the node is swept away. For no limit, specify: 0 You can customize this setting for some cache holders. See Customizable Cache Holders. |
|
Specifies the number of seconds an entry should be allowed to stay in the cache holder since its creation time. For no time limit, specify: 0 This setting is only available for Customizable Cache Holders. |
These settings are required, which means that there must be a global value for each, and optionally a local value too.
If you want to override the global value of a setting with a local value, select the
check box for that setting. Then specify the local value. (Make sure that all of your local values are valid. Otherwise, you won’t be able to save your changes.)NOTE:For those settings where
is deselected, any existing local values are deleted when you save.Click
.When you’re ready for your saved settings to take effect, restart the User Application on the applicable application servers.
You can customize the Table 5-2.
, , and settings for some cache holders. The cache holders are listed inTable 5-2 Customizable Cache Holders
Cache Holder Name |
Description |
---|---|
DirectoryAbstractionLayerDefinitions |
Caches the Directory Abstraction Layer definitions to optimize performance for all data model operations. See Flushing the Directory Abstraction Layer Cache. |
DirectoryService.ContainerCacheHolder |
Caches containers in the directory layer. Containers are shared by many users and groups, and reading them from the directory layer involves both network communication (with the LDAP server) and object creation. By default, the cache is limited to 50 containers, and the LRUs have a default Time To Live (TTL) of 10 minutes. Depending on the directory topography in your enterprise, you might need to adjust the maximum number of nodes or the TTL if you find the performance is suffering because of queries to the LDAP server for container objects. Making settings too high in combination with a large number of usable containers can cause unneeded memory consumption and net lower performance from the server. |
DirectoryService.DelProxyRuntimeServiceDelegate |
Caches delegate assignments. |
DirectoryService.DelProxyRuntimeService.Delegation |
Caches user availability settings. |
DirectoryService.DelProxyRuntimeService.Delegator |
Caches the delegator entities. |
DirectoryService.DelProxyRuntimeService.Proxy |
Caches proxy assignments. |
DirectoryService.GroupCacheHolder |
Caches groups in the directory layer. Groups are often shared by many users, and reading them from the directory layer involves both network communication (with LDAP server) and object creation. By default, the cache is limited to 500 groups, and the LRUs have a default TTL of 10 minutes. Depending on the user/group topography in your enterprise, you might need to adjust the maximum number of nodes or the TTL if you find the performance is suffering because of queries to the LDAP server for groups objects. Settings that are too high, in combination with a large number of usable groups, can cause unneeded memory consumption, and net lower performance from the server. |
DirectoryService.MemberhipCacheHolder |
Caches the relationship between a user and a set of groups. Querying the set of groups a user belongs to can be a network and CPU intensive operation on the LDAP server, especially if dynamic groups are enabled. For this reason, relationships are cached with an expiration interval so that changes in the criteria for inclusion/exclusion in a group (such as time-based dynamic groups) are reflected. The default Max Age is five minutes. However, if you use dynamic groups which have a requirement for finer grained time control, then you can adjust the Max Age on this cache holder to be just below the minimum time your finest grained time based dynamic group requires. The lower this value is, the more times the user's groups are queried during a session. Setting a value too high keeps the user/group relationships in memory perhaps longer than the user's session needlessly consuming memory. |
DirectoryService.RolesMembershipCacheHolder |
Caches the application role membership list by role. |
DirectoryService.TeamManagerRuntime.Team |
Caches the application team instances and team provisioning requests. |
DirectoryService.UserCacheHolder |
Caches users in the directory layer. Reading users from the directory layer involves both network communication (with LDAP server) and object creation. By default, the cache is limited to 1000 users, and the LRUs have a default TTL of 10 minutes. Depending on the user topography in your enterprise, you might need to adjust the maximum number of nodes or the TTL if you find the performance is suffering because of queries to the LDAP server for user objects. Making settings too high combined with a large number of different users logging in can cause unneeded memory consumption, and net lower performance from the server. |
GlobalCacheHolder |
The general purpose cache holder. This configuration applies to all caches that are not customizable (that is, all cache holders not listed in this table.) |
JUICE |
Caches the resource bundles used by the user interface controls and DN display expression lookup results. Changing the setting of the cache holder has a performance impact for the DN display expression lookups because they are frequently used in the User Application. The low value should be at least 300 seconds, but a higher value than 900 seconds is ok. A lower value should be used if the customer is frequently changing the attributes that are used in the DN display expression |
RoleManager.RolesCacheHolder |
Caches user role memberships listed by user. |
Workflow.Model.Process |
Caches the provisioning process XML object structure. |
Workflow.Model.Request |
Caches the provisioning request XML object structure. |
Workflow.Provisioning |
Caches provisioning request instances that have not completed. The default maximum capacity for the LRU cache is 500. The capacity can be modified by clicking the tab and choosing the Engine and Cluster settings. The Process Cache Maximum Capacity appears on this page. This cache reduces the memory footprint for workflow processing without compromising performance. |
This section discusses how to configure caching when you run the Identity Manager User Application across a cluster of application servers.
In the Identity Manager User Application, cluster support for caching is implemented via JGroups. JGroups is an open-source clustering architecture that’s included with the JBoss Application Server but also runs on other application servers.
The User Application’s cluster consists of nodes on a network that run JGroups and use a common Group ID. By default, the Group ID provided for the User Application’s cluster is a UUID that looks like this:
c373e901aba5e8ee9966444553544200
The UUID helps ensure uniqueness, so that the Group ID of the User Application’s cluster doesn’t conflict with the Group IDs of other clusters in your environment. For instance, the JBoss Application Server itself uses several JGroups clusters and reserves associated names including the Group IDs DefaultPartition and Tomcat-Cluster for them.
To learn more about JGroups, go to www.jboss.org/products/jgroups.
When you start the User Application, the application’s cluster configuration settings on the
page determine whether to participate in a cluster and invalidates cache changes in the other nodes in that cluster. If clustering is enabled, the User Application accomplishes this by sending cache entry invalidation messages to each node as changes occur.To use caching across a cluster:
Set up your JGroups cluster. This involves using the User Application installation program to install the Identity Manager User Application to each application server in the cluster (see Section 2.7, Clustering).
Enable the use of that cluster in the User Application’s cache configuration settings
After you have a cluster ready to use, you can specify settings for the support of caching across that cluster.
Go to the Caching page.
In the
section of the page, specify global or local values for the following settings, as appropriate:
Setting |
What to do |
---|---|
|
Select to invalidate cache changes to the other nodes in the cluster specified by Group ID. If you don’t want to participate in a cluster, select . |
|
Specify the Group ID of the JGroups cluster in which you want to participate. There’s no need to change the default Group ID that’s provided for the User Application’s cluster, unless you want to use a different cluster. The Group ID must be unique and must not match any of the known JBoss cluster names such as DefaultPartition and Tomcat-Cluster. HINT:To see the Group ID in logging messages, make sure that the level of the caching log ( com.sssw.fw.cachemgr) is set to Info or higher. |
|
Specify the JGroups protocol stack for the cluster specified by Group ID. This setting is for experienced administrators who might need to adjust the cluster properties. Otherwise, you should not change the default protocol stack. To see the current cluster properties, click .For details on the JGroups protocol stack, go to www.joss.org/wiki/Wiki.jsp?page=JGroups. |
If you want to override the global value of a setting with a local value, select the
check box for that setting. Then specify the local value.For those settings where
is unselected, any existing local values are deleted when you save.Make sure that all nodes in your cluster specify the same Group ID and Cluster Properties. To see these settings for a particular node, you must access the Identity Manager user interface running on that node—by browsing to the URL of the user interface on that server—and then display the Caching page there.
If you need to use the TCP protocol instead of the default UDP protocol, see Specifying the User Application Cluster Group Caching Configuration.
Click
.When you’re ready for your saved settings to take effect, restart the User Application on the applicable application servers.
You can use the Driver Status pane to determine the expiration status of your driver.
Figure 5-1 Sample Driver Status for a “Trial” Driver
An Expiration Date value of
means that the driver has been started and is fully licensed or has not yet been started. If it has not been started, it might also be a trial driver. If there is an expiration date, then the driver is a trial driver and it has been started. The page itself describes what values of UNKNOWN mean.You can use the LDAP Parameters pane to:
Change the credentials used by the Identity Manager User Application when connecting to the Identity Vault (LDAP provider)
Change the credentials for the guest account, if your system is configured to use a specific guest account, rather than LDAP anonymous account.
View other LDAP properties of the Identity Manager User Application. The values of these settings are determined when you install the User Application.
The user interface displays different fields depending on how you configured the guest account during installation. If you specified a guest account, the user interface includes fields that let you update the credentials for that account. If you have configured your system to use the LDAP Public Anonymous account, the user interface displays this message: The application is configured to use public anonymous account. To use a specific guest account, enable the guest account using the ldap configuration tool.
To administer LDAP connection parameters:
On the Application Configuration page, select
from the navigation menu on the left.The LDAP Connection Parameters panel displays:
Examine and modify the settings, as appropriate. For details, see:Settings You Can Change.
If you make changes that you want to apply, click
.On the LDAP Connection Parameters panel, you can modify settings for the credentials for:
The Identity Manager User Application whenever it connects to the Identity Vault (LDAP provider).
The guest account (if configured).
The initial values for the credentials are specified during installation. These installation values are written to the sys-configuration-xmldata file. If you make changes to these credentials via the Administration page, your changes are saved to the User Application’s database; they are not saved to the sys-configuration-xmldata file. After values are written to the database, the User Application no longer checks the values written to the sys-configuration-xmldata file. This means that you cannot use the configupdate utility to change the credentials because they are ignored. However, you can use configupdate to change the type of guest user (LDAP Guest or Public Anonymous Account).
Table 5-3 LDAP Parameters
If TLS is enabled for your LDAP server, you might encounter the following error when you update the Admin username and password: Unable to authenticate to LDAP Provider. Disable this error by disabling TLS via iManager.
You can use the Logging page to control the levels of logging messages you want the Identity Manager User Application to generate and specify whether those messages are sent to Novell® Audit.
The Identity Manager User Application implements logging by using log4j, an open-source logging package distributed by The Apache Software Foundation. By default, event messages are logged to both of the following:
The system console of the application server where the Identity Manager User Application is deployed
A log file on that application server, for example:
jboss/server/IDM/log/server.log
This is a rolling log file; after it reaches a certain size, it rolls over to another file. If you have configured your environment to include Novell Audit, you have the option of logging event messages there as well. For details on configuring your logging environment and Novell Audit, see Section 3.0, Setting Up Logging.
The Logging page lists a variety of logs, each outputting event messages from a different part of the Identity Manager User Application. Each log has its own independent output level.
The log names are based on log4j conventions. You’ll see these log names in the event messages that are generated, indicating the context of the message output.
Table 5-4 lists and describes the logs.
Table 5-4 Identity Manager User Application Logs
The User Application logs are hierarchical. For example, com.novell is the parent of other logs underneath it. Any additional logs inherit its properties.
You can control the amount of information that is written to a particular log by changing the level that is set for it. By default, all logs are set to Info, which is an intermediate level.
Go to the Logging page:
At the top of the page, find a log whose level you want to change.
Use the drop-down list to select one of the following levels:
Click
.You can change the log level for all of the logs to one setting by selecting
of all above logs and using the drop-down list to select the level.You can add logs for other packages used by the User Application.
Go to the Logging page:
At the bottom of the page, select
, then use the drop-down list to select the package.Choose a log level from the drop-down, then click
.You can use the Logging page to control whether the Identity Manager User Application sends event message output to Novell Audit. Novell Audit logging is off by default, unless you turn it on when installing the User Application.
To toggle Novell Audit logging on/off:
Go to the Logging page.
Select or deselect the following setting, as appropriate:
.Click
.By default, changes you make on the Logging page stay in effect until the next application-server restart or User Application redeployment. After that, the log settings revert to their default values.
However, the Logging page does offer you the option of persisting your changes to its settings. If you turn on this feature, values for the log settings are stored in a logging configuration file on the application server where the Identity Manager User Application is deployed. For example:
On JBoss, this file is
jboss/server/IDM/conf/idmuserapp_logging.xml
On WebSphere, this file is specified according to the custom property named idmuserapp.logging.config.dir.
To toggle persistence of settings on or off:
Go to the Logging page.
Select or deselect the following setting, as appropriate:
Click
.You can use the Portal page to view characteristics of the Identity Manager User Application.The settings are for informational purposes and cannot be changed.The values of these settings are set in the User Application WAR. (
reflects your current theme choice from the Themes page.)You can use the Themes page to control the look and feel of the Identity Manager user interface.
A theme is a set of visual characteristics that apply to the entire user interface (including the guest and login pages, the
tab, the tab, and the tab). There’s always just one theme in effect for the user interface. The Themes page offers a choice of several themes, in case you want to switch to a different one.The Themes page also enables you to:
Preview each theme choice to see how it looks
Customize any theme choice to reflect your own branding (such as a logo)
Before choosing a theme, you can preview how it will change the look of the Identity Manager user interface.
Go to the Themes page:
Find a theme that you are interested in, then click the corresponding
button.The preview for that theme displays in a new browser window:
Scroll through the preview to see the characteristics of this theme.
When you’re done, click
(in the top left corner) or close the preview window manually.When you find a theme that you like, you can choose to make it the current theme for the Identity Manager user interface.
Go to the Themes page.
Click the radio button for the theme you want.
Click the
button.The look of the user interface changes to reflect your chosen theme.
You can tailor any theme by substituting your own images and changing some color settings. This enables you to give the Identity Manager user interface a custom look to meet the branding requirements of your company or organization.
Go to the Themes page.
Find a theme that you want to customize, then click the corresponding
button.The Themes page displays the Customize Branding settings for that theme:
Specify your customizations by changing the settings in one or more tabs (as needed). Each tab contains the settings for different parts of the User Application interface. They include:
: Lets you specify general theming properties such as a favorites icon, background, link and hover color, and the left navigation area properties.
: Lets you specify the header color, texture, logo and username properties.
: Lets you specify the properties for the header tabs.
: Lets you specify the properties for the tab.
: Lets you specify the properties for the login screen.
Follow the on-screen instructions for specifying each setting. The changes are not reflected in the User Application until you save them. If you have made unsaved changes, the
button displays an asterisk * to indicate that the changes are pending a save.Click
.If you’re editing the current theme, the look of the user interface changes to reflect your customizations. If you want to undo all of your customizations to the theme, click the Reset button.
When you’re done working on this theme, click
.You can also create and deploy your own custom themes and deploy them in their own WAR file. When they are deployed, the custom themes are available through the Themes management page of the
tab. Before attempting to create your own custom theme, make sure you have a working knowledge of the following technologies:The structure of J2EE WAR files, how to modify the contents of a WAR file, and how to deploy one to your application server.
How to modify CSS and XML files
How to create the graphic elements for your theme
To create a custom theme, begin with a copy of an existing theme (such as
from the User Application WAR:Back up the deployed User Application WAR file ( IDMProv.WAR) to the directory in which you install, for example the /opt/novell/idm subdirectory.
In a test environment, extract the contents of the User Application WAR file.
The files that comprise the User Application’s themes are located in the resource\themes subdirectory. Each theme resides in its own directory with an appropriate name.
In the test environment, create a directory for the custom theme.
The directory name can be any valid directory name, but it should reflect the name of the theme, and it should not contain spaces.
Copy the contents of the BlueGloss theme from the extracted WAR file to the new subdirectory. You will be working with the following files:
Rules for working with these files:
Do not change the names of the theme.xml, theme.css, and print.css files.
The CSS Selector names must remain the same, but you can change the properties of the selectors to establish the look and feel.
The images subdirectory can have any name, but you must reference it correctly in the CSS and XML files.
Make your changes to the images, CSS style sheets and other theme elements as needed. The following changes are recommended:
In the theme.xml file:
display-name: Change this to a value that represents your theme. It displays as the Theme-name in the Themes page of the User Application’s
tab.description: Change this to a value that describes your theme. It displays as the Description in the Themes page of the User Application’s
tab.Consider whether to localize the
and fields.In the graphics directory:
thumbnails.gif: Replace the copy with your own image. This image displays along with the Theme-name and Description of the theme (described above) that is shown in the Themes page of the
tab. It typically illustrates what the User Application landing page looks like when the associated theme is appliedRenaming graphics files: If you change the names of graphics files (rather than just substituting a different image of the same name), make sure to change the reference to the image in both the theme.xml and the theme.css file. If the image is not used in the branding interface (for example, if it is not listed as one of the subset of brandable images in the theme.xml file), then you will only need to change the reference to the image in the theme.css file. Suppose you want to rename images/header_left.gif to images/my_company_name.gif. Edit the theme.css file to reflect the new image name.
After you make all of the desired changes to the theme files, add your customized theme directory to a new WAR file that contains one or more custom themes. Deploy the new WAR to your test application server. Testing tip: Open the Themes page (available under the
tab). Your theme should display along with the prepackaged themes. Use the Theme Preview action to see how the customized changes to your new theme will render. This is a useful way to ensure that you have completed all of your intended changes to your theme.After your changes are fully tested, you can deploy the WAR containing the custom theme to your production application server.
Any number of custom themes can reside in a single WAR. Any number of custom WARs containing custom themes can be deployed.
To undeploy the theme, remove the WAR that contains the theme from the application server’s deploy directory. Before undeploying, make sure that any themes it contains are not defined as the User Application’s default theme. If you remove the WAR and it does contain the default theme, the Theme Administration screen displays an error message and reverts the User Application theme to the original default theme defined at installation time.
If you configured Password Management to use an IDMPwdMgt.WAR. The IDMPwdMgt.WAR contains one theme; by default, it is . It does not include a user interface for modifying or branding this theme.
, the theme for the Forgot Password page is defined in that external password WAR. The default name for the external password WAR isYou can define a custom theme for the external Forgot Password page. The procedure for defining a custom theme is described in Defining a Custom Theme; however, the deployment procedure for the external Forgot Password page is different and the rules about the custom theme WAR are more restrictive. After you define the custom theme:
Package the theme in a WAR named IDMPwdMgtTheme.WAR.
The IDMPwdMgtTheme.WAR can contain a single theme, and the theme must be located in the resource/themes/Theme directory within the WAR.
Deploy the IDMPwdMgtTheme.WAR on the application server where the external WAR is located. Only one custom theme can be deployed at a time.