IBM WebSphere Developer Technical Journal: WebSphere Application Server Community Edition V1 system administration -- Part 1

Administering and configuring the server

Learn everything you need to know to successfully administer a WebSphere® Application Server Community Edition environment. Part 1 of this two-part series covers options for starting the server, deployment, configuration management, and error handling and recovery. Part 2 goes into more detail on configuring elements such as Java™ Message Service (JMS), databases, LDAP, SSL, and CORBA over IIOP.

Lin Sun (linsun@us.ibm.com), Staff Software Engineer, IBM

Lin SunLin Sun is an advisory software engineer for IBM in Research Triangle Park, North Carolina, in the Software Group WebSphere Application Server Community Edition Development Team. She received a master's degree in information science from the University of North Carolina at Chapel Hill.



Nell Gawor (ngawor@us.ibm.com), Advisory Software Engineer, IBM

Nell GaworNell Gawor is an advisory software engineer for IBM in Research Triangle Park, North Carolina, in the Software Group Advanced Design and Technology Group. She received a Masters Degree in Computer Science from the University of Illinois at Urbana-Champaign. Contact Nell at ngawor@us.ibm.com.



18 January 2006 (First published 10 February 2005)

Also available in Russian

From the IBM WebSphere Developer Technical Journal.

Introduction

IBM® WebSphere® Application Server Community Edition (hereafter called Community Edition) Version 1 is a lightweight Java™ 2 Platform, Enterprise Edition (J2EE) application server. It is built on top of Apache Geronimo Milestone 5, an open-source application server created by the Apache Software Foundation. In Part 1 of this two-part series, you will learn the Community Edition directory structure, how to startup the server with different options, and how to use different commands and options provided by the deployer. In addition, you will master configuring the server, Tomcat default ports, logging properties, and recovering your server from system failure. In Part 2, you will learn how to configure databases (including IBM Cloudscape, Oracle®, Microsoft® SQL server, and DB2®), Java Message Service (JMS), LDAP, SSL, and CORBA over IIOP.

Before you continue: This article was written for WebSphere Application Server Community Edition V1.0, which was the current version at the time the article was published. Some of the information in this article may not be applicable to later versions. To follow along with this article, be sure to use the product version on which this article is based. If you wish, you can download the current version of WebSphere Application Server Community Edition, or you can download an earlier version by visiting the product archive page.


Community Edition directory structure

To install Community Edition, ensure you meet the the system requirements and follow the download and installation instructions provided in Get started with WebSphere Application Server Community Edition. After the installation, the following subdirectories are created:

  • bin/: This directory contains the server.jar, server startup scripts, deployer.jar, client.jar, and IBM Cloudscape ij tool script. These files allow you to start the server, run the deploy tool, start the J2EE client, and start the Cloudscape ij tool, respectively.
  • config-store/: This directory holds resources and application modules, some of which are started along with the Community Edition server. It contains the index.properties file. This file maps modules to the numeric names of the config-store subdirectories in which they are contained.
  • doc/: This directory contains the default server, Tomcat, database, activemq, client, CORBA, and other system plans that are used by the server initially.
  • graphics/: This directory contains the graphics that are used by the server welcome page and the administrative console.
  • lib/: This directory contains the kernel jars, which are used to provide kernel services and load other service, resource, and application modules.
  • license/: This directory contains the license and notices for Community Edition.
  • repository/: This directory contains shared libraries, such as database drivers and JMS drivers, which are used by many application modules. Each library is loaded when a module that depends on it is loaded.
  • schema/: This directory contains schema definitions for XML deployment descriptors and configuration files.
  • var/: This directory contains log files, transaction logs, and security files as well as information about the configurations used when the server was last running.
  • _uninstall/: This directory contains information that will be used by the uninstaller.

Starting the WebSphere Application Server Community Edition server

Startup options

When starting the server, there are different options you can use to control the amount of output:

  • -quiet: This suppresses the progress bar. The server will output only messages of level WARN or higher.
  • -v: The server will output messages of level INFO or higher.
  • -vv: The server will output messages of level DEBUG or higher.

Selectively start up configurations

If you run into problems and you need to isolate the cause, or if Community Edition will not start, you can override the list of configurations normally started without permanently changing it. To do this, pass the configuration or configurations to start as arguments when starting the server. For instance, if you have an application module called hello and you are having problems, you may want to try running only that module and its dependencies to make sure the problems are not coming from another application module (Listing 1).

