admintool

 

admintool

 

Overview

The WSDP includes the Tomcat Web Server Administration Tool (admintool), which can be used to manipulate Tomcat while it is running. One can configure hosts, realms, contexts, and connectors, or set up users and roles. To run:

  1. Generate a username and password associated with the "admin" role by editing...

    $TOMCAT_HOME/conf/tomcat-users.xml

    ...creating a file that looks something like this... 

    <user name="username" 
      password="secret" 
      roles="admin, manager" />

    This user name and password must match the user name and password in the build.properties file.

  2. Start Tomcat

  3. Start a Web browser.

  4. Pull up the administrative web application by going to:

    http://yourdomain/admin

  5. When you have finished, log out of admintool by selecting Logout from the upper pane.

 

Roles, Groups, and Users

The Tomcat server authentication service includes the following components:

Role an abstract name for the permission to access a particular set of resources. A role can be compared to a key that can open a lock. Many people might have a copy of the key, and the lock doesn't care who you are, just that you have the right key.
User an individual (or application program) identity that has been authenticated (authentication was discussed in the previous section). A user can have a set of roles associated with that identity, which entitles them to access all resources protected by those roles.
Group a set of authenticated users classified by common traits such as job title or customer profile. Groups are also associated with a set of roles, and every user that is a member of a group inherits all of the roles assigned to that group.
Realm a complete database of roles, users, and groups that identify valid users of a webapp (or a set of webapps).

 

Adding Roles Using admintool

To set up new roles for container-managed security, follow these instructions. Additions, deletions, and changes made in admintool are written to the tomcat-users.xml file.

  1. Scroll down the left pane of admintool to the User and Group Administration node.
  2. Select Role Administration.
  3. From the Roles List, select Create New Role.
  4. Enter a Role Name and Description, for example Customer or User.
  5. Select Save.

 

Adding Users Using admintool

To set up new users for container-managed security, follow these instructions. Additions, deletions, and changes made in admintool are written to the tomcat-users.xml file.

  1. Scroll down the left pane of admintool to the User and Group Administration node.
  2. Select User Administration.
  3. From the Users List, select Create New User.
  4. Enter a User Name, Password, and select a Role for the new user. If you select the admin role for the new user, the user will be able to access admintool.
  5. Select Save.

 

Problems and Fixes

     

  1. Problem

    2. After starting Tomcat, when trying to pull up page in browser, getting:

    Unable to Locate the Server localhost:8080

    Fix:

    Tomcat can take quite some time before fully loading, so first of all, make sure you've allowed at least 5 minutes for Tomcat to load before continuing troubleshooting. To verify that Tomcat is running, point your browser to http://localhost:8080. When the Tomcat index screen displays, you may continue. If the index screen does not load immediately, wait up to several minutes and then retry. If Tomcat still has not loaded, check the log files, as explained below, for further troubleshooting information.

    When Tomcat starts up, it initializes itself and then loads all the webapps in $TOMCAT_HOME/webapps. When you run Tomcat by calling startup.sh, the server messages are logged to $TOMCAT_HOME/logs/catalina.out. The progress of loading webapps can be viewed in the file $TOMCAT_HOME/logs/jwsdp_log.<date>.txt.

     

  2. Problem

    3. After running "ant install", getting the following message:

    BUILD FAILED
    /home/you/gs/build.xml:44:
    java.io.IOException: Server returned HTTP response code: 401
    for URL: http://localhost:8080/manager/install?path= ...

    Fix:

    Make sure that the user name and password in your build.properties file match a user name and password with the role of manager in the tomcat-users.xml file.

     

  3. Problem

    4. When you type ant build, these messages appear: 

    Buildfile: build.xml does not exist!
Build failed.

    Fix:

    Start Ant from the $TOMCAT_HOME/tech/examples/gs/ directory, or from the directory where you created the application. If you want to run Ant from your current directory, then specify the build file on the command line. For example, you would type this command on a single line: 

    ant -buildfile 
$TOMCAT_HOME/tech/examples/gs/build.xml
build

     

  4. Problem

    5. When you type ant build, the compiler reports many errors, including these: 

    cannot resolve symbol
. . .
BUILD FAILED
. . .
Compile failed, messages should have been provided

    Fix:

    Make sure you are using the version of Ant that ships with this version of the Java WSDP. The best way to ensure that you are using this version is to use the full PATH to the Ant files to build the application, $TOMCAT_HOME/bin/ant build. Other versions may not include all of the functionality expected by the example application build files.

     

  5. Problem

    6. When you type ant install at the terminal prompt, you get the following message: 

    $TOMCAT_HOME/tech/examples/gs/build.xml:82: 
