Chapter 1 Access Manager 7 2005Q4 Configuration Scripts

This chapter describes how to configure and deploy Sun Java^TM System Access Manager using the amconfig script and the sample silent mode input file (amsamplesilent). Topics include:

• Access Manager 7 2005Q4 Installation Overview

• Access Manager Sample Configuration Script Input File

• Access Manager amconfig Script

• Access Manager Deployment Scenarios

• Example Configuration Script Input File

Access Manager 7 2005Q4 Installation Overview

For a new installation, always install the first instance of Access Manager 7 2005Q4 by running the Sun Java Enterprise System (Java ES) installer. When you run the installer, you can select either of these configuration options for Access Manager:

• The Configure Now option allows you to install and configure the first instance during the installation by the choices (or default values) that you select on the Access Manager installation panels.

• The Configure Later option installs the Access Manager 7 2005Q4 components, and then after installation, you must manually configure them or run the Access Manager scripts as described in Configuring and Reconfiguring an Instance of Access Manager. If you choose this option, then none of the products that you are currently installing will be configured. For example, if you choose to install Access Manager and Application Server and select the Configure Later option, neither application will be configured.

If you are installing BEA WebLogic or IBM WebSphere Application Server as the Access Manager web container, you must choose the Configure Later option when installing Access Manager. See Chapter 2, Installing and Configuring Third-Party Web Containers for more information.

For information about the installer, refer to the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX.

The Java Enterprise System installer installs the Access Manager 7 2005Q4 amconfig script and sample silent mode input file (amsamplesilent) in the AccessManager-base /SUNWam/bin directory on Solaris systems or the AccessManager-base/identity/bin directory on Linux systems.

AccessManager-base represents the Access Manager base installation directory. On Solaris systems, the default base installation directory is /opt, and on Linux systems, it is /opt/sun. However, you can specify another directory, if you prefer, when you run the installer.

The amconfig script is a top-level script that calls other scripts as needed to perform the requested operation. For more information, see the Access Manager amconfig Script.

The sample configuration script input file (amsamplesilent) is a template that you can use to create the input file that you must specify when you run the amconfig script in silent mode.

This sample configuration script input file is an ASCII text file that contains Access Manager configuration variables. Before you run the amconfig script, copy (and rename, if you wish) the amsamplesilent file, and then edit the variables in the file based on your system environment. The configuration variables are in the following format:

variable-name=value

For example:

DEPLOY_LEVEL=1
 NEW_INSTANCE=true
 SERVER_HOST=ishost.example.com

For a list of the variables you can set in a configuration script input file, see the Access Manager Sample Configuration Script Input FileAccess Manager Sample Configuration Script Input File.

The format of the sample configuration script input file used when you run the amconfig script in silent mode does not follow the same format or necessarily use the same variable names as a Java Enterprise System silent installation state file. This file contains sensitive data, such as the administrator password. Make sure to protect or delete this file as appropriate.

Access Manager amconfig Script Operations

After you install first instance of Access Manager using the Sun Java Enterprise System installer, you can run the amconfig script to perform the following operations, depending on the values of the variables in the silent mode input file:

• Deploy and configure the first instance of Access manager or deploy and configure for additional instances of Access Manager on the same host system. For example, after you configure an additional instance of a web container, you can then deploy and configure a new Access Manager instance for that web container instance.

• Reconfigure both the first instance and any additional instances of Access Manager.

• Deploy and configure the Access Manager full server services or only the SDK services, which enables support for these products:

  • BEA WebLogic

  • IBM WebSphere Application Server

  Deploy and configure specific Access Manager components such as the console or Federation Management module.

• Uninstall instances and components of Access Manager that you deployed using the amconfig script.

Access Manager Sample Configuration Script Input File

After you run the Java Enterprise System installer, the Access Manager sample configuration script input file (amsamplesilent) is available in the AccessManager-base/SUNWam/bin directory on Solaris systems or the AccessManager-base/identity/bin directory on Linux systems.

To set configuration variables, first copy and rename the amsamplesilent file. Then set the variables in the copy for the operation you want to perform. For an example of this file, see Example Configuration Script Input File.

This sample silent mode input file contains the following configuration variables:

• Deployment Mode Variable

• Access Manager Configuration Variables

• Web Container Configuration Variables

• Directory Server Configuration Variables

Deployment Mode Variable