java -jar server.jar hello

This only works as expected if the configuration has correctly declared its dependencies, or you already know exactly what configurations to start. Otherwise, the module may fail unexpectedly because not all the necessary pieces are started. For instance, if you are having a problem with deployment, you might decide you want to run only the org/apache/geronimo/RuntimeDeployer configuration. Even if the configuration starts successfully, when you actually try to deploy, the deploy fails and tells you that the server has to be running to use that command. The reason is that the RuntimeDeployer does not work without other configurations, such as the JMX infrastructure, but does not have explicit dependencies on those configurations. Therefore, not everything needed to run the RuntimeDeployer is actually started. Running only part of the server is not recommended because you may cause more problems, which hide the true reasons you are trying to solve.

Keeping the server from stopping

If it is a problem to keep the same user logged in all the time, you can run Community Edition in the background on Linux. On Windows, your only option is to lock the machine to keep the current user logged in.


Using the deployer

The Community Edition deployer helps you manage your application deployments with various commands. To invoke the deployer, the format is:

deploy.[bat|sh] [general options] command [command options]

For more detailed information on any one command, type:

deploy.[bat|sh] help command

The help information is not necessarily accurate, however. For instance, many of the deployer commands can only be run when the server is started, but the help documentation says they can work when the server is stopped. When in doubt, refer to the Community Edition documentation.

General options

For a full list of the general options, type:

deploy.[bat|sh] help options

The general options (for any command) are:

  • --uri: This is the URI of a running server to contact. You can use this to run the deployment tool against a server that is not running on the default port (1099) on localhost. The URI format is:

    deployer:geronimo:jmx:rmi:///jndi/rmi://host:port/JMXConnector
  • --driver: You can use the deployer tool not only with Community Edition, but with any JSR-88-compliant server. For servers other than Community Edition, you need to provide the location of the jar file containing the JSR-88 deployment implementation classes.
  • --user: This is the username to use when authenticating. If no username is provided, you will be prompted. The default username for Community Edition is "system".
  • --password: This is the password to use when authenticating. If no password is provided, Community Edition will try to connect without a password. If that fails, you will be prompted. The default password for Community Edition is "manager".
  • --syserr: If true, errors will be logged to the syserr device. The default is false.
  • --verbose: If true, output debug information to standard out. The default is false.

Available deployer commands and their usage

Common commands are:

  • deploy: The deploy command normally takes a module and a plan for how to deploy that module. It validates the module and plan, installs the module on to the server, and starts the module. If the module is very simple and you are willing to accept all of the defaults, it may not be necessary to have a plan. Also, instead of providing the plan as a separate argument, it can also be part of the module itself. If the plan is packaged as part of the module, its location depends on the type of module:
    Module typePlan location
    Web moduleWEB-INF/geronimo-web.xml
    EJB moduleMETA-INF/openejb-jar.xml
    Resource adapterMETA-INF/geronimo-ra.xml
    Client applicationMETA-INF/geronimo-application-client.xml
    J2EE applicationMETA-INF/geronimo-application.xml
    The deploy command, like many of the others, has additional options to cover the case where you want to work with multiple deployment targets. Because multiple target support is so limited at this point, we will not cover those additional options here.
  • redeploy: The redeploy command is equivalent to running undeploy, and then deploy. The module will be started after redeployment even if the module was stopped before. While the redeploy is occurring, some portions of the application may be available to clients while others may be unavailable, causing requests to fail.
  • start: The start command starts a module that has already been deployed. You can list multiple module IDs to start them all.
  • stop: The stop command stops a module that has already been deployed. You can list multiple module IDs to stop them all. After stopping, the module cannot be accessed until it is started again.
  • undeploy: The undeploy command stops a module and removes all its deployment information from the server. It will not be accessible unless it is deployed again. Unlike deploy and redeploy, you can specify multiple modules to undeploy.

Other commands are:

  • distribute: The distribute command is similar to deploy. The difference is that it also makes the module available but, unlike deploy, does not start it. This means you can use distribute when the server is not started.
  • list-modules: The list-modules command lets you view all the available modules. For Web modules, you can use the list-modules command to find out their Web address (URL). You can specify either --started or --stopped to see only those modules in that state. The server must be running to use this command.
  • list-targets: The list-targets command lists the places where you can deploy modules. Each target is either a cluster or a server and represents one configuration store. However, support for multiple configuration stores is not fully tested. There is no support for a cluster as a target so this command is not useful yet. The server must be running to use this command.

