Programming Guides › Programming Guide for C › Guidance for the Agent API in C › Central Host Configuration

Central Host Configuration

SiteMinder agents, including custom agents, connect to a Policy Server through the Agent API. SiteMinder recognizes two different types of agents, based on the way that connection parameters are provided:

• v4.x agents. Connection parameters required to connect to a Policy Server are agent-specific. They include the agent’s name, the name or IP address of the host machine where the agent resides, and the shared secret. These parameters are provided when you define an agent object on the Policy Server. Connection parameters defined for a v4.x agent apply to that agent only.
• v5.x and later agents. Connection parameters required to connect to the Policy Server can apply to multiple agents on the host machine where the agents reside. With v5.x and later agents, the host machine is called a trusted host.

  The information required to initialize the connection to a Policy Server is stored in an SmHost.conf file on the host machine. Additional information that determines how the Policy Server interacts with its agents is defined on the Policy Server in a host configuration object.

  Host configuration object parameters (such as failover and clustering instructions) apply to all agents associated with the host configuration object. They are centrally managed in the Administrative UI.

Custom v5.x and later agents support central host configuration (which determines the way a Policy Server and its agents interact), but not central agent configuration (which determines the way an agent operates). You cannot define an agent configuration object for a custom agent in the Policy Server. Configuration parameters for the operation of a custom agent are defined in the WebAgent.conf file (or in the case of IIS 6.0 agents, in the LocalConfig.conf file).

Configuration Requirements

To configure a custom agent through a host configuration object on the Policy Server, you must complete the following steps:

1. Register the client machine where the agent resides as a trusted host.

   You register a trusted host with the smreghost tool. This tool is installed in directory <install_path>/sdk/bin.

   Registering a trusted host creates the following items:

   • A host configuration object on the Policy Server. The host configuration object can be modified in the Administrative UI at any time.
   • The file SmHost.conf on the client. This file includes the parameter hostconfigobject, which references the host configuration object on the Policy Server.

     The information in SmHost.conf is used to initialize the connection between the Policy Server and its agents, through the Agent API. Once the connection is initialized, the information in the host configuration object determines how the Policy Server and its agents interact.

2. Define an agent object on the Policy Server.

   An agent object establishes a unique identity for your custom agent by defining a name and other information that is specific to your custom agent.

   The name assigned to the custom agent must match the name that the custom agent passes programmatically to SiteMinder.

Code Requirements

For a custom agent to be configured through a central host configuration object on the Policy Server, the agent must do the following:

• Initialize agent configuration through Sm_AgentApi_GetConfig().

  This function lets you pass to SiteMinder the name and path of the SmHost.conf file that resides on the trusted host. This file references the host configuration object on the Policy Server.

  Alternatively, you can pass the name and path of the WebAgent.conf file if it contains a reference to SmHost.conf.

  After the trusted host connects to the Policy Server, the interaction between the Policy Server and the agents on the trusted host is determined by the host configuration object on the Policy Server.

  Note: When you call Sm_AgentApi_GetConfig(), SiteMinder populates the Sm_AgentApi_Init_t structure. With central host configuration, you do not populate the structure directly.

• Pass the agent’s name through Sm_AgentApi_SetDefaultAgentId().

  The name that the custom agent passes to SiteMinder in this function must match the name of the agent object that establishes a unique identity for your custom agent on the Policy Server.

  Call Sm_AgentApi_SetDefaultAgentId() after calling Sm_AgentApi_Init() and before making any other Agent API calls. This allows you to specify your custom agent name to SiteMinder without sending the name with each transaction.

Upgrade an Agent

To upgrade an existing v4.x agent

1. If the host machine where the v4.x agent resides is not currently registered with the Policy Server as a trusted host, run smreghost to register it.

   Registration creates an SmHost.conf file on the trusted host and a host configuration object on the Policy Server.

2. Call Sm_AgentApi_GetConfig() to initialize the structure Sm_AgentApi_Init_t with the information in SmHost.conf.
3. Call Sm_AgentApi_Init() to connect to the Policy Server.
4. Call Sm_AgentApi_SetDefaultAgentId() to set the default name of the custom agent.