Chapter 1 Getting Started

This chapter describes the basics of Sun Java System Web Server 7.0 by providing a brief description of terms used in this guide.

• Introduction

• What is New?

• Starting the Administration Server

• Different Ways of Administering Your Server

• Using Administration Console

• Using CLI

• Understanding Web Server 7.0

Introduction

Web Server is a multi-process, multi-threaded, secure web server built on industry standards. It provides high performance, reliability, scalability, and manageability for medium to large enterprises.

Web Server provides comprehensive command-line interface support, consolidated configuration, enhanced security with Elliptic Curve Cryptography support, and clustering support. It also comes with a robust built-in migration tool that helps migrate applications and configurations from Web Server 6.0 and 6.1 to Web Server .

What is New?

See Chapter 1, Sun Java System Web Server Release Notes, in Sun Java System Web Server 7.0 Update 3 Release Notes for more information on the new features and enhancements in Sun Java System Web Server 7.0.

Starting the Administration Server

In order to use the administration interface, you need to start the Administration Server.

Starting the Administration Server in Unix/Linux

To start the Administration Server perform the following tasks:

Starting the Administration Server in Unix/Linux

1. Go to the install_root/admin-server/bin directory (for example, /usr/sjsws7.0/admin-server/bin)

2. Type ./startserv.

   This command starts the Administration Server using the port number you specified during installation.

Starting the Administration Server in Windows

The Web Server installation program creates a program group with several icons for Windows platforms. The program group includes the following icons:

• Release Notes

• Start Administration Server

• Uninstall Web Server

Note that the Administration Server runs as a services applet; thus, you can also use the Control Panel to start this service directly.

Different Ways of Administering Your Server

You can manage your Web Server by using the following user interfaces:

• Administration Console (GUI).

• Command Line Interface (wadm shell).

You can either use the wadm shell interface (discussed later in this chapter) or the web based Administration Console for managing your instances. Note that the Administration Node can have only one instance of a particular Configuration running.

Using Administration Console

After installing Web Server , use your browser to access the Administration Console.

The URL you use to navigate to the Administration Server page depends on the computer host name and the port number you choose for the Administration Server when you install Web Server . For example, if you installed the Administration Server with SSL port 1234, the URL will look like this:

https://myserver.sun.com:1234/

You need to log in to the Administration Console to perform server administration. You set up the administrator user name and password when you install Web Server on your computer. The following figure shows the authentication screen:

The first page you see when you access the Administration Server, is the common tasks page. You use the buttons on this page to manage, add, remove, and migrate your servers. The common tasks page is shown in the following figure:

Clicking any of these tabs may result in child tabs appearing on the page. The actions provided by the child tabs are specific to the parent tab functionality.

The following figure shows the child tabs for a selected tab:

Clicking on the tab opens pages in the same window. There are certain tasks that involves gathering data from the user in series of steps. The Administration Console has wizard interface for such tasks. These wizards always open up in a new window.

Help on Administration Console GUI Screens

All form elements and GUI components have a detailed inline help providing information on the validation and optional parameters. For wizard interface, at any step in the wizard, click on the help tab to get the help specific to the current task.

Using CLI

This section describes the Command Line Interface for Web Server and defines all the commands supported for configuring and administering the server.

Web Server introduces a new CLI called as wadm.

The earlier version of the server supported a few discrete command lines, which together addressed only a subset of whole administration functionality provided in GUI. Command line interfaces supported in Web Server 6.1 were HttpServerAdmin, wdeploy and flexanlg. The new CLI (wadm) features:

• Embedded JACL shell for scripting.

• Extensible CLI — more commands can be added to the CLI by third party plug-ins.

Web Server does not support HttpServerAdmin.

wdeploy is supported in Web Server only for backward compatibility with 6.x versions and will work only on the Administration Server node.

Modes of CLI

wadm supports invocation in 3 different modes. They are:

• Standalone mode — In this mode, you invoke wadm from a command shell, specifying the desired command, options and operands. When the command finishes execution, CLI exits back to the shell. This mode can support both interactive and non-interactive execution of commands. Interactive execution, which is the default, will prompt for the password if password is not already specified in the password file (passed through the --password-file option). Non-interactive execution will result in an error if --password-file option is not specified.

  For example,

  • Non-interactive Standalone mode

    bash-3.00# cat /passwd wadm_password=mypassword bash-3.00# /opt/sun7ur2websvr/bin/wadm list-configs --user=admin --port=8800 --no-ssl --password-file=/passwd instance1

  • Interactive Standalone mode

    bash-3.00# /opt/sun7ur2websvr/bin/wadm list-configs --user=admin --port=8800 --no-ssl Please enter admin-user-password> instance1

• Shell Mode — In this mode, you invoke wadm from a command shell with no command. wadm prompts the user for a command. After the command is executed, it will return back to the shell. This shell can be exited by typing exit or quit command. Interactive and non-interactive executions are applicable to this mode. For example,

  bash-3.00# /opt/sun7ur2websvr/bin/wadm --user=admin --port=8800 --host=serverhost --no-ssl Please enter admin-user-password> Connected to serverhost:8800 Sun Java System Web Server 7.0U2 B12/09/2007 07:28 wadm> list-configs instance1 wadm> list-jvm-options --config=instance1 -Djava.security.auth.login.config=login.conf -Xms128m -Xmx256m wadm> list-instances --config=instance1 sunhost1.sun.com wadm> quit bash#

• File Mode — In this mode, you can add a list of commands in a file and pass the file as an argument to wadm. For example,

  wadm -user=admin -host=serverhost --password-file=admin.pwd --port=8989 -commands-file=/space/scripts/admscr

The figure below depicts the syntax for invoking wadm commands.

With the wadm CLI, you can perform all of tasks that you can do with the Administration Console.

Where Can I Find wadm CLI?

Where can I find the CLI for Web Server administration?

The administration CLI is located at install-root/bin/wadm. To use the CLI, you need to know:

• Administration server hostname (default is localhost).

• SSL port for the administration server (default is 8989).

• Administration server user name (default is admin).

• Administration server password.

Administration server needs to be running in order to use the CLI. You can start the server by running install-root/admin-server/bin/startserv.

Authentication in CLI

wadm will use username and password of the administrator to authenticate to Administration Server. A valid username and password file must be passed as arguments to each command running in single mode. Shell mode accepts username and password file when wadm executable is invoked. Commands invoked in the shell mode do not require the connection options (for example, user, password-file, host, port and ssl). If specified, they will be ignored.

Some commands supported by the CLI require password inputs. For example, bindpw, user-password and token-pin. User can specify these passwords in the same file that contains the administration user password. If the password-file is not specified with the command, then user will be prompted for the password.

The wadm communicates with the Administration Server through SSL, if SSL is enabled on Administration Server. The Certificate passed by the Administration Server will be verified against the truststore (~/.wadmtruststore). If the certificate exists and is valid, the command proceeds normally. Otherwise, wadm displays the certificate and gives the user the choice of accepting it. If the user accepts it, the certificate will be added to the truststore and the command proceeds normally.

truststore need not be password protected since it does not contain any sensitive data.

Resetting the Administration Password

Open a command prompt terminal and navigate to install-root/bin/wadm directory and type the following command to reset the password:

./wadm reset-admin-password.

You will be prompted to type the new admin password. Type the password again to confirm. Restart the server for password to take effect. Now, use the new password to login to the server.

While changing the password using set-admin-prop command. You must restart the Administration Server from install-root/admin-server/bin/restart directory. Do not use restart-admin command to restart the server.

Registering with Sun Connection