java.net.ConnectException: Connection refused

    Fix:

    Tomcat has not fully started. Wait a few minutes, and then attempt to install the application again. For more information on troubleshooting Tomcat startup, see "Unable to Locate the Server localhost:8080" Error.

     

  6. Problem

    7. When you type ant install, the system appears to hang.

    Fix:

    The Tomcat startup script starts Tomcat in the background and then returns the user to the command line prompt immediately. Even though you are returned to the command line, the startup script may not have completely started Tomcat. If the install task does not run immediately, wait up to several minutes and then retry the install task. To verify that Tomcat is running, point your browser to http://localhost:8080. When the Tomcat index screen displays, you may continue. If the splash screen does not load immediately, wait up to several minutes and then retry. If Tomcat still has not loaded, check the log files, as explained below, for further troubleshooting information.

    When Tomcat starts up, it initializes itself and then loads all the webapps in $TOMCAT_HOME/webapps. When you run Tomcat by calling startup.sh, the server messages are logged to $TOMCAT_HOME/logs/catalina.out. The progress of loading webapps can be viewed in the file $TOMCAT_HOME/logs/jwsdp_log.<date>.txt.

     

  7. Problem

    8. The browser reports that the page cannot be found (HTTP 404).

    Fix:

    • If you just started Tomcat, give it another minute to warm up, then retry loading the Web client.

    • If you are behind a firewall proxy, this could be preventing access to the domain. Run "ping domain, to verify it is accessible.

    • Tweak the LAN settings in the browser. To do this within Internet Explorer:

      Tools | Internet Options | Connections | LAN Settings

     

  8. Problem

    9. The browser reports that the page cannot be found (HTTP 404).

    Fix:

    Deploy the application. For more detail, see Deploying the Application.

     

  9. Problem

    10. When you enter ant install at a terminal prompt, you get this message:


    [install] FAIL - Application already exists at path /GSApp
    BUILD FAILED
    $TOMCAT_HOME/tech/examples/gs/build.xml:82: FAIL -
    Application already exists at path /GSApp

    This application has already been installed. If you've made changes to the application since it was installed, use ant reload to update the application in Tomcat.

     

  10. Problem

    11. Getting the following when trying to run a deployed app.

    HTTP 500: No Context Error

    Fix:

    This error means that Tomcat is loaded, but it doesn't know about your application. If you have not deployed the application, that would be the first step. If you have successfully deployed the application by running ant remove, ant build, ant install, ant reload, and you're still getting the error, read on.

    If Tomcat is loaded, but has not yet loaded all of the existing contexts, you will also get this error. Continue to select the Reload or Refresh button on your browser until either the application loads or you get a different error message.

ConverterBean.java JavaBean Contains the get and set methods for the yenAmount and euroAmount properties used to convert U.S. dollars to Yen and convert Yen to Euros.
web/index.jsp Web client
web/WEB-INF/web.xml Deployment descriptor
build.xml Build file. Uses Ant.

 

Roles, Groups, and Users

The Tomcat server authentication service includes the following components:

Role an abstract name for the permission to access a particular set of resources. A role can be compared to a key that can open a lock. Many people might have a copy of the key, and the lock doesn't care who you are, just that you have the right key.
User an individual (or application program) identity that has been authenticated (authentication was discussed in the previous section). A user can have a set of roles associated with that identity, which entitles them to access all resources protected by those roles.
Group a set of authenticated users classified by common traits such as job title or customer profile. Groups are also associated with a set of roles, and every user that is a member of a group inherits all of the roles assigned to that group.
Realm a complete database of roles, users, and groups that identify valid users of a webapp (or a set of webapps).

 

Adding Roles Using admintool

To set up new roles for container-managed security, follow these instructions. Additions, deletions, and changes made in admintool are written to the tomcat-users.xml file.

  1. Scroll down the left pane of admintool to the User and Group Administration node.
  2. Select Role Administration.
  3. From the Roles List, select Create New Role.
  4. Enter a Role Name and Description, for example Customer or User.
  5. Select Save.

 

Adding Users Using admintool

To set up new users for container-managed security, follow these instructions. Additions, deletions, and changes made in admintool are written to the tomcat-users.xml file.

  1. Scroll down the left pane of admintool to the User and Group Administration node.
  2. Select User Administration.
  3. From the Users List, select Create New User.
  4. Enter a User Name, Password, and select a Role for the new user. If you select the admin role for the new user, the user will be able to access admintool.
  5. Select Save.

  Home