All configuration information for SmPortal is stored in the SmPortal.cfg file. SmPortal looks for this file using several techniques, in this order:
If the file is still not found, an error will occur (it will not use default values).
The SmPortal.cfg file supplied with the kit is not configured to work immediately after installation. It must be modified before communications will work correctly. It must also be modified as each new service is installed.
The following shows the file as it is installed (more or less):
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; Servers ;; ;; Each server should have an ip ;; address, specified as: ;; <server>.ip=aaa.bbb.ccc.ddd ;; ;; It *may* also have a port as: ;; <server>.port=44442 ;; ;; It *may* also have a timeout as: ;; <server>.timeout=30000 ;; ;; It *may* also have a minimum number ;; of connections as: ;; <server>.ConnMin=1 ;; ;; It *may* also have a maximum number ;; of connections as: ;; <server>.ConnMax=5 ;; ;; It *may* also have a connection ;; step value as: ;; <server>.ConnStep=1 ;; ;; The entry "Servers" should contain ;; a comma-delimited list of all ;; server names. ;; ;; Entry names are not case-sensitive. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Servers=MyServer MyServer.ip=127.0.0.1 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; Agents ;; ;; Each agent should have list of ;; servers, specified as: ;; <agent>.servers=<s1>,<s2>... ;; ;; It must also have a shared secret as: ;; <agent>.secret=xyzzy ;; shared secrets may be encrypted using ;; the APSEncrypt utility (see documentation) ;; ;; It *may* also specify round robining ;; (instead of fail over) as: ;; <server>.RoundRobin ;; ;; The entry "Agents" should contain ;; a comma-delimited list of all ;; Agent names. ;; ;; Entry names ARE case-sensitive. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Agents=ghost ghost.Servers=MyServer ghost.Secret=[NDSEnc-A]6UUYOUf4E6O42CEuYo8H(E4UdyZ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; Services ;; ;; Each service should point to a ;; single agent, specified as: ;; <service>.agent= ;; ;; It *may* also specif<agent>y tracing as: ;; <service>.Trace ;; ;; It *may* also specify debugging as: ;; <service>.Debug ;; ;; The entry "Services" should contain ;; a comma-delimited list of all ;; Service names. ;; ;; Entry names are not case-sensitive. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Services=PortalTest,SmPassword PortalTest.Agent=ghost SmAPS.Agent=ghost
The file is well documented, so that changes can be made with minimal (if any) referral to external documentation.
Any text following a semicolon (;) is considered a comment. Blank lines are ignored.
The file consists of three sections.
The Server Section defines the SiteMinder Policy Servers that are available from this computer.
The Servers= entry contains a comma-delimited list of all of the servers defined for this machine.
Server names are arbitrary. CA Professional Services recommends that the server names match the network name of the Policy Server machine. The name is only used to cross reference values within the configuration file. The name may contain embedded periods and is not case-sensitive.
Any number of servers may be defined in this section, but each server must have at least one entry following the Servers entry:
<servername>.ip=<IP-address>
This entry defines the IP address used to get to the specified Policy Server. The IP address specified here must be the one used to access the Policy Server from the server running the SmPortal code. Thus, if address translation is in effect at the firewall, the address may not match the actual address of the Policy Server.
The easiest way to determine this address at most sites is to open the SiteMinder Web Agent Management Console on the system and examine the address of the Primary SiteMinder Policy Server. If the Web Agent communicates properly with the SiteMinder Policy Server, then this is the correct address.
The <servername> portion of the setting name must match the name listed in the Servers setting.
<server>.port=CA Portal
This setting may be used to change the port used to communicate with the Policy Server. The default is port 44442. It must match the port used by the Authentication Service on the SiteMinder Policy Server.
<server>.timeout=<timeout in milliseconds>
This allows the administrator to override the timeout for the specified server. The default is 30000 (30 seconds). This is a reasonable timeout and should not, in general, be changed.
<server>.ConnMin=<minimum connections>
This setting allows the specification of the minimum number of connections to the server that SmPortal should initialize. The default value of one should be used in almost all cases. This setting is intended for use by applications that require multiple connections to a Policy Server.
<server>.ConnMax=<maximum connections>
This setting allows the specification of the maximum number of connections to the server that SmPortal should initialize. The default value of one should be used in almost all cases. This setting is intended for use by applications that require multiple connections to a Policy Server.
<server>.ConnStep=<connection step value>
If the minimum and maximum connections are set, this value specifies the stepping value that SmPortal should use between the minimum and maximum values. For example, if the minimum value is one and the maximum value is 25, the stepping value might be five. This would cause SmPortal to increment the number of connections by five each time that it runs out of connections. The default value of one should be used in almost all cases. This setting is intended for use by applications that require multiple connections to a Policy Server.
The Agent section tells SmPortal which agents exist and the servers that know about them.
The Agents= entry contains a comma-delimited list of all of the agents which may be used from this machine.
Agent names are not arbitrary. Each must match an Agent configured on a Siteminder Policy Server. The name is case-sensitive. Typically, the same agent names are used for both services and the resident Web Agent, but this is not required.
Any number of Agents may be listed immediately after the Agents line. Each Agent must be defined using the following two lines:
<agent>.Servers=<serverlist> <agent>.Secret=<shared secret>
The first line defines the servers on which this agent is defined. The server list contains a comma-delimited list of servers that know about this Agent. Each server so referenced must be defined in the server section.
The order in which servers are defined is significant. By default, SmPortal will attempt to contact servers in the order listed here. Multiple servers are used for fault-tolerance; if a server cannot be contacted, the next server in the list is used. Any number of servers can be listed.
The Secret line defines the shared secret used between the Agent and the Policy Server. This must be the same secret configured on the Policy Server(s) for the Agent.
Secrets can be stored in either plain text or in encrypted format. If the secret is stored in plain text and this is a problem, define specific agents for services, thus hiding the shared secret used by the Web Agent. Since no policies need to be created in order to run the services through the tunnel (though they may be required to access the application through the Web Agent), security is maintained.
To store the secret in encrypted format, use the APSEncrypt utility to encrypt the shared secret, then copy the encrypted value (output from APSEncrypt) into the <agent>.Secret line in SmPortal.cfg.
By default, if multiple servers are specified for an agent, the servers will be used in failover mode (the first server used unless it is unavailable, in which case, SmPortal will use the second server, and so on).
To specify that the server list is to be used in round robin format, use the following setting:
<agent>.RoundRobin
SmPortal cannot do true round-robining because each application that uses SmPortal is a completely independent instance. Instead, SmPortal will simulate round-robining by randomly rotating the list of servers, then using the resulting list as though failover mode were specified. This technique provides the same results as true round-robining.
The Service section defines the services that can use SmPortal and what Agent configuration each should use.
The Services= entry contains a comma-delimited list of all services that may be used from this system.
Each application or API that uses a service has its service name encoded within it. See the documentation for the service itself to determine the name of the service. Note that the name may not correspond to the actual product name.
After the Services= entry, each service is identified by a single line that define the Agent to be used by that service.
<service>.Agent=<agent>
The value for the agent must correspond to an Agent name defined in the previous section.
The service name for SmPortalTest is PortalTest and should already be listed in SmPortal.cfg.
Some applications may support qualified service names. For example, SmPortalTest allows multiple definitions of the PortalTest service within the configuration file. Each entry must be qualified as in:
Qualifier1.PortalTest.Agent=ghost
AnotherInstance.PortalTest.Agent=ranger
Qualifiers allow the same service to run on multiple servers, yet still be addressable independently. In the PortalTest example, it allows the SmPortalTest application to select from several possible configurations (targets) for the PortalTest service.
If a service name is to be qualified, all optional settings should be qualified as well.
If a qualified service name is requested by an application, but no qualifiers match for that service, the unqualified settings for the same service will be used (if configured).
Not all applications support qualified services.
<service>.Trace
This setting turns on trace logging for the service. The back-end service library will be notified that tracing is requested. The actual tracing performed is up to the service itself and will vary. All tracing is written to the SiteMinder console log.
Trace and debug logging may also be turned on within the code. If so, these settings will have no effect.
<service>.Debug
This setting turns on debug logging for the service. The back-end service library will be notified that debug tracing is requested. The actual logging performed is up to the service itself and will vary, though SmTransact performs some debug logging as well, if this setting is turned on.
Trace and debug logging may also be turned on within the code. If so, these settings will have no effect.
|
Copyright © 2014 CA.
All rights reserved.
|
|