CLI Agent Administration Methods

Programming Guides › Programming Guide for Perl › CLI Agent API Methods › CLI Agent Administration Methods

CLI Agent Administration Methods

AddServerConfig Method—Adds Policy Server Configurations to Agent API Object

The AddServerConfig method adds one or more Policy Server configurations to the Agent API object. Before you can establish a connection between the Policy Server and the Agent API, you must call this method at least once.

Syntax

The AddServerConfig method has the following format:

Netegrity::AgentAPI‑>AddServerConfig(IPAddress[, minConn]
[, maxConn][, stepConn][, timeout][, azPort][, auPort]
[, acPort])

Parameters

The AddServerConfig method accepts the following parameters:

IPAddress (string)

Specifies the IP address of the Policy Server.

minConn (int)

(Optional) Specifies the minimum number of connections allowed.

maxConn (int)

(Optional) Specifies the maximum number of connections allowed.

stepConn (int)

(Optional) Specifies the number of connections to add when all existing connections are being used.

timeout (int)

(Optional) Specifies the time in seconds before the Agent API stops trying to connect to the Policy Server.

azPort (int)

(Optional) Specifies the port number for the authorization service.

auPort (int)

(Optional) Specifies the port number for the authentication service.

acPort (int)

(Optional) Specifies the port number for the accounting service.

Return Value

The AddServerConfig method returns the following value:

AgentSvrCfg (object)

Remarks

The single-process Policy Server introduced in SiteMinder v6.0 combines the previously separate authentication, authorization, and accounting processes into one combined process whose requests go through one TCP port. As a result, the parameters azPort, auPort, and acPort all reference the same port number. The three arguments are maintained for backward compatibility.

Connect Method—Establishes Connection between Agent API and Policy Server

The Connect method establishes a connection between the Agent API and the Policy Server.

Syntax

The Connect method has the following format:

Netegrity::AgentAPI‑>Connect([bootFile])

Parameters

The Connect method accepts the following parameter:

bootFile (string)

(Optional) Specifies the name of the configuration file to be used for connecting to a v5.x agent.

Note: You can use an existing file such as SmHost.conf or create a new file. For more information, see the method AgentAPI‑>CreateBootstrapFile.

Return Value

The Connect method returns one of the following values:

SM_AGENTAPI_YES (value = 1)
Specifies that the connection was successful.
SM_AGENTAPI_FAILURE (value = -1)
Specifies that the Agent API could not reach the Policy Server.
SM_AGENTAPI_TIMEOUT (value = -2)
Specifies that the method timed out.
SM_AGENTAPI_NOCONNECTION (value = -3)
Specifies that initialization failed.

CreateBootstrapFile Method—Generates Bootstrap File for Connecting to Agent

The CreateBootstrapFile method generates a bootstrap file that the Policy Server can use for connecting to a v5.x agent. The bootstrap file contains the settings specified by the method's parameters. Once the connection is made, the Policy Server can provide the remaining settings. SmHost.conf is an example of a bootstrap file.

Syntax

The CreateBootstrapFile method has the following format:

Netegrity::AgentAPI‑>CreateBootstrapFile(trustedHostName, ipAddress,
hostConfigName, sharedSecret, registrationDataFileName)

Parameters

The CreateBootstrapFile method accepts the following parameters:

trustedHostName (string)

Specifies the name of the trusted host.

ipAddress (string)

Specifies the IP address of the Policy Server.

hostConfigName (string)

Specifies the name of the host configuration object.

sharedSecret (string)

Specifies the value of the shared secret used by the host.

registrationDataFileName (string)

Specifies the name of the bootstrap file generated by the method.

Return Value

The CreateBootstrapFile method returns one of the following values:

file_name (string)
Specifies the name of the newly-created file.
empty_string (string)
Specifies that the method failed.

Example

The following code fragment is an example of how to use the CreateBootstrapFile method:

# A shared secret is not specified in the context of a v5.x agent.
# A v5.x agent by the specified name needs to exist in the policy
# store. Use Netegrity::AgentAPI.

$agentapi = Netegrity::AgentAPI‑>New($agentname);

# Create the bootstrap file.

$agentapi‑>CreateBootstrapFile($thostname, $ipaddr, $hconfname, $secret, $fname);

# Notice that in the v5.x context, the connect() method takes a filename.

$agentapi‑>Connect($fname);

CreateUser Method—Creates a User Object

The CreateUser method creates a user object containing the information passed to the method in the parameters. Perl uses this object to perform user operations, such as login.

Note: This method does not create a new user in the user directory.

Syntax

The CreateUser method has the following format:

Netegrity::AgentAPI‑>CreateUser(Username, Password[, cert][, certLength])

Parameters

The CreateUser method accepts the following parameters:

Username (string)

Specifies the user's ID.

Password (string)

Specifies the user's password.

cert (string)

(Optional) Specifies an X.509 certificate for user authentication.

certLength (int)

(Optional) Specifies the length of the certificate.

Return Value

The CreateUser method returns one of the following values:

AgentUser (object)
undef
Specifies that the method failed.

Disconnect Method—Closes Connection between Agent and Policy Server

The Disconnect method closes the connection between the Agent and the Policy Server.

Syntax

The Disconnect method has the following format:

Netegrity::AgentAPI‑>Disconnect()

Parameters

The Disconnect method accepts no parameters.

Return Value

The Disconnect method returns one of the following values:

SM_AGENT_SUCCESS (value = 0)
Specifies that the connection was closed successfully.
SM_AGENT_FAILURE (value = 1)
Specifies that the connection was not successfully closed.

DoManagement Method—Requests Agent Commands from Policy Server

