Sun Java System Access Manager 6 2005Q1 Administration Guide |
Chapter 1
Access Manager 2005Q1 Configuration ScriptsThis chapter describes how to configure and deploy Sun Java System Access Manager using the amconfig script and the sample silent mode input file (amsamplesilent). Topics include:
Access Manager 2005Q1 Installation OverviewFor a new installation, always install the first instance of Access Manager 2005Q1 by running the Sun Java Enterprise System 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 2005Q1 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.
Note
If you are installing BEA WebLogic 8.1.x or IBM WebSphere 5.1.x as the Access Manager web container, you must choose the Configure Later option when installing Access Manager. See Installing and Configuring Third-Party Web Containers for more information.
For information about the installer, refer to the Sun Java Enterprise System 2005Q1 Installation Guide (http://docs.sun.com/doc/819-0056).
The Java Enterprise System installer installs the Access Manager 2005Q1 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 File.
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 Manger 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:
- 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 FileAfter 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
Table 1-1 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
Table 1-2 describes the Access Manager configuration variables.
Table 1-2 Access Manager Configuration Variables
Variable
Description
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 7, this variable should match AS70_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 7, this variable should match AS70_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 7, this variable should match AS70_PROTOCOL.
CONSOLE_HOST
Fully qualified host name of the server where the console is installed.
Default: Value provided for the Access Manager host (SERVER_HOST variable)
CONSOLE_PORT
Port of the web container where the console is installed and listens for connections.
Default: Value provided for the Access Manager port (SERVER_PORT variable)
CONSOLE_PROTOCOL
Protocol of the web container where the console is installed.
Default: Server protocol (SERVER_PROTOCOL variable)
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 (DS_DIRMGRDN variable).
See the note about special characters in the description of ADMINPASSWD.
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 ADMINPASSWD.
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 ADMINPASSWD.
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.
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:
Default: false
Web Container Configuration Variables
To specify the web container for Access Manager, set the WEB_CONTAINER variable in the silent mode input file, as described in Table 1-3.
Table 1-3 Access Manager WEB_CONTAINER Variable
Value
Web Container
WS6 (default)
AS7
Sun Java System Application Server 7.0 Update 3 (Provided for compatibility with previous versions of Access Manager)
AS8
WL6
WL8
WAS4
IBM WebSphere 4.0.5 (Provided for compatibility with previous versions of Access Manager)
WAS5
Sun Java System Web Server 6.1 SP4
Table 1-4 describes the configuration variables for Web Server 6.1 SP4 in the silent mode input file.
Table 1-4 Web Server 6.1 SP4 Configuration Variables
Variable
Description
WS61_INSTANCE
Name of the Web Server instance on which Access Manager will be deployed or un-deployed.
Default: https-web-server-instance-name
where web-server-instance-name is the Access Manager host (SERVER_HOST variable)
WS61_HOME
Web Server base installation directory.
Default: /opt/SUNWwbsvr
WS61_PROTOCOL
Protocol used by the Web Server instance set by the WS61_INSTANCE variable where Access Manager will be deployed: http or https.
Default: Access Manager protocol (SERVER_PROTOCOL variable)
WS61_HOST
Fully qualified host name for the Web Server instance (WS61_INSTANCE variable).
Default: Access Manager host instance (SERVER_HOST variable)
WS61_PORT
Port on which Web Server listens for connections.
Default: Access Manager port number (SERVER_PORT variable)
WS61_ADMINPORT
Port on which the Web Server Administration Server listens for connections.
Default: 8888
WS61_ADMIN
User ID of the Web Server administrator.
Default: "admin"
WS61_IS_SECURE
Specifies whether a secure port is enabled:
Default: false (not enabled)
Sun Java System Application Server 7.0 Update 3
Table 1-5 describes the configuration variables for Application Server 7.0 Update 3 in the silent mode input file.
Table 1-5 Application Server 7.0 Update 3 Configuration Variables
Variable
Description
AS70_HOME
Path to the directory where Application Server 7.0 is installed.
Default: /opt/SUNWappserver7
AS70_PROTOCOL
Protocol used by the Application Server instance: http or https.
Default: Access Manager protocol (SERVER_PROTOCOL variable)
AS70_HOST
Fully qualified domain name (FQDN) on which the Application Server instance listens for connections.
Default: Access Manager host (SERVER_HOST variable)
AS70_PORT
Port on which Application Server instance listens for connections.
Default: Access Manager port number (SERVER_PORT variable)
AS70_ADMINPORT
Port on which the Application Server administration server listens for connections.
Default: 4848
AS70_ADMIN
Name of the user who administers the Application Server administration server for the domain into which Application Server is being displayed.
Default: admin
AS70_ADMINPASSWD
Password for the Application Server administrator for the domain into which Application Server is being displayed.
See the note about special characters in the description of ADMINPASSWD.
AS70_INSTANCE
Name of the Application Server instance that will run Access Manager.
Default: server1
AS70_DOMAIN
Path to the Application Server directory for the domain to which you want to deploy this Access Manager instance.
Default: domain1
AS70_INSTANCE_DIR
Path to the directory where Application Server stores files for the instance.
Default: /var/opt/SUNWappserver7/domains/domain1/server1
AS70_DOCS_DIR
Directory where Application Server stores content documents.
Default: /var/opt/SUNWappserver7/domains/domain1/server1/docroot
AS70_IS_SECURE
Specifies whether a secure port is enabled:
Default: false (not enabled)
During installation, if the Application Server admin port is SSL enabled, configuration will fail. Do not use the admin server in https mode.
Sun Java System Application Server 8.1.x
Table 1-6 describes the configuration variables for Application Server 8.1 in the silent mode input file.
Table 1-6 Application Server 8.1 Configuration Variables
Variable
Description
AS81_HOME
Path to the directory where Application Server 8.1 is installed.
Default: /usr/appserver1
AS81_PROTOCOL
Protocol used by the Application Server instance: http or https.
Default: Access Manager protocol (SERVER_PROTOCOL variable)
AS81_HOST
Fully qualified domain name (FQDN) on which the Application Server instance listens for connections.
Default: Access Manager host (SERVER_HOST variable)
AS81_PORT
Port on which Application Server instance listens for connections.
Default: Access Manager port number (SERVER_PORT variable)
AS81_ADMINPORT
Port on which the Application Server administration server listens for connections.
Default: 4849
AS81_ADMIN
Name of the user who administers the Application Server administration server for the domain into which Application Server is being displayed.
Default: admin
AS81_ADMINPASSWD
Password for the Application Server administrator for the domain into which Application Server is being displayed.
See the note about special characters in the description of ADMINPASSWD.
AS81_INSTANCE
Name of the Application Server instance that will run Access Manager.
Default: server
AS81_DOMAIN
Path to the Application Server directory for the domain to which you want to deploy this Access Manager instance.
Default: domain1
AS81_INSTANCE_DIR
Path to the directory where Application Server stores files for the instance.
Default: /var//appserver/domains/domain1
AS81_DOCS_DIR
Directory where Application Server stores content documents.
Default: /var/appserver/domains/domain1/docroot
AS81_IS_SECURE
Specifies whether a secure port is enabled:
Default: false (not enabled)
In ampsamplesilent, there is an additional setting that specified whether the application server administration port is secure:
Default: True (enabled).
BEA WebLogic Server 6.1 SP4 and SP5
Table 1-7 describes the configuration variables for BEA WebLogic Server 6.1 in the silent mode input file.
Table 1-7 BEA WebLogic Server 6.1 SP4 and SP5 Configuration Variables
Variable
Description
WL61_HOME
WebLogic home directory. Default: /export/bea61a
WL61_PROJECT_DIR
WebLogic project directory. Default: user_projects
WL61_DOMAIN
WebLogic domain name. Default: mydomain
WL61_SERVER
WebLogic server name. Default: myserver
WL61_INSTANCE
WebLogic instance name. Default: WS61_HOME/wlserver6.1
WL61_PROTOCOL
WebLogic protocol. Default: http
WL61_HOST
WebLogic host name.
WL61_PORT
WebLogic port. Default: 7001
WL61_SSLPORT
WebLogic SSL port. Default: 7002
WL61_ADMIN
WebLogic administrator. Default: “system”
WL61_PASSWORD
WebLogic administrator password.
See the note about special characters in the description of ADMINPASSWD.
WL61_JDK_HOME
WebLogic JDK home directory. Default: WS61_HOME/jdk131
BEA WebLogic Server 8.1
Table 1-8 describes the configuration variables for BEA WebLogic Server 8.1 in the silent mode input file.
Table 1-8 BEA WebLogic Server 8.1 Configuration Variables
Variable
Description
WL8_HOME
WebLogic home directory. Default: /export/bea8
WL8_PROJECT_DIR
WebLogic project directory. Default: projects
WL8_DOMAIN
WebLogic domain name. Default: mydomain
WL8_SERVER
WebLogic server name. Default: myserver
WL8_INSTANCE
WebLogic instance name. Default: /export/bea8/weblogic81
WL8_PROTOCOL
WebLogic protocol. Default: http
WL8_HOST
WebLogic host name. Default: none
WL8_PORT
WebLogic port. Default: 7001
WL8_SSLPORT
WebLogic SSL port. Default: 7002
WL8_ADMIN
WebLogic administrator. Default: "system"
WL8_PASSWORD
WebLogic administrator password.
See the note about special characters in the description of ADMINPASSWD.
WL8_JDK_HOME
WebLogic JDK home directory. Default: WL8_HOME/jdk141_03
WL8_CONFIG_LOCATION
Should be set to the parent directory of the location of the WebLogic start script.
WL8_IS_SECURE
Specifies whether a secure port is enabled:
Default: false (not enabled)
IBM WebSphere 5.1
Table 1-9 describes the configuration variables for IBM WebSphere Server 5.1 in the silent mode input file.
Directory Server Configuration Variables
Access Manager 2005Q1 supports Sun ONE Directory Server 5.1 and Sun Java System Directory Server 5 2005Q1. Table 1-10 describes the Directory Server configuration variables in the silent mode input file.
Access Manager amconfig ScriptAfter your 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 install 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:
where:
-s runs amconfig in silent mode.
input-file is a silent install 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.
Access Manager Deployment ScenariosAfter 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 mode input file and then running the amconfig script.
This section describes the following scenarios:
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 6.1 SP2, see:
http://docs.sun.com/coll/S1_websvr61_en- For Application Server 7.0 Update 3, see:
http://docs.sun.com/coll/s1_asseu3_enThe 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 Installing and Configuring Third-Party Web Containers for more information.
To Deploy an Additional Access Manager Instance
- 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.
- 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.
- Set the following variables in the new amnewws6instance file:
DEPLOY_LEVEL=1
NEW_INSTANCE=trueSet 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:
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.
- Run the amconfig script, specifying the new amnewws6instance file. For example, on Solaris systems:
cd AccessManager-base/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.
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
- 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.
- Copy the silent install 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.
- In the amnewinstanceforWS61 file, set the DEPLOY_LEVEL variable to one of the values described for a Re-install operation. For example, set DEPLOY_LEVEL=21 to reconfigure a full installation.
- In the amnewinstanceforWS61 file, set the NEW_INSTANCE variable to false:
NEW_INSTANCE=false
- 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:
- Run the amconfig script, specifying your edited input file. For example, on Solaris systems:
cd AccessManager-base/SUNWam/bin/
./amconfig -s /reconfig/amnewinstanceforWS61The -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 an Access Manager Instance
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
- 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.
- Copy the silent install 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.
- In the amnewinstanceforWS61 file, set the DEPLOY_LEVEL variable to one of the values described for an Uninstall (unconfigure) operation. For example, set DEPLOY_LEVEL=11 to uninstall (or unconfigure) a full installation.
- Run the amconfig script, specifying your edited input file. For example, on Solaris systems:
cd AccessManager-base/SUNWam/bin/
./amconfig -s /unconfigure/aminstanceforWS61The -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 2005Q1 instances and packages from a system.
To Completely Remove Access Manager 2005Q1 From a System
- Log in as or become superuser (root).
- In the input file you used to deploy the instance, set the DEPLOY_LEVEL variable to one of the values described for an Uninstall (unconfigure) operation. For example, set DEPLOY_LEVEL=11 to uninstall (or unconfigure) a full installation.
- Run the amconfig script using the file you edited in Step 2. For example on Solaris systems:
cd AccessManager-base/SUNWam/bin/
./amconfig -s /newinstances/amnewws6instanceThe 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.
- 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 Installation Guide.
Example Configuration Script Input FileThe following section includes an example of an Access Manager configuration script input file for deployment with WebLogic 8.1.
Table 1-11
Sample Configuration Script Input File for WebLogic 8.1.x