You can use the Admin Console to register the Web Server with Sun Connection. Click the Register with Sun Connection tab from the home page, a wizard opens up. Follow the wizard to complete the registration. By registering the Web Server with Sun Connection you receive the following benefits.

• Patch information and bug updates

• News and events

• Support and training offerings

CLI Scripts

install-root/samples/admin/scripts directory contains scripts that you can run using the wadm command line utility. wadm is built on a TCLengine and hence supports TCL scripting. These scripts can be used to perform common administrative tasks. They also demonstrate how new utilities can be built on top of existing commands.

The following table describes the scripts:

Understanding Web Server 7.0

Web Server includes a new administration framework that provides enhanced distributed management across servers in a server farm. Robust administration capabilities enable Web Servers to be managed and deployed remotely using both graphical and command-line interfaces. Servers can be managed on a central location in a server farm and distributed to one or more nodes to create server instances. Monitoring and lifecycle management of these server instances are also provided.

Web Server is configured to enable you to turn on or off various features, determine how to respond to individual client requests, and write programs that run on and interact with the server’s operation. The instructions (called directives) that identifies these options are stored in configuration files. Web Server reads the configuration files on startup and during client requests to map your choices with the desired server activity.

For more information about these files, see the Web Server Administrator’s Configuration File Reference Guide.

In Web Server all configurable elements of a server instance like web applications, configuration files, and search collection indexes are logically grouped and termed as a Configuration. A Configuration can be created, modified or deleted using CLI or the web based administration interface. You can manage more then one Configuration at a time. The term Configuration also refers to the set of metadata that configures the runtime services of the server. For example, a runtime service serves web pages from a configured document root. The configuration metadata is used by the server runtime to load built-in services, third party plug-ins and setup other server extensions such as database drivers for serving web pages and dynamic web applications.

All the Configuration related files are stored in a repository in your file system called as Configuration Store. You must refrain from manually editing any of the files in this repository unless explicitly specified in this guide.

In Web Server, any change to the Configuration using the CLI or through the web based administration interface is first made to the Configuration Store and then the Configuration is deployed. Consequently the changes are copied to the instance directory. When a web application is deployed it gets deployed under:

<install_dir>/admin-server/config-store/<config_name>/web-app/<virtual_servername>/

When you deploy a configuration, the entire web application directory and configuration directory under config-store is zipped up and copied to the server instance directory. This file is the current.zip file under:

<install_dir>/admin-server/config-store/<config_name>

Hence depending on the size of the web application, deploying a selected configuration might take some time to complete.

The following figure shows a schematic diagram of how Configurations are deployed to Administration Nodes:

When you deploy a Configuration to a Node (Network resource, such as server or a host), an Instance of that Configuration is created. The instance contains log files and other runtime files such as lock databases, caches and temporary files that are required by the instance. You can manage these instances through the CLI or web based administration interface.

Instances can also span across one or more nodes to form a Cluster. In case of a cluster, all nodes that form the cluster must have identical configuration. All nodes in a cluster must be homogenous. They must have the same operating system, be identically configured, and offer the same services.

One node in the server farm has a server running on which the administration application is deployed. This specially configured server is called the Administration Server and the administration application that is deployed is the web based Administration Console. You use the Administration Console to control the lifecycle of your server instances.

The Administration Server controls the actions of other servers in that node called as Administration Nodes. An administration node does not provide a GUI interface. One node in the server farm has the Administration Server installed. All other nodes in the server farm have Administration Nodes installed. An administration Node is registered with an Administration Server upon installation. This action will make the Administration Server aware of that Administration Node.

The Administration server and the administration node always communicate over SSL. The Administration Server and Administration Node authenticate each other by the Administration Server trusting the Administration Node's server certificate and the Administration Node trusting the client certificate presented by the Administration Server. During registration of an Administration Node, the Administration Server will generate a server certificate for that Administration Node, which is then downloaded and installed on the Administration Node. The issuer of the server certificate is also installed on the Administration Node.