Skip to content
CA Application Performance Management - 10.0
Documentation powered by DocOps

Define and Configure Introscope Domains

Last update December 29, 2015

You can define and configure Introscope domains before you set up Introscope security. You can set public and private keys for secure authentication between the MOM, Collectors, and Workstations.

Define and Configure Introscope Domains

Introscope uses domains to partition agents and monitoring logic to define which CA APM users can see what information. You map Introscope agents to a domain using a Perl5 regular expression in the domains.xml file. This file is located in the <EM_Home>/config directory. You use domains.xml to define your domains regardless of which security realm you are using.

In addition to configuring domains, you also configure domain permissions when setting up Introscope security. For Local security, you’ll configure domain permissions in the domains.xml file. If you deploy CA EEM for Introscope security, the Enterprise Manager ignores domain permissions in domains.xml, and you configure them instead in CA EEM.

Domain Types

There are two types of domains in Introscope:

  • SuperDomain -- The SuperDomain is the superset domain that contains all user-defined domains in the system. All agents are visible in the SuperDomain, but may also appear in user-defined domains. The default Introscope configuration contains only the SuperDomain. If you don’t configure any other domains, all agents are mapped to the SuperDomain.
  • User-defined domain -- You define new domains in the domains.xml file, which is located in the <EM_Home>/config directory. The domains.xml file provides mappings of domain names to regular expressions.

Rules for Defining Domains

The rules for defining domains in the domains.xml file are:

  • Domain defining must follow valid XML file rules.
  • Domain names are case-sensitive.
  • Any domain must be placed inside the root XML domain’s element.
  • You may have multiple agent mappings within a domain or SuperDomain. If a domain is configured to match an agent, then that agent maps to that domain, and is also visible from the SuperDomain.

    Note: When initiating a transaction trace, such agent will be attached to a user-defined domain in the Transaction Trace window.
  • An agent always maps to the first domain to which is it is assigned. If no domain is assigned, the agent maps to the SuperDomain. If a user-defined domain is assigned, the agent maps to the user-defined domain.
  • If you do not alter the current SuperDomain Agent mapping (by default it is configured to match all agents), Introscope places any newly-defined domains before the <SuperDomain> tags.
  • Introscope places agents that do not match any mappings (either due to mistakes in the regular expressions in the domains.xml file, or other issues) in the SuperDomain.

Use Identical domains.xml Within and Across Clusters

Understand these important domains.xml rules when deploying a MOM and Collectors within a cluster and optional CDVs in and across clusters.

Important! Do not have differing domains.xml files for the MOM, Collectors, and CDVs within and across CA APM clusters.

The MOM can handle differing domains within the cluster for live agents (agents presently sending data to the cluster). However, having differing domains for historical agents on the MOM and Collectors can cause inconsistency in the MOM view of historical data. In such mixed-domain clusters, historical agents on Collectors are not tracked, so their data does not display in Workstation graphs made through the MOM unless you explicitly mount the historical agents. To avoid this situation, CA Technologies strongly recommends that you place the identical domains.xml file on the MOM and all the Collectors in a cluster. This allows live and historical agent data to be visible at all times from the MOM Workstation without mounting historical agents to view historical data on a Workstation associated with a specific Collector.

If you are deploying a Cross-cluster Data Viewer (CDV), the CDV domains.xml file must contain these domains:

  • All domains for all the Collectors to which a CDV connects.
  • All domains across all clusters containing Collectors from which the CDV gathers data.

If a domain exists in a Collector domains.xml file and is missing from the CDV domains.xml file, then the following occur:

  • CDV does not gather data for the missing Collector domain.
  • CDV Workstation does not display data from the missing Collector domain.

Define and Map Agents to a Domain

You use the domains.xml file to define domains and map agents to a domain.