This section describes the values for the required DEPLOY_LEVEL variable. This variable determines the operation you want the amconfig script to perform.

Access Manager Configuration Variables

This section describes the Access Manager configuration variables.

Variable	Description
AM_REALM	Indicates the Access Manager mode:  enabled: Access Manager operates in Realm Mode, with Access Manager 7 2005Q4 features and console. disabled: Access Manager operates in Legacy Mode, with Access Manager 6 2005Q1 features and console. Default: enabled  Caution – Access Manager Realm Mode is enabled by default. If you are deploying Access Manager with Portal Server, Messaging Server, Calendar Server, Delegated Administrator, or Instant Messaging, you must select Legacy Mode (AM_REALM=disabled) before you run the amconfig script.
BASEDIR	Base installation directory for Access Manager packages.  Default: PLATFORM_DEFAULT  For Solaris systems, PLATFORM_DEFAULT is /opt For Linux systems, PLATFORM_DEFAULT is /opt/sun
SERVER_HOST	Fully qualified host name of the system where Access Manager is running (or will be installed).  For a remote SDK installation, set this variable to the host where Access Manager is (or will be) installed and not the remote client host.  This variable should match the counterpart variable in the web container configuration. For example, for Application Server 8, this variable should match AS81_HOST.
SERVER_PORT	Access Manager port number. Default: 58080  For a remote SDK installation, set this variable to the port on the host where Access Manager is (or will be) installed and not the remote client host.  This variable should match the counterpart variable in the web container configuration. For example, for Application Server 8, this variable should match AS81_PORT.
SERVER_PROTOCOL	Server protocol: http or https. Default: http  For a remote SDK installation, set this variable to the protocol on the host where Access Manager is (or will be) installed and not the remote client host.  This variable should match the counterpart variable in the web container configuration. For example, for Application Server 8, this variable should match AS81_PROTOCOL.
CONSOLE_HOST	Fully qualified host name of the server where the console is installed.  Default: Value provided for the Access Manager host
CONSOLE_PORT	Port of the web container where the console is installed and listens for connections.  Default: Value provided for the Access Manager port
CONSOLE_PROTOCOL	Protocol of the web container where the console is installed.  Default: Server protocol
CONSOLE_REMOTE	Set to true if the console is remote from the Access Manager services. Otherwise, set to false. Default: false
DS_HOST	Fully qualified host name of Directory Server.
DS_PORT	Directory Server port. Default: 389.
DS_DIRMGRDN	Directory manager DN: the user who has unrestricted access to Directory Server.  Default: "cn=Directory Manager"
DS_DIRMGRPASSWD	Password for the directory manager  See the note about special characters in the description of Access Manager Configuration Variables.
ROOT_SUFFIX	Initial or root suffix of the directory. You must make sure that this value exists in the Directory Server you are using.  See the note about special characters in the description of Access Manager Configuration Variables.
ADMINPASSWD	Password for the administrator (amadmin). Must be different from the password for amldapuser. Note: If the password contains special characters such as a slash (/) or backslash (\\), the special character must be enclosed by single quotes (”). For example: ADMINPASSWD=’\\\\\\\\\\####///’ However, the password cannot have a single quote as one of the actual password characters.
AMLDAPUSERPASSWD	Password for amldapuser. Must be different from the password for amadmin. See the note about special characters in the description of Access Manager Configuration Variables.
CONSOLE_DEPLOY_URI	URI prefix for accessing the HTML pages, classes and JAR files associated with the Access Manager Administration Console subcomponent.  Default: /amconsole
SERVER_DEPLOY_URI	URI prefix for accessing the HTML pages, classes, and JAR files associated with the Identity Management and Policy Services Core subcomponent.  Default: /amserver
PASSWORD_DEPLOY_URI	URI that determines the mapping that the web container running Access Manager will use between a string you specify and a corresponding deployed application.  Default: /ampassword
COMMON_DEPLOY_URI	URI prefix for accessing the common domain services on the web container.  Default: /amcommon
COOKIE_DOMAIN	Names of the trusted DNS domains that Access Manager returns to a browser when it grants a session ID to a user. At least one value should be present. In general, the format is the server’s domain name preceded with a period.  Example: .example.com
JAVA_HOME	Path to the JDK installation directory. Default: /usr/jdk/entsys-j2se. This variable provides the JDK used by the command line interface’s (such as amadmin) executables. The version must be 1.4.2 or later.
AM_ENC_PWD	Password encryption key: String that Access Manager uses to encrypt user passwords. Default: none. When the value is set to none, amconfig will generate a password encryption key for the user, so a password encryption will exist for the installation that is either specified by the user or created through amconfig . Important: If you are deploying multiple instances of Access Manager or the remote SDK, all instances must use the same password encryption key. When you deploy an additional instance, copy the value from the am.encryption.pwd property in the AMConfig.properties file for the first instance.
PLATFORM_LOCALE	Locale of the platform. Default: en_US (US English)
NEW_OWNER	New owner for the Access Manager files after installation. Default: root
NEW_GROUP	New group for the Access Manager files after installation. Default: other For a Linux installation, set NEW_GROUP to root.
PAM_SERVICE_NAME	Name of the PAM service from the PAM configuration or stack that comes with the operating system and is used for the Unix authentication module (normally other for Solaris or password for Linux). Default: other.
XML_ENCODING	XML encoding. Default: ISO-8859-1
NEW_INSTANCE	Specifies whether the configuration script should deploy Access Manager to a new user-created web container instance:  true = To deploy Access Manager to a new user-created web container instance other than an instance that already exists. false = To configure the first instance or re-configure an instance. Default: false
SSL_PASSWORD	Is not used in this release.

