Chapter 6 Installing the OpenSSO Enterprise Utilities and Scripts

The Sun^TM OpenSSO Enterprise ZIP (opensso_enterprise_80.zip) file includes utilities, scripts, libraries, and other supporting files in the following ZIP files:

• ssoAdminTools.zip contains the files to run the OpenSSO Enterprise command-line utilities and scripts such as ssoadm, amtune, and ampassword.

  See Installing the OpenSSO Enterprise Utilities and Scripts in the ssoAdminTools.zip File.

• ssoSessionTools.zip contains the scripts and supporting files to install Sun Java System Message Queue and the Oracle Berkeley DB, which then allows you to configure multiple OpenSSO Enterprise instances for session failover.

  For information about the ssoSessionTools.zip file and how to configure session failover, see Chapter 7, Implementing OpenSSO Enterprise Session Failover.

This chapter also describes:

• Using ssoadm With OpenSSO Enterprise Configured as a Site

• Running the Unix Authentication Helper (amunixd Daemon)

For information about uninstallation, see Uninstalling the OpenSSO Enterprise Utilities and Scripts

Installing the OpenSSO Enterprise Utilities and Scripts in the ssoAdminTools.zip File

After you download and unzip the opensso_enterprise_80.zip file, the ssoAdminTools.zip file is available in the zip-root/opensso/tools directory.

The following table describes the layout after you unzip the ssoAdminTools.zip file. The directory where you unzip ssoAdminTools.zip is represented by tools-zip-root.

Table 6–1 ssoAdminTools.zip File Layout

tools-zip-root File or Directory	Description
README.setup	Description of the ssoAdminTools.zip file.
license.txt	License agreement.
setup	Script to install the tools on Solaris and Linux systems.
setup.bat	Script to install the tools on Windows systems.
lib/	JAR files required to run the scripts.
locale/	Properties files required to run the scripts.
mo/	Files for localizing the amtune scripts
template/	Script templates for Solaris, Linux, and Windows systems.

To Install the OpenSSO Enterprise Utilities and Scripts in the ssoAdminTools.zip File

1. Make sure that your JAVA_HOME environment variable points to JDK 1.5 or later.

2. Create a new directory to unzip the ssoAdminTools.zip file (represented by tools-zip-root in the previous table).

3. Unzip the ssoAdminTools.zip file in the new directory.

4. In the directory where you unzipped the ssoAdminTools.zip file, run the setup script:

   On Solaris and Linux systems, run the setup script as follows:

   # ./setup

   When you are prompted, enter the path to the OpenSSO Enterprise configuration, log, and debug directories. The configuration directory was specified during the initial configuration using the Configurator. For example: /opensso

   Considerations:

   On Windows systems, run the setup.bat script.

Next Steps

You can now run the OpenSSO Enterprise CLI utilities and scripts from the following directory:

tools-zip-root/deploy_uri/bin

where:

• tools-zip-root is the directory where you unzipped the ssoAdminTools.zip file.

• deploy_uri is the name of the OpenSSO Enterprise deploy URI. For example: opensso

For information about the CLI utilities, see the OpenSSO Enterprise 8.0 Administration Reference.

For information about the tuning scripts, see the OpenSSO Enterprise 8.0 Performance and Tuning Guide.

Using ssoadm With OpenSSO Enterprise Configured as a Site

In a typical large deployment, OpenSSO Enterprise server instances are configured behind one or load balancers. The HTTP(s) traffic is usually one directional. That is, the traffic goes from one of the load balancers to the servers, but requests from servers are unable to reach the load balancers. If the above scenario applies to your deployment and you need to use the ssoadm utility (Solaris and Linux systems) or ssoadm.bat utility (Windows), perform the following procedure.

To Use ssoadm With OpenSSO Enterprise Configured as a Site

1. After you install the tools, edit the ssoadm or ssoadm.bat utility in the tools-zip-root/deploy_uri/bin directory.

   where:

   • tools-zip-root is the directory where you unzipped the ssoAdminTools.zip file.

   • deploy_uri is the name of the OpenSSO Enterprise deploy URI. For example: opensso

2. In the ssoadm or ssoadm.bat utility, add the following property to the java command:

   -D"com.iplanet.am.naming.map.site.to.server=
   http://lb.example.com:58080/opensso=http://ssohost1.example.com:58080/opensso"

   where:

   • lb is the load balancer.

   • ssohost1 is the OpenSSO Enterprise server where ssoadm is installed.

3. Save the ssoadm or ssoadm.bat utility.

   The utility can now send naming requests to the OpenSSO Enterprise server instance.

   Once the site is enabled, this property prevents the administrator from being denied access to the server when the load balancer is inaccessible. When the ssoadmin command tries to access the load balancer, if the load balancer is not accessible, ssoadmin can directly access the server specified in this property.

Running the Unix Authentication Helper (amunixd Daemon)

The Unix authentication module is supported on Solaris SPARC, Solaris x86, or Linux systems. The Unix authentication module requires the amunixd helper daemon for Unix authentication.

After you unzip the opensso_enterprise_80.zip file, the helper files for the Unix authentication module are in the zip-root/opensso/tools/helpers directory.

To Run the Unix Authentication Helper (amunixd Daemon)

1. To change any of the Unix authentication module configuration values, use the OpenSSO Enterprise administration Console:

   1. Login into the Console as amadmin.

   2. Click Configuration, Authentication, and then Unix.

   3. Set the Unix authentication attributes, as required for your deployment:

      • Configuration Port: Port that the amunixd daemon listens to at startup for configuration information. Default:58946

      • Authentication Port: Port that the amunixd daemon listens for authentication requests. Default:57946

      • Timeout: Minutes to complete the authentication. Default: 3

      • Threads: Number of simultaneous authentication sessions. Default: 5

      • Authentication Level: How much to trust an authentication mechanism. Default: 0

      • PAM Service Name: Configuration or stack that is shipped for the operating system. Default: other

        Solaris systems: PAM Service Name=other

        Linux systems: PAM Service Name=password

        Linux Note: On some Linux systems, you might need to set PAM Service Name to a different value. For example, on some Linux systems, the PAM Service Name is passwd.If password or passwd is not correct, you will need to determine the PAM Service Name for your Linux system.

   4. Click Save and logout of the Console.

2. Login as superuser (root).

3. Start the amunixd daemon by running the amunixd script in the zip-root/opensso/tools/helpers/bin directory.

   For example:

   # cd zip-root/opensso/tools/helpers/bin
   # ./amunixd

   Notes

   • Run the amunixd daemon as root. If the daemon is started by a non-root user, Unix authentication will succeed only for NIS users. Local users in /etc/passwd or /etc/shadow on Solaris systems will not be able to authenticate.

   • The Unix authentication service Configuration Port in the Administration Console and the port the amunixd process is started with (default 58946) must match. If you change the port in the Administration Console, use the -c portnumber option to start the amunixd process. For example:

     If the Configuration Port is changed from the default value (58946) using the OpenSSO Enterprise Admin Console, run the amunixd script with the -c and -p arguments to specify the new port and IP address, respectively. For example:

     # ./amunixd -c portnumber

   • If the you want the amunixd process to accept connections from systems other than the localhost (that is, the OpenSSO Enterprise host), use the following options:

     -i N -a ipaddr1 ... -a ipaddrN

     where N is the number of IP addresses you want to specify, and ipaddr1 ..."ipaddrN are the IP addresses in the 3-dot (111.111.111.111) format of the systems that amunixd is to accept connections from.