Follow these steps:

  1. Navigate to the <EM_Home>/config directory.
  2. Open the domains.xml file.
  3. Define a domain using the rules for defining domains and these properties.
    • name
      The name of the domain
      The rules for this property are:
      • Alphanumeric characters only, and _ and -
      • No spaces are allowed
    • description
      A short description of the domain
      Any characters except quotation marks are allowed.
    Note: All XML tags are case-sensitive.
  4. Repeat step 3 for any additional domains.
  5. Make sure the SuperDomain mapping is defined at the end of the domains.xml, which allows domains.xml to map agents into specific domains before mapping agents to the SuperDomain.
    For example, if the following SuperDomain mapping is placed at the beginning of domains.xml, then all agent are placed under the SuperDomain before the remainder of the XML file is processed.

    <SuperDomain>

                <agent mapping="(.*)"/>

                <grant group="Admin" permission="full"/>

    </SuperDomain>

    By placing this SuperDomain mapping at the end of the domains.xml, the SuperDomain catches all unmatched agents.

  6. Save and close the domains.xml file.
  7. Restart the Enterprise Manager so it can load the new domain or domains.
Note: If there are syntax or other errors in the domains.xml file, the Enterprise Manager does not start.

domains.xml syntax for New Domains

The syntax for a domain is:

<domain name="Domainname" description="Domain description">
<agent mapping="host\|process\|agentname or matching agents"/>
<grant user="username" permission="permission"/>
</domain>

Associate Management Modules with Domains

When you create new management modules, you can choose the domains that will contain them.

You associate management modules with domains by creating directories that correspond to the names of the domains you defined in domains.xml, then moving the management modules into the new directories.

Follow these steps:

  1. In the <EM_Home>/config/modules directory, create a directory that corresponds to the domain name you created in the previous section.
    For example, if you defined a domain named "PetstoreA," you would create a directory also named PetstoreA, as in the following example:

    <EM_Home>/config/modules/PetstoreA

    Note: The domain directory must match the name defined in the domains.xml file exactly (spelled correctly and also matching in case) or any management modules that reside in the directory will not be loaded.
  2. Move the desired management module from the <EM_Home>/config/modules directory into the new directory you just created.
  3. Restart the Enterprise Manager so it can load the new domains.

Add Sample Management Modules to Newly Defined Domains

When you define a new domain, it does not contain any management modules. If you want the newly defined domain to show the default sample dashboards, you need to copy the Sample Management Module into the newly defined domain.

Follow these steps:

  1. Navigate to the <EM_Home>/config/modules/ directory.
  2. Copy the SampleManagementModule.jar file to the appropriate modules directory in the newly defined domain.
    For example, if you defined a domain called Petstore A, you would copy SampleManagementModule.jar into this directory:

    <EM_Home>/config/modules/PetstoreA

  3. Restart the Enterprise Manager to load the new management module.
Important! The Sample Management Module copied into the new domain is not linked in any way to the original Sample Management Module. Any changes to the original Sample Management Module will not be reflected in any copies of the Sample Management Module in other domains, and vice versa.

Change the Domain Mapping of an Agent

Remapping an agent to a different domain, (either after deleting a domain or merging two domains), has the following ramifications:

  • If an agent mapped to a deleted domain is not reassigned and is still reporting, it will appear under the SuperDomain.
  • If an agent has associated SNMP collections, the SNMP MIB will have to be republished.
  • When an agent is moved into a different domain, all shutoff information within that agent is lost.

Delete a Domain

You might need to delete a domain when you:

  • assign an agent to a different domain
  • merge two domains

Follow these steps:

  1. Shut down the Enterprise Manager.
  2. Navigate to the <EM_Home>/config directory.
  3. Delete the domain from the domains.xml file.
  4. If necessary, reassign any mapped agents to different domains.
  5. Delete the corresponding domain directory from the <EM_Home>/config/modules directory.
  6. Restart the Enterprise Manager.

Merge Two Domains

Merging two domains involves merging all agent mapping information into one domain, and moving any associated management modules under one domain.

Follow these steps:

  1. Shut down the Enterprise Manager.
  2. Open the domains.xml file in the <EM_Home>/config directory.
  3. Under the source domain (for example, Domain A), copy the agent mapping XML code information.
  4. Under the target domain (for example, Domain B), paste the agent mapping XML code information.
  5. Delete agent mapping XML code from the source domain (for example, Domain A).
  6. Move any management modules from the source domain (for example, Domain A) directory in <EM_Home>/config/modules/ to the target domain (for example, Domain B).

    Note: If any management modules already exist in the target domain directory with the same name as the ones you are moving over, you will need to rename the management modules from the source domain. If two management modules with the same name exist, the Enterprise Manager will not start.
  7. Delete the source domain from domains.xml.
  8. Restart the Enterprise Manager.

