Previous Contents Index Next |
iPlanet Application Server Administrator's Guide |
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)
Performing Administrative Tasks Using iASAT
Performing Administrative Tasks Using Command-Line Tools
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 Windows: From the Start menu, choose Programs> iPlanet Application Server 6.5> iPlanet Application Server Administration Tool.
On a Solaris system: Open a Terminal window and navigate to the path <iASInstallDir>/ias/bin/ and type the following at the command prompt:
- ksvradmin &
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
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.When you install iPlanet Application Server, the local host is automatically registered with iASAT.
Note iPlanet Application Server must be registered with iASAT, before you can administer it.
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.
Complete one of the following:
In the Name text box, specify the name of the server.
In the Host text box, specify the host name of the server.
Click Local Host to register a server running on your local machine.
- 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.
- This automatically enters a server name and your machine name.
In the Port text box, specify the port number of the Administration Server. In a default installation, this port is set to 10817.
- This is the DNS name of your server machine. You can also use an IP address.
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.
(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.
- 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.
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.
Select the server you want to delete.
- A list of all registered application servers is displayed.
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.
iascontrol
You can stop or start a server using command line tools, on both Windows and Solaris systems by performing the following tasks:
On Windows, choose Run from the Start menu.
Run the following script:Type-in iascontrol in the Run field.
On Solaris systems, navigate to iASInstallDir\ias\bin\ directory.
iascontrol subcommand -instance <instance> -user <user> -password <password> -host <host> -port <port> -eng <engineId>
where subcommand can be one of the following:
The following parameters apply:
Starting a specific instance of iPlanet Application Server engine:
Starting an engine within a specified instance of iPlanet Application Server.
- 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 associated with a specified instance.
- 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 specific instance on the local host.
- 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.
Note KAS must be running on the specified instance before running this command.
- 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.
Stopping the engines of a specified instance.
4. Stopping specified engines associated with an instance on the local host.
Stopping specific engines on the local host.
- 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 a specific instance of iPlanet Application Server.
- iascontrol stop -eng 1
- This command stops specified engines on the local host. However, KAS continues to run.
- iascontrol stop -instance prodnode1 -eng 2
- This command stops the specified engines associated with an instance called prodnode1. However, KAS continues to run.
- 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:
You will see one of these codes displayed on your terminal window when you execute any of the given commands.
- iascontrol stop -instance prodnode1 -user admin1 -password admin -host prodserver -port 10817
1 - could not contact one or more of the specified servers.
2 - authentication/authorization failed against one or more of the specified servers.
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.
We recommend that you do not change the values in the iasenv.ksh script unless absolutely necessary.
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.
Note As Solaris supports multiple instances of iPlanet Application Server, each instance has its own registry. Ensure that you start kregedit from where the instance you want is installed.
On Windows, click Start>Run. Type kregedit and click OK.
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
To Modify a Value in iPlanet Registry
To Find and Replace Values in iPlanet Registry
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.
In the Value field, provide a value for the key, as required.
- 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 Type field, select either String or Integer, based on the type of the value you have specified.
- 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:
- c:\iplanet\ias6\ias.
- If you are specifying the number of auto starts for a server, as given in example 2 above, type a number, for example, 1.
Click OK to register the value in iPlanet Registry.
- 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.
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.
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.
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.
Note If you do not mark this checkbox, only the selected sub-tree will be searched for the required value.
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 the following key:
Double-click the Key String value and enter the new Installation Key value.
- SOFTWARE\iPlanet\Application Server\6.5\CCS0\ENG
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
To Update IP Address of iPlanet Console Administration Server
Note If iPlanet Console Administration Server is not installed on your machine, you can ignore the second section.
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.
To change the IP address in iPlanet registry, perform the following tasks:
Start iPlanet Registry Editor
Select the following key:
- (See About iPlanet Registry Editor.)
From the Edit menu, choose Change IP Address in sub-tree.
- SOFTWARE\iPlanet
- This is the root key. You need to select this key, to update all occurrences of the old IP Address, in the entire registry
In the Old IP text field, enter the old IP Address.
In the New IP text field, enter the new IP Address.
Note The IP Address you enter must be of this format: 129.29.191.128. Each sequence of digits must be separated with a dot.
Click OK to save your changes.
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 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:
Go to <iASInstallDir>/slapd-<hostname>/ldif and locate the LDIF file with the latest date and time stamp.
- db2ldif
- 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:
- 2001_06_03_140238.ldif.
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:
- On Windows:
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.
- On Solaris:
Navigate to the <iASInstallDir>/slapd-<hostname> path.
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:
- stop-slapd
- The Directory Server stops.
Start the Directory Server.
- ldif2db -i ldif/<path>/<filename>.ldif
- When you run this script, the changes made to the file are recorded in 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.
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.129.158.228.63.
Locate nsadminaccessaddress entries if any and change the IP Address value. The entries will look like this: configuration.nsadminaccessaddress.129.158.228.63.
Stop and start the iPlanet Console Administration Server, by performing the following tasks
- On Windows:
Go to <iASInstallDir>/ and double-click the stop-admin executable to stop the server.
Double-click the start-admin executable to start the server.
- On Solaris
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.
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, john.doe@acme.com, 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.
To add a domain name to iPlanet registry, perform the following tasks:
Open the iPlanet Registry Editor.
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:
Open the following key:
- (See About iPlanet Registry Editor.)
Create a subkey using a new domain name, for example, iPlanet.
- Software/iPlanet/Application Server/6.5/Principal
Select the new domain name and from the Edit menu, choose Edit>Add Value.
In the Name text field, provide a name for the value, for example, Backend.
In the Value field, specify a value, for example, LDAPBackend2.
Click OK to register the value in iPlanet Registry.
- 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.
Select the new domain key, and choose Add Value from the Edit menu.
- You now need to create a second value for the domain subkey, as described in the following steps.
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.
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/
This procedure configures the back-end entries for the new domain name in the Directory Server.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.
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated March 06, 2002