Offline deployer

The deployer works even when the server is not running, but there is not much you can do. You can only distribute an application, which means Community Edition will validate that it is a valid application and install it. None of the other commands (besides the package command, which is not discussed here) will work when the server is not running.


Understanding the config-store directory

The config-store directory, located at the wasce_install_root\config-store directory, holds resources and application modules, some of which are started along with the Community Edition server. The available configuration modules are listed in the wasce_install_root\config-store\index.properties, which provides the mapping between the module configuration name and the numeric config-store subdirectories in which they are contained. After your J2EE application has been deployed successfully, you will see a serialized version of its configuration in the config-store/assigned number directory.

By looking at the index.properties file, you can find out the numeric directory name that is assigned by the server when the J2EE application is deployed. For example, if you deployed the hello sample program provided by Community Edition, you will see the hello program assigned to a numeric ID:

#Wed Nov 16 09:28:46 EST 2005
org/apache/geronimo/applications/Welcome/Tomcat=18
org/apache/geronimo/Tomcat=7
org/apache/geronimo/SampleSecurityRealm=17
org/apache/geronimo/RMINaming=4
org/apache/geronimo/ActiveMQServer=15
org/apache/geronimo/TomcatRuntimeDeployer=9
org/apache/geronimo/DefaultDatabase=13
hello=44
...

This means the serialized version of the hello program's configuration is in the config-store/44 directory. The first line indicates the date and time last time the index.properties file was last written. There is also an index.backup file that contains the backup version of the index.properties file by the server. The contents of the config-store directory are maintained by the deployment tools automatically, so it is not recommended that system administrators modify this directory.


Understanding the config.list file

The config.list file, located in the wasce_install_root\var\config directory, contains the resources and application modules that were running when the server was previously shutdown. If the server is started without special direction, the server will read the config.list to determine what resources and application modules it should start. If you do not make any changes, you see the following default start sequence in the config.list file from top row to bottom row.

Configuration IDInitial default planUsage
org/apache/geronimo/Systemsystem-plan.xmlContains the basic services needed for Community Edition to operate. Should always be started.
org/apache/geronimo/RMINamingnaming-server-plan.xmlContains the RMI Naming server configuration.
org/apache/geronimo/Serverj2ee-server-plan.xmlContains the service necessary for Community Edition to act as a J2EE server.
org/apache/geronimo/Securityj2ee-security-plan.xmlContains the security configuration of the server. If you are looking for a security realm sample to use in your own applications, check out the j2ee-secure-plan.xml file.
org/apache/geronimo/SystemDatabasesystem-database-plan.xmlStarts the embedded IBM Cloudscape database server, which listens on port 1527 by default.
org/apache/geronimo/SystemJMSsystem-jms-plan.xmlStarts the JMS connection factory and default connection queues.
org/apache/geronimo/RuntimeDeployerj2ee-runtime-deployer-plan.xmlContains the deployment configuration of the server.
org/apache/geronimo/TomcatRuntimeDeployerj2ee-tomcat-runtime-deployer-plan.xml Contains the Tomcat Web module builder configuration.
org/apache/geronimo/applications/Welcome/Tomcatwelcome-tomcat-plan.xmlStarts the Community Edition Welcome Page.
org/apache/geronimo/Console/Tomcatwebconsole-tomcat-plan.xmlStarts the Community Edition Administrative Console (Technial Preview).

You can issue the following deployer command to find out what modules have started:

deploy.[bat|sh] --user system --password manager list-modules --started
Output of the deploy list-modules command
Found 12 modules
+ org/apache/geronimo/applications/Welcome/Tomcat @ http://LinT42:8080/
+ org/apache/geronimo/Tomcat
+ org/apache/geronimo/RMINaming
+ org/apache/geronimo/ActiveMQServer
+ org/apache/geronimo/TomcatRuntimeDeployer
+ org/apache/geronimo/Server
+ org/apache/geronimo/Security
+ org/apache/geronimo/SystemDatabase
+ org/apache/geronimo/SystemJMS
+ org/apache/geronimo/RuntimeDeployer
+ org/apache/geronimo/Console/Tomcat
    `-> geronimo-console-standard-1.0-M5.war @ http://LinT42:8080/console-standard
    `-> geronimo-console-framework-1.0-M5.war @ http://LinT42:8080/console
