|Previous Contents Index Next|
|iPlanet Application Server 6.5 SP1, Enterprise Edition Administrator's Guide|
|Updated: November 25, 2002|
Chapter 1 Performing Basic Administrative Tasks
This chapter describes how to administer iPlanet Application Server, using iPlanet Application Server Administration Tool (iASAT), iPlanet Registry Editor and command line tools.
This chapter also covers the basic iPlanet Application Server configuration tasks you can perform using iPlanet Application Server Administration Tool (iASAT), various command line tools and iPlanet Registry Editor.
The basic administrative and configuration tasks that you can perform using iASAT, command-line tools and iPlanet Registry Editor are divided into the following topics:
About iPlanet Application Server Administration Tool (iASAT)
iPlanet Application Server Administration Tool (iASAT) is a stand-alone Java application with a graphical user interface that allows you to administer one or more instances of iPlanet Application Server. iPlanet Application Server administration involves performance-related tasks such as adjusting database connection threads and load-balancing parameters. Server administrators must also separately configure components that the application server uses, including the web server.
You also use iASAT to administer application components. You can group, enable and partition Application components using iASAT, to achieve better performance. Application components, the core of an iPlanet Application Server application, are contained in code and stored on the application server. Enterprise Java Beans (EJBs), servlets, JavaServer Pages (JSPs), and AppLogic objects are all application components. For more information about each of these, refer to the Developer's Guide.
Administrative tasks are performed using iASAT. When iASAT is opened to the default General window, the toolbar, main window with left and right panels, and the menu bar are shown as illustrated in the following figure:
The left panel of the main window displays all iPlanet Application Servers registered with iASAT. The right panel displays individual features of the registered iPlanet Application Servers.
To Start iASAT
To administer one or more iPlanet Application Server machines, start iASAT using one of the following ways:
- On a Solaris system: Open a Terminal window and navigate to the path <iASInstallDir>/ias/bin/ and type the following at the command prompt:
Performing Administrative Tasks Using iASAT
This section describes the concepts and tasks associated with using iASAT. The following topics are included in this section:
To Register an iPlanet Application Server
Registering an iPlanet Application Server adds that server to the scope of the Administration Tool. This is best done after you add a server or a group of servers to the enterprise's network.
To register an iPlanet Application Server machine, perform the following tasks:
- On the iASAT toolbar, click General to open the General window.
- From the File menu, click New>Server.
The New iPlanet Application Server dialog box appears.
- Complete one of the following:
- In the Name text box, specify the name of the server.
This is an arbitrary name you use to distinguish one application server from another. For example, Prod-Node-A. More application servers can be configured, such as, Prod-Node-B, Dev-Node, etc.
- Click Local Host to register a server running on your local machine.
In the Host text box, specify the host name of the server.
This is the DNS name of your server machine. You can also use an IP address.
In the Port text box, specify the port number of the Administration Server. In a default installation, this port is set to 10817.
If you are registering your local host, in the User Name and Password text boxes, specify the user name and password you entered during installation of the server or when modifying the Users and Groups.
If the server that you are registering is not the local host, then you need to provide the user name and login password of the machine you want to add. For example, to register a machine called Solo that is available on your network, you need to provide the user name and password of Solo in the User Name and Password text boxes.
(Optional) To always connect to this server and display it in the Administration Tool window, select the Connect to This Server Automatically Next Time checkbox.
Click OK to register the server.
To Unregister an iPlanet Application Server
When an application server is no longer available, you can remove it from the Administration Tool.
To unregistered, or delete an iPlanet Application Server instance, perform the following tasks:
- On the iASAT toolbar, click General to open the General window.
- In the left pane of the General window, double-click All Registered Servers.
A list of all registered application servers is displayed.
- Select the server you want to delete.
- From the Edit menu, choose Delete.
The selected server is removed from the scope of iASAT.
To Start and Stop a Server Using iASAT
You can choose automatic server start-up when you install iPlanet Application Server. Thereafter, iPlanet Application Server starts automatically on system start-up. However, if you want to manually stop and start iPlanet Application Server, you can do so from iASAT by performing the following tasks:
- Click the General menu on the iASAT toolbar to open the General window.
- In the left pane of the General window, select the server you want to start.
- In the right pane of the General window, click Start Server.
About Command-Line Tools
iPlanet Application Server comes with various command-line tools and executables, that can be run from the command-line prompt (Windows) and the shell prompt (Solaris).
Using command-line tools, you can perform a variety of tasks, right from basic configuration to deploying an application.
To get a complete description of any command-line tool, type command -help at the command prompt. For example, to get a complete list of all the options available in the iascontrol command, type iascontrol-help at the command prompt.
Using Command-Line Tools
For ease of use, most of the command-line tools have been integrated with the iPlanet Application Server Administration Tool (iASAT) and the iPlanet Application Server Deployment Tool (iASAT.
The options available with iPlanet Application Server's command-line tools are different for Windows and Solaris platforms.
On Solaris, even though iASAT and iASAT are available, you can use command-line tools extensively. As you can have multiple instances of iPlanet Application Server on Solaris, it becomes necessary at times to modify the attributes of only one particular instance using command-line tools from the installation directory of a specific instance.
On Windows, command-line tools are in the form of executable (.exe) files.
Command-line tools are located in the iASInstallDir/ias/bin path, on both Solaris and Windows systems.
The following section describes iPlanet Application Server using command-line tools.
Performing Administrative Tasks Using Command-Line Tools
In this section, the procedure for stopping and starting iPlanet Application Server using command-line tools is discussed.
You can stop or start a server using command line tools, on both Windows and Solaris systems by performing the following tasks:
- On Solaris systems, navigate to iASInstallDir\ias\bin\ directory.
Run the following script:
iascontrol subcommand -instance <instance> -user <user> -password <password> -host <host> -port <port> -eng <engineId>
where subcommand can be one of the following:
Starts an application server instance. If you execute this command from the local host, it also starts the Administration Server (KAS), if not already started.
Stops the engines of an application server. The administration server is not stopped.
Forces immediate, non-graceful termination of all application server processes that are running on the local host, as well as the iPlanet Application Server Administration Server (KAS).
The following parameters apply:
Name of the server instance that you want to stop or start. The server instance must be registered in iASAT.
Name of the user that is authorized to start, stop or kill the server instance. The user must be registered with iASAT
The password associated with the user
The hostname or IP address of the server instance you want to start, stop or kill
The port number of the application server's administrative server. Port 10817 is the default
The Id of the engine you want to start or stop. Using the eng option, you can stop specific engines associated with an instance of iPlanet Application Server. If the eng option is not used, then all the engines associated with the required server will be stopped.
Example iascontrol start
- Starting a specific instance of iPlanet Application Server engine:
iascontrol start -instance <instance> -user <user> -password <password> -host <host> -port <port> [-eng <engineid>]
This command starts engines of the specified instance. In the case of a local instance of iPlanet Application Server, KAS is started if not already running.
- Starting an engine within a specified instance of iPlanet Application Server.
iascontrol start -eng 1
This command starts the specified engines and KAS (if not already started) on your local host.
- Starting an engine associated with a specified instance.
iascontrol start -instance prodnode1 -eng 2
This command starts the engines associated with the instance specified. In the given example, the specified instance is called prodnode1.
- Starting an engine associated with a specific instance on the local host.
iascontrol start -user admin1 -password admin -host prodserver -port 10817 -eng 1
This command starts the engines associated with instance on host prodserver. KAS must already be started and listening on specified Port.
Example iascontrol stop
- Stopping the engines of a specified instance.
iascontrol stop [-instance <instance> [-user <user> -password <password>] [-host <host> -port <port>] ] [-eng <engineid>]
This command stops the engines of the specified instance. Engines are shutdown gracefully. However, KAS continues to run.
- Stopping specific engines on the local host.
iascontrol stop -eng 1
This command stops specified engines on the local host. However, KAS continues to run.
- Stopping a specific instance of iPlanet Application Server.
iascontrol stop -instance prodnode1 -eng 2
This command stops the specified engines associated with an instance called prodnode1. However, KAS continues to run.
4. Stopping specified engines associated with an instance on the local host.
iascontrol stop -user admin1 -password admin -host prodserver -port 10817 [-eng 2]
This command stops engines associated with an instance on the local host. However, KAS continues to operate.
- The command to stop an iPlanet Application Server instance should look like this:
iascontrol stop -instance prodnode1 -user admin1 -password admin -host prodserver -port 10817
You will see one of these codes displayed on your terminal window when you execute any of the given commands.
0 - completed successfully.
1 - could not contact one or more of the specified servers.
2 - authentication/authorization failed against one or more of the specified servers.
Note You need to register an iPlanet Application Server using iASAT, before you can use any of the given commands on it.
Environment Variable Setting on Solaris
On the Solaris platform, the common environment variable settings are recorded in a single script file, iasenv.ksh. The iasenv.ksh script records the common environment variable settings, such as CLASSPATH, GX_ROOTDIR and LD_LIBRARY_PATH.
Therefore, These settings are no longer set in each of the scripts located under the ias/bin or ias/jms/bin directory.
The iasenv.ksh script is located in the <iASInstallDir>/ias/env directory.
- If you face backward compatibility issues, you can define the required variables within iasenv.ksh instead of modifying the individual scripts, such as kxs and kjs.
If the same values are present in both iasenv.ksh script and other scripts which refer to iasenv.ksh (such as kjs), then depending on the location of the definition of that variable within these scripts, either iasenv.ksh script setting would be considered (for example, when the variable is defined before the invocation of iasenv.ksh script within, say kjs) or the setting that is defined within the other script would be taken into account (for example, when the variable is defined after the invocation of iasenv.ksh script within kjs).
About iPlanet Registry Editor
The iPlanet Registry Editor, kregedit, is a stand-alone GUI tool that can display and edit registry information for iPlanet Application Server. The editor is installed with each instance of iPlanet Application Server and is similar in appearance and function to the registry editor installed on Windows. The iPlanet registry editor displays values that are stored both in your local machine's registry and your directory Server.
Using the iPlanet registry editor, you can effectively manage the entries that form the backend resource for the various functions and processes of iPlanet Application Server. You can add keys, modify key values, and delete redundant keys. kregedit has a comprehensive Find/Replace option using which, you find and replace multiple occurrences of the same value in the application server's registry.
To Start kregedit
To start kregedit, perform the following tasks:
- On Solaris, go to iASInstallDir/ias/bin and type kregedit at the command line to launch iPlanet Registry Editor.
- On Windows, click Start>Run. Type kregedit and click OK.
The following window appears:
Performing Administrative Tasks Using iPlanet Registry Editor
The iPlanet Application Server Administration Tool and Deployment Tool create back-end entries in iPlanet Registry when required. However, you may at times need to manually create or edit specific configurations in the application server's registry.
For more information on the various keys and their values, see iPlanet Application Server Registry Guide.
Many of these configuration tasks are described in several chapters in this guide. In this chapter, the following basic configuration tasks that you can perform using kregedit are discussed:
The following sections describe how to perform basic administrative tasks using kregedit:
To Add a Value To iPlanet Registry
iPlanet Registry contains several keys, each representing a folder. The values that are contained in these keys are accessed by various tools and servers such as the Administration Tool, Deployment Tool, Web-connector Plug-in and Directory Server.
To add a key to iPlanet Registry, perform the following tasks:
- Select the key under which you want to create a new key.
- Click Edit>Add Key. Provide a name for the key and click OK.
- To add a value to this key, select the key and from the Edit menu, choose Add Value. The Add Value dialog box appears as shown below:
- In the Name field, specify a name for the value.
Example 1: If you are creating a value that will point to an application path, type AppPath.
Example 2: If you are specifying the number of auto starts for a server, type AutoStart.
- In the Value field, provide a value for the key, as required.
If you are specifying a class path, as indicated in example 1 above, type in the class path, that looks similar to the following example:
If you are specifying the number of auto starts for a server, as given in example 2 above, type a number, for example, 1.
- In the Type field, select either String or Integer, based on the type of the value you have specified.
For example, if the value is a class path, select String from the Type drop-down list.
If the value is a number that indicates, for example, the number of auto restarts specified for a server, select Integer from the Type drop-down list.
- Click OK to register the value in iPlanet Registry.
To Modify a Value in iPlanet Registry
To modify a value in iPlanet Registry, perform the following tasks:
- Select the value that you want to modify.
- Double-click the entry or click Edit>Modify Value. The following dialog box appears:
- Modify the value and click OK.
Note In the Modify Value dialog box, you can modify only the value specified for the key. You can't modify the type of value, which could be either String or Integer. If you want to modify the value type specification, you need to delete the value and add it again.
To Find and Replace Values in iPlanet Registry
You can find and replace values in iPlanet Registry, using the Find/Replace menu option. You can find and replace a value that occurs within a particular sub-tree or replace all the occurrences of that value in the entire registry.
To find and replace a value in iPlanet Registry, perform the following tasks:
- From the Edit menu, choose Find/Replace.
- In the Find text field, specify the value that you want to find in Iplanet Registry. If you want to change only a part of the value, specify only that part. For example, if you want to replace iPlanet.com with Sun.com, you can type just iPlanet.
- In the Replace with field, specify the value with which you want to replace the existing value. For example, to replace iPlanet. com with Sun.com, type just Sun. The rest of the value will automatically be retained.
- Click String, if the value you are searching for is a string, such as a classpath.
- Click Integer, if the value you are searching for is an integer, such as 1.
- Mark the Case Sensitive text box, to search for occurrence(s) of the required item that conform to the format of your find input.
- Mark the Confirm before Replacing checkbox, if you want to be prompted for confirmation before the required value is replaced in iPlanet Registry. When you choose this option, you will be asked for confirmation before the any value is replaced in iPlanet Registry.
Note iPlanet Registry holds a lot of critical information on which the various engines and processes depend. It is strongly recommended that you choose this option before confirming the find/replace action.
- Mark the Find/Replace in Entire Registry checkbox, to find and replace all occurrences of the required value in the entire registry. Marking this checkbox ensures that the find/replace function is not restricted to a single tree or sub-tree.
- Click OK to begin the find/replace action.
When the find/replace action is complete, you will see a confirmation dialog showing the search results and replacements made. This dialog will give you a complete list of all the replacements that were made, along with complete tree structure of the keys whose values were replaced.
To Update the Installation Key
If you installed iPlanet Application Server with an evaluation license, the server stops running at the end of the evaluation period. You will need to update the installation key if you have extended the evaluation period or purchased the server. Updating the installation key saves you from having to reinstall the server software and reconfigure the environment.
To reset the installation key, perform the following tasks:
- Shutdown iPlanet Application Server.
- Open iPlanet Registry Editor.
(See About iPlanet Registry Editor.)
The following window appears:
- Open the following key:
- Double-click the Key String value and enter the new Installation Key value.
- Click OK.
- Close the registry editor.
- Restart iPlanet Application Server.
To Change the IP Address
When the IP Address of a machine on which iPlanet Application Server has been installed changes, such as when the machine is moved or has been assigned to a different network, you need to replace the old IP Address with the new IP Address.
You need to replace the IP Address in the local iPlanet Registry of each instance of iPlanet Application Server. This is to let the network know the current IP Address of your machine.
If you have installed iPlanet Console 5.0 on your machine, you need to let the other machines on the network know from where the iPlanet Console Administration Server can be accessed.
The procedure for changing the IP Address is described in the following sections:
To Modify IP Address in the Local iPlanet Registry
You can update the new IP Address in iPlanet registry using iPlanet Registry Editor, kregedit. When you do this, the IP Address is updated in both the local registry and in the Directory Server that stores your machine's configuration.
Note Multiple instances of iPlanet Application Server are supported on Solaris machines. If you have installed multiple instances of iPlanet Application Server, you need to replace the old IP Address with the new IP Address in the iPlanet Registry of each instance.
To change the IP address in iPlanet registry, perform the following tasks:
- Start iPlanet Registry Editor
(See About iPlanet Registry Editor.)
- Select the following key:
This is the root key. You need to select this key, to update all occurrences of the old IP Address, in the entire registry
- From the Edit menu, choose Change IP Address in sub-tree.
The Change IP Address in sub-tree dialog box appears:
- In the Old IP text field, enter the old IP Address.
- In the New IP text field, enter the new IP Address.
- Click OK to save your changes.
- If you enter the IP address along with the Port number (for example, 22.214.171.124:10818), in the Change IP Address in sub-tree dialog box, only the IP Address will be extracted, validated and replaced in iPlanet Registry.
- To ensure that all occurrences of the old IP Address have been replaced in the registry, use the Find/Replace option from the Edit menu. Note that though this option checks for the correctness of the IP Address format, it does not validate the IP Address before replacing it in iPlanet Registry.
To Update IP Address of iPlanet Console Administration Server
iPlanet Console 6.5 performs common server administration functions such as stopping and starting servers, installing new server instances, and managing user and group information through the LDAP services of Directory Server. Using iPlanet Console, you can manage remote instances of Directory Server that might exist on your network.
iPlanet Console comes with its own Administration Server, which is used internally by iPlanet Console. If iPlanet Console is installed on your machine, you need to ensure that all the machines in your network know the correct nsserveraddress (iPlanet Console Administration Server's IP Address) and the nsadminaccessaddress (the IP Address of the machine from which the iPlanet Console Administration Server can be accessed).
The nsserveraddress for the iPlanet Console Administration server is stored in two locations; Directory Server and the local configuration file of iPlanet Console.
The nsadminaccessaddress is stored only in the local configuration file of iPlanet Console.
The following sections describe how you can change the nsserveraddress and the nsadminaccessaddress:
To Modify IP Address in Directory Server
To change the nsserveraddress in Directory Server, perform the following tasks:
- Go to <iASInstallDir>/slapd-<hostname> and run the following script:
This script generates an LDIF (LDAP Data Interchangeable Format) file, whose preliminary filename will bear the stamp of the date and time it was generated, in the YYYY-MM-DD format. For example, an LDIF file generated on 3rd June 2001 at 14 hours, 2 minutes and 38 seconds will look like this:
- Go to <iASInstallDir>/slapd-<hostname>/ldif and locate the LDIF file with the latest date and time stamp.
- Open the LDIF file (using any text editor) and search for the nsserveraddress entry. Replace the old IP Address with the new one. Note that you will need to search for all occurrences of the old IP Address and replace with the new one, to ensure that the change is complete.
- Stop the Directory Server, by performing the following tasks:
- From the Start menu, choose Settings>Control Panel.
- Double-click the Services icon
- In the Services window, select iPlanet Directory Server.
- Click Stop to stop the server.
- Navigate to the <iASInstallDir>/slapd-<hostname> path.
- Run the following script:
The Directory Server stops.
- The next step is to write the LDIF file to the Directory Server. To do this, go to <iASInstallDir>/slapd-<hostname> and run the following script:
ldif2db -i ldif/<path>/<filename>.ldif
When you run this script, the changes made to the file are recorded in Directory Server.
- Start the Directory Server.
To start Directory Server, follow the procedure described in Step 4 above. For Windows, click Start in the Services window to start the server. For Solaris, run the script start-slapd to start the server.
Note Check the log files that are stored in the following path, to make sure that all occurrences of the old IP Address have been replaced in the Directory Server:
To Modify IP Address in Local Configuration File
To change the IP Address in the local configuration file(s) of the iPlanet Console Administration Server, perform the following tasks:
- Go to <iASInstallDir>/admin-serv/config and open the local.conf file, using any text editor.
- Locate nsserveraddress entries and change the IP Address value in them. The entries will look like this: configuration.nsserveraddress.126.96.36.199.
- Locate nsadminaccessaddress entries if any and change the IP Address value. The entries will look like this: configuration.nsadminaccessaddress.188.8.131.52.
- Stop and start the iPlanet Console Administration Server, by performing the following tasks
- Go to <iASInstallDir>/ and double-click the stop-admin executable to stop the server.
- Double-click the start-admin executable to start the server.
- Go to <iASInstallDir/> and run the stop-admin script to start the server.
- To start the server, run the start-admin script from the same path.
- If multiple instances of iPlanet Application Server have been installed on a single host (supported only on Solaris machines), a local configuration file is present for each instance. When the IP Address changes, you need to update the required entries in the local configuration file for each instance of iPlanet Application Server.
- If you have installed multiple instances of iPlanet Application Server on your machine, you need to stop and start the iPlanet Administration Server for each instance, for the changes to take effect.
Configuring Multiple LDAP Domains
iPlanet Application Server supports multiple LDAP domain names, based on the Nortel LDAP schema.
A user can now use different domain names such as, firstname.lastname@example.org, to log on to an application. Each domain name that a user is associated with is entered into the directory server.
To use multiple domains, you need to add the new domain name(s) to iPlanet registry and create the corresponding backend entries in the directory server. This can be done on both Solaris and Windows.
This section includes the following topics:
To Add a Domain Name to iPlanet Registry.
To add a domain name to iPlanet registry, perform the following tasks:
- Open the iPlanet Registry Editor.
(See About iPlanet Registry Editor.)
- Open the following key:
- Create a subkey using a new domain name, for example, iPlanet.
- Select the new domain name and from the Edit menu, choose Edit>Add Value.
The Add Value dialog box appears, as shown in the figure:
- In the Name text field, provide a name for the value, for example, Backend.
- In the Value field, specify a value, for example, LDAPBackend2.
The value you specify here must find a corresponding value of the same name in the directory server.
For more information, refer to "To Configure a New Domain Name in Directory Server.
- Click OK to register the value in iPlanet Registry.
You now need to create a second value for the domain subkey, as described in the following steps.
- Select the new domain key, and choose Add Value from the Edit menu.
- In the Add Value dialog box, provide a name, for example, Repository.
- Specify a value, for example, 1. Select Integer from the Type drop-down list.
You have now defined a new domain name in iPlanet Registry. When you complete the process of defining a new domain name in iPlanet Registry, your entries must look like the following example:
To Configure a New Domain Name in Directory Server
After you define the new domain name in iPlanet Registry, you need to configure the domain name in Directory Server. The domain name entries in iPlanet Registry will point to the entries that you create in Directory Server.
To configure the new domain name in Directory Server, perform the following tasks:
- In iPlanet registry, open the key Software/iPlanet/Application Server/GDS/Backends/LDAP/
- Create a subkey with the same value that you specified under Software/iPlanet/Application Server/6.5/Principal, i.e, LDAPBackend1.
- Create a value for this subkey, which defines the attributes of the Common Name (cn) that is defined in Directory Server. For example: root=cn=global,cn=iasconfig,cn=iAScluster,O=NetscapeRoot.
- Create a new subkey under the key LDAPBackend1, for example 0.
- Create the following values for the subkey 0.
- UserPath = ou=People, O=<new domain>
This procedure configures the back-end entries for the new domain name in the Directory Server.
Note You need an encrypted password when you login using your new domain name, through which you are identified by Directory Server. You can generate an encrypted password by running the following script:
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated November 25, 2002