Clone Domains Between Different Introscope Installations

Carry out this procedure if the target installation domain configuration is exactly the same as the source installation. (That is, if all domains defined in the domains.xml file are going to be exactly the same.)

Follow these steps:

  1. Copy the <EM_Home>/config/domains.xml file in the source installation over to the same directory in the target installation.
  2. Copy the <EM_Home>/config/shutoff/MetricShutoffConfiguration.xml, if it exists, in the source installation over to the same directory in the target installation.
  3. Copy the contents of the <EM_Home>/config/modules/<domain> directory from the source installation to the target installation.
  4. Restart the Enterprise Manager.

Move a Domain Between Non-cloned Installations

Carry out this procedure when you want to move a domain between non-cloned installations if the domain configurations between the old and new installations vary slightly.

Follow these steps:

  1. Open the domains.xml file in the <EM_Home>/config directory in the source installation.
  2. Copy the domain information.
  3. Open the domains.xml file in the <EM_Home>/config directory in the target installation.
  4. Copy the domain information into the domains.xml file.
  5. In the target installation, create new management module directories that correspond to those in the source installation in the <EM_Home>/config/modules directory.
  6. Copy any management modules that belong to the domain you are moving over and paste them into the corresponding domain directories.
  7. Delete the domain from the source installation.
  8. Restart the Enterprise Manager.

Agent Failover and User/Domain Configuration

If you use the agent failover functionality and have users and passwords defined, verify that the domains.xml, server.xml, and users.xml files are in sync across the specified failover Enterprise Managers.

Configuring Public and Private Keys for Secure Authentication

In a clustered environment the communication protocol between the MOM, Collectors, and Workstations use public and private keys for secure authenticating.

Note: The public and private keys are used only to secure passwords when logging-in. To secure all communications requires SSL.

About the Default Collector Private Key

Each Collector uses a private key for decrypting the password that the MOM uses to connect. The public key and private key must be a matched set. The private key for a Collector Enterprise Manager is defined in the introscope.enterprisemanager.clustering.privatekey property in the IntroscopeEnterpriseManager.properties file.

The default value is

config/internal/server/EM.private

You do not need to reconfigure the private key unless you want to generate a new public and private key set for the Collector for added security.

Note: CA APM public and private keys do not expire.

Generate a New Public and Private Key Set

To make your CA APM environment more secure, you can generate a new public and private key for each Collector, place the public keys on the MOM, and update the MOM's Collector properties.

Follow these steps:

  1. Navigate to an Introscope installation directory.
  2. At a command prompt, type this command:

    java -classpath product\enterprisemanager\plugins\com.wily.introscope.em.client14_9.5.0.jar;lib\CLWorkstation.jar;product\enterprisemanager\configuration\org.eclipse.osgi\bundles\24\1\.cp\lib\WilyBouncyCastle.jar com.wily.util.encryption.KeyGenerator EM.public EM.private

  3. If you generate new keys for a Collector, copy the public key to the location specified in the introscope.enterprisemanager.clustering.login.em1.publicKey property in the MOM IntroscopeEnterpriseManager.properties file.

    Note: This step does not apply if you are generating new keys for a MOM.
  4. Copy the public and private keys into the Enterprise Manager installation at <EM_Home>\config\internal\server.
Was this helpful?

Please log in to post comments.

  1. Lynn Williams
    2015-10-23 01:35

    The java command above to generate the new public and private key set is out of date for APM 10.0 and should read as follows

    java -classpath product\enterprisemanager\plugins\com.wily.introscope.em.client14_10.0.0.jar;lib\CLWorkstation.jar;product\enterprisemanager\configuration\org.eclipse.osgi\bundles\40\1\.cp\lib\WilyBouncyCastle.jar com.wily.util.encryption.KeyGenerator EM.public EM.private

    Thanks

    Lynn

    P.S. APM 10.1 wiki may also need to be updated

    1. Lucie Stehnova
      2016-07-07 09:32

      Hi Lynn, Thank you very much for letting us know. We will amend. Lucy