Configuration Agent

The Configuration Agent is part of a number of different packages, which are listed in the following table:

Solaris Package Name	Description
SUNWapbas	Configuration Shared libraries
SUNWapmsc	Configuration Agent miscellaneous files
SUNWapoc	Configuration Agent
SUNWapdc	Configuration Agent wizard

When you install these packages, the files that are required for this API are installed. You can install the packages manually or through the Java Desktop System installation. After installation, you must configure and enable the Configuration Agent on your system.

---

Note –

Configuration Agent packages are installed as part of the Solaris with Java Desktop System installation; however, the Desktop Manager patches these files during installation to provide the proper level of functionality.

---

To access the remote configuration data, the Configuration Agent requires some minimal bootstrap information, such as the host name and port of the LDAP server. This information is maintained in a set of properties files, such as policymgr.properties, apocd.properties, os.properties. These files are stored locally in the /etc/apoc directory. You can manually edit these properties files (see Appendix A, Configuration Parameters), or you can use the configuration wizard for the Configuration Agent.

The configuration wizard offers a graphical user interface that guides you through the necessary settings of the Configuration Agent. For each page of the wizard, a corresponding help screen is available. You can start the wizard as super user (root) by means of the /usr/bin/apoc-config script.

---

Note –

The wizard can also be started without launching the graphical interface. For example, execute /usr/bin/apoc-config -nodisplay to start the wizard in console mode.

---

Bootstrap Information

Figure 3–1 Configuration Agent, Configuration Repository

---

Note –

Associated property file keys are indicated in parentheses, where appropriate.

---

• State: The status of the Configuration Agent. The check box can be used to either activate or deactivate the Configuration Agent. To make use of the configuration repository, the Configuration Agent must be active. The activation automatically includes the necessary registration with the service management facility ( smf(5) ) on Solaris.

• Host Identifier (HostIdentifierType): can be ”HostName” or “IPAddress”. When searching for host-specific policy data, the Configuration Agent will identify the current host either by host name or IP address. Choose the correct value based on how your host is identified in the selected Context Type.

• Context Type: Use this setting to indicate to the Configuration Agent whether your organizational hierarchy and configuration data are defined in LDAP or File-based storage or a mixture of both.

  ---

  Note –

  To manually enable or disable the Configuration Agent, log in as root and type the command /usr/lib/apoc/apocd enable or /usr/lib/apoc/apocd disable, respectively.

  ---

Figure 3–2 Configuration Agent, LDAP Hierarchy and File-Based Storage

---

Note –

The screen in Figure 3–2 varies, depending on the Context Type chosen on the previous screen. Server Identifier, Server Port and Suffix are required if an LDAP or Hybrid context type is chosen. Configuration Settings URL is required if a File-based or Hybrid context type is chosen.

---

• Server Identifier: host name of the LDAP server.

• Server Port: port number of the LDAP server.

• Suffix: base DN of the LDAP repository.

• Configuration Settings URL: URL specifying the location of the file based repository.

  A list of URLs can be used to specify fallback repositories in case the connection to the first one does not succeed. The list can be composed of one or more white space-separated URLs, each URL being of the form file://<filepath>, http://<host>:<port>/<filepath>, or https://<host>:<port>/<filepath>. See Appendix A, Configuration Parameters for more information.

  ---

  Note –

  The Agent tries to access the LDAP server using a SSL connection first. If this fails the Agent tries a plain SSL connection.

  For the SSL connection to succeed, the proper certificate must be present in the Java runtime environment key store. That key store is located for a standard JRE in <installation directory>/lib/security/cacerts, and for a standard JDK in <installation directory>/jre/lib/security/cacerts. Either the Certification Authority or the LDAP server certificate must be added to that store, using the command keytool -import -file <certificate file> -keystore <cacerts file location>. The default password for that key store is changeit.

  ---

Figure 3–3 Configuration Agent, Authentication Mechanism

• Authentication Type for the Configuration Agent: can be "Anonymous" or "Simple". If "Anonymous" is selected, the Qualified User Name and Password fields are automatically disabled.

• Qualified User Name (AuthDn): full DN of a user with read and search access rights on the repository.

• Password (Password): password of a registered LDAP user

  ---

  Note –

  If anonymous access is enabled in the directory, the Qualified User Name and the Password settings can be left blank.

  ---

• Authentication Type for applications (AuthType): can be “Anonymous” or “GSSAPI”, depending on how the LDAP server authenticates users.

  ---

  Note –

  For more information, see Data Access/User Authentication.

  ---

Port Settings

The Configuration Agent uses two ports:

• Agent Port (DaemonPort): used by the agent to communicate with client applications (default is 38900).

• Administration Port (DaemonAdminPort): used by the agent controller program, apocd, when communicating with the agent (default is 38901).

Figure 3–4 Configuration Agent, Port Settings

Change Detection Interval

The Configuration Agent periodically checks for any changes in the configuration data using the following two intervals:

• General Detection Interval (ChangeDetectionInterval): interval in minutes between the change detection cycles for the desktop application's (client's) configuration data.

  ---

  Note –

  Specifying -1 turns off change detection.

  ---

• Interval for Agent Settings (DaemonChangeDetectionInterval): interval in minutes between the change detection cycles for the agent-specific configuration settings.

  ---

  Note –

  Specifying -1 turns off change detection.

  ---

You can use the general detection interval to tune the propagation of remote configuration data changes to client side applications. The value provided for this setting is the maximum length of time in minutes that elapses before remotely made changes are reflected in the client applications.

Smaller values result in increased Configuration Agent and LDAP server activity. As a result, use caution when you adjust the value of the settings. For example, in an initial deployment phase, you can set the value to one minute so that you can test the impact of remote configuration on client applications. After you complete the testing, return this setting to the initial value.

Operational Settings

Figure 3–5 Configuration Agent, Data Directory

The following settings can be configured:

• Data Directory (DataDir): the directory used to store runtime data. The default is /var/opt/apoc.

• Cached Data Storage Life (TimeToLive): interval in minutes that non-offline configuration data remains in the local database.

Figure 3–6 Configuration Agent, Request Handling and Logging

• Garbage Collection Cycle (GarbageCollectionInterval): interval in minutes between the garbage collection cycles in the local configuration database.

• Maximum Client Threads (MaxClientThreads): maximum number of client requests that can be processed simultaneously.

• Maximum Client Connections (MaxClientConnections): maximum number of client connections.

• Maximum Request Size (MaxRequestSize): maximum size of client requests.

• Connection Timeout (ConnectTimeout): denotes the allowed interval of the LDAP server to answer a connection request. The default is one second.

• Log Level (LogLevel): level of detail in the agent log files. The logging level is consistent with the Java Logger levels. In order of decreasing severity, these levels are as follows:

  • SEVERE

  • WARNING

  • INFO

  • CONFIG

  • FINE

  • FINER

  • FINEST

---

Note –

Most of the operational settings, with the exception of the Data Directory and Connection Timeout settings, can also be maintained centrally through corresponding policies stored in the LDAP server. If you want to use this feature, do not adapt the corresponding settings by means of the wizard. Instead, use the Configuration Agent policies within the Desktop Manager to centrally specify operational settings.

---

Applying Agent Settings

With the exception of "Data Directory" and "Connection Timeout", operational settings that have been stored on the LDAP server by means of the Desktop Manager take effect automatically at the next change detection cycle for the agent configuration (see DaemonChangeDetectionInterval).

Figure 3–7 Configuration Agent, Summary Page

All other settings changed locally require a reload or restart of the Configuration Agent. The reload or restart is performed automatically if you use the configuration wizard.

---

Note –

To manually restart the Configuration Agent, ensure that no related client applications are running, log in as root, and type the command /usr/lib/apoc/apocd restart.

---

Additional Agent Settings

---

Note –

The following settings are not available in the configuration wizard.

---

• Application of local policy (ApplyLocalPolicy): use this setting to indicate whether or not policy data available on the local host should be made available to client applications. A value of “true” indicates that local policy data should be made available. A value of “false” indicates that local policy data should not be made available. For more details, see Using Local Policy.

Using Local Policy

You may configure the Configuration Agent to apply configuration settings from locally deployed policy in addition to or as an alternative to any globally available policy. Use the following steps to deploy any such local policy:

Deploying a Local Policy

Steps

1. Using the Desktop Manager create a profile with the required policy settings.

2. Using the Desktop Manager export the profile to a zip file.

3. On your client host, create the directory ${DataDir}/Policies/profiles/PROFILE_REPOSITORY_default, if it does not already exist.

   ${DataDir} corresponds to the value of the Configuration Agent's Data Directory which is /var/opt/apoc by default.

4. Copy the previously exported zip file to ${DataDir}/Policies/profiles/PROFILE_REPOSITORY_default.

5. Ensure that the Configuration Agent is configured to apply available local policies (see Additional Agent Settings for more details ).

   ---

   Note –

   If you change the Configuration Agent's “ApplyLocalPolicy” setting, you should reload the Configuration Agent by logging in as root and typing the command /usr/lib/apoc/apocd reload.

   Any local policy deployed in this manner will be made available to clients during the next Configuration Agent change detection cycle.

   ---

Automatic Restart of the Configuration Agent

In the event of a failure, the Configuration Agent will be automatically restarted. The service management facility ( smf(5) ) is responsible for making this decision. If the service management facility decides that a restart is inappropriate (for example, if too many failures have already occurred), the Configuration Agent is placed in maintenance mode.

In the event that the Configuration Agent is not restarted, you should disable the Agent temporarily by logging in as root and executing the command /usr/lib/apoc/apocd disable, rectify any problems causing the Agent to fail and re-enable the Agent by executing the command /usr/lib/apoc/apocd enable.