The DoManagement method requests the list of Agent commands pending from the Policy Server and returns them in an array. To access the commands in the array, call the AgentResponseAttr‑>GetID method.

Syntax

The DoManagement method has the following format:

Netegrity::AgentAPI‑>DoManagement()

Parameters

The DoManagement method accepts no parameters.

Return Value

The DoManagement method returns one of the following values:

AgentResponseAttr (array)
undef
Specifies that there are no pending Agent commands.

GetResource Method—Retrieves the Specified Resource

The GetResource method retrieves the specified resource.

Syntax

The GetResource method has the following format:

Netegrity::AgentAPI‑>GetResource(resName[, action][, clientIP])

Parameters

The GetResource method accepts the following parameters:

resName (string)

Specifies the name of the resource to retrieve.

action (string)

(Optional) Specifies the HTTP action to perform (for example, GET, POST, or PUT).

clientIP (string)

(Optional) Specifies the client's IP address.

Return Value

The GetResource method returns the following value:

AgentResource (object)

IncrementRefCount Method—Increment the Reference Count

You can call the IncrementRefCount method when the Agent API is operating in multi-threaded mode. After calling the Perl function fork, for example, you can call this method within the child process.

Syntax

The IncrementRefCount method has the following format:

Netegrity::AgentAPI‑>IncrementRefCount()

Parameters

The IncrementRefCount method accepts no parameters.

Return Value

The IncrementRefCount method does not return a value.

New Method—Constructs the Agent API

The New method constructs the Agent API object and must be called before the Agent API object can be used.

Syntax

The New method has the following format:

Netegrity::AgentAPI‑>New(agentName[, sharedSecret][, failover])

Parameters

The New method accepts the following parameters:

pagentName (string)

Specifies the name of the agent as it appears in the policy store.

Note: The agent name is not case-sensitive.

psharedSecret (string)

(Optional) Specifies the shared secret as it appears in the policy store.

Note: If you provide a value for the shared secret, a v4.x agent object is created. If you do not provide a value for the shared secret, a v5.x agent object is created. The shared secret is case-sensitive.

failover (int)

(Optional) Specifies whether to enable or disable failover operation:

value = -1
Specifies enabling failover operation.
value = 0
Specifies disabling failover operation.

Return Value

The New method returns the following value:

AgentAPI (object)

PrintDebugTrace Method—Outputs Trace Information to Console

The PrintDebugTrace method enables or disables the output of error or trace information to the console and returns the value of 1 or 0, respectively.

Syntax

The PrintDebugTrace method has the following format:

Netegrity::AgentAPI‑>PrintDebugTrace([debugFlag])

Parameters

The PrintDebugTrace method accepts the following parameter:

debugFlag (int)

(Optional) Specifies enabling or disabling output of error or trace information to the console:

value = 1
Specifies enabling output.
value = 0
Specifies disabling output.

Return Value

The PrintDebugTrace method returns one of the following integer values:

value = 1
Specifies that output is enabled.
value = 0
Specifies that output is disabled.

ProcessAuthResponse Method--Extracts Information from a Login of Change Password

The ProcessAuthResponse method extracts pertinent information returned from a login or change password.

Syntax

The ProcessAuthResponse method has the following format:

Netegrity::AgentAPI‑>GetResource(UserCreds)

Parameters

The ProcessAuthResponse method accepts the following parameter:

UserCreds (UserCredentials)

Specifies the user credentials from a login or change password call

Return Value

The ProcessAuthResponse method returns the pertinent information as a string.

SetErrorCallback Method—Registers Subroutine that Processes Error Messages

The SetErrorCallback method registers a user-defined Perl subroutine that processes SiteMinder error messages. If multiple subroutines are registered, SiteMinder calls the most recently registered subroutine.

Syntax

The SetErrorCallback method has the following format:

Netegrity::AgentAPI‑>SetErrorCallback(subref)

Parameters

The SetErrorCallback method accepts the following parameter:

subref (string)

Specifies the name of the Perl subroutine or a reference to the subroutine:

name

Example:

$agentapi‑>SetErrorCallback("CustomErrorHandler");

reference

Example:

$agentapi‑>SetErrorCallback(\&CustomErrorHandler);

Return Value

The SetErrorCallback method returns one of the following integer values:

value = 1
Specifies that registration was successful.
value = 0
Specifies that registration failed.

SetTraceCallback Method—Registers Subroutine that Processes Trace Messages

The SetTraceCallback method registers a user-defined Perl subroutine that processes SiteMinder trace messages. If multiple subroutines are registered, SiteMinder calls the most recently registered subroutine.

Syntax

The SetTraceCallback method has the following format:

Netegrity::AgentAPI‑>SetTraceCallback(subref[, mode][, delim]
[, configFileName])

Parameters

The SetTraceCallback method accepts the following parameters:

subref (string)

Specifies the name of the Perl subroutine or a reference to the subroutine:

name

Example:

$agentapi‑>SetErrorCallback("CustomTraceHandler");

reference

Example:

$agentapi‑>SetErrorCallback(\&CustomTraceHandler);

mode (string)

(Optional) Specifies an output format for the trace messages:

default
Specifies fields enclosed by square brackets.
fixed
Specifies fixed-width fields.
delim
Specifies using a character to delimit the fields.
xml
Specifies fields enclosed by XML-like tags.

delim (string)

(Optional) Specifies the character to use as a delimiter when mode is set to delim.

configFileName (string)

(Optional) Specifies the name of the configuration file that specifies the data to be included in the trace.

Default: If no filename is specified, default settings are used.

Return Value

The SetTraceCallback method returns one of the following integer values:

value = 1
Specifies that registration was successful.
value = 0
Specifies that registration failed.