Previous     Contents     Index     DocHome     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)

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 (Java).

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.0> 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

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.

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:

  1. On the iASAT toolbar, click General to open the General window.

  2. From the File menu, click New>Server.

    The New iPlanet Application Server dialog box appears.



  3. 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 server from another. For instance, you might name the servers in your enterprise according to their host name, such as Bozo1, Bozo2, Bozo3.

    • Click Local Host to register a server running on your local machine.

      This automatically enters a server name and your machine name.

  4. 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.

  5. In the Port text box, specify the port number for the Administrative Server. During installation this is set to 10817 by default.

  6. 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.

  7. (Optional) To always connect to the server and display it in the Enterprise window, mark the "Connect to this server" checkbox.

  8. Click OK to register the server.


To Unregister an iPlanet Application Server

When a server is no longer available, you can remove it from the scope of the enterprise.

To unregister, or delete an iPlanet Application Server machine, perform the following tasks:

  1. On the iASAT toolbar, click General to open the General window.

  2. In the left pane of the General window, double-click All Registered Servers.

    A list of all registered servers in the enterprise appears.

  3. Select the server you want to delete.

  4. 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 manually stop iPlanet Application Server or if the server crashes, you can start the server from iASAT by performing the following tasks:

  1. Click General on the iASAT toolbar to open the General window.

  2. In the left pane of the General window, select the server you want to start.

  3. In the right pane of the General window, click Start Server.

To stop a server, select the server you want to stop and click Stop Server from the right pane of the General window.


Note You can expand the servers in the hierarchical tree only when they are running




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.

For a complete list of all the command-line tools that you can use to administer iPlanet Application Server, see Administering Distributed Transactions from the Command Line.

To get a complete description of any command-line tool, type the command at the prompt, insert a space and type -help. For example, to get a complete list of all the options that you can try with the iascontrol command, type iascontrol-help at the command line prompt.



Using Command-Line Tools


The usage of iPlanet Application Server's command-line tools is different for Windows and Solaris platforms. Most of the command-line tools have been integrated with the iPlanet Application Server Administration Tool and the iPlanet Application Server Deployment Tool, for ease of use.

On Solaris, even though the iPlanet Application Server Administration Tool and the iPlanet Application Server Deployment Tools are available, the usage of command-line tools is quite extensive. As you can have multiple instances of iPlanet Application Server on Solaris, it becomes necessary at times to execute command-line tools from the installation directory of a specific instance of iPlanet Application Server, to modify the attributes of only that 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.

There are many command-line tools that can be used to administer iPlanet Application Server. These are described in different chapters in this guide. The following section describes how you can stop and start 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 Windows, choose Run from the Start menu.

  • On a Solaris systems, navigate to the <iASInstallDir>\ias\bin\ path.

Run the following script:

iascontrol subcommand -instance<instance> -user<user> -password <password> -host<host> -port<port>

where subcommand can be one of the following:
start

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.

stop

Stops the engines of an application server. The administration server is not stopped.

kill

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:
instance

Name of the server instance that you want to stop or start. The server instance must be registered in iASAT.

user

Name of the user that is authorized to start, stop or kill the server instance. The user must be registered with iASAT

password

The password associated with the user

host

The hostname or IP address of the server instance you want to start, stop or kill

port

The port number of the application server's administrative server. Port 10817 is the default

For example, the command to stop an iPlanet Application Server instance should look like this:

iascontrol stop -instance ias2 -user ar126587 -password suniplanet -host bozo -port 10817

Note
  • You need to register the iPlanet Application Server instance using the Administration Tool, before you use any of these commands.

  • If the User ID is longer than 8 characters, the -stop and -kill commands do not work as expected.




About iPlanet Registry Editor


The iPlanet Registry Editor is a stand-alone GUI tool that displays registry information for iPlanet products. 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. iPlanet Registry Editor displays values that are stored both in your local machine's registry and your Directory Server.


To Start iPlanet Registry Editor

To start iPlanet Registry Editor (known as kregedit), perform the following tasks:

  1. On Solaris machines, 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 navigate to the path where the instance you want is installed, before invoking iPlanet Registry.


  2. On Windows systems, click Start>Run. Type kregedit and click OK.

    The following window appears:





Performing Administrative Tasks Using iPlanet Registry Editor

Using iPlanet Registry, 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. iPlanet Registry Editor comes with a comprehensive Find/Replace option using which you find and replace multiple occurrences of the same value in iPlanet Registry.

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 iPlanet Registry, other than those done by iPlanet Application Server tools.

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 iPlanet Registry Editor are discussed:

The following sections describe how to perform basic administrative tasks using iPlanet Registry Editor


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:

  1. Select the key under which you want to create a new key.

  2. Click Edit>Add Key. Provide a name for the key and click OK.

  3. 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:



  4. 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.

  5. 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:

    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.

  6. 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.

  7. 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:

  1. Select the value that you want to modify.

  2. Double-click the entry or click Edit>Modify Value. The following dialog box appears:



  3. 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 delete a value from the registry, select the value and press Delete or click Edit>Delete. You will see a dialog box asking for delete confirmation. Click Yes to confirm the action.


    Note Once a value is deleted, it cannot be recovered.



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:

  1. From the Edit menu, choose Find/Replace.

  2. 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.

  3. 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.

  4. Click String, if the value you are searching for is a string, such as a classpath.

  5. Click Integer, if the value you are searching for is an integer, such as 1.

  6. Mark the Case Sensitive text box, to search for occurrence(s) of the required item that conform to the format of your find input.

  7. 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.


  8. 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.


  9. 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:

  1. Shutdown iPlanet Application Server.

  2. Open iPlanet Registry Editor.

    (See About iPlanet Registry Editor.)

    The following window appears:



  3. Open the following key:

    SOFTWARE\iPlanet\Application Server\6.0\CCS0\ENG

  4. Double-click the Key String value and enter the new Installation Key value.



  5. Click OK.

  6. Close the registry editor.

  7. Restart iPlanet Application Server.


Changing 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 (previously known as Netscape Console) 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:

  1. Start iPlanet Registry Editor

    (See About iPlanet Registry Editor.)

  2. Select the following key:

    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

    .

  3. From the Edit menu, choose Change IP Address in sub-tree.

    The Change IP Address in sub-tree dialog box appears:



  4. In the Old IP text field, enter the old IP Address.

  5. 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.


  6. Click OK to save your changes.


    Note
    • If you enter the IP address along with the Port number (for example, 129.29.191.128: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 (previously known as Netscape Console) 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 may 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:

  1. Go to <iASInstallDir>/slapd-<hostname> and run the following script:

    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.

  2. Go to <iASInstallDir>/slapd-<hostname>/ldif and locate the LDIF file with the latest date and time stamp.

  3. 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.

  4. Stop the Directory Server, by performing the following tasks:

    On Windows:

    1. From the Start menu, choose Settings>Control Panel.

    2. Double-click the Services icon

    3. In the Services window, select Netscape Directory Server.

    4. Click Stop to stop the server.

    On Solaris:

    1. Navigate to the <iASInstallDir>/slapd-<hostname> path.

    2. Run the following script:

      stop-slapd

      The Directory Server stops.

  5. 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.


    Note
    You need to provide the absolute path of the LDIF file in which you changed the nsserveraddress value.


  6. 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:

    <iASInstallDir>/slapd-<hostname>/logs



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:

  1. Go to <iASInstallDir>/admin-serv/config and open the local.conf file, using any text editor.

  2. Locate nsserveraddress entries and change the IP Address value in them. The entries will look like this: configuration.nsserveraddress.129.158.228.63.

  3. Locate nsadminaccessaddress entries if any and change the IP Address value. The entries will look like this: configuration.nsadminaccessaddress.129.158.228.63.

  4. Stop and start the iPlanet Console Administration Server, by performing the following tasks

    On Windows:

    1. Go to <iASInstallDir>/ and double-click the stop-admin executable to stop the server.

    2. Double-click the start-admin executable to start the server.

    On Solaris

    1. Go to <iASInstallDir/> and run the stop-admin script to start the server.

    2. To start the server, run the start-admin script from the same path.


      Note
      • 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 Netscape Administration Server for each instance, for the changes to take effect.



To Configure Support for 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 iPlanet.com, sun.com, netscape.com to log on to an application. Each domain name that a user is associated with is entered into 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:

  1. Open the iPlanet Registry Editor.

    (See About iPlanet Registry Editor.)

  2. Open the following key:

    Software/iPlanet/Application Server/6.0/Principal

  3. Create a subkey using a new domain name, for example, iPlanet.com.

  4. 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:



  5. In the Name text field, provide a name for the value, for example, Backend.

  6. In the Value field, specify a value, for example, LDAPBackend1. The value you specify here must find a corresponding value of the same name in Directory Server.

    For more information, refer to To Configure the New Domain Name in Directory Server.

  7. 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.

  8. Select the new domain key, and choose Add Value from the Edit menu.

  9. In the Add Value dialog box, provide a name, for example, Repository.

  10. 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 the 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:

  1. In iPlanet registry, open the key Software/iPlanet/Application Server/GDS/Backends/LDAP/

  2. Create a subkey with the same value that you specified under Software/iPlanet/Application Server/6.0/Principal, i.e, LDAPBackend1.

  3. 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.

  4. Create a new subkey under the key LDAPBackend1, for example 0.

  5. Create the following values for the subkey 0.

    • GroupPath = ou=Groups, o=<new domain>

    • Host = <hostname>

    • Password = <encrypted password>. See note below.

    • Port = <Directory Server Port>. The default port is 389.

    • User = cn=Directory Manager

    • 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:

<iASInstallDir>/ias/bin/kencrypt2 <text to be encrypted>

This script creates an encrypted password out of the alpha-numeric string that you provide. Your password can comprise as many characters that you want.


When you finish creating the required back-end entries for the new domain name, your entries in iPlanet Registry must look like the following example:




Previous     Contents     Index     DocHome     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated June 25, 2001