+ org/apache/geronimo/System

You may find it strange that you do not see org/apache/geronimo/Tomcat and org/apache/geronimo/ActiveMQServer listed in the config.list file, but they have actually started. The parentId of org/apache/geronimo/applications/Welcome/Tomcat and org/apache/geronimo/Console/Tomcat is org/apache/geronimo/Tomcat. Therefore, org/apache/geronimo/Tomcat will be started before the welcome page and console page start, based on the dependency injection deployment architecture of Community Edition. The situation is the same for org/apache/geronimo/ActiveMQServer server, which will be started before org/apache/geronimo/SystemJMS is started.

Using config.xml to configure server attributes

If you want to change the ports and host names of different servers like Tomcat, RMI, Cloudscape server, or configure your own CORBA properties, you can change the initial configuration provided by Community Edition. Config.xml, located in the wasce_install_root\var\config directory, is designed to store system administrators' own customized configuration. You can customize all the server configurations in config.xml, either by modifying the default configurations (RMINaming, RuntimeDeployer, Tomcat, Server, Security, ServerCorba, and ActiveMQServer GBeans) provided in the config.xml that comes with Community Edition, or by adding your own configurations. When the server starts next time, it reads the configuration from the config.xml file and applies it to the config store. The configuration changes will not be written back into the initial configuration files located in the wasce_install_root\doc\plan directory, which you want to remain intact. No matter what you do, do not forget to backup your server first! See Recovering from a system failure for more information.

The example below shows how to change the Tomcat server Web container from running on the default port number 8080 to run on 80 instead.

Tomcat WebConnector configuration in config.xml
<configuration name="org/apache/geronimo/Tomcat">
	<gbean name="TomcatWebConnector">
		<attribute name="host">0.0.0.0</attribute>
		<attribute name="port">80</attribute>
		<attribute name="redirectPort">8443</attribute>
		<attribute name="catalinaHome">var/catalina</attribute>
	</gbean>
	...
</configuration>

Save the config.xml file and restart the server. You must restart the server for the change to take effect because server will only read the config.xml during server initialization. You can also change the other attributes' value as needed. However, it is not a good idea to change the configuration name or GBean name. You may notice that in the same directory, there is also a file called config.tomcat.xml. This file contains sample configuration settings for running the server with Tomcat as the Web container and it is not used when server starts. If you had changed the configuration and wanted to return to the default Tomcat settings, you would copy this file over your existing config.xml file.


Logging and system recovery

When you encounter a problem, the best place to look is in the log files in wasce_install_root/var/logs. See Get started with WebSphere Application Server Community Edition for more information about the logs and what each one contains.

Each log has a corresponding -log4j.properties file that dictates where the log file is, how much detail is written to the log file, and what format it is in. The line you will most likely be the most concerned with is log4j.appender.FILE.threshold=. By setting this to ERROR, WARN, INFO, or DEBUG, you can control what is written into the log. For more information on the Log4j format, see Log4j delivers control over logging.

Recovering from a system failure

Community Edition does not have a system for managing configuration changes. If a mistake is made, or the configuration becomes corrupted, it is difficult to recover. The best thing to do is to make regular backups of your Community Edition configuration directories.

  1. When your Community Edition is in the state you wish to backup, make sure the server is stopped.
  2. Make copies of your config-store and var/config directories. You can store these in a zip file for convenience.
  3. When you need to return your server to the desired state, make sure the server is stopped.
  4. Restore the config-store and var/config directories by first deleting the existing directories, and then unzipping or copying the older directories into the their location.
  5. Start the server. The server startup configuration should be in the state it was in when you backed it up. Changes that were made to the repository or logging properties may still affect the overall state of the server.

Conclusion

Part 1 of this two-part series provided an overview of what you need to know to administer Community Edition V1. Part 2 of this series covers how to configure:

  • Database resources, including IBM Cloudscape, Oracle, Microsoft SQL 2000, and DB2
  • JMS resources
  • SSL
  • LDAP
  • CORBA over IIOP

Now that you have the information you need to get started with system administration, you can successfully manage your Community Edition server.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Java technology
ArticleID=102115
ArticleTitle=IBM WebSphere Developer Technical Journal: WebSphere Application Server Community Edition V1 system administration -- Part 1
publish-date=01182006