Sun Java System Web Server 7.0 Update 8 Troubleshooting Guide

Chapter 4 Administration Server And Nodes

Running Administration Server As Non-Root

Problem: Unable to bind at port <port_number>.

The administration server and the administration nodes should be run by the same user id in Unix. This is because of the following reason:

  1. If the instances are running as part of the root process, the Administration Server will not have sufficient permissions to modify the instance's configuration files, if it is not running as part of the root process.

So for the administration server to perform its job of maintaining the server instances, it either needs to be part of the root process or at least the same user as that of the server instance. However in Solaris 10, you don't need to run the Administration Server as root to bind to port 80 (or < 1024). Execute the following commands:

# su
# /usr/sbin/usermod -K defaultpriv=basic,net_privaddr webservd

Pulling Configuration Changes to the Administration Server

Whenever you make manual changes to the configuration, you should replicate the changes back into the Administration server repository as follows:

  1. Manually edit server instance's configuration files as you would do with the earlier version of Web Server (Not Recommended).

  2. Start the Web Server 7.0 Administration Server. See the Administrator's Guide.

  3. For pulling the changes back to the Administration Server repository, execute the following command.

    wadm> pull-config --user=admin --config=CONFIG_NAME

Note –

The operation may take some time depending on the configuration.

Note –

Always use the Administration Console or the wadm CLI to edit the settings.

Making Changes to server.policy File

If you are deploying your web site containing Java web applications and would like to enable security manager within the web container, then you will need to edit the server instance's server.policy file. In this scenario, Administration Server does not provide a direct command line interface or GUI to edit this server.policy file. But you can still perform the steps as mentioned in the previous section to make any manual edit to the server.policy file.

Deployment Pending Message in Administration Console


When I make changes to a configuration from the GUI, I see a deployment pending message. What does it mean?


The deployment pending message indicates that there are changes to the configuration that are saved into the administration server's configuration store. You need to click the Deploy button to save these changes to the instances.

Save and Deploy — Two Different Actions


What is the difference between the Save and Deploy buttons that shows up on every page in the Administration Console within a configuration?


If you click on Save, then the changes that you have made through the Administration Console pages are saved only in the configuration store. When you click the Deploy button, the changes will be saved to the instances. Always use the Deploy button to persist your changes to the running instances.

Manually Editing Configuration Files


Can I make manual edits to my configuration files? Will these be reflected in the CLI and GUI?


If you need to make manual changes to the configuration files, make the changes within the configuration store. These changes will be reflected in the CLI and GUI and can be deployed using the deploy-config command or by clicking on Deploy button in the GUI. But if you make changes directly in the instance, the Administration Console will show up a warning stating that there are manual modifications to the configuration files and you need to either overwrite these changes with the configuration in the configuration store or else get these changes back into the configuration store overwriting the existing configuration changes.

Note –

Always use the Administration Console or the wadm CLI to edit the settings.

Where Are My Changes?


I have made changes to my configuration files in the configuration store. I could not see the configuration effected by my changes.


Have you executed deploy-config command? (Manually Editing Configuration Files). Log in to the Administration Console and go that particular configuration. Do you notice a 'Deployment Pending' Message? (Deployment Pending Message in Administration Console).

deploy-config Command Fails


Sometimes the deploy-config fails saying that a server restart is needed. Why?


When deploy-config is invoked, the configuration changes in the configuration store are propagated to the instances and the running servers are re-configured so that the configuration changes are picked up. But certain changes cannot be applied dynamically and need a server restart. You will hence need to run a restart-instance command in order to restart the server instances.

Where Can I Find wadm CLI?

If you are using wadm CLI on the same machine where the Administration Server is installed, then you do not need to know the Administration Server's port number. You are required to know the port number only if you have configured Administration Node and need to use wadm CLI to connect to a remote Administration Server.


Where can I find the CLI for Sun Java System Web Server 7.0 administration?


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

Note –

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.

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:

Table 4–1 Sample wadm Scripts





Enables SSL on a given virtual server and port. 

wadm -f enable-ssl.tcl <config> <vs> <server> <port>


Fetches the matching MIME types from the given configuration and virtual server. 

wadm -f filter-mime.tcl "<regex>" <config> <vs>


Removes the matching MIME types from the given configuration and virtual server. 

wadm -f remove-mime.tcl "<regex>" <config> <vs>


Adds the specified extension to the matching MIME types in the given configuration and virtual server. 

wadm -f add-mime-ext.tcl "<regex>" "ext" <config> <vs>


Provides a summary of the installation. It contains list of listeners, ports, and SSL status. 

wadm -f summary.tcl


Provides a summary of all the deployed web applications. 

wadm -f list-webapps.tcl


Provides a collated logs across multiple nodes. 

wadm -f collate-logs.tcl <config> <node1> <node2> ..


Allows renewal of self signed certificates with a given nickname 

wadm -f renew-selfsigned-cert.tcl <config> <cert-nickname> [<validity>]

Enabling SSL Port on Windows Firewall

On windows, if the firewall is enabled on the node it does not allow any inbound request. The administration server does not respond for a while. This will happen for every node related operation. To troubleshoot this problem, you should perform the following steps:

ProcedureTo Enable Administration Node SSL Port on Windows

  1. Start > Settings > Control Panel

  2. Click the Windows Firewall icon

    A window appears.

  3. Click the Exceptions tab

  4. Click the Add Port button

    A window appears.

  5. Enter the name in Name field

  6. Enter the Administration Server's port number in Port field

  7. Select the TCP option

  8. Click the OK button.

Setting up LDAP Over SSL Through the Admin Console

When an administrator tries to setup an authentication database to a LDAPS server for their web server access control. If the LDAP server is setup to use SSL and has a self signed certificate, or is a certificate from a non-CA authority then the error will occur in the admin gui. This error is misleading because in reality the server instance is able to connect to the LDAP server given the CA certificate from the LDAPS server has been installed as trusted in the certificate database for the server instance. What administrators often miss is that the CA certificate has not been trusted for the administrator server's trust database and so the admin reports the following error.

"ADMIN3120: Could not connect to LDAP server"

For troubleshooting, the administrator needs to check the certificate authorities for both the administrator server and the server instance to make sure that the CA certificate that signed the LDAP server's SSL certificate is installed and trusted for the administration server via Nodes->Administration server->Certificate Authorities-> Install and also for the web instance.