Академический Документы
Профессиональный Документы
Культура Документы
This documentation and any related computer software help programs (hereinafter referred to as the Documentation) is for the end users informational purposes only and is subject to change or withdrawal by CA at any time. This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and protected by the copyright laws of the United States and international treaties. Notwithstanding the foregoing, licensed users may print a reasonable number of copies of the Documentation for their own internal use, and may make one copy of the related software as reasonably required for back-up and disaster recovery purposes, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the user who are bound by the provisions of the license for the product are permitted to have access to such copies. The right to print copies of the Documentation and to make a copy of the related software is limited to the period during which the applicable license for the product remains in full force and effect. Should the license terminate for any reason, it shall be the users responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed. EXCEPT AS OTHERWISE STATED IN THE APPLICABLE LICENSE AGREEMENT, TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION AS IS WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED OF SUCH LOSS OR DAMAGE. The use of any product referenced in the Documentation is governed by the end users applicable license agreement. The manufacturer of this Documentation is CA. Provided with Restricted Rights. Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.2277014(b)(3), as applicable, or their successors. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies. Copyright 2006 CA. All rights reserved.
CA Product References
This document references the following CA products: eTrust SiteMinder eTrust TransactionMinder eTrust Identity Manager
Contents
Chapter 1: Prepare for the Installation 11
Use a Supported Operating System ....................................................................................... 11 Ensure the Policy Server is Installed and Configured................................................................. 12 Gather information Needed to Complete the Agent Installation .................................................. 13 Install the Correct Agent for a Web Server.............................................................................. 14 Install an Apache Web Server on Windows as a Service for All Users ..................................... 14 Use the IIS Default Web Site ................................................................................................ 15 Install UNIX Patches ............................................................................................................ 15 Required Solaris Patches................................................................................................. 15 Required AIX Patches ..................................................................................................... 16 Required HP-UX Patches ................................................................................................. 16 Required Linux Patches .................................................................................................. 17 Required Linux Libraries....................................................................................................... 17 Install IBM Hot Fixes for Domino Web Servers ......................................................................... 17 IBM Hot Fixes for Domino 6.0.2 CF1 and CF2..................................................................... 18 IBM Hot Fix Required for Domino 6.5.2 ............................................................................. 18 Set the DISPLAY For Web Agent Installations on UNIX .............................................................. 18 Modify the Apache 2.0 httpd.conf File for Agents on IBM HTTP Servers ....................................... 19 Enable Write Permissions for IBM HTTP Server Logs ................................................................. 19 Add a Logs Subdirectory for Apache Web Agents ..................................................................... 19 Compile an Apache Web Server on a Linux System .................................................................. 20 Set Up DNS on AIX Platforms for Agent Operation ................................................................... 20 Prepare for Cryptographic Hardware Support (Optional)............................................................ 20 Decide Whether to Implement Cryptographic Hardware....................................................... 21 Install nCipher on an Agent Web Server............................................................................ 21 Add a SiteMinder Agent User to nCipher UNIX Group (UNIX Only)......................................... 21 Collect nCipher Information............................................................................................. 21 Fix Display Errors on Sun Java System with Cryptographic Hardware .................................... 22 Preserve Changes in the WebAgentTrace.conf File.................................................................... 22 Prerequisites and Guidelines for Password Services .................................................................. 22 Repair ServletExecs CLASSPATH for JSP Password Services (Windows) ................................. 23 Password Services and Forms Directories .......................................................................... 23 Prerequisites and Guidelines for Registration Services (Optional)................................................ 24 Use Registration Services................................................................................................ 24 Install a Servlet Engine for Registration Services (Optional) ................................................. 24 Use Active Directory for Registration Services (Windows Only) ............................................. 25 Modify the DMS Admin Password for Registration Services................................................... 26 Run Registration Services with ServletExecAS (UNIX only)................................................... 27
Contents v
29
Install the Web Agent on Windows Systems ............................................................................ 29 Run a GUI Mode Installation on Windows .......................................................................... 30 Run an Unattended Installation on Windows ...................................................................... 32 Reinstall the Web Agent on Windows ..................................................................................... 35 Register Your System as a Trusted Host on Windows................................................................ 35 Review the Results of the Installation and Host Registration ...................................................... 38 Modify the SmHost.Conf File (Windows) ................................................................................. 39 SmHost.conf Settings That Should Not Be Modified (Windows) ............................................. 41 Re-register a Trusted Host Using the Registration Tool (Windows) .............................................. 42 Register Multiple Trusted Hosts on One System (Windows) ....................................................... 45 Registration Services Installed Files (Windows) ....................................................................... 46 Fix the ServletExec CLASSPATH for DMS ................................................................................ 47
49
Install the Web Agent Documentation on UNIX Systems ........................................................... 50 Install the Web Agent on a UNIX System ................................................................................ 51 Run a GUI Mode Installation on UNIX ............................................................................... 52 Run a Console Mode Installation on UNIX .......................................................................... 54 Run an Unattended Installation on UNIX ........................................................................... 55 Run the nete_wa_env.sh Script After Installation ..................................................................... 58 Reinstall a Web Agent on UNIX ............................................................................................. 59 Register Your System as a Trusted Host on UNIX..................................................................... 59 Register a Trusted Host in GUI or Console Mode ...................................................................... 60 Review the Results of the Installation and Host Registration ...................................................... 63 Modify the SmHost.Conf File (UNIX) ...................................................................................... 63 SmHost.conf Settings That Should Not Be Modified (UNIX) .................................................. 66 Re-register a Trusted Host Using the Registration Tool (UNIX) ................................................... 67 Register Multiple Trusted Hosts on One System (UNIX)............................................................. 70 Registration Services Installed Files (UNIX)............................................................................. 71
73
Configure an IIS Web Agent ................................................................................................. 73 Prerequisites for Configuring the Web Agent on IIS 6.0 ....................................................... 73 Configuration Notes for Web Agents on IIS 6.0 Servers ....................................................... 75 Configure a Sun Java System Web Agent................................................................................ 80 Configure Sun Java System Web Agents on Windows Systems ............................................. 81 Configure Sun Java System Web Agents on UNIX Systems .................................................. 84 Apply Changes to Sun Java System Web Server Files .......................................................... 88 Configure an Apache Web Agent............................................................................................ 89
Configure an Apache Web Agent on Windows Systems ........................................................ 89 Configure an Apache Web Agent on UNIX Systems ............................................................. 92 Add Entries to the httpd.conf File to Improve Server Performance......................................... 96 Set the LD_PRELOAD Variable for Apache Agent Operation .................................................. 96 Set the LD_ASSUME_KERNAL for ..................................................................................... 98 Enabling SHLIB Path for an Agent on Apache 2.0/HP-UX 11 ................................................. 99 Configure Apache for Oracle 9.0.2/9.0.3 HTTP Server ........................................................100 Modify the http.conf File for Apache Reverse Proxy Server ..................................................101 Configure a Domino Web Agent............................................................................................102 Configure a Domino Web Agent on Windows Systems ........................................................102 Configure Domino Web Agents on UNIX Systems ..............................................................105 Configure Any Web Agent in Unattended Mode .......................................................................108 Prepare an Unattended Configuration ..............................................................................109 Run an Unattended Configuration....................................................................................110 Reconfigure a Web Agent ....................................................................................................111 Tune the Shared Memory Segments (Apache and Sun Java System) .........................................112 Set Up Additional Agent Components ....................................................................................115 Use SiteMinder Password Services ........................................................................................116 Set Up Your Environment for JSP Password Services ..........................................................116
121
Notes About Uninstalling Web Agents ....................................................................................121 Set JRE in PATH Variable Before Uninstalling the Web Agent ...............................................122 Uninstall a Web Agent from a Windows System ......................................................................123 Uninstall a Web Agent from a UNIX System ...........................................................................124 Uninstall Documentation from a Windows System ...................................................................125 Uninstall Documentation from UNIX Systems .........................................................................126
127
Review the Upgrade Procedure.............................................................................................127 Upgrade Tasks and Issues ...................................................................................................127 Back Up Customized Files ..............................................................................................127 Know Which Password Services and Forms Template are Upgraded......................................128 Know the Results of Running the Configuration Wizard After Upgrades .................................128 Replace Existing Read-only Files .....................................................................................128 Ensure LD_PRELOAD Variable Does Not Conflict with Existing Agent.....................................128 Cookie Provider Redirection Differences Between 4.x and 6.x Agents....................................129 Manual Upgrade from 4.x QMR x Japanese Web Agents Required ..............................................129 Upgrade a 5.x Web Agent to 6.x on Windows Systems ............................................................130 Upgrade a 6.x Web Agent to 6.x QMR 5 on Windows Systems ..................................................132 Upgrade a 4.x Web Agent to 6.x on Windows Systems ............................................................134
Contents vii
Upgrade a 4.x Web Agent to 6.x on UNIX Systems..................................................................136 Upgrade a 5.x Web Agent to 6.x on UNIX Systems..................................................................138 Upgrade a 6.x Web Agent to 6.x QMR 5 on UNIX Systems........................................................140
Chapter 7: Troubleshooting
143
Agent Start-Up/Shutdown Issues (Framework Agents Only) .....................................................143 Troubleshoot Agent Start-Up/ShutDown with LLAWP..........................................................143 Web Agent Start Up and Shut Down Issues (IBM HTTP Server) .................................................144 Stop LLAWP When Stopping IBM HTTP Server 2.0.47 .........................................................145 Connectivity and Trusted Host Registration Issues ..................................................................146 General Installation Issues ..................................................................................................147 Cryptographic Hardware Issues ............................................................................................147 Uninstallation Issues...........................................................................................................148 Online Documentation Issues...............................................................................................148 Upgrade Issues (Windows and UNIX) ....................................................................................149 IIS Web Agent Issues .........................................................................................................149 Sun Java System Web Agent Issues......................................................................................149 Apache Web Agent Issues ...................................................................................................150 Domino Web Agent Issues...................................................................................................151
153
nete-wa-installer.properties File ...........................................................................................154 Modify General Information .................................................................................................157 Register a Trusted Host.......................................................................................................157 Enable Cryptographic Hardware Configuration ........................................................................158 Identify Policy Servers for Trusted Host Registration ...............................................................159 Specify the Host Configuration File .......................................................................................159 Select a Web Server for Configuration ...................................................................................160 WEB_SERVER_INFO Variables ........................................................................................161 Configure the Web Server to Restart (Windows Only) ..............................................................164 Name the Trusted Host Name and Host Configuration Object....................................................164
167
Add Settings to the Sun Java System Server 6.0 ....................................................................167 Modifications Made to Sun Java System/Windows Platforms .....................................................168 Code Added to the magnus.conf File on Windows Platforms ................................................168 Code Added to the obj.conf File on Windows Platforms .......................................................169 Code Added to the mime.types File on Windows Platforms ..................................................170 Check Agent Start-up with LLAWP ........................................................................................171 Modifications Made to Sun Java System/UNIX Platforms ..........................................................171
Code Added to the magnus.conf File on UNIX Platforms .....................................................172 Code Added to the obj.conf File on UNIX Platforms ............................................................172 Code Added to the mime.types File on UNIX Platforms .......................................................173
185
Index
187
Contents ix
For all Agentsthe Agent Configuration Object must include a value for the DefaultAgentName. This entry should match an entry you defined in the Agents object. The DefaultAgentName identifies the Agent identity that the Web Agent uses when it detects an IP address on its Web server that does not have an Agent identity assigned to it. For Domino Web Agentsthe Agent Configuration Object must include values for the following parameters: DominoDefaultUserif the user is not in the Domino Directory, and they have been authenticated by SiteMinder against another user directory, this is the name by which the Domino Web Agent identifies that user to the Domino server. This value can be encrypted. DominoSuperUserensures that all users successfully logged into SiteMinder will be logged into Domino as the Domino SuperUser. This value can be encrypted. For IIS Web Agentsthe Agent Configuration Object may need to include values for the DefaultUserName and DefaultPassword parameters. The DefaultUserName and DefaultPassword identify an existing NT user account that has sufficient privileges to access resources on an IIS Web server protected by SiteMinder. When users want to access resources on an IIS Web server protected by SiteMinder, they may not have the necessary server access privileges. The Web Agent must use this NT user account, which is assigned by an NT administrator, to act as a proxy user account for users granted access by SiteMinder. Note: If you plan to use the NTLM authentication scheme, or enable the Windows User Security Context feature, do not specify values for these IIS Web Agent parameters.
Web Server Microsoft IIS IBM Lotus Domino Sun Java System Apache, Covalent FastStart, Covalent Enterprise Ready Server, HP-based Apache, IBM HTTP, Oracle HTTP Server, Stronghold Most of the information for the Apache Web server applies to these Web servers.
For details on Web server and operating system versions, go to Technical Support http://support.netegrity.com, and search for the SiteMinder Platform Matrix for 6.0.
Patch IBM HTTP Server patch IBM PQ 71734 for IBM HTTP Server 1.3.19.4 and 1.3.19.5 C++ runtime patch 108434-09 111721-04 (need this patch to avoid a runtime issue with Web Agent installation binaries)
Patch IBM HTTP Server patch IBM PQ 71734 for IBM HTTP Server 1.3.19.4 and 1.3.19.5 111722-04 (need this patch to avoid a runtime issue with Web Agent installation binaries)
Patch IBM libpthreads patch 5.1.0.50 IBM HTTP Server patch IBM PQ 71734 for IBM HTTP Server 1.3.19.4 and 1.3.19.5. You should have AIX 5.1 Maintenance Level 4 installed or apply the file set needed to obtain libpthreads 5.1.0.50
Before installing a Web Agent on an Apache 1.x Web Server/AIX system, be sure to apply IBM HTTP Server patch PQ87084.
Patch PHCO_29029 is recommended for SiteMinder 6.0.4 and SiteMinder 6.0.5. PHSS_26560 ld and linker cumulative patch IBM HTTP Server patch IBM PQ 71734 for IBM HTTP Server 1.3.19.4 and 1.3.19.5
Modify the Apache 2.0 httpd.conf File for Agents on IBM HTTP Servers
Modify the Apache 2.0 httpd.conf File for Agents on IBM HTTP Servers
If an Apache 2.0 Web Agent is installed on an IBM HTTP Server 2.0.47 on Windows, the server does not load if the ibm_afpa_module is also loaded in the httpd.conf file. To avoid this problem, comment out the following lines from the httpd.conf file:
#LoadModule ibm_afpa_module modules/mod_afpa_cache.so #AfpaEnable #AfpaCache on #AfpaPort 9080 #AfpaLogFile "D:/Program Files/IBM HTTP Server 2.0/logs/afpalog" V-ECLF
On Windows 2000, if this procedure does not fix the classpath: 1. 2. 3. 4. Open the classpath.pref in a text editor. Collapse all entries to one line separated by a semi-colon(;). Save the file. Restart the Web server.
If... You have DMS 1 You install v6.x with SM 6.x You have DMS 2.01 You install 6.x with SM 6.x You have DMS 2.01 You install v6.x with SM 6.0 SP 4
apply DMS 2.01 Hot Fix CR5 before you continue running DMS 2.01
6.
Click OK.
In this CLASSPATH entry, replace: /usr/iplanet/servers with the actual server installation directory myserver.netegrity.com with the actual server instance where ServletExec is installed /export/smuser/netegrity/siteminder/webagent/ with the actual SiteMinder Web Agent installation directory 3. Extend the document directories definition by adding the entry in bold:
$SENAME $HOMEDIR $MIMEFILE $DOCROOTDIR es/dmspages"" -port $PORT $SEOPTS -addl "/siteminderagent/dmspages=/export/smuser/netegrity/siteminder/webagent/sampl
Note: There are two double-quotes at the end of the definition. 4. Set the library path variable to point to <web_agent_home>/binfor example:
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/export/smuser/netegrity/siteminder/webagent /bin; export LD_LIBRARY_PATH
The library path variable depends on the operating system. The following table lists the variables.
For Web Agents installed on IIS 6.0 servers, reboot your system after installation; it is not sufficient to restart the IIS service. Important! If you are configuring an Agent on an IIS 6.0 server, do not configure the Agent immediately after installation. There are some tasks you need to do before configuring the Agent. 11. If you choose not to configure the Agent, the Install Complete dialog box displays, and prompts you to reboot the system. 12. Click Done. If you selected the option to configure the Agent automatically, the installation program prepares the Web Agent Configuration Wizard and begins the trusted host registration and configuration processes. Do the following: Register the trusted host. You can do this before or after configuring an Agent, but you must register the trusted host at some point. Configure the Web Agent. Installation Notes: After installation, you can review the installation log file in <web_agent_home>\install_config_info. The file name is: CA_SiteMinder_Web_Agent_v6QMR5_InstallLog.log You may choose not to start the Web Agent Configuration Wizard immediately after installationyou may have to reboot your machine after installation. If so, you can start the Wizard manually when you are ready to configure an Agent. More Information Register Your System as a Trusted Host on UNIX (see page 59) Configure an IIS Web Agent (see page 73) Configure a Sun Java System Web Agent (see page 79) Configure an Apache Web Agent (see page 89) Configure a Domino Web Agent (see page 101) Prerequisites for Configuring the Web Agent on IIS 6.0 (see page 73)
The default parameters and paths in the file reflect the information you entered during the initial Web Agent installation. To prepare for an unattended installation: 1. 2. Run an initial installation of the Web Agent. Open the nete-wa-installer.properties file and modify the parameters in the file. The parameters are as follows: USER_INSTALL_DIR--Specifies the installed location of the Web Agent. Enter the full path to the installation directory. USER_SHORTCUTS--Specifies where the Web Agent Configuration Wizard shortcut should be installed. Enter the path to the desired location. (Windows only) USER_REQUESTED_RESTART--Indicates whether the installation program should reboot a Windows machine if required. Set to YES to allow the reboot. (Windows only) 3. Save the file.
More Information Prerequisites for Configuring the Web Agent on IIS 6.0 (see page 73) Configure Any Web Agent in Unattended Mode (see page 108)
Open a command window and navigate to the directory where you copied the two files. Run the installation executable with the -f and - i silent options, as follows: <agent_executable> -f <properties_file> -i silent Assuming that you run the installation from the directory where the executable and properties file are located, the command would be: nete-wa-6qmr5-win32.exe -f nete-wa-installer.properties -i silent Note: If you are not at the directory where these files reside, you must specify the full path to each file. If there are spaces in the directory paths, enclose the entire path between quotation marks. When the installation is complete, you return to the command prompt.
4.
Check to see if the installation completed successfully by looking in the CA_SiteMinder_Web_Agent _v6QMR5_InstallLog.log file, located in the <web_agent_home>\install_config_info directory. This log file contains the results of the installation. Register the trusted host and configure the Web Agent. Note: If you are configuring an Agent on an IIS 6.0 server, do not configure the Agent immediately after installation. There are some setup procedures you need to perform before configuring the Agent.
5.
More Information Run a GUI Mode Installation on Windows (see page 30)
b. c. 3.
If you are using PKCS11 cryptographic hardware in your SiteMinder environment, select the checkbox. Click Next.
If you enabled cryptographic hardware, complete the fields. If not, skip to the next step. a. In the PKCS11 DLL field, enter the full path to the PKCS11 DLL. This DLL is installed with the nCipher software installed on same Web server as the Web Agent. Click on Choose to search for the DLL. Optionally, specify the token label in the Token Label and Token Passphrase, if applicable. Re-confirm the passphrase in the Confirm token passphrase field then click Next.
b.
4.
In the Admin Registration dialog box, complete the following fields to identify an administrator with the rights to register a trusted host, then click Next: Admin User Nameenter the name of the administrator allowed to register the host with the Policy Server. This administrator should already be defined at the Policy Server and have the permission Register Trusted Hosts set. The default administrator is SiteMinder. Admin Passwordenter the administrators password. Confirm Admin Passwordre-enter the password. Enabled Shared Secret Rollovercheck this box to periodically change the shared secret used to encrypt communication between the trusted host and the Policy Server. Key rollover must be enabled at the Policy Server for this feature to work. To disable shared secret rollover or enable it at a later time, you have to re-register the trusted host, or use the Policy Management API in the C and Perl Scripting Interface to enable or disable shared secret rollover.
5.
In the Trusted Host Name and Configuration Object dialog box, enter values for the two fields then click Next. a. In the Trusted Host Name field, enter a unique name that represents the trusted host to the Policy Server. This name does not have to be the same as the physical client system that you are registering; it can be any unique name, for example, mytrustedhost. Note: This name must be unique among trusted hosts and not match the name of any other Web Agent. b. In the Host Configuration Object field, enter the name of the Host Configuration Object specified in the Policy Server, then click Next.
This object defines the connection between the trusted host and the Policy Server. For example, to use the default, enter DefaultHostSettings. In most cases, you will have created your own Host Configuration Object. Note: The entry you specify must match the Host Configuration Object entry set at the Policy Server. 6. In the Policy Server IP Address dialog box: a. Enter the IP address, or host name, and the authentication port of the Policy Server where you are registering the host. The default port is 44442. If you do not provide a port, the default is used. You can specify a non-default port number, but if you are using a nondefault port and you omit it, SiteMinder displays the following error: Registration Failed (bad ipAddress[:port] or unable to connect to Authentication server (-1) Note also that if you specify a non-default port, that port is used for the Policy Servers authentication, authorization, and accounting ports; however, the unified server responds to any Agent request on any port. The entry in the SmHost.conf file will look like: policyserver="112.11.2.55,5555,5555,5555" b. Click Add. You can add more than one Policy Sever; however, for host registration, only the first server in the list will be used. If multiple Policy Servers are specified, the Agent uses them as bootstrap servers. When the Agent starts up, the Web Agent has several Policy Servers to which it can connect to retrieve its Host Configuration Object. After the Host Configuration Object is retrieved, the bootstrap Policy Server is no longer used by that server process. The Host Configuration Object can contain another set of servers, which may or may not include any of the bootstrap servers. c. 7. Click Next.
Accept the default location of the host configuration file, SmHost.conf or click Choose to select a different location. Click Next. If you select a non-default location then want to revert to the default directory, click Restore Default Folder. The host is registered and a host configuration file, SmHost.conf, is created in <web_agent_home>/config. You can modify this file.
8. 9.
Click Continue. Continue with the configuration by doing the following appropriate tasks: Configure an IIS Web Agent
Configure a Sun Java System Web Agent Configure an Apache Web Agent Configure a Domino Web Agent More Information Configure an IIS Web Agent (see page 73) Configure a Sun Java System Web Agent (see page 79) Configure an Apache Web Agent (see page 89) Configure a Domino Web Agent (see page 101) Modify the SmHost.Conf File (UNIX) (see page 63)
Description and Configuration Specifies the host configuration object that defines connectivity between the trusted host and the Policy Server. If the trusted host where the Web Agent is installed has changed, or you want to use an object with a different configuration, you need to modify this setting. This name must match a name defined in the Policy Server User Interface. The syntax for this parameter is: hostconfigobject="<host_configuration_object>"
Description and Configuration Specifies the Policy Server(s) to which the trusted host will try to connect. The proper syntax is: "<IP_address>, CA Portal,CA Portal,CA Portal" The default ports are 44441,44442,44443, but you can specify non-default ports using the same number or different numbers for all three ports. The unified server responds to any Agent request on any port. To specify additional bootstrap servers for the Agent, add multiple Policy Server entries to the file. Multiple entries provide the Agent with several Policy Servers to which it can connect to retrieve its Host Configuration Object. After the Host Configuration Object is retrieved, the bootstrap servers are no longer needed for that server process. Important: If an Agent is configured on a multiprocess web server, specifying multiple Policy Server entries is recommended to ensure that any child process can establish a connection to the secondary Policy Server if the primary Policy Server fails. Each time a new child process is started, it will not be able to initialize the Web Agent if only one Policy Server is listed in the file and that Policy Server is unreachable. Multiple entries can be added during host registration or by modifying this parameter. Place each server entry on its own line. For example: policyserver="123.122.1.1, 44441,44442,44443" policyserver="111.222.2.2, 44441,44442,44443" policyserver="321.123.1.1, 44441,44442,44443" If a Policy Server is removed from your SiteMinder environment or is no longer in service, delete the entry.
requesttimeout
Determines the number of seconds the trusted host waits before deciding that a Policy Server is unavailable. You can modify this value. The default is 60 seconds. You may want to increase the timeout value if the Policy Server is busy due to heavy traffic or a slow network connection. For example, requesttimeout="60"
Note: There should be a space between each command argument and its value. Example:
smreghost -i 123.123.1.1 -u SiteMinder -p mypw -hn hostA -hc DefaultHostSettings
For a list of all the smreghost command arguments, see the following table.
Value IP address of the Policy Server where you are registering this host. Specify the port of the authentication server only if you are not using the default, which is 44442. (required) If you specify a port number, which can be a non-default port, that port is used for all three Policy Server servers (authentication, authorization, accounting), however, the unified server responds to any Agent request on any port. The policyserver entry in the SmHost.conf file will be: "112.11.2.5,5555,5555,5555"
u <administrator_username>
Name of the SiteMinder administrator with the rights to register a trusted host. (required) Password for the Administrator allowed to register a trusted host. (required) Name of the host to be registered. This can be any name that identifies the host, but it must be unique. After registration, this name is placed in the Trusted Host list in the Policy Server User Interface. (required) Name of the Host Configuration Object configured at the Policy Server. (required)
p <administrator_password>
hn <hostname_for_registration>
hc <host_config_object>
Arguments f <path_to_host_config_file>
Value Full path to the file that contains the registration data. The default file is SmHost.conf. If you do not specify a path, the file is installed in the location where you are running the smreghost tool. If you use the same name as an existing host configuration file, the tool backups up the original and adds a .bk extension to the backup file name. (optional) On Windows systems, if you specify a file path with spaces, the entire path must be enclosed in quote marks.
cp <cryptographic_provider>
Name of the cryptographic provider you are using for encryption. If you do not specify a value, BSAFE is the default. (optional) Full path to the PKCS11 DLL. This DLL is installed with the nCipher software installed on same Web server as the Web Agent. (required for PKCS11 encryption) Token label for the hardware token. Only use this argument if there is a token label. (optional for PKCS11 encryption) Passphrase for the token. (required for PKCS11 encryption) Overwrites an existing trusted host without having to delete it first. The proper syntax is -o.
cd <crypto_provider_DLL_path>
ct <crypto_provider_token_label>
ck <crypto_provider_token_pin> o <overwrite_existing_trusted_host>
Directory dmspages
Description Contains JSPs and JavaScript used in Registration Services pages. This directory includes files that support Registration Services in hierarchical and flat user directory structures.
dmsforms properties
Contains .fcc files, which collect user credentials. Contains the directories: DefaultContains properties files for configuring a hierarchical directory structure Default_attr-basedContains properties files for configuring a flat directory structures
Note: The forms, formsfr, and formsja folders are used by Registration Services with DMS v1.0. You should not modify these files unless you are using Registration Services with DMS v1.0.
On Windows 2000, if this procedure does not fix the classpath: 1. 2. 3. 4. Open the classpath.pref in a text editor. Collapse all entries to one line separated by a semi-colon(;). Save the file. Restart the Web server.
where <operating_system> is sol, aix, linux, rhel30, SuSE-zLinux, hp, or hp-itan The documentation installation starts. 6. Read the License Agreement, pressing ENTER to page through the entire document. If you agree with the terms, enter Y to continue the installation. Review the Important Instructions, then click Next. Specify the installation directory. The installation program installs the 6.x Web Agent documentation in the directory you specified.
7. 8.
Note: The Web Agent installation adds and modifies a few system environment variables. More Information Install UNIX Patches (see page 15) Environment Variables Added or Modified by the Web Agent Installation (see page 185)
2.
Linux 3.0: nete-wa-6qmr5-rhel30.bin Suse-zLinux: nete-wa-6qmr5-SuSE-zLinux.bin HP-UX: nete-wa-6qmr5-hp.bin HP-UX Itanium: nete-wa-6qmr5-hp-itan.bin 8. Depending on your permissions, you may need to add executable permissions to the installation file by running the chmod command, for example: chmod +x nete-wa-6qmr5-sol.bin 9. Open a console window and from the local installation directory enter: ./nete-wa-6qmr5-<operating_system>.bin where <operating_system> is sol, aix, linux, rhel30, SuSE-zLinux, hp, or hp-itan The installation program prepares the files. 10. In the Introduction dialog box, read the information then click Next. 11. Read the License Agreement then select the radio button to accept the agreement. Click Next. If you do not accept the agreement, the installation terminates. 12. Read the notes in the Important Information dialog box, then click Next. 13. In the Choose Install Location dialog box, accept the default location or use the Choose button to select a different location. Click Next. If you select a non-default location then want to revert to the default directory, click Restore Default Folder. 14. Review the information in the Pre-Installation Summary dialog box, then click Install. The Web Agent files are installed in the specified location. 15. In the Install Complete dialog box, click Done. 16. After installing the Agent, run the Agent Configuration Wizard to register a trusted host and configure the Web Agent. More Information Run a Console Mode Installation on UNIX (see page 54) Register Your System as a Trusted Host on UNIX (see page 59) Configure a Web Agent (see page 73)
10. Enter Y to accept the agreement and continue with the installation.
11. Review the Important Information section for information about the installation and documentation. Press ENTER to page through the notes and continue through the installation. 12. In the Choose Install Location section, specify the location where the installation should place the Agent files. To accept the default location, press ENTER. If you specify a path, it must contain the word "webagent." If it does not, the installation program will create this folder and append it to the path. For example, if you specify export/netegrity/wa, the path becomes export/netegrity/wa/webagent. However, if you specify export/netegrity/sm_webagent as the path, the installation program will accept this. 13. Review the information in the Pre-Installation Summary, then press ENTER to continue. The program begins installing files. 14. When the installation is complete, you will receive a message along with instructions on locating the Configuration Wizard. 15. Press ENTER to exit the installer. 16. After installing the Agent, run the Agent Configuration Wizard to register a trusted host and configure the Web Agent. More Information Register Your System as a Trusted Host on Windows (see page 35) Configure a Web Agent (see page 73)
Parameter USER_SHORTCUTS
Meaning Specifies where the Web Agent configuration shortcut should be installed. Enter the path to the desired location. (Windows only) Specifies the installed location of the Web Agent. Enter the full path to the installation directory. Indicates whether the installation program should reboot a Windows machine if required. Set to YES to allow the reboot. (Windows only)
USER_INSTALL_DIR
USER_REQUESTED_RESTART
3.
More Information Run a GUI Mode Installation on UNIX (see page 52) Set Up the nete-wa-installer.properties File (see page 153)
More Information Configure Any Web Agent in Unattended Mode (see page 108)
Open a console window and navigate to the directory where you copied the two files. Run the installation executable with the -f and - i silent options, as follows: <agent_binary> -f <properties_file> -i silent Note: If you are not at the directory where these files reside, you must specify the full path to each file. Assuming that you run the installation from the directory where the executable and properties file are located, the command for a Solaris system would be: ./nete-wa-6qmr5-sol.bin -f nete-wa-installer.properties -i silent When the installation is complete, you return to the command prompt.
4.
CA_SiteMinder_Web_Agent _v6QMR5_InstallLog.log file, located in the <web_agent_home>/install_config_info directory. This log file contains the results of the installation. Register the trusted host and configure the Web Agent.
5.
If you enabled cryptographic hardware, complete the fields. If not, skip to the next step. a. In the PKCS11 DLL field, enter the full path to the PKCS11 DLL. This DLL is installed with the nCipher software installed on same Web server as the Web Agent. Click on Choose to search for the DLL. Optionally, specify the token label in the Token Label and Token Passphrase, if applicable. Re-confirm the passphrase in the Confirm token passphrase field then click Next.
b.
4.
Complete the following fields in the Admin Registration dialog box, then click Next: Admin User Nameenter the name of the administrator allowed to register the host with the Policy Server.
This administrator should already be defined at the Policy Server and have the permission Register Trusted Hosts set. The default administrator is SiteMinder. Admin Passwordenter the administrators password. Confirm Admin Passwordre-enter the password. Enabled Shared Secret Rollovercheck this box to periodically change the shared secret used to encrypt communication between the trusted host and the Policy Server. Key rollover must be enabled at the Policy Server for this feature to work. Important: If you enable shared secret rollover, the user who owns the Web server process must have permissions to write to the SmHost.conf file. If this file cannot be modified by this user, then the shared secret rollover cannot be updated. For example, for Sun Java System and Apache Web servers, the person specified by the User directive needs write permission to the SmHost.conf file. If the SmHost.conf file is owned by User1 and no other user has write permissions, the shared secret rollover is not written to the SmHost.conf file if User2 owns the server process. 5. In the Trusted Host Name and Configuration Object dialog box, enter values for the two fields then click Next. a. In the Trusted Host Name field, enter a unique name that represents the trusted host to the Policy Server. This name does not have to be the same as the physical client system that you are registering; it can be any unique name, for example, mytrustedhost. Note: This name must be unique among trusted hosts and not match the name of any 4.x Web Agent. It can be the same name as a 5.0 Web Agent, but this is not recommended. b. In the Host Configuration Object field, enter the name of the Host Configuration Object specified in the Policy Server, then click Next. This object defines the connection between the trusted host and the Policy Server. To use the default, enter DefaultHostSettings. In most cases, you will use your own Host Configuration Object. Note: The entry you specify must match the Host Configuration Object entry set at the Policy Server. 6. In the Policy Server IP Address dialog box: a. Enter the IP address, or host name, and the authentication port of the Policy Server where you are registering the host. The default port is 44442. If you do not provide a port, the default is used. You can specify a non-default port number, but if you are using a nondefault port and you omit it, SiteMinder displays the following error:
Registration Failed (bad ipAddress[:port] or unable to connect to Authentication server (-1)) Note also that if you specify a non-default port, that port is used for the Policy Servers authentication, authorization, and accounting ports; however, the unified server responds to any Agent request on any port. The entry in the SmHost.conf file will look like: policyserver="112.11.2.55,5555,5555,5555" b. Click Add. You can add more than one Policy Sever; however, for host registration, only the first server in the list will be used. If you add multiple entries, separate them by a comma. If multiple Policy Servers are specified, the Agent uses them as bootstrap servers. When the Agent starts up, the Web Agent has several Policy Servers to which it can connect to retrieve its Host Configuration Object. After the Host Configuration Object is retrieved, the bootstrap Policy Server is no longer used by that server process. The Host Configuration Object can contain another set of servers, which may or may not include any of the bootstrap servers. c. 7. Click Next.
Accept the default location of the host configuration file, SmHost.conf or click Choose to select a different location. Click Next. If you select a non-default location then want to revert to the default directory, click Restore Default Folder. The host is registered and a host configuration file, SmHost.conf, is created in <web_agent_home>/config. You can modify this file.
8.
More Information Configure an IIS Web Agent (see page 73) Configure a Sun Java System Web Agent (see page 79) Configure an Apache Web Agent (see page 89) Modify the SmHost.Conf File (UNIX) (see page 63)
Description and Configuration Specifies the host configuration object that defines connectivity between the trusted host and the Policy Server. If the trusted host where the Web Agent is installed has changed, or you want to use an object with a different configuration, you need to modify this setting. This name must match a name defined in the Policy Server User Interface. The syntax for this parameter is: hostconfigobject="<host_configuration_object>"
Description and Configuration Specifies the Policy Server(s) to which the trusted host will try to connect. The proper syntax is: "<IP_address>, CA Portal,CA Portal,CA Portal" The default ports are 44441,44442,44443, but you can specify non-default ports using the same number or different numbers for all three ports. The unified server responds to any Agent request on any port. To specify additional bootstrap servers for the Web Agent, add multiple Policy Server entries to the file. Multiple entries provide the Agent with several Policy Servers it can connect to and retrieve its Host Configuration Object. Once the Host Configuration Object is retrieved, the bootstrap servers are no longer needed for that server. Important: If an Agent is configured on a multiprocess web server, specifying multiple Policy Server entries is recommended to ensure that any child process can establish a connection to the Policy Server if the primary Policy Server fails. Each time a new child process is started, the new process will not be able to initialize the Web Agent if only one Policy Server is listed in the file and that Policy Server is unreachable. Multiple entries can be added during host registration or by modifying this parameter. Place each server entry on its own line. For example: policyserver="123.122.1.1, 44441,44442,44443" policyserver="111.222.2.2, 44441,44442,44443" policyserver="321.123.1.1, 44441,44442,44443" If a Policy Server is removed from your SiteMinder environment or is no longer in service, delete the entry.
Description and Configuration Determines the number of seconds the trusted host waits before deciding that a Policy Server is unavailable. You can modify this value. The default is 60 seconds. You may want to increase the timeout value if the Policy Server is busy due to heavy traffic or a slow network connection. For example, requesttimeout="60"
Enter the smreghost command using the following required arguments: smreghost -i <policy_server_IP_address:[port]> -u <administrator_username> -p <Administrator_password> -hn <hostname_for_registration> -hc <host_configuration_ object> Note: There should be a space between each command argument and its value. Example: smreghost -i 123.123.1.1 -u SiteMinder -p mypw -hn hostA -hc DefaultHostSettings Example with the -o argument: smreghost -i 123.123.1.1 -u SiteMinder -p mypw -hn hostA hc DefaultHostSettings -o The following table lists all the smreghost command arguments.
Path Variable IP address of the Policy Server where you are registering this host. Specify the port of the authentication server only if you are not using the default, which is 44442. (required) If you specify a port number, which can be a nondefault port, that port is used for all three Policy Server servers (authentication, authorization, accounting), however, the unified server responds to any Agent request on any port. The policyserver entry in the SmHost.conf file will be: "112.11.2.5,5555,5555,5555"
Name of the SiteMinder administrator with the rights to register a trusted host. (required) Password for the Administrator allowed to register a trusted host. (required)
Path Variable Name of the host to be registered. This can be any name that identifies the host, but it must be unique. After registration, this name is placed in the Trusted Host list in the Policy Server User Interface. (required) Name of the Host Configuration Object configured at the Policy Server. (required)
hc <host_config_obj ect>
f <path_to_host_con Full path to the file that contains the registration fig_file> data. The default file is SmHost.conf. If you do not specify a path, the file is installed in the location where you are running the smreghost tool. If you use the same name as an existing host configuration file, the tool backups up the original and adds a .bk extension to the backup file name. (optional) cp <cryptographic_pr Name of the cryptographic provider you are using ovider> for encryption. If you do not specify a value, BSAFE is the default. (optional) cd <crypto_provider _DLL_path> Full path to the PKCS11 DLL. This DLL is installed with the nCipher software installed on same Web server as the Web Agent. (required for PKCS11 encryption)
ct <crypto_provider_ Token label for the hardware token. Only use this token_label> argument if there is a token label. (optional for PKCS11 encryption) ck <crypto_provider_ Passphrase for the token. (required for PKCS11 token_pin> encryption) o <overwrite_existin g_trusted_host> Overwrites an existing trusted host without having to delete it first. The proper syntax is -o
More Information Re-register a Trusted Host Using the Registration Tool (UNIX) (see page 67)
Directory dmspages
Description Contains JSPs and JavaScript used in Registration Services pages. This directory includes files that support Registration Services in hierarchical and flat user directory structures.
dmsforms properties
Contains .fcc files, which collect user credentials. Contains the directories: DefaultContains properties files for configuring a hierarchical directory structure Default_attr-basedContains properties files for configuring a flat directory structures
Important! The forms, formsfr, and formsja folders are used by Registration Services with DMS v1.0. You should not modify these files unless you are using Registration Services with DMS v1.0.
More Information Assign Read Permissions to Samples and Error Files Directories (see page 74) Allow IIS to Execute Web Agent ISAPI and CGI Extensions (see page 75) Run the Configuration Wizard for an IIS Web Agent (see page 77)
You return to the Properties dialog box for the directory. 6. 7. In the Permissions for Network Service scroll-box, allow Read permissions. Click OK to finish.
IIS 6.0 Web Agent Operating with Third-Party Software on the Same Server
The IIS 6.0 Web Agent consists of an ISAPI filter and an ISAPI extension. The majority of Web Agent processing occurs in the extension, following Microsoft IIS development guidelines. These guidelines specify that for the IIS 6.0 Web server, the ISAPI filters should be used for filtering requests and the ISAPI extensions should be used to process and/or redirect requests. When the Web Agent is installed on an IIS 6.0 Web Server with other thirdparty software, such as WebSphere or ServletExec, the Agent has the following restrictions: The Web Agent filter and Web Agent extension must be configured to run before other third-party filters installed on the Web server. The Web Agent must be configured as the first wildcard application map if it is going to protect applications running as or spawned by an ISAPI extension. The IIS 6.0 Web server does not enforce how third-party filters and extensions behave. IIS 6.0 processes ISAPI filters before calling ISAPI extensions, including the Web Agent extension. Therefore, the SiteMinder Web Agent for IIS 6.0 is unable to authenticate or authorize access to applications implemented as pure ISAPI filters. This limitation impacts Web Agent integration with other third-party offerings for the IIS 6.0 Web server, if those offerings are implemented as ISAPI filters that process and/or redirect the request before ISAPI extensions are called.
Web Agent on IIS 6.0 Has Size Limit for Uploading Files
The Web Agent installed on an IIS 6.0 Web server has a size limit of 2.5 MB for uploading files. To upload files that are larger than this limit: 1. 2. Create a new DWORD registry key in SOFTWARE\Netegrity\SiteMinder Web Agent\Microsoft IIS called MaxRequestAllowed. Set this value to the desired file size limit. The value of this key overrides the default limit. If the value of this key is less than or equal to 0, than the default of 2.5 MB will be used. Note: The IIS 6.0 Web server has its own size limit. Changing the Web Agents limit will not affect the IIS 6.0 limit. If you want to change the IIS 6.0 servers limit, refer to Microsoft IIS 6.0 documentation.
In the Agent Configuration Object field, enter the name of the Agent Configuration Object for this Web server instance, then click Next. This name must match an Agent Configuration Object already defined at the Policy Server. For example, enter IISDefaultSettings to use the default.
5.
If you want to configure Registration Services for DMS2, select Yes. If not, select No. A servlet engine is required to run Self Registration. If the Web Agent Configuration Wizard does not detect a servlet engine, the Select Servlet Engine for Registration dialog box is not displayed. If you selected Yes to configure Registration Services:
a.
Select a servlet engine to be configured for the web server. If you do not see your engine displayed, select Other Advanced server. Click Next. In the Self Registration Services Admin Account dialog box, identify the the DMS Administrator by provide values for the Admin User Name, Admin Password and Admin Confirm Password fields and click Next. The user name and password that you enter here must match the DMS Admin values you set at the Policy Server. The DMS Administrator account secures DMS requests that are performed outside of the scope of a DMS administrator, such as selfregistration. The user name and encrypted password for the account are stored in the dms.properties file on the Web Agent.
b.
6.
In the Web Server Configuration Summary dialog box, confirm that the configuration settings are correct, then click Install. The Web Agent files are installed.
7. 8.
Click Done when the installation is complete. If you enabled cryptographic hardware on an Agent, you need to allow the associated Web-server service to interact with the desktop. This allows the service to prompt for the hardwares associated passphrase. To configure the service to interact with the desktop: a. Open the Services control panel. On Windows 2000, you access Services by selecting Administrative Tools, Computer Management, Services and Applications. b. Double click the World Wide Web Publishing Service. The Service dialog box opens. c. Select Allow Service to Interact with Desktop. On Windows 2000, this checkbox is on the Log On tab for the World Wide Web Publishing Service. d. e. Click OK. Exit the Control Panel.
9.
Enable the Web Agent: a. Open the WebAgent.conf file located in <web_agent_home>\bin\IIS Example: C:\Program Files\netegrity\webagent\bin\IIS b. c. Set the EnableWebAgent parameter to Yes. Save the file and restart the Web server.
Note: You need to reboot the machine once the Agent is configured to ensure proper logging of Agent and trace messages.
More Information Register Your System as a Trusted Host on Windows (see page 35) Install a Web Agent on a Windows System (see page 29)
Put the Agent Filter and Extension Before Other Third-Party Filters
After you install and configure an IIS 6.0 Web Agent, it is essential that the siteminderagent ISAPI filter and extension be listed before any third-party filter or extension. This enables the Web Agent to process requests before a third-party. Checking the ISAPI Filter When you install the Web Agent on an IIS 6.0 Web server, the Agents filter is automatically placed at the top of the ISAPI filters list. However, if you install any other third-party plugins after installing the Web Agent, those filters may take precedence. To check the filter order: a. b. c. d. Open the IIS Manager. Select Web Sites then right-click and select Properties. Select the ISAPI Filters tab. Check the list of filters and ensure that siteminderagent is the first entry in the list. If it is not, use the Move Up button to place it at the top of the list. Click OK. Exit the IIS Manager.
e. f.
Checking the ISAPI Extensions To ensure the ISAPI extension is listed first, open the IIS management console and access the properties for the Web server top level or for the servers default Web site. In the Home Directory tab, go to the application settings and display the Application Mappings list to see the list of extensions.
Important! If you uncheck a previously configured server, the Web Agent will be removed from this server. b. 4. Click Next.
In the Agent Configuration Object field, enter the name of the Agent Configuration Object for this Web server instance, then click Next. This name must match an Agent Configuration Object already defined at the Policy Server. For example, to use the default enter iPlanetDefaultSettings.
5.
If applicable, select one of the advanced SSL authentication schemes listed in the SSL Authentication dialog box. If the Agent is not providing advanced authentication, select No advanced authentication. Click Next. The selections are: HTTP Basic over SSLidentifies a user based on a user name and password. The credential delivery is always done over an encrypted Secure Sockets Layer (SSL) connection. X509 Client Certificateidentifies a user based on X.509 V3 client certificates. Digital certificates act as a signature for a user. Certificate authentication uses SSL communication. X509 Client Cert and HTTP Basiccombines X.509 Client Certificate and Basic authentication. The users X.509 client certificate must be verified and he or she must provide a valid user name and password. X509 Client Cert or HTTP Basiccombines X.509 Client Certificate and Basic authentication. The users X.509 client certificate must be verified, or he or she must provide a valid user name and password. X509 Client Cert or FormThe X.509 Client Certificate or HTML Forms authentication scheme combines the use of X.509 Client Certificates and the use of customized HTML forms to collect authentication information. Using this scheme, the users X.509 client certificate must be verified or the user must provide the credentials requested by an HTML form. X509 Client Cert and FormThe X.509 Client Certificate and HTML Forms authentication scheme combines the use of X.509 Client Certificates and the use of customized HTML forms to collect authentication information. Using this scheme, the users X.509 client certificate must be verified and the user must provide the credentials requested by an HTML form. Note: For additional information about advanced authentication schemes, refer to CA eTrust Policy Design. If this Web Agent is installed on an SSL server to handle only credential collection requests for advanced authentication schemes, set the Agents EnforcePolicies setting to No to improve performance. To modify the Agents configuration, refer to CA eTrust Policy Design or, for local configuration, this guide.
6.
If you want to configure Self Registration for DMS2, select Yes. If not, select No. A servlet engine is required to run Self Registration. If the Web Agent Configuration Wizard does not detect a servlet engine, the Select Servlet Engine for Registration dialog box is not displayed. If you selected Yes to configure Self Registration: a. b. Select a servlet engine to be set up for the web server. If you do not see your engine displayed, select Other Advanced server. Click Next. In the Self Registration Services Admin Account dialog box, identify the the DMS Administrator by provide values for the Admin User Name, Admin Password and Admin Confirm Password fields and click Next. The user name and password that you enter here must match the DMS Admin values you set at the Policy Server. The DMS Administrator account secures DMS requests that are performed outside of the scope of a DMS administrator, such as selfregistration. The user name and encrypted password for the account are stored in the dms.properties file on the Web Agent.
7.
In the Web Server Configuration Summary dialog box. Confirm that the configuration settings are correct, then click Install. The Web Agent files are installed and the Configuration Complete dialog box displays.
8. 9.
Click Done to exit the Configuration Wizard. If you enabled cryptographic hardware on an Agent, you also need to allow the associated Web-server service to interact with the desktop. This allows the service to prompt for the hardwares associated passphrase. To configure the service to interact with the desktop: a. Open the Services control panel. On Windows 2000, select Administrative Tools, Computer Management, Services and Applications. b. Double click the appropriate iWS or Netscape server entry. The Service dialog box opens. c. d. e. Select Allow Service to Interact with Desktop. Click OK. Exit the Control Panel.
10. Enable the Web Agent: a. Open the WebAgent.conf file, located in: <Sun_Java_System_server_home>\servers\httpshostname\config
b. c.
11. Apply changes to Sun Java System Web Server files. This is required for the Agents configuration to take effect.
More Information Apply Changes to Sun Java System Web Server Files (see page 88)
Configure Sun Java System Web Agents Using GUI or Console Mode
These instructions are for GUI and Console Mode configuration. The steps for the two modes are the same, with these exceptions for Console Mode: You may be instructed to select an option by entering a corresponding number. For example, to select the Sun Java System Web Server, you enter a 3, which corresponds to this server. Press ENTER after each step to proceed through the process instead of "clicking Next," as stated in the following procedure. All passwords that you enter are displayed in clear text. To workaround this issue, run the installation in GUI or unattended mode. The prompts for each mode will help guide you through the process. To configure the Web Agent on an Sun Java System Web Server: 1. If necessary, start the Configuration Wizard. a. b. c. Open a console window. Navigate to <web_agent_home>/install_config_info Enter one of the following commands: GUI mode: ./nete-wa-config.bin Console mode: ./nete-wa-config.bin -i console 2. If you have already done host registration, skip to the next step. Otherwise, select the option to skip host registration, then click Next. To register the trusted host, go to the installation chapter for your platform. 3. 4. In the Select Web Server(s) dialog box, select the option for the iPlanet or Sun ONE Web Server and click Next. Specify the root path where the Sun Java System Web server is installed and click Next. For example, /opt/iPlanet/servers. You can click Choose to locate the root directory. 5. Select the Web server instances that you want to configure with Web Agents.
If you have already configured a server with a Web Agent and you are running the Configuration Wizard to configure additional Web servers instances, the Wizard displays the Select One or More Instances to Overwrite dialog box. This dialog box lists the Web servers that you have previously configured. a. Select one of the following: Overwriteto overwrite the server instance configuration. Preserveto preserve the Web servers configuration. Important! If you uncheck a previously configured server, the Web Agent will be removed from this server. b. 6. Click Next.
In the Agent Configuration Object field, enter the name of the Agent Configuration Object for this Web server instance. This name must match an Agent Configuration Object already defined at the Policy Server. For example, to use the default enter iPlanetDefaultSettings.
7.
If applicable, select one of the advanced SSL authentication schemes listed in the SSL Authentication dialog box. If the Agent is not providing advanced authentication, select No advanced authentication. Click Next following your choice. The selections are: HTTP Basic over SSLidentifies a user based on a user name and password. The credential delivery is always done over an encrypted Secure Sockets Layer (SSL) connection. X509 Client Certificateidentifies a user based on X.509 V3 client certificates. Digital certificates act as a signature for a user. Certificate authentication uses SSL communication. X509 Client Cert and HTTP Basiccombines X.509 Client Certificate and Basic authentication. The users X.509 client certificate must be verified and he or she must provide a valid user name and password. X509 Client Cert or HTTP Basiccombines X.509 Client Certificate and Basic authentication. The users X.509 client certificate must be verified, or he or she must provide a valid user name and password. X509 Client Cert or FormThe X.509 Client Certificate or HTML Forms authentication scheme combines the use of X.509 Client Certificates and the use of customized HTML forms to collect authentication information. Using this scheme, the users X.509 client certificate must be verified or the user must provide the credentials requested by an HTML form.
X509 Client Cert and FormThe X.509 Client Certificate and HTML Forms authentication scheme combines the use of X.509 Client Certificates and the use of customized HTML forms to collect authentication information. Using this scheme, the users X.509 client certificate must be verified and the user must provide the credentials requested by an HTML form. Note: For additional information about advanced authentication schemes, refer to CA eTrust Policy Design. If this Web Agent is installed on an SSL server to handle only credential collection requests for advanced authentication schemes, set the Agents EnforcePolicies setting to No to improve performance. To modify the Agents configuration, refer to CA eTrust Policy Design or, for local configuration, this guide. 8. If you want to configure Self Registration for DMS2, select Yes. If not, select No. A servlet engine is required to run Self Registration. If the Web Agent Configuration Wizard does not detect a servlet engine, the Select Servlet Engine for Registration dialog box is not displayed. If you selected Yes to configure Self Registration: a. Select a servlet engine to be configured for the web server. If you do not see your engine displayed, select Other Advanced server. Click Next. In the Self Registration Services Admin Account dialog box, identify the the DMS Administrator by provide values for the Admin User Name, Admin Password and Admin Confirm Password fields and click Next. The user name and password that you enter here must match the DMS Admin values you set at the Policy Server. The DMS Administrator account secures DMS requests that are performed outside of the scope of a DMS administrator, such as selfregistration. The user name and encrypted password for the account are stored in the dms.properties file on the Web Agent. 9. In the Web Server Configuration Summary dialog box. Confirm that the configuration settings are correct, then click Install. The Web Agent files are installed and the Configuration Complete message is displayed. 10. Click Done when the installation is complete. 11. Enable the Web Agent: a. Open the WebAgent.conf file, located in <Sun_Java_System_server>/servers/https-hostname/config b. Set the EnableWebAgent parameter to Yes.
b.
c. d.
12. Apply changes to the Sun Java System Web Server files. This is required for the Agents configuration to take effect.
You may be required reboot your machine once the Agent is configured. More Information Settings Added to the Sun Java System Server Configuration (see page 167) Tune the Shared Memory Segments (Apache and Sun Java System) (see page 112)
Choose this option to skip Apache configuration and continue with the Agent configuration. Click Next. 5. Following the server root path, specify the version of Apache you are using. Select from these two options: Apache version 1.0 Apache version 2.0 6. Select the Web server instances that you want to configure with Web Agents. If you have already configured a server with a Web Agent and you are running the Configuration Wizard to configure additional Web servers instances, the Wizard displays the Select One or More Instances to Overwrite dialog box. This dialog box lists the Web servers that you have previously configured. a. Select one of the following: Overwriteto overwrite the server instance configuration. Preserveto preserve the Web servers configuration. Important! If you uncheck a previously configured server, the Web Agent will be removed from this server. b. 7. Click Next.
In the Agent Configuration Object field, enter the name of the Agent Configuration Object for this Web server instance. This name must match an Agent Configuration Object already defined at the Policy Server. For example, to use the default enter ApacheDefaultSettings.
8.
If you want to configure Self Registration for DMS2, select Yes. If not, select No and go to Step . A servlet engine is required to run Self Registration. If the Web Agent Configuration Wizard does not detect a servlet engine, the Select Servlet Engine for Registration dialog box is not displayed. If you selected Yes to configure Self Registration: a. Select a servlet engine to be configured for the web server. If you do not see your engine displayed, select Other Advanced server. Click Next. In the Self Registration Services Admin Account dialog box, identify the the DMS Administrator by provide values for the Admin User Name, Admin Password and Admin Confirm Password fields and click Next. The user name and password that you enter here must match the DMS Admin values you set at the Policy Server.
b.
The DMS Administrator account secures DMS requests that are performed outside of the scope of a DMS administrator, such as selfregistration. The user name and encrypted password for the account are stored in the dms.properties file on the Web Agent. 9. In the Web Server Configuration Summary dialog box. Confirm that the configuration settings are correct, then click Install. The Web Agent files are installed. 10. Click Done when the installation is complete. 11. If you enabled cryptographic hardware on an Agent, you need to allow the associated Web-server service to interact with the desktop. This allows the service to prompt for the hardwares associated passphrase. To configure the service to interact with the desktop: a. Open the Services Control Panel. On Windows 2000, from the control panel select Administrative Tools, Computer Management, Services and Applications. b. Double click the appropriate Apache server entry. The Service dialog box opens. c. d. e. Select Allow Service to Interact with Desktop. Click OK. Exit the Control Panel.
12. Enable the Web Agent: a. Open the WebAgent.conf file, located as follows: <Apache_home>\conf where Apache_home is the installed location of the Apache Web server. b. c. Set the EnableWebAgent parameter to Yes. Save and close the file.
13. Restart the Web server. When you run the Configuration Wizard for the Apache Web Agent, it makes changes to the Web Servers httpd.conf file and to the library path. For httpd.conf changes to take effect, you need to restart the web server. More Information Register Your System as a Trusted Host on Windows (see page 35) Configuration Changes to Web Servers with Apache Web Agent (see page 175) Configure an Apache Web Agent (see page 89)
I dont have an Apache Web server. Choose this option to skip Apache configuration and continue with the Agent configuration. Click Next. 5. Following the server root path, specify the version of Apache you are using. Select from these two options: Apache version 1.0 Apache version 2.0 6. Select the Web server instances that you want to configure with Web Agents. If you have already configured a server with a Web Agent and you are running the Configuration Wizard to configure additional Web servers instances, the Wizard displays the Select One or More Instances to Overwrite dialog box. This dialog box lists the Web servers that you have previously configured. a. Select one of the following: Overwriteto overwrite the server instance configuration. Preserveto preserve the Web servers configuration. Important! If you uncheck a previously configured server, the Web Agent will be removed from this server. b. 7. Click Next.
In the Agent Configuration Object field, enter the name of the Agent Configuration Object for this Web server instance. This name must match an Agent Configuration Object already defined at the Policy Server. For example, to use the default enter ApacheDefaultSettings.
8.
If you want to configure Self Registration for DMS2, select Yes. If not, select No. A servlet engine is required to run Self Registration. If the Web Agent Configuration Wizard does not detect a servlet engine, the Select Servlet Engine for Registration dialog box is not displayed. If you selected Yes to configure Self Registration: a. Select a servlet engine to be configured for the web server. If you do not see your engine displayed, select Other Advanced server. Click Next. In the Self Registration Services Admin Account dialog box, identify the the DMS Administrator by provide values for the Admin User Name, Admin Password and Admin Confirm Password fields and click Next.
b.
The user name and password that you enter here must match the DMS Admin values you set at the Policy Server. The DMS Administrator account secures DMS requests that are performed outside of the scope of a DMS administrator, such as selfregistration. The user name and encrypted password for the account are stored in the dms.properties file on the Web Agent. 9. In the Web Server Configuration Summary dialog box. Confirm that the configuration settings are correct, then click Install. The Web Agent files are installed. 10. Click Done when the installation is complete. 11. Enable the Web Agent: a. Open the WebAgent.conf file, located as follows: <Apache_home>/conf b. c. Set the EnableWebAgent parameter to yes. Save and close the file.
12. Restart the Web server. When you run the Configuration Wizard for the Apache Web Agent, it makes changes to the Web Servers httpd.conf file and to the library path. For httpd.conf changes to take effect, you need to restart the web server. 13. For Apache on UNIX systems, optimize the Apache Web Agent by tuning the shared memory segments. More Information Configuration Changes to Web Servers with Apache Web Agent (see page 175) Configure an Apache Web Agent (see page 89) Tune the Shared Memory Segments (Apache and Sun Java System) (see page 112)
Set the LD_PRELOAD Variable for Apache Web Server on SUSE Linux 98
After you install the Web Agent v6.x on an Apache Web server running on SUSE 9, you must set the LD_PRELOAD environment variable as follows: LD_PRELOAD=<web_agent_home>/bin/libbtunicode.so Without this setting, two problems may occur: The Apache web server may dump core upon shutdown. When a SAML Affiliate Agent is running on an Apache Web Server, a load change may spawn multiple processes that eventually consume 100% of the CPU cycles. Note: Setting this environment variable causes any application executed from that environment to bind with libbtunicode.so. Therefore, only set this variable when starting or stopping a Web server that loads the SiteMinder Web Agent.
Set the LD_PRELOAD Variable for an Oracle 10G Web Server on Linux
After you install the Web Agent v6.x on an Oracle 10G Web server running on a Linux platform, you must set the LD_PRELOAD environment variable in the apachectl script. If the LD_PRELOAD variable is not included in the apachectl script, the Oracle 10G Web server may dump core upon shutdown and fail to restart. 1. 2. Open the apachectl file. Add the LD_PRELOAD entry as follows: LD_PRELOAD=<web_agent_home>/bin/libbtunicode.so export LD_PRELOAD 3. Run the script to start the Apache server.
Note: Setting this environment variable causes any application executed from that environment to bind with libbtunicode.so. Therefore, set this variable only when starting or stopping a Web server that loads the SiteMinder Web Agent.
Set the LD_PRELOAD Variable for SSL Configuration on an IBM HTTP Server 2.0.47/Linux AS 3.0 System
When configuring SSL on an IBM HTTP Server 2.0.47.1 running SUSE8, ikeyman, the graphical user interface for the IBM key management utility, crashes when it is used to create a key database. To resolve this issue, set the following environment variable: export LD_PRELOAD=/usr/lib/libstdc++-libc6.2-2.so.3 After setting this variable, the key database file, key.kdb, is created successfully.
Set LD_PRELOAD for Using X.509-based Auth Schemes with Domino 6.5.3/SuSe8 Linux System
When accessing resource protected with any X.590-based Authentication Schemes on Domino 6.5.3/SuSe8 Linux, the Domino Server Crashes and generates an NSD. To resolve this issue, set the following environment variable before starting the Domino Web Server: export LD_PRELOAD=/usr/lib/libstdc++-libc6.2-2.so.3
2.
If it is not enable, enter chatr +s enable httpd. A partial sample of the output is shown below. First the current values are shown followed by the new values.
httpd: current values: shared executable shared library dynamic path search: SHLIB_PATH disabled second embedded path enabled first /home/userx/apache2043hp/lib:/ home/userx/apache2043hp//lib . . . shared library dynamic path search: SHLIB_PATH enabled second embedded path enabled first /home/userx/apache2043hp/lib: home/userx/apache2043hp//lib shared library list:
2. 3.
Important! If you uncheck a previously configured server, the Web Agent will be removed from this server. b. 6. Click Next.
In the Agent Configuration Object field, enter the name of the Agent Configuration Object for this Web server instance, then click Next. This name must match an Agent Configuration Object already defined at the Policy Server. For example, to use the default enter DominoDefaultSettings.
7.
In the Web Server Configuration Summary dialog box, confirm that the configuration settings are correct, then click Install. The Web Agent files are installed.
8. 9.
Click Done when the installation is complete. Enable the Web Agent: a. b. c. Open the WebAgent.conf file, located in where you installed the Domino Web server root directory. Set the EnableWebAgent parameter to YES. Save the file.
More Information Register Your System as a Trusted Host on UNIX (see page 59)
3. 4.
In the Select the Web server(s) dialog box, select the radio button for the Domino Web Sever and click Next. In the Domino Web Server Path dialog box, specify the location of the notes.ini file, such as /local/notesdata, then click Next. Note: The installation automatically writes the path to the WebAgent.conf in the notes.ini file.
5.
Select the Web server instances that you want to configure with Web Agents. If you have already configured a server with a Web Agent and you are running the Configuration Wizard to configure additional Web servers instances, the Wizard displays the Select One or More Instances to Overwrite dialog box. This dialog box lists the Web servers that you have previously configured. a. Select one of the following: Overwriteto overwrite the server instance configuration. Preserveto preserve the Web servers configuration. Important! If you uncheck a previously configured server, the Web Agent will be removed from this server. b. Click Next.
6.
In the Agent Configuration Object field, enter the name of the Agent Configuration Object for this Web server instance. This name must match an Agent Configuration Object already defined at the Policy Server. For example, to use the default enter DominoDefaultSettings.
7.
In the Web Server Configuration Summary dialog box. Confirm that the configuration settings are correct, then click Install. The Web Agent files are installed.
8. 9.
Click Done when the installation is complete. Enable the Web Agent: a. b. c. Open the WebAgent.conf file, located in the Domino Web server root directory. Set the EnableWebAgent parameter to Yes. Save the file.
Configure ServletExec 5.0 for JSP Password Services for an IIS Web Server
To properly configure ServletExec 5.0 for JSP-based Password Services: 1. Start the ServletExec Administration page by entering the following in a browser: http://localhost/servletexec/admin 2. Select Virtual Machine, Classpath and enter the following: <Web_Agent_installation>\jpw\jpw.jar <Web_Agent_installation>\java\jsafe.jar 3. 4. 5. 6. 7. Select Web Applications, Manage. Under Manage Web Applications, select the top web.xml link. On the servletexec: Set Display Options screen, select Servlets, Manage. Under servletexec: Manage Servlets, click Add Servlet. Under servletexec: Add Servlet, add the following and click submit: Servlet Name: PSWDChangeServlet Servlet Class: PSWDChangeServlet ServletExec should verify that the PSWDChangeServlet has been added successfully. 8. Select Servlets, Mapping, and add the following: URL pattern: /siteminderagent/pwservlet/PSWDChangeServlet Servlet Name: PSWDChangeServlet 9. Go back to the main ServletExec Administration page.
10. Select Web Applications, Manage. 11. Under Manage Web Applications, select the next web.xml link. 12. Repeat steps 5 to 8, and then ServletExec is properly configured.
More Information Set Up the nete-wa-installer.properties File (see page 153) Install a Web Agent on a UNIX System (see page 49) Install a Web Agent on a Windows System (see page 29)
2.
Tune the Shared Memory Segments (Apache and Sun Java System)
Tune the Shared Memory Segments (Apache and Sun Java System)
If you install an Apache or Sun Java System Web Agent on Solaris or HP-UX systems, you must tune the operating systems shared memory settings for the Web Agent to function correctly. By increasing the operating systems shared memory segments, you improve the performance of the Web Agent. The variables that control shared memory segments are defined in the operating systems specification file, as shown in the following table: Note: No tuning is necessary for Apache or Sun Java System servers on Linux and AIX platforms.
Name shmsys:shminfo_shmmax
Description
Required Change
Web Server 33554432 (32 mb) for busy sites that need large cache capacity.
Maximum Adjust the shared setting memory accordingly. segment size. Note: To estimate the Controls the amount of memory segments required, allocate maximum 4KB/entry in each cache, or size of the view cache usage statistics Agent resource and in the OneView Monitor. session cache. See the CA eTrust SiteMinder Web Agent Guide to learn how to configure the Web Agent to use the OneView Monitor. shmsys:shminfo_shmmin Minimum Adjust the shared setting memory accordingly. segment size. Controls the minimum size of the Agent resource and session cache.
1 mb
Tune the Shared Memory Segments (Apache and Sun Java System)
Name shmsys:shminfo_shmmni
Description
Required Change
The maximum Adjust the setting number of accordingly. shared memory segments that can exist simultaneousl y, systemwide. Maximum number of shared memory segments per process Number of semaphore identifiers. 6
24
semsys:seminfo_semmni
10 for every instance of the Agent that you run on the system.
100
semsys:seminfo_semmns
Number of 10 for every semaphores instance of the in the system. Agent that you run on the system Number of processes using the undo facility. For optimal performance, semmnu should be greater than the number of Apache child processes or Sun Java System processes running on the system at any one time.
100
semsys:seminfo_semmnu
200 or greater than the maxclients (Apache) or maxprocs (Sun Java System) setting.
Tune the Shared Memory Segments (Apache and Sun Java System)
To increase shared memory segments: 1. Follow the procedure for your operating system: Solaris: Open the /etc/system file, using the editor of your choice. HP-UX: Start the System Administration Manager (SAM) utility 2. Modify the shared memory variables: Solaris: Add the variables listed below and configure them using the recommended settings. Use the following syntax: set shmsys:shminfo_shmmax=33554432 HP-UX: Using the SAM utility, select Kernel Configuration, Configurable Parameters. SAM displays a set of variables. Highlight and modify each one listed below using the recommended settings.
Variable Name
Recommended Recommended SettingApache Setting excluding Apache 1.x/Solaris 9 1.x/Solaris 9 33554432 N/A N/A 24 33554432 1 200 24
shmsys:shminfo_shmmax shmsys:shminfo_shmmin shmsys:shminfo_shmmni shmsys:shminfo_shmseg Note: This parameter is no longer required for Solaris 9. semsys:seminfo_semmni semsys:seminfo_semmns semsys:seminfo_semmnu 3. 4. 5.
Save your changes then exit the file or the utility. Reboot the system. Verify your changes by entering the command:
$ sysdef -i
Configure ServletExec for JSP Password Services for a UNIX Sun Java System Web Server
The following procedure assumes an Sun Java System 6.x Web Server installed on a UNIX system. Consult your Web Server documentation for how to configure servlets on other Web Servers. To properly configure ServletExec for JSP-based Password Services: Note: In this procedure, <web_agent_home> refers to the installed location of the SiteMinder Web Agent. 1. 2. Open the Web Server administration console and open the particular instance on which the Web Agent is configured. Select Legacy Servlets, Configure Servlet Attributes, and add the following: Servlet Name: PSWDChangeServlet Servlet Code: PSWDChangeServletServlet Classpath: <web_agent_home>/jpw/jpw.jar 3. Select Legacy Servlets, Configure Servlet Virtual Path Translation, and add the Virtual Path: /siteminderagent/pwservlet/PSWDChangeServlet and Servlet Name: PSWDChangeServlet 4. 5. 6. Select Java, Enable/Disable Servlets/JSP, and uncheck the two check boxes to disable the Sun Java System servlet engine. Install ServletExec ASAPI. In a text editor, open the file: <ServletExec_home>/se-<instance_name>/StartServletExec where ServletExec_home is the installed location of ServletExec 7. Make the following modifications: a. In the StartServletExec file, find PORT="8888", and change the port of communication with Web server to any free port (for example, PORT="7777"). Extend the CLASSPATH definition by adding the following entries to the end of the CLASSPATH: <web_agent_home>/jpw/jpw.jar <web_agent_home>/java/jsafe.jar c. Extend the document directories definition by adding the directory entries after the following line: $SENAME $HOMEDIR $MIMEFILE $DOCROOTDIR -port $PORT $SEOPTS -addl "/siteminderagent/jpw=<web_agent_home>/jpw""
b.
Note: There are two quotation marks at the end of the entry. 8. Start ServletExec by running the script StartServletExec and open the ASAPI admin console by giving the URL. For example: http://<web_agent_instance:port>/servlet/admin 9. Select Servlets, Manage, and add the following: Servlet Name: PSWDChangeServlet Servlet Class: PSWDChangeServlet 10. Select Servlets, Aliases, and add the alias: /siteminderagent/pwservlet/PSWDChangeServlet Servlet Name: PSWDChangeServlet 11. Navigate to the config folder, located in <Sun_Java_System_home>/<https-hostname>/config and open the magnus.conf file. For the following line, change the IP address and port number to match the address for the Agent system that you already defined: Init fn="ServletExecInit" <instance_name>.instances="<IP_address>:7777" 12. Open the Sun Java System obj.conf file and add the following entry: NameTrans fn="assign-name" from="/siteminderagent/pwservlet/PSWDChangeServlet" name="<instance_name>" Insert the entry into the following block: <Object name="default"> AuthTrans fn="SiteMinderAgent" NameTrans fn="assign-name" from="/servlet/*" name="<instance_name>" NameTrans fn="assign-name" from="/siteminderagent/pwservlet/PSWDChangeServlet" name="<instance_name>" --------</Object> 13. Restart the Sun Java System Web server and start ServletExec.
10. Change to your home directory (the current directory has been deleted). 11. Restart the Web server(s).
Note: For Sun Java System Web servers, the obj.conf, magnus.conf, and mime.types files are restored to its original settings prior to the Web Agent installation.
To reinstall the documentation, run the appropriate documentation program for the product.
6.
Select the placement of the Agent Configuration Wizard shortcut in the Choose Shortcut Folder dialog box then click Next. Note: To allow all users access to the Configuration Wizard via the shortcut, ensure the Create Icons for All Users check box is checked. Otherwise, deselect this option. The upgrade program locates the existing Web Agent and displays the Confirm Upgrade dialog box.
7.
In the Confirm Upgrade dialog box, select one of the following then click Next: Continue with the upgradeupgrades the Web Agent to 6.x. Abort the upgradeexits the upgrade procedure without upgrading the Web Agent.
8.
In the Pre-installation Summary dialog box, confirm that the installation settings are correct, and then click Install. The new Web Agent files are copied to the specified location. Note: The installation program may detect that newer versions of certain system dlls are installed on your system. It asks if you want to overwrite these newer files with older files. Select No To All if you see this message.
9.
In the Install Complete dialog box, choose whether to restart your system immediately or later, and then click Done.
More Information Register Your System as a Trusted Host on UNIX (see page 59)
To allow all users access to the Configuration Wizard via the shortcut, ensure the Create Icons for All Users check box is checked. Otherwise, deselect this option. The upgrade program locates the existing Web Agent and displays the Confirm Upgrade dialog box. 8. In the Confirm Upgrade dialog box, select one of the following options, and then click Next: Continue with the upgradeupgrades the Web Agent to 6.x. Abort the upgradeexits the upgrade procedure without upgrading the Web Agent. 9. In the Pre-installation Summary dialog box, confirm that the installation settings are correct, then click Install. The new Web Agent files are copied to the specified location. Note: The installation program may detect that newer versions of certain system .dlls are installed on your system. It asks if you want to overwrite these newer files with older files. Select No To All, if you see this message. 10. In the Install Complete dialog box, choose whether to restart your system immediately or later. Then click Done.
10. In the Pre-installation Summary dialog box, confirm the installation settings, then click Install. The new Web Agent files are copied to the specified location. Note: The installation program may detect that newer versions of certain system dlls are installed on your system. It asks if you want to overwrite these newer files with older files. Select No To All if you see this message. Afterward, the Web Agent Configuration dialog box is displayed. 11. Choose one of the following options, then click Next: Yes. I would like to configure the Agent now. No. I will configure the Agent later. If you select Yes to configure the Agent, the Web Agent Configuration Wizard starts up and does one of the following: If you have not registered your system as a trusted host, the Wizard prompts you to register. If your system is already registered as a trusted host, the Wizard prompts you to configure the Web Agent. Note: If you are installing an Agent on an Sun Java System Web server, you may see an error message stating that the httpd.exe service is unable to locate the smconapi.dll. If this message appears, reboot your system before launching the Web Agent Configuration Wizard. 12. When the Configuration Complete dialog box is displayed, click Done. 13. In the Install Complete dialog box, choose whether to reboot your system immediately or later, then click Done. More Information Register Your System as a Trusted Host on UNIX (see page 59) Configure an IIS Web Agent (see page 73) Configure a Sun Java System Web Agent (see page 79) Configure an Apache Web Agent (see page 89) Configure a Domino Web Agent (see page 101)
chmod +x nete-wa-6qmr5-sol.bin 6. Open a console window and from the location of the installation program enter: ./nete-wa-6qmr5-<operating_system>.bin. where <operating_system> is sol, aix, linux, hp, or hp-itan The installation program prepares the files. 7. 8. 9. In the Introduction dialog box, read the information. Then click Next. Read the License Agreement. Then select the radio button to accept the agreement. Click Next. Read the notes in the Important Information dialog box. Then click Next.
10. Specify the installation directory in the Choose Install Folder dialog box, and then click Next. The Confirm Upgrade dialog box displays. 11. In the Confirm Upgrade dialog box, select one of the following then click Next: Continue with the upgradeUpgrades the Web Agent to 6.x. Abort the installationExits the upgrade procedure without upgrading the Web Agent. 12. In the Pre-installation Summary dialog box, confirm that the installation settings are correct, then click Install. The new Web Agent files are copied to the specified location. 13. In the Install Complete dialog box, click Done. 14. After installing the Agent, run the Agent Configuration Wizard to register a trusted host and configure the Web Agent. More Information Configure a Web Agent (see page 73) Register Your System as a Trusted Host on UNIX (see page 59)
./nete-wa-6qmr5-<operating_system>.bin where <operating_system> is sol, aix, linux, rhel30, SuSE-zLinux, hp, or hp-itan 7. 8. 9. In the Introduction dialog box, read the information. Then click Next. Read the License Agreement then select the radio button to accept the agreement. Click Next. Read the notes in the Important Information dialog box. Then click Next. The Confirm Upgrade dialog box is displayed. 10. In the Confirm Upgrade dialog box, select one of the following, and then click Next: Continue with the upgradeupgrades the Web Agent to 6.x. Abort the installationexits the upgrade procedure without upgrading the Web Agent. 11. In the Pre-installation Summary dialog box, confirm that the installation settings are correct, then click Install. The new Web Agent files are copied to the specified location. 12. In the Install Complete dialog box, click Done. If the system with the 5.x Web Agent being upgraded has not previously been registered as a trusted host, you need to register at the system at some point. More Information Register Your System as a Trusted Host on UNIX (see page 59)
where <operating_system> is sol, aix, linux, rhel30, SuSE-zLinux, hp, or hp-itan 7. 8. 9. In the Introduction dialog box, read the information then click Next. Read the License Agreement then select the radio button to accept the agreement. Click Next. Read the notes in the Important Information dialog box, and then click Next. The Confirm Upgrade dialog box is displayed. 10. In the Confirm Upgrade dialog box, select one of the following, and then click Next: Continue with the upgradeupgrades the Web Agent to 6.x. Abort the installationexits the upgrade procedure without upgrading the Web Agent. 11. In the Pre-installation Summary dialog box, confirm that the installation settings are correct, then click Install. The new Web Agent files are copied to the specified location. 12. In the Install Complete dialog box, click Done. If the system with the 5.x Web Agent being upgraded has not previously been registered as a trusted host, you need to register at the system at some point. More Information Register Your System as a Trusted Host on UNIX (see page 59)
Chapter 7: Troubleshooting
This section contains the following topics: Agent Start-Up/Shutdown Issues (Framework Agents Only) (see page 143) Web Agent Start Up and Shut Down Issues (IBM HTTP Server) (see page 144) Connectivity and Trusted Host Registration Issues (see page 146) General Installation Issues (see page 147) Cryptographic Hardware Issues (see page 147) Uninstallation Issues (see page 148) Online Documentation Issues (see page 148) Upgrade Issues (Windows and UNIX) (see page 149) IIS Web Agent Issues (see page 149) Sun Java System Web Agent Issues (see page 149) Apache Web Agent Issues (see page 150) Domino Web Agent Issues (see page 151)
Troubleshooting 143
Web Agent Start Up and Shut Down Issues (IBM HTTP Server)
Web Agent Start Up and Shut Down Issues (IBM HTTP Server)
If the Web Agent does not start after installation or you cannot shut it down, check the following error logs: On Windows, check the Event Viewers Application Log. On UNIX, messages are processed by the servers standard error handling.
Web Agent Start Up and Shut Down Issues (IBM HTTP Server)
Troubleshooting 145
More Information Install the Web Agent on a UNIX System (see page 51)
More Information Fix the ServletExec CLASSPATH for DMS (see page 47)
More Information Add a SiteMinder Agent User to nCipher UNIX Group (UNIX Only) (see page 21)
Troubleshooting 147
Uninstallation Issues
Uninstallation Issues
If... You cannot uninstall the Web Agent from the Add/Remove Programs list control panel because the SiteMinder Web Agent is not listed. Then... Remove the Agent as follows: 1. Open the registry editor. 2. Go to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Curr entVersion\Uninstall\SiteMinder\WebAgent 3. Highlight the entire UninstallString entry and copy it. 4. Open a DOS window and paste the UninstallString into the window at a DOS prompt. 5. Press ENTER. The Agent is uninstalled.
Then... If the Acrobat Reader installation program hangs while the Policy Server is running, stop the server using the Policy Server Management Console, then the installation program should start.
Troubleshooting 149
If... Web Agent configuration changes are not in the obj.conf file. The Web Agent cannot operate. Sun Java System Web server is failing at run time.
Then... You used the Sun Java System Administration console to make server modifications before you applied the changes made by the Agent configuration to the obj.conf. Re-configure the Web Agent. Increase the StackSize setting in the Sun Java System servers magnus.conf file to a value of 256 KB. The magnus.conf file is located in: <Sun_Java_System_home>/<web_server_instance> / config More Information Tune the Shared Memory Segments (Apache and Sun Java System) (see page 112)
If...
Then...
More Information Tune the Shared Memory Segments (Apache and Sun Java System) (see page 112)
More Information Add the Domino Web Agent DLL (Windows) (see page 104)
Troubleshooting 151
nete-wa-installer.properties File
nete-wa-installer.properties File
The nete-wa-installer.properties file is generated during a Web Agent installation and configuration. It contains all of the parameters, paths, and passwords entered during the installation and configuration. During an unattended installation and configuration, this properties file provides the settings that would be entered by an end-user in a GUI or Console mode installation. Be default, the nete-wa-installer.properties file contains the settings from the initial installation. You can use the default properties file to run installations with the same settings or use the file as a template that you modify to suite your environment. An unattended installation uses a properties file that is initially configured with values from the initial GUI or console mode Web Agent installation. Therefore, you can only run an unattended installation on a system with the same platform and web server image as the system where you first installed the Web Agent. For example, you cannot install an Agent on a Solaris system with an Sun Java System Web server, then use the properties file to run an unattended installation on a Linux system with an Apache Web server. The following is a sample of the nete-wa-installer.properties file.
################################################################## ## nete-wa-installer.properties ## Properties file for the SiteMinder Web Agent ## unattended installation and configuration ## ## This file is generated by an initial Web Agent installation ## and configuration performed in GUI or Console mode. ## ## ## ## ## ##
################################################################ # General Information ################################################################ # Specifies the information used for the unattended installation. USER_INSTALL_DIR=C:\\Program Files\\Netegrity\\webagent USER_SHORTCUTS=C:\\Documents and Settings\\jdoe\\Start Menu\\Programs ################################################################ # 1. Trusted Host Registration ################################################################ # A trusted host is a client computer where one or more Agents # can be installed. To establish a connection between the # trusted host and the Policy Server, register the host with # the Policy Server.
nete-wa-installer.properties File
# Register the trusted host only once, not each time you install # and configure a Web Agent. # Set to 1 to register this host as a trusted host. HOST_REGISTRATION_YES=1 ################################################################ # 1.1 Administrator For Trusted Host Registration ################################################################ # Enter the name and password of an administrator who has the # right to register a trusted host with the Policy Server. # This entry must match the name of an administrator defined # at the Policy Server. ADMIN_REG_NAME=siteminder ADMIN_REG_PASSWORD=ENC:nGDaSDy1H7qZqcdbkJKPEQ== # Set to 1 to enable shared secret rollover SHARED_SECRET_ROLLOVER_YES=0 ################################################################ # 1.2 Cryptographic Hardware Configuration (optional) ################################################################ # This section only applies if you registered a trusted host. # # NOTE: These are only used if CRYPTO_CONFIG_YES = 1. # # # Select a path and file name of PKCS11, then enter the token label and pass phrase. The token label can be blank. The passphrase cannot be blank.
# Set to 1 to enable PKCS11 Cryptographic Hardware. CRYPTO_CONFIG_YES=$CRYPTO_CONFIG_YES$ # The location and file name of the PKCS11 library. PKCS11_FILENAME= # The token label for PKCS11 TOKEN_LABEL= # The token passphrase TOKEN_PASS_PHRASE= ################################################################ # 1.3 Trusted Host Name and Host Configuration Object ################################################################ # Specify the name of the host you want to register with the # Policy Server.
nete-wa-installer.properties File
# Enter the name of the host configuration object. # The name must match a host configuration object name # already defined at the Policy Server. TRUSTED_HOST_NAME=mytrustedhost CONFIG_OBJ=MyHostSettings ################################################################ # 1.4 List of Policy Servers IP Addresses ################################################################ # Enter the IP Address of the Policy Server where you are # registering this host. # # Specify the IP address in the form of <IP_address:port> # To list multiple addresses, enter <IP_address:port>, # <IP_address:port> # For example: 111.112.1.45, 122.113.1.47:45 IP_ADDRESS_STRING=111.11.1.111 ################################################################ # 1.5 Host Configuration File Location ################################################################ # Enter a name and location for the Host Configuration File, # SmHost.conf. SM_HOST_FILENAME=SmHost.conf SM_HOST_DIR=C:\\Program Files\\Netegrity\\webagent\\config ############################################################### # 2. Web Server Selection ############################################################### #The following entries are for UNIX systems only: APACHE_SELECTED= APACHE_WEBSERVER_ROOT= DOMINO_SELECTED= DOMINO_WEBSERVER_ROOT= IPLANET_SELECTED= IPLANET_WEBSERVER_ROOT= # NOTE: Do not edit the following WEB_SERVER_INFO entry. To modify # # it, re-run the Web Agent configuration to regenerate this string with the appropriate values.
WEB_SERVER_INFO=;https-host1,C:\\iPlanet\\Servers\\https-host1\\config,httpshost1 (Netscape ES 6.0),https-host1,iplanet,6.0,C:\\iPlanet\\Servers\\httpshost1,Windows,+EMPTYSTR+,1,1,1,0,0,1, No advanced authentication,iPlanetDefaultSettings,0,undefined, ENC:6f1I5TLVEpuSBHpf4GrASg==, ################################################################ # 3. Restart Web Server Option (Windows only) ################################################################ # Set to YES to allow the installation program to reboot the # Windows machine, if required. USER_REQUESTED_RESTART=
Parameter USER_INSTALL_DIR
Description and Sample Value The location where the unattended installation will place the Web Agent. For example: C:\\Program Files\\netegrity\\webagent
USER_SHORTCUTS
The location where the installation places a shortcut to the Configuration Wizard. For example: C:\\Documents and Settings\\jdoe\\Start Menu\\Programs
Parameter
HOST_REGISTRATION_Y Indicates whether the installation will go through ES the trusted host registration process. For example, HOST_REGISTRATION_YES=1
Parameter ADMIN_REG_NAME
Description and Sample Value Name of the administrator with the rights to register a trusted host. For example, ADMIN_REG_NAME=siteminder
ADMIN_REG_PASSWOR D
Password for the administrator with the rights to register a trusted host. This value is encrypted by the installation program. For example, ADMIN_REG_PASSWORD=ENC:nGDaSDy1H7qZqcd bkJKPEQ To change the password, you can either reconfigure the Agent or modify this parameter by entering a new password in clear text.
SHARED_SECRET_ROLL OVER_YES
Enables shared secret rollover, which periodically changes the secret that encrypts communication between the trusted host and the Policy Server. The default is 0. Set this parameter to 1 to enable shared secret rollover. For example, SHARED_SECRET_ROLLOVER_YES=1
Parameter CRYPTO_CONFIG_YES
Description and Sample Value Indicates whether cryptographic hardware will be configured. Set to 1 to enable. The default is 0. For example: CRYPTO_CONFIG_YES=1
PKCS11_FILENAME
Full path, including the file name, to the PKCS11 DLL. This DLL is installed with the nCipher software on the server where the Web Agent is installed. For example: PKCS11_FILENAME=/opt/nfast/swspro/lib/libcknfas t.so
TOKEN_LABEL
Parameter TOKEN_PASS_PHRASE
Description and Sample Value Specifies the passphrase for the token. For example: TOKEN_PASS_PHRASE=cardpassword
Parameter IP_ADDRESS_STRING
Description and Sample Value Specifies the IP address of the Policy Server where you are registering the trusted host. To have multiple bootstrap servers for failover. you can specify multiple addresses, separated by a comma. For example, IP_ADDRESS_STRING=111.11.1.11, 122.123.2.34
Parameter SM_HOST_FILENAME
Description and Sample Value Names the Host Configuration File, SmHost.conf. For example, SM_HOST_FILENAME=SmHost.conf
SM_HOST_DIR
Identifies the directory where the SmHost.conf file is installed. The default For example, SM_HOST_DIR=C:\\Program Files\\Netegrity\\webagent\\config
Parameter APACHE_SELECTED
Indicates which Apache Web server you are configuring and that servers root directory. For APACHE_WEBSERVER_ROOT example, for UNIX Systems: APACHE_SELECTED=0 APACHE_WEBSERVER_ROOT=/export/apache IPLANET_SELECTED For UNIX Systems. Indicates which Sun Java System Web server you are configuring and that servers root IPLANET_WEBSERVER_ROOT directory. For example, for UNIX Systems: IPLANET_SELECTED=0 IPLANET_WEBSERVER_ROOT=C:\\iPlanet\\ servers DOMINO_SELECTED DOMINO_WEBSERVER_ROO T For UNIX Systems. Indicates which Apache Web server you are configuring and that servers root directory. For example, for UNIX Systems: DOMINO_SELECTED=1 DOMINO_WEBSERVER_ROOT=/usr/lotus
Parameter WEB_SERVER_INFO
Description and Sample Value The WEB_SERVER_INFO setting contains information about the Web servers configured with a SiteMinder Web Agent. You can either edit this setting in the file or re-run the Web Agent configuration to regenerate this string with the appropriate values. The WEB_SERVER_INFO entry consists of a set of Web servers, separated by a semicolon. Each web server consists of comma-separated values. Important! The WEB_SERVER_INFO setting can be modified from one Web server to another, even for the same machine, but modify the setting at your own risk. Making a mistake when changing a value could cause the Agent installer to fail or the Agent to be configured with inappropriate data. The WEB_SERVER_INFO setting is as follows: WEB_SERVER_INFO=;<server_instance>,<web_serv er_config_dir>,<web_server_listing>,<service_name >,<web_server_type>,<web_server_version>,<web_ server_path>,<empty_string>,<empty_string>,<sele cted_web_server>,<existing_server_config>,<preser ve_web_server>,<document_selection>,<OneView_ Monitor_config>,<confirm_web_server_config>,<adv anced_auth_scheme>,<agent_config_obj>,<self_regi stration>,<DMS_admin_username>,<DMS_admin_pa ssword>
WEB_SERVER_INFO Variables
The values of each variable are listed in the table in the following table:
Variable <server_instance>
Variable
Meaning
<web_server_config_dir Path to the Web servers config directory. > Example: /usr/iplanet/servers/https-server1/config <web_server_listing> During the Agent configuration, this entry reflects how the Web server is shown in the list of available Web servers to configure. Example: https-server1 (Sun Java System 6.0) <service_name> Web server service name Example: https-server1 <web_server_type> Type can be: apache, domino, IIS, iplanet, sunone Note: For the Sun Java System web server, use iplanet or sunone. Example: sunone <web_server_version> Web server version Example: 6.0 <web_server_path> Path to the web_server_instance root Example: /usr/iplanet/servers/https-server1 <empty_string> Empty string for future use. Example: +EMPTYSTR+ <empty_string> Empty string for future use. Example: +EMPTYSTR+ <selected_web_server> Indicates whether the selected Web server should be configured with an Agent. Enter: 1=yes or 0=no <existing_server_config > Previous Web server configuration states whether there is an existing Agent configuration Enter: 1=yes 0=no <preserve_web_server> Indicates whether the specified Web servers configuration with a Web Agent should be overwritten with a new configuration or preserved. Enter: 1=preserve 0=overwrite
Variable <document_selection>
Meaning For Policy Server only. Entry is ignored by Web Agent. Accept the default. Valid entry: 1=yes or 0=no
<OneView_Monitor_conf For Policy Server only. Entry is ignored by the Web ig> Agent. Accept the default. Valid entry: 1=yes or 0=no <confirm_web_server_c onfig> Confirm that the selected Web server should be configured with an Agent. Enter: 1=yes or 0=no <advanced_auth_schem Specifies the advanced authentication scheme, if e> any, being used. Choose one of the following options: HTTP Basic over SSL X509 Client Certificate X509 Client Certificate and HTTP Basic X509 Client Certificate or HTTP Basic X509 Client Certificate or Form X509 Client Certificate and Form No advanced authentication <agent_config_object> Indicates which Agent Configuration Object to use. Example: iplanetdefaultsettings <self_registration> Enables self Registration. Enter: 1=yes or 0=no <DMS_admin_name> DMS Administrators name. Example: Admin1 <DMS_admin_password > DMS Administrators password. Example: ENC:6f1I5TLVEpuSBHpf4GrASg
Any of these values can be changed except for DMS Admin password. Password can be reused by copying the value from one properties file to another. The only way to change the DMS Admin password is to re-run the Agent configuration. The encryption and decryption will always encrypt and decrypt in the same manner. Sample Entry:
WEB_SERVER_INFO=;https-server1,/usr/iplanet/servers/https-server1/config,httpsserver1 (iPlanet 6.0),https-server1,iplanet,6.0,/usr/iplanet/servers/httpshost,+EMPTYSTR+,+EMPTYSTR+,1,0,1,0,0,1,HTTP Basic over SSL,agent1,0,undefined,ENC:6f1I5TLVEpuSBHpf4GrASg==,;httpshost2,/usr/iplanet/servers/https-host2/config,https-host2 (Netscape ES 6.0),https-host2,iplanet,6.0,/usr/iplanet/servers/httpsiplanetdefaultsettings,+EMPTYSTR+,+EMPTYSTR+,1,0,0,0,1,No advanced authentication,host2,0,undefined,ENC:6f1I5TLVEpuSBHpf4GrASg==
Parameter
USER_REQUESTED_RESTA Allows the installation program to reboot the RT Windows machine, if required after the configuration process. Set to Yes to allow a reboot. Otherwise, set to No.
Parameter TRUSTED_HOST_NAME
Description and Sample Value Names the trusted host. This name must be unique. For example: TRUSTED_HOST_NAME=mytrustedhost
Parameter CONFIG_OBJ
Description and Sample Value Identifies the Host Configuration Object, which defines communication between the trusted host and Policy Server. For example: CONFIG_OBJ=MyHostSettings
These lines instruct the Web server to load the SiteMinder Web Agent with three NSAPI functions: SmInitAgent, SiteMinderAgent, and SmRequireAuth.
The following provides more information about each line: The line that reads AuthTrans fn="SiteMinderAgent" is added to the default object (<Object name="default">). It sets up the SiteMinder Web Agent as the Authorization method, or AuthTrans function, for the Web server. The lines that read NameTrans fn="assign-name" from="*.jsp*" name="myservletengine" and NameTrans fn="assign-name" from="/servlet/*" name="myservletengine"create mappings for the Agent to support SiteMinders Password Services. The line that reads NameTrans fn="assign-name" from= "/siteminderagent/pwservlet/*" name="myservletengine" is a filter added by the Web Agent that maps the JSP Password Services servlet to the instance of the servlet engine so that engine can process it. Most of the lines that begin NameTrans fn="pfx2dir" add virtual directories and mappings for the Agent to support SiteMinders Password Services (CGI and JSP versions). The line that begins NameTrans fn="pfx2dir" from="/siteminderagent/certoptional" is added if you chose to configure a certificate based authentication scheme.
The lines that read PathCheck fn="SmRequireAuth" is added to any existing PathCheck lines in the default object. It verifies that the user is authorized to perform the requested action on the requested resource. The line that reads PathCheck fn="get-client-cert" dorequest="1" is added if, during configuration, you indicated that the Web Agent would support advanced authentication schemes. It supports the use of certificate, certificate plus basic, and certificate and forms authentication schemes. The line that reads PathCheck fn="get-client-cert" require="0" dorequest="1" is added if, during configuration, you indicated that the Web Agent would support advanced authentication schemes. It supports the use of certificate or basic and certificate or forms authentication schemes. Note: Both PathCheck lines for advanced authentication should be commented out for "Basic Auth over SSL." The lines that begin Service method are added to instruct the Web server what to do with the MIME types.
These lines set up the mime types to support advanced SiteMinder features.
These lines instruct the Web server to load the SiteMinder Web Agent with four NSAPI functions: SmInitAgent, SmInitChild, SiteMinderAgent, and SmRequireAuth.
The following provides more information about each line: The line that reads AuthTrans fn="SiteMinderAgent" is added to the default object (<Object name="default">). It sets up the SiteMinder Web Agent as the Authorization method, or AuthTrans function, for the Web server. The line that reads NameTrans fn="assign-name" from= "/siteminderagent/pwservlet/*" name="myservletengine" is a filter added by the Web Agent that maps the JSP Password Services servlet to the instance of the servlet engine so that engine can process it. Most of the lines that begin NameTrans fn="pfx2dir" add virtual directories and mappings for the Agent to support SiteMinders Password Services (CGI and JSP versions). The line that begins NameTrans fn="pfx2dir" from="/siteminderagent/certoptional" is added if you chose to configure a certificate based authentication scheme. The line that reads PathCheck fn="SmRequireAuth" is added to any existing PathCheck lines in the default object. It verifies that the user is authorized to perform the requested action on the requested resource. The line that reads PathCheck fn="get-client-cert" dorequest="1" is added if, during configuration, you indicated that the Web Agent would support advanced authentication schemes. It supports the use of certificate, certificate plus basic, and certificate and forms authentication schemes. The line that reads PathCheck fn="get-client-cert" require="0" dorequest="1" is added if, during configuration you indicated during installation that the Web Agent would support advanced authentication schemes. It supports the use of certificate or basic or the certificate or forms authentication schemes. Note: Both PathCheck lines for advanced authentication should be commented out for "Basic Auth over SSL." The lines that begin Service method are added to instruct the Web server what to do with the MIME types.
These lines set up the mime types to support advanced SiteMinder features.
Library Path for the Web Server is Set for UNIX Systems
The library path for the Apache Web server is required because it enables the Apache server to load libraries correctly on a UNIX system. For example: export LD_LIBRARY_PATH <web_agent_home>/bin The library path variable depends on the operating systemit should always point to <web_agent_home>/bin. The following table lists the variables.
Set Library Path and Path for Oracle 10g Web Server Running in Apache 2.x Mode
The entries are as follows: Oracle HTTP Server 9.0.2 on Solaris and Linux: if [ -z "$LD_LIBRARY_PATH" ] then LD_LIBRARY_PATH=<OHS_home>/libexec:<web_agent_home>/bin; export LD_LIBRARY_PATH else LD_LIBRARY_PATH=<OHS_home>/libexec:${LD_LIBRARY_PATH}; export LD_LIBRARY_PATH Oracle HTTP Server 9.0.2 on HP-UX: if [ -z "$SHLIB_PATH" ] then SHLIB_PATH=/<OHS_home>/libexec:<web_agent_home>/bin; export SHLIB_PATH else SHLIB_PATH=<OHS_home>/libexec:${SHLIB_PATH}; export SHLIB_PATH
Set Library Path and Path for Oracle 10g Web Server Running in Apache 2.x Mode
For an Oracle 10g Web server running in Apache 2.x mode, both the LD_LIBRARY_PATH and PATH variables need to be set in the apachectl script. LD_LIBRARY_PATH is automatically added to the apachectl script, which is located in the directory <OHS_home>/Apache/Apache/bin/. Add the following entry for PATH in the apachectl script: PATH=<Path of webagent install>/bin:${PATH} ; export PATH
mod_smcertenv enables certificate-based authentication to work with Apache Web servers without requests being redirected to the SSL credential collector. Note: This module is only for Apache 1.3.27 Web servers. It is not supported for proprietary versions of the Apache 1.3.x Web server, such as Stronghold, IBM HTTP Server, or Oracle HTTP Server. The entry to load mod_smcertenv must come after the entry to load mod_sm. Note: HP-UX uses the extension .sl to refer to a shared library. If the operating system for the Web Agent is HP-UX, the .sl extension is used.
Password Services
Alias /siteminderagent/pwcgi/ <web_agent_home>/pw/ <Directory "/export/webagent/pw/"> Options Indexes MultiViews ExecCGI AllowOverride None Order allow,deny Allow from all </Directory> Alias /siteminderagent/pw/ <web_agent_home>/pw/ <Directory "/export/webagent/pw/"> Options Indexes MultiViews ExecCGI AllowOverride None Order allow,deny Allow from all </Directory>
Note: This is the alias that should be placed at the end of the section.
SiteMinder Feature Password Services Forms authentication Certificate and Forms authentication Certificate or forms authentication SSL authentication, including: Basic over SSL Certificate Certificate or basic Certificate and basic Cookie provider for single sign-on
The modified section would appear as follows: AddHandler cgi-script .exe AddHandler smformsauth-handler .fcc AddHandler smsslformsauth-handler .sfcc AddHandler smadvancedauth-handler .scc AddHandler smcookieprovider-handler .ccc
Agent Parameter Added for SSL Connections Using Apache 1.x Based Servers
Agent Parameter Added for SSL Connections Using Apache 1.x Based Servers
If you are using SSL connections (HTTPS) to an Apache 1.x based server, the httpsports parameter is added to the WebAgent.conf file or the Agent Configuration Object configured at the Policy Server. This parameter specifies one or more (comma-separated) HTTPS port numbers the Web server is listening on. For example, set httpsports to 80. Note: If a server is behind an HTTPS accelerator, which converts HTTPS to HTTP, all requests are treated as SSL connections by your browser.
Index
A
Add a Logs Subdirectory for Apache Web Agents 19 Add a SiteMinder Agent User to nCipher UNIX Group (UNIX Only) 21 Add Entries to the httpd.conf File to Improve Server Performance 96 Add Password Services JAR files to the Servlet Engine Classpath 117 Add Settings to the Sun Java System Server 6.0 167 Add the Domino Web Agent DLL (UNIX) 108 Add the Domino Web Agent DLL (Windows) 104 Added or Modified Environment Variables 185 AddHandler Entries Added for Agents v5.x QMR 6 182 Agent Configuration Object definition 12 Domino requirements 12 IIS requirements 12 installation requirement 12 Agent Parameter Added for SSL Connections Using Apache 1.x Based Servers 183 Agent Start-Up/Shutdown Issues (Framework Agents Only) 143 Alias Entries Added 180 Allow IIS to Execute Web Agent ISAPI and CGI Extensions 75 Allow Unattended Failover for nCipher Cryptographic Modules 120 Apache Web Agent as reverse proxy server 101 Configuration Wizard, accessing 35, 77, 81, 89, 105 configuring 89, 93 configuring, console mode 93 configuring, GUI mode 93 for IBM HTTP Web server 92 for Stronghold server 92 http.conf, modifying 101 increasing shared memory 112 installing 51 LD_PRELOAD, setting 97 modifying httpd.conf 177 reinstalling 59 supported platforms 11 tuning shared memory 112 uninstalling, UNIX 124 Apache Web Agent Issues 150 Apache Web server installing as service 14 installing on windows, caution 14 Apply Changes to Sun Java System Web Server Files 88 Assign Read Permissions to Samples and Error Files Directories 74 authentication schemes HTTP Basic over SSL 81, 85 SSL, configuring 81, 85 using forms authentication 115 X.509 client certificate and basic 81, 85 X.509 client certificate and HTML Forms 81, 85 X.509 client certificate or basic 81, 85 X.509 client certificate or HTML Forms 81, 85 X509 Client Certificate 81, 85
B
Back Up Customized Files 127 boostrap servers, configuring 35, 39, 60, 63
C
CA Product References iii Certificate Authentication Entries Added 183 Changes to the httpd.conf File 177 Check Agent Start-up with LLAWP 171 Check SmHost.conf File Permissions for Shared Secret Rollover 111 Code Added to the magnus.conf File on UNIX Platforms 172 Code Added to the magnus.conf File on Windows Platforms 168 Code Added to the mime.types File on UNIX Platforms 173 Code Added to the mime.types File on Windows Platforms 170 Code Added to the obj.conf File on UNIX Platforms 172
Index 187
Code Added to the obj.conf File on Windows Platforms 169 Collect nCipher Information 21 Compile an Apache Web Server on a Linux System 20 configuration unattended mode, Windows 108 Configuration Changes to Web Servers with Apache Web Agent 175 Configuration Notes for Web Agents on IIS 6.0 Servers 75 Configure a Domino Web Agent 102 Configure a Domino Web Agent on Windows Systems 102 Configure a Sun Java System Web Agent 80 Configure a Web Agent 73 Configure an Apache Web Agent 89 Configure an Apache Web Agent on UNIX Systems 92 Configure an Apache Web Agent on Windows Systems 89 Configure an Apache Web Agent Using GUI or Console Mode 93 Configure an IIS Web Agent 73 Configure Any Web Agent in Unattended Mode 108 Configure Apache for Oracle 9.0.2/9.0.3 HTTP Server 100 Configure Domino Web Agents in GUI or Console Mode 105 Configure Domino Web Agents on UNIX Systems 105 Configure ServletExec 5.0 for JSP Password Services for an IIS Web Server 107 Configure ServletExec for JSP Password Services for a UNIX Sun Java System Web Server 118 Configure Sun Java System Web Agents on UNIX Systems 84 Configure Sun Java System Web Agents on Windows Systems 81 Configure Sun Java System Web Agents Using GUI or Console Mode 85 Configure the Web Server to Restart (Windows Only) 164 Connectivity and Trusted Host Registration Issues 146 console mode configuring Domino 105
Contact Technical Support iii Cookie Provider Redirection Differences Between 4.x and 6.x Agents 129 cryptographic hardware settings, unattended installation 158 unattended failover 120 Cryptographic Hardware Issues 147
D
Decide Whether to Implement Cryptographic Hardware 21 DLLs adding, Domino Web Agent 104 DMS Admin account, modifying password 26 dms.properties 26 dmsencrytpkey modifying DMSAdmin password 26 documentation installing, UNIX 50 uninstalling UNIX 126 uninstalling on a UNIX system 126 uninstalling on a Windows system 125 Domino Web Agent configuring/Windows 102 Domino Web Agent adding DLLs 104 Configuration Wizard, accessing 102 configuring, UNIX 105 installing, UNIX 51 reconfiguring, Windows 111 reinstalling, UNIX 59 uninstalling, UNIX 124 upgrading 4.x Agents, UNIX 136 upgrading 4.x Agents, Windows 134 upgrading 5.x Agents, UNIX 138 upgrading 5.x Agents, Windows 130 upgrading 6.x Agents, UNIX 140 upgrading 6.x Agents, Windows 132 Domino Web Agent Issues 151
E
Enable Cryptographic Hardware Configuration 158 Enable Write Permissions for IBM HTTP Server Logs 19 Enabling SHLIB Path for an Agent on Apache 2.0/HP-UX 11 99
Ensure LD_PRELOAD Variable Does Not Conflict with Existing Agent 128 Ensure the Policy Server is Installed and Configured 12 Entries Added to DSO Support Section 177 Environment Variables Added or Modified by the Web Agent Installation 185
F
Fix Display Errors on Sun Java System with Cryptographic Hardware 22 Fix the ServletExec CLASSPATH for DMS 47 forms authentication scheme credential collection 115
G
Gather information Needed to Complete the Agent Installation 13 general information settings, unattended installation 157 General Installation Issues 147 GUI mode installation 52
H
hardware encryption using, Windows 20 Host Configuration File modifying, Windows 39, 63 purpose 39, 59, 63 settings, unattended installation 159 Host Configuration Object definition 12 installation requirement 12 HP-UX uninstalling, Sun Java System Web Agent 124 HTTP Basic over SSL authentication scheme 81, 85 httpd.conf modifying for Apache 177
I
IBM Hot Fix Required for Domino 6.5.2 18 IBM Hot Fixes for Domino 6.0.2 CF1 and CF2 18 IBM HTTP Server Agent configuration 92 installing Agent 14, 51 upgrading 4.x Agents, UNIX 136
upgrading 4.x Agents, Windows 134 upgrading 5.x Agents, UNIX 138 upgrading 5.x Agents, Windows 130 upgrading 6.x Agents, Windows 132 upgrading Agents, UNIX 140 Identify Policy Servers for Trusted Host Registration 159 IIS 6.0 Web Agent Operating with Third-Party Software on the Same Server 76 IIS Web Agent configuring 77 IIS 6.0, prerequisites 73 reconfiguring 111 reinstalling 35 IIS Web Agent Issues 149 Install a Servlet Engine for Registration Services (Optional) 24 Install a Web Agent on a UNIX System 49 Install a Web Agent on a Windows System 29 Install an Apache Web Server on Windows as a Service for All Users 14 Install IBM Hot Fixes for Domino Web Servers 17 Install nCipher on an Agent Web Server 21 Install the Correct Agent for a Web Server 14 Install the Web Agent Documentation on UNIX Systems 50 Install the Web Agent on a UNIX System 51 Install the Web Agent on Windows Systems 29 Install UNIX Patches 15 installer.properties file description 56 installer.properties, description 32, 109 installing documentation, UNIX 50 installing Web Agents Apache 51 Domino/UNIX 51 Domino/Windows 29 GUI mode, UNIX 52 IIS 29 on UNIX 51 Sun Java System/UNIX 51 Sun Java System/Windows 29
J
JSP Password Services adding JAR files, Windows 117 invoking password services servlet 117
Index 189
O
obj.conf modifications made by Agent 167 Online Documentation Issues 148 Oracle 9.x HTTP Server configuring 100 Oracle HTTP Server httpd.conf, modifying 100
K
Know the Results of Running the Configuration Wizard After Upgrades 128 Know Which Password Services and Forms Template are Upgraded 128
L
LD_PRELOAD setting, Apache/Linux 97 Library Path for the Web Server is Set for UNIX Systems 175 Linux compiling Apache server 20 LoadModule Entries Added 178
P
Password Services configuring JSP version, Windows 116 JSP servlet, modifying 117 JSP version 116 JSP-based JARs 117 Password Services and Forms Directories 23 PKCS11 cryptographic hardware using, Windows 20 Policy Server checking configuration 12 initial connection to Agent 35 initial connection with Agent 59 registering a trusted host, UNIX 59 registering a trusted host, Windows 35 settings, unattended installation 159 Prepare an Unattended Configuration 109 Prepare an Unattended Installation on UNIX 56 Prepare an Unattended Installation on Windows 32 Prepare for Cryptographic Hardware Support (Optional) 20 Prepare for the Installation 11 Prerequisites and Guidelines for Password Services 22 Prerequisites and Guidelines for Registration Services (Optional) 24 Prerequisites for Configuring the Web Agent on IIS 6.0 73 prerequisites for installation Web Agents, UNIX 11 Preserve Changes in the WebAgentTrace.conf File 22 properties files dms.properties 26 Put the Agent Filter and Extension Before Other Third-Party Filters 79
M
Manual Upgrade from 4.x QMR x Japanese Web Agents Required 129 mod_sm.c Entry Added to ClearModuleList 179 Modifications Made to Sun Java System/UNIX Platforms 171 Modifications Made to Sun Java System/Windows Platforms 168 Modify General Information 157 Modify the Apache 2.0 httpd.conf File for Agents on IBM HTTP Servers 19 Modify the DMS Admin Password for Registration Services 26 Modify the File to Invoke JSP Password Services Servlet 117 Modify the http.conf File for Apache Reverse Proxy Server 101 Modify the SmHost.Conf File (UNIX) 63 Modify the SmHost.Conf File (Windows) 39 multiple bootstap servers, configuring 35, 39, 60, 63
N
Name the Trusted Host Name and Host Configuration Object 164 nete-wa-installer.properties File 154 Netscape. See iPlanet Web Server 77, 81, 89 Notes About Uninstalling Web Agents 121 NT. See Windows 102
R
Reconfigure a Web Agent 111 reconfiguring Web Agent, Windows 111 Register a Trusted Host 157 Register a Trusted Host in GUI or Console Mode 60 Register Multiple Trusted Hosts on One System (UNIX) 70 Register Multiple Trusted Hosts on One System (Windows) 45 Register Your System as a Trusted Host on UNIX 59 Register Your System as a Trusted Host on Windows 35 registering a trusted host on UNIX platform 59 on Widows platform 35 registering trusted hosts administrator rights 12 registering multiple hosts 45, 70 Registration Services installed files 46 prerequisites 24 requirements for Web Agent 24 Registration Services Installed Files (UNIX) 71 Registration Services Installed Files (Windows) 46 Registration Tool reregisring trusted hosts. Windows 42 reregistering trusted hosts 42 using, UNIX 67 using, UNIX 67 using, Windows 42, 67 Reinstall a Web Agent on UNIX 59 Reinstall the Web Agent on Windows 35 re-installing Web Agents, UNIX 59 Web Agents, Windows 35 Repair ServletExecs CLASSPATH for JSP Password Services (Windows) 23 Replace Existing Read-only Files 128 Required AIX Patches 16 Required HP-UX Patches 16 Required Linux Libraries 17 Required Linux Patches 17 Required Solaris Patches 15
Re-register a Trusted Host Using the Registration Tool (UNIX) 67 Re-register a Trusted Host Using the Registration Tool (Windows) 42 reregistering trusted hosts 42, 67 using smreghost, UNIX 67 using smreghost, Windows 42, 67 reverse proxy server modifying http.conf 101 Review the Results of the Installation and Host Registration 38, 63 Review the Upgrade Procedure 127 Run a Console Mode Installation on UNIX 54 Run a GUI Mode Installation on UNIX 52 Run a GUI Mode Installation on Windows 30 Run an Unattended Configuration 110 Run an Unattended Installation on UNIX 55, 57 Run an Unattended Installation on Windows 32, 33 Run Registration Services with ServletExecAS (UNIX only) 27 Run the Configuration Wizard for an IIS Web Agent 77 Run the Configuration Wizard on Windows 81 Run the nete_wa_env.sh Script After Installation 58
S
Select a Web Server for Configuration 160 servlet engine required, Registration Services 24 ServletExec invoking PWS servlet 117 repairing classpath, DMS 23, 47 with registration services 27 Set JRE in PATH Variable Before Uninstalling the Web Agent 122 Set LD_PRELOAD for Using X.509-based Auth Schemes with Domino 6.5.3/SuSe8 Linux System 98 Set Library Path and Path for Oracle 10g Web Server Running in Apache 2.x Mode 176 Set the DISPLAY For Web Agent Installations on UNIX 18 Set the LD_ASSUME_KERNAL for 98 Set the LD_PRELOAD Variable for an Oracle 10G Web Server on Linux 97
Index 191
Set the LD_PRELOAD Variable for Apache Agent Operation 96 Set the LD_PRELOAD Variable for Apache Web Server on SUSE Linux 98 97 Set the LD_PRELOAD Variable for SSL Configuration on an IBM HTTP Server 2.0.47/Linux AS 3.0 System 98 Set Up Additional Agent Components 115 Set Up DNS on AIX Platforms for Agent Operation 20 Set Up the nete-wa-installer.properties File 153 Set Up Your Environment for JSP Password Services 116 Settings Added to the Sun Java System Server Configuration 167 shared memory segments, tuning 112 Shut Down LLAWP 144 SiteMinder Administrator for registering hosts 12 SmHost.conf creating, UNIX 59 creating, Windows 35 description 39, 63 modifying, Windows 39, 63 purpose 35, 59 SmHost.conf Settings That Should Not Be Modified (UNIX) 66 SmHost.conf Settings That Should Not Be Modified (Windows) 41 SmInitFile Entry Added 179 smreghost Registration Tool 42, 67 using, UNIX 67 using, Windows 42, 67 Specify the Host Configuration File 159 SSL authentication schemes, configuring 81, 85 Stop an Unattended Installation in Progress on UNIX 57 Stop an Unattended Installation in Progress on Windows 34 Stop LLAWP When Stopping IBM HTTP Server 2.0.47 145 Stronghold Web server Apache Web Agent, upgrading UNIX 136 installing an Agent 14, 51 upgrading 4.x Agents, Windows 134 upgrading 5.x Agents, Windows 130
using Apache Agent 92 Sun Java System Web Agent Configuration Wizard, accessing 81 configuring, Windows 81 increasing shared memory 112 reconfiguring, Windows 111 reinstalling, UNIX 59 reinstalling, Windows 35 tuning shared memory 112 uninstalling, UNIX 124 upgrading 4.x Agents, UNIX 136 upgrading 4.x Agents, Windows 134 upgrading 5.x Agents, UNIX 138 upgrading 5.x Agents, Windows 130 upgrading 6.x Agents, UNIX 140 upgrading 6.x Agents, Windows 132 Sun Java System Web Agent Issues 149 Sun Java System Web server changes to obj.conf 167 supported platforms UNIX 11
T
Troubleshoot Agent Start-Up/ShutDown with LLAWP 143 Troubleshooting 143 trusted host definition 12, 35, 59 registering multiple hosts 45, 70 registering, UNIX 59 registering, Windows 35 reregistering 42, 67 settings, unattended installation 157, 164 Tune the Shared Memory Segments (Apache and Sun Java System) 112
U
unattended configuration Windows 108 unattended failover, nCipher modules 120 unattended installation installer.properties file, description 56 installer.properties, description 32, 109 preparing 32, 56, 109 running, UNIX 57 running, Windows 33, 110 UNIX 55 Windows 32 Uninstall a Web Agent 121
Uninstall a Web Agent from a UNIX System 124 Uninstall a Web Agent from a Windows System 123 Uninstall Documentation from a Windows System 125 Uninstall Documentation from UNIX Systems 126 Uninstallation Issues 148 uninstalling documentation UNIX 126 uninstalling Web Agent documentation UNIX 126 Windows 125 UNIX platforms Agent, Stronghold server 92 configuring an Apache Web Agent 93 data needed to install Agent 13 GUI mode installation 52 installation prerequisites 11 installing an Agent 51 installing, Domino Web Agent 51 installing, Sun Java System Web Agent 51 reinstalling a Web Agent 59 Upgrade a 4.x Web Agent to 6.x on UNIX Systems 136 Upgrade a 4.x Web Agent to 6.x on Windows Systems 134 Upgrade a 5.x Web Agent to 6.x on UNIX Systems 138 Upgrade a 5.x Web Agent to 6.x on Windows Systems 130 Upgrade a 6.x Web Agent to 6.x QMR 5 on UNIX Systems 140 Upgrade a 6.x Web Agent to 6.x QMR 5 on Windows Systems 132 Upgrade a Web Agent to 6.x QMR 5 127 Upgrade Issues (Windows and UNIX) 149 Upgrade Tasks and Issues 127 upgrading 4.x QMR x Japanese Agents 129 4.x Web Agents, UNIX 136 4.x Web Agents, Windows 134 5.x Web Agents, UNIX 138 5.x Web Agents, Windows 130 6.x Web Agents, Windows 132, 140 back up custom files 127
cookie provider redirection differences 129 forms templates 128 general procedure 127 password services templates 128 pre-upgrade issues 127 replacing read-only files 128 running Configuration Wizard, results 128 setting LD_PRELOAD 128 Use a Supported Operating System 11 Use Active Directory for Registration Services (Windows Only) 25 Use Registration Services 24 Use SiteMinder Password Services 116 Use the IIS Default Web Site 15
W
Web Agent 4.x, upgrading 134 4.x, upgrading, UNIX 136 5.x, upgrading 130 5.x, upgrading 130 5.x, upgrading, UNIX 138 6.x, upgrading 132, 140 Apache, configuring 89, 93 Apache, configuring, console mode 93 Apache, configuring, GUI mode 93 Domino, configuring Console Mode, UNIX 105 Domino, configuring GUI Mode, UNIX 105 Domino/Windows, configuring 102 IBM HTTP server, configuring 92 IIS, configuring 77 installing, UNIX platforms 51 modifying httpd.conf, Apache 177 reconfiguring, Windows 111 reinstalling, UNIX 59 reinstalling, Windows 35 Sun Java System/Windows, configuring 81 supported UNIX platforms 11 uninstalling documentation, Windows 125 uninstalling, UNIX 124 Windows systems, configuring 134 Web Agent Configuration Wizard accessing, Apache Web Server 35, 77, 81, 89, 105 accessing, Domino Web Server 102 accessing, Sun Java System Web 81
Index 193
Web Agent on IIS 6.0 Has Size Limit for Uploading Files 76 Web Agent Start Up and Shut Down Issues (IBM HTTP Server) 144 web server configuration restarting Windows, unattended instal 164 settings, unattended installation 160 WEB_SERVER_INFO Variables 161 Windows configuring an IIS Web Agent 77 Domino Web Agent, configuring 102 installing, Domino Web Agent 29 installing, IIS Web Agent 29 installing, Sun Java System Web Agent 29 reinstalling a Web Agent 35 Sun Java System Web Agent Configuration Wizard, acc 81 uninstalling documentation 125 Windows platforms configuring an Apache Web Agent 89
X
X.509 client certificate and basic authentication schemes 81, 85 X.509 client certificate and HTML Forms authentication schemes 81, 85 X.509 client certificate or basic authentication schemes 81, 85 X.509 client certificate or HTML Forms authentication schemes 81, 85 X509 Client Certificate authentication scheme 81, 85