CLI Agent Administration Methods
Contents
sm1252sp1
Contents
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
CA Single Sign-On
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)
- undefSpecifies 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)
- undefSpecifies 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 secretiscase-sensitive.
- failover(int)(Optional) Specifies whether to enable or disable failover operation:
- value = -1Specifies enabling failover operation.
- value = 0Specifies 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 = 1Specifies enabling output.
- value = 0Specifies disabling output.
Return Value
The PrintDebugTrace method returns one of the following integer values:
- value = 1Specifies that output is enabled.
- value = 0Specifies 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
CA Single Sign-On
error messages. If multiple subroutines are registered, CA Single Sign-On
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:
- nameExample:$agentapi->SetErrorCallback("CustomErrorHandler");
- referenceExample:$agentapi->SetErrorCallback(\&CustomErrorHandler);
Return Value
The SetErrorCallback method returns one of the following integer values:
- value = 1Specifies that registration was successful.
- value = 0Specifies that registration failed.
SetTraceCallback Method Registers Subroutine that Processes Trace Messages
The SetTraceCallback method registers a user-defined Perl subroutine that processes
CA Single Sign-On
trace messages. If multiple subroutines are registered, CA Single Sign-On
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:
- nameExample:$agentapi->SetErrorCallback("CustomTraceHandler");
- referenceExample:$agentapi->SetErrorCallback(\&CustomTraceHandler);
- mode(string)(Optional) Specifies an output format for the trace messages:
- defaultSpecifies fields enclosed by square brackets.
- fixedSpecifies fixed-width fields.
- delimSpecifies using a character to delimit the fields.
- xmlSpecifies 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 = 1Specifies that registration was successful.
- value = 0Specifies that registration failed.