Web Container Configuration Variables

To specify the web container for Access Manager, set the WEB_CONTAINER variable in the silent mode input file. For the versions of the web containers supported by Access Manager 7 2005Q4, see the Sun Java System Access Manager 7 2005Q4 Release Notes.

Sun Java System Web Server 6.1 SP5

This section describes the configuration variables for Web Server 6.1 2005Q4 SP5 in the silent mode input file.

Sun Java System Application Server 8.1

This section describes the configuration variables for Application Server 8.1 in the silent mode input file.

BEA WebLogic Server 8.1

This section describes the configuration variables for BEA WebLogic Server 8.1 in the silent mode input file.

IBM WebSphere 5.1

This section describes the configuration variables for IBM WebSphere Server 5.1 in the silent mode input file.

Directory Server Configuration Variables

For the versions of Directory Server supported by Access Manager 7 2005Q4, see the Sun Java System Access Manager 7 2005Q4 Release Notes. This section describes the Directory Server configuration variables in the silent mode input file.

Access Manager amconfig Script

After you run the Java Enterprise System installer, the amconfig script is available in the AccessManager-base /SUNWam/bin directory on Solaris systems or the AccessManager-base/identity/bin directory on Linux systems.

The amconfig script reads a silent configuration input file and then calls other scripts in silent mode, as needed, to perform the requested operation.

To run the amconfig script, use this syntax:

amconfig -s
          input-file

      

where:

-s runs amconfig in silent mode.

input-file is the silent configuration input file that contains the configuration variables for the operation you want to perform. For more information, see Access Manager Sample Configuration Script Input File.

Several considerations for running the amconfig script are:

• You must be running as superuser (root).

• Specify the full path to the amsamplesilent file (or copy of the file). For example:

  # cd /opt/SUNWam/bin 
  # ./amconfig -s ./amsamplesilent

  or

  # ./amconfig -s /opt/SUNWam/bin/amsamplesilent

In the Access Manager 7 2005Q4 release, the following scripts are not supported:

• amserver with the create argument

• amserver.instance

Also, by default amserver start starts only the authentication amsecuridd and amunixd helpers. The amsecuridd helper is available only on the Solaris OS SPARC platform.

Access Manager Deployment Scenarios

After you have installed the first instance of Access Manager using the Java Enterprise System installer, you can deploy and configure additional Access Manager instances by editing the configuration variables in the silent configuration input file and then running the amconfig script.

This section describes the following scenarios:

• Deploying Additional Instances of Access Manager

• Configuring and Reconfiguring an Instance of Access Manager

• Uninstalling Access Manager

• Uninstalling All Access Manager Instances

Deploying Additional Instances of Access Manager

Before you can deploy a new instance of Access Manager, you must create and start the new web container instance using the administration tools for the web container. For information, refer to the specific web container documentation:

• For Web Server, see http://docs.sun.com/coll/1308.1

• For Application Server, see http://docs.sun.com/coll/1310.1

The steps described in this section only apply to an Access Manager instance that has been installed with the Configure Now option. If you are planning to use WebLogic or WebSphere as web containers, you must use the Configure Later option when installing Access Manager. See Chapter 2, Installing and Configuring Third-Party Web Containers for more information.

Deploying an Additional Access Manager Instance

This section describes how to deploy an additional Access Manager instance on a different host server and update the Platform Server List.

To Deploy an Additional Access Manager Instance

1. Log in as an administrator, depending on the web container for the instance. For example, if Web Server 6.1 will be the web container for the new instance, log in either as superuser (root) or as the user account for the Web Server Administration Server.

2. Copy the amsamplesilent file to a writable directory and make that directory your current directory. For example, you might create a directory named /newinstances.

   Tip Rename the copy of the amsamplesilent file to describe the new instance you want to deploy. For example, the following steps use an input file named amnewws6instance to install a new instance for Web Server 6.1.

3. Set the following variables in the new amnewws6instance file:

   DEPLOY_LEVEL=1 NEW_INSTANCE=true

   Set other variables in the amnewws6instance file as required for the new instance you want to create. For a description of these variables, refer to the tables in the following sections:

   • Access Manager Configuration Variables

     • Web Container Configuration Variables

     • Directory Server Configuration Variables

       Important All Access Manager instances must use the same value for the password encryption key. To set the AM_ENC_PWD variable for this instance, copy the value from the am.encryption.pwd property in the AMConfig.properties file for the first instance.

       In case you might need to uninstall this instance later, save the amnewws6instance file.

4. Run the amconfig, specifying the new amnewws6instance file. For example, on Solaris systems:

   # cd opt/SUNWam/bin/ # ./amconfig -s ./newinstances/amnewws6instance

   The -s option runs the amconfig script in silent mode.

   The amconfig script calls other configuration scripts as needed, using variables in the amnewws6instance file to deploy the new instance.

To Update the Platform Server List

When you crate an additional container instance, you must update the Access Manager Platform Server list to reflect the addition of the container(s).

1. Log in to the Access Manager Console as the top-level administrator.

2. Click on the Service Configuration tab.

3. Click on the Platform service.

4. Enter the following information for the new instance in the Server List:

   protocol://fqdn:port|instance-number

   The instance number should be the next available number that is not in use.

5. Click Add.

6. Click Save.

Configuring and Reconfiguring an Instance of Access Manager

You can configure an instance of Access Manager that was installed with the Configure Later option or reconfigure the first instance that was installed using Configure Now option in the Java Enterprise System installer by running the amconfig script.

For example, you might want to reconfigure an instance to change the Access Manager owner and group.

To Configure or Reconfigure an Instance of Access Manager

1. Log in as an administrator, depending on the web container for the instance. For example, if Web Server 6.1 is the web container, log in either as superuser (root) or as the user account for Web Server Administration Server.

2. Copy the silent configuration input file you used to deploy the instance to a writable directory and make that directory your current directory. For example, to reconfigure an instance for Web Server 6.1, the following steps use an input file named amnewinstanceforWS61 in the /reconfig directory.

3. In the amnewinstanceforWS61 file, set the DEPLOY_LEVEL variable to one of the values described for a Deployment Mode Variable operation. For example, set DEPLOY_LEVEL=21 to reconfigure a full installation.

4. In the amnewinstanceforWS61 file, set the NEW_INSTANCE variable to false:

   NEW_INSTANCE=false

5. Set other variables in the amnewinstanceforWS61 file to reconfigure the instance. For example, to change the owner and group for the instance, set the NEW_OWNER and NEW_GROUP variables to their new values.

   For a description of other variables, refer to the tables in the following sections:

   • Access Manager Configuration Variables

     • Web Container Configuration Variables

     • Directory Server Configuration Variables

6. Run the amconfig script, specifying your edited input file. For example, on Solaris systems:

   # cd opt/SUNWam/bin/ # ./amconfig -s ./reconfig/amnewinstanceforWS61

   The -s option runs the script in silent mode. The amconfig script calls other configuration scripts as needed, using variables in the amnewinstanceforWS61 file to reconfigure the instance.

Uninstalling Access Manager

You can uninstall an instance of Access Manager that was installed by running the amconfig script. You can also temporarily unconfigure an instance of Access Manager, and unless you remove the web container instance, it is still available for you to re-deploy another Access Manager instance later.

To Uninstall an Instance of Access Manager

1. Log in as an administrator, depending on the web container for the instance. For example, if Web Server 6.1 is the web container, log in either as superuser (root) or as the user account for Web Server Administration Server.

2. Copy the silent configuration input file you used to deploy the instance to a writable directory and make that directory your current directory. For example, to unconfigure an instance for Web Server 6.1, the following steps use an input file named amnewinstanceforWS61 in the /unconfigure directory.

3. In the amnewinstanceforWS61 file, set the DEPLOY_LEVEL variable to one of the values described for an Deployment Mode Variable operation. For example, set DEPLOY_LEVEL=11 to uninstall (or unconfigure) a full installation.

4. Run the amconfig script, specifying your edited input file. For example, on Solaris systems:

   # cd opt/SUNWam/bin/ # ./amconfig -s ./unconfigure/aminstanceforWS61

   The -s option runs the script in silent mode. The amconfig script reads the amnewinstanceforWS61 file and then uninstalls the instance.

   The web container instance is still available if you want to use it to re-deploy another Access Manager instance later.

Uninstalling All Access Manager Instances

This scenario completely removes all Access Manager 7 2005Q4 instances and packages from a system.

To Completely Remove Access Manager 7 2005Q4 From a System

1. Log in as or become superuser (root).

2. In the input file you used to deploy the instance, set the DEPLOY_LEVEL variable to one of the values described for an Deployment Mode Variable operation. For example, set DEPLOY_LEVEL=11 to uninstall (or unconfigure) a full installation.

3. Run the amconfig script using the file you edited in Uninstalling All Access Manager Instances. For example on Solaris systems:

   # cd opt/SUNWam/bin/ # ./amconfig -s ./newinstances/amnewws6instance

   The amconfig script runs in silent mode to uninstall the instance.

   Repeat these steps for any other Access Manager instances you want to uninstall, except for the first instance, which is the instance you installed using the Java Enterprise System installer.

4. To uninstall the first instance and remove all Access Manager packages from the system, run the Java Enterprise System uninstaller. For information about the uninstaller, refer to the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX.

Example Configuration Script Input File

The following section includes an example of an Access Manager configuration script input file for deployment with WebLogic 8.1.

DEPLOY_LEVEL=1
BASEDIR=/opt
SERVER_HOST=ide-56.example.company.com
SERVER_PORT=7001
SERVER_PROTOCOL=http
CONSOLE_HOST=$SERVER_HOST
CONSOLE_PORT=$SERVER_PORT
CONSOLE_PROTOCOL=$SERVER_PROTOCOL
CONSOLE_REMOTE=false
DS_HOST=ide-56.example.company.com
DS_PORT=389
DS_DIRMGRDN=”cn=Directory Manager”
DS_DIRMGRPASSWD=11111111
ROOT_SUFFIX=”dc=company,dc=com”
ADMINPASSWD=11111111
AMLDAPUSERPASSWD=00000000
CONSOLE_DEPLOY_URI=/amconsole
SERVER_DEPLOY_URI=/amserver
PASSWORD_DEPLOY_URI=/ampassword
COMMON_DEPLOY_URI=/amcommon
COOKIE_DOMAIN=.iplanet.com
JAVA_HOME=/usr/jdk/entsys-j2se
AM_ENC_PWD=””
PLATFORM_LOCALE=en_US
NEW_OWNER=root
NEW_GROUP=other
XML_ENCODING=ISO-8859-1
NEW_INSTANCE=false
WEB_CONTAINER=WL8
WL8_HOME=/export/bea8
WL8_PROJECT_DIR=user_projects
WL8_DOMAIN=mydomain
WL8_CONFIG_LOCATION=$WL8_HOME/$WL8_PROJECT_DIR/domains
WL8_SERVER=myserver
WL8_INSTANCE=/export/bea8/weblogic81
WL8_PROTOCOL=http
WL8_HOST=ide-56.example.company.com
WL8_PORT=7001
WL8_SSLPORT=7002
WL8_ADMIN=”weblogic”
WL8_PASSWORD=”11111111”
WL8_JDK_HOME=$WL8_HOME/jdk142_04
DIRECTORY_MODE=1
USER_NAMING_ATTR=uid
ORG_NAMING_ATTR=o
ORG_OBJECT_CLASS=examplemanagedorganization
USER_OBJECT_CLASS=inetorgperson
DEFAULT_ORGANIZATION=
Sample Configuration Script Input File for WebLogic 8.1.x