Author: Blaine Simpson. [email protected]
$Revision: 1.4 $
The software which is referred to in this document and which is hosted on the admc.com web site, is distributed for free according to the Gnu Public License.
Keep a browser handy, with the WAS InfoCenter at http://publib7b.boulder.ibm.com/webapp/wasinfo1/index.jsp?deployment=ApplicationServer&lang=en bookmarked.
Most items discussed in this document apply to both Windows and UNIX setups, but the command-line commands all use Bourne-compatible shell syntax (unless otherwise noted), UNIX filesystem layout, and UNIX path delimiters. Note that there are a handful of basic features of the Administrative Console which just do not work with the lightweight server. When I discuss the Administrative Console, I mean an Administrative Console running on a standalone WAS instance.
This document does not explain installation, since that is covered by a different HOWTO. This document does explain how to use and administer the WAS server, with the specific goal of making the attentive reader a power user in a very short time.
Web Server administration is nearly entirely separate from WAS administration. Unlike other application servers, you need to take care of starting and stopping your front end web server independently of WAS.
Some names you will need to know. Instance name and node name appear in some directory paths, so I'm defining the following <KEYWORDS> to make this document easier to understand.
There are WAS programs for remotely administering nodes, and for building and deploying standalone J2EE application clients. I do not cover those programs here since these are atypical uses.
You should run the programs in this document (other than web interfaces) as the owner of the web instance or via sudo. The environment for that account will need to be set up. If you own your own WAS instance, then, once your environment is set up, you can run all the WAS commands. If your instance is owned by a shared account, then you will have to log into that account or use sudo. Do not attempt to run these commands as any other user (especially root) unless you have explicitly set up environments for file sharing. (I recommend against it for WAS because it is very easy for one user to mess up everything for all other users).
N.b. In general, you should not do everything as the instance owner, but only stuff related to the WAS "server", such as deploying apps or restarting the WAS server. If you are a developer, you should do all of your editing and compiling and building using your personal account.
You must set and exported the following variables.
$WAS_HOME
$ORACLE_HOME
$LD_LIBRARY_PATH
$ORACLE_HOME/lib.
If you are running an alternate instance, then you also must source $USER_INSTALL_ROOT/bin/setupCmdLine.sh, like
. /home/blaine/inst2/bin/setupCmdLine.sh
(If we have C-shell users, then let me know and I'll convert it
to C-shell).
(In addition to other things, this will set the variable $USER_INSTALL_ROOT to the instance home directory. $USER_INSTALL_ROOT is not set for users using the default WAS instance.)
Add $WAS_HOME/bin to your search path.
To really make things easy, set up the login files for the account that you will run the WAS commands from.
su - or sudo su -) then set up the instance owner account.
Download http://admc.com/blaine/howtos/was.profile and http://admc.com/blaine/howtos/was.kshrc and rename them to .profile and .kshrc in the user's home directory. Then edit .profile to enter your local path(s) as the file says to.
If you use some other shell, or if you have existing .profile and/or .kshrc file(s) that you don't want to clobber, then merge the contents of the downloaded files into your existing .profile and .kshrc files.
After you do this, verify that you can log in as this user and
successfully run startServer.sh server1 and
startServer.sh server1 (without making any manual environment settings).
The rest of this section is only applicable to setups using a shared account as the instance owner (i.e, your personal account is not the instance owner). If you own your instance, then you can safely skip the rest of this section.
For the remainder of this section, I use the name websphere to represent the WAS instance owner.
N.b. Note that if you just get a shell as the new user by running something
like sudo -u websphere -s or sudo -u websphere ksh
, you will not get a proper environment for the target user.
If you want to get a full environment set up as if you logged in as the
instance owner, then you need to run somethng like sudo su - websphere
or su - websphere (or actually log into the server as websphere).
The Architecture is simple once you understand the high-level architecture objects.
The default server name is server1.
The default cell name is the same as your node name.
I give the paths of all remaining items relative to $USER_INSTALL_ROOT. In the event that you are running the default instance, just substitute $WAS_HOME for $USER_INSTALL_ROOT.
Applications under here are basically expanded .ear's,
with component .war's (but not .jar's) also expanded.
The deployment descriptors (including those within .jar's) reflect
deployment-time settings and bindings.
(The deployment descriptors also get written under $USER_INSTALL_ROOT/config.
See below).
The WAS command-line programs which every WAS Administrator should know.
serverStatus.sh server1
serverStatus.sh -help
startServer.sh server1
startServer.sh -help
Be aware that if you are running a default instance, you don't need your environment set up at all ($WAS_HOME will be determined by location of the startup script). However, if you are running a non-default instance, you need to set $WAS_HOME and then source $USER_INSTALL_ROOT/bin/setupCmdLine.sh (not $WAS_HOME/bin/setupCmdLine.sh!).
BEWARE! Many of the messages about the environment printed to the startup log (.../logs/server1/startServer.log) are WRONG. If you edit the IBM scripts, be aware that some variables (including $WAS_CLASSPATH) are obsolete and are not used at all.
If you have Oracle data sources, be aware that the Oracle JDBC drivers will not work unless you have $LD_LIBRARY_PATH and $ORACLE_HOME set and exported properly when startServer.sh is invoked.
If you run startServer.sh using sudo, then be sure to get the patched version of startServer.sh (as documented in the Installation HOWTO), otherwise your $LD_LIBRARY_PATH setting will be lost when you use sudo.
stopServer.sh server1
stopServer.sh -help
telnet 1.2.3.4 5678, where 1.2.3.4 is the IP address and
5678 is the WAS SOAP port for your instance (see the installation HOWTO
for how to determine and set your WAS port numbers).
Dumps all JNDI names.
dumpNameSpace.sh -port 1234
dumpNameSpace.sh
For default instance running on default bootstrap port.
Where 1234 is your "BOOTSTRAP_PORT" (defaults to 2809).
See the file $WAS_HOME/bin/wsinstance/<NODE>_<INST>_portdef.props if you
are running an alternate instance and don't know your bootstrap port.
dumpNameSpace.sh -help
Verify server health. This command works only for the default instance. Even with the default instance, it will only work if you have the ivtApp.ear application installed and running.
ivt.sh
Builds all skeleton and stub classes needed for ejb-jar file(s).
ejbdeploy.sh original.jar /tmp/z new.jar -cp a/lib.jar -quiet
ejbdeploy.sh original.ear /tmp/z new.ear -cp a/lib.jar -quiet
ejbdeploy.sh -help
This program doesn't deploy anything. For each ejb-jar file, generates skeleton and stub class and inserts them into a copy of the ejb-jar. The generated skeleton and stub class files are of the form EJS*.class, _EJS*class, *_Stub*.class, *Tie.class. (The .java files for these classes are also created in the work area).
wsadmin.sh gives you a JACL shell from which you can perform nearly any WAS administration interactively or with scripts. This is an advanced tool. See the separate section on wsadmin below.
ws_ant
ws_ant -help
Most of the tasks will not work with alternative configuration instances. The classpath mechanism does not work for WsEjbDeploy, making it worthless.
The validation task is useful for ear files, but usually not for ejb jar files, since the mechanism for setting a class path does not work. This target also suffers from the same failing as that of validation by ejbdeploy.sh and assembly.sh-- often it complains of an internal error for no known reason.
ws_ant sets $WAS_HOME if it is not already set.
So, if you are using the default instance (i.e., there is no
$USER_INSTALL_ROOT), you can invoke ws_ant like
/path/to/ws-home/bin/ws_ant without setting up your environment
at all.
To use our Nextel ant build file, see my WAS Ant Builds at Nextel HOWTO.
If you have not upgraded Ant to 1.5, then definitely upgrade it (it has many important features )
To upgrade the version of ant used by WAS, get rid of the ant.jar in $WAS_HOME/lib (WAS) or $WSAD_SOFTWARE_ROOT/runtimes/base_v5/lib (WSAD), and put the following files into that directory. Make sure that you either remove ant.jar, or move it out of that directory (renaming it in that directory won't work because it will continue to be used).
These are UNIX commands, not WAS commands. Like it or not, sometimes WebSphere gets stuck. In those cases, ps and kill can get you unstuck.
ps -eo pid,ppid,args | grep java # Solaris
OR
ps axo pid,ppid,args | grep java # Linux
# Look for a process like ".../java -Xbootclasspath..." with ppid of 1.
kill 1234 # Where 1234 is the desired pid
kill -KILL 1234 # If the default signal (INT) fails to stop it.
Repeat until all the target java processes are gone.
Do give it a little while to quit after a signal.
If you are running multiple instances, then supply different args to ps
in order to differentiate the desired instance's processes.
You should run the ps command right now so that you know what the processes look like when things are healthy. (Don't use the kill command unless stopServer.sh won't work).
The WAS graphical programs which every WAS Administrator should know.
This is the Administrative Gui for WAS 5.0. If you are running the default instance of a default setup of WAS on your local computer, you can access the Admin Console by using a browser to go to http://localhost:9090/admin.
In general, go to /admin on the host name, with the Administrative HTTP port.
Normally, you can use any username to gain access. If global security is turned on, you may need to enter a valid local OS account username and password, or a username and password from some LDAP database.
Most of the data displayed is cached. If you want to see changes made by other Administrators using Admin Consoles or wsadmin, you have to use the Logoff menu item then log back in again.
See the Deployment section below.
IBM likes to call this AAT (stands for Application Assembly Tool). Run it like
assembly.sh > /dev/null 2>&1 &
since the program isn't smart enough to go into the background by itself.
Notice that the stderr and stdout output are thrown away.
Unlike IWS's deploytool, I don't know of any problems with assembly.sh where
stderr output is needed for troubleshooting.
The validation feature is moderately useful. It misses many obvious errors which will get caught during deployment. It constantly reports an internal error and says to see the log file (there is no log file).
It is usually easier to use the JTree in the left pane to add/remove items (usually by right-clicking and picking "Add something" or "New").
When asked for "Module Visibility", choose "COMPATIBILITY".
First of all, be aware that when IBM says EJB deployment, they usually mean the generation of EJB stubs and skeletons, not the deployment of anything. This is accomplished with the ejbdeploy.sh program. This section of this document is about deployment in the normal J2EE sense-- deploying something to an application server, not IBM's idiosyncratic use of the word.
Note that in this section I use $USER_INSTALL_ROOT to indicate the home of your WAS instance, whether it is an alternate instance or not. If you are running the default instance, the variable used is actually $WAS_HOME.
Note that what most of the J2EE world calls redeployment, IBM calls update. I.e.
update = redeploy
What happens during deployment?
For "application name", do not include a file extension, like ".ear", because WAS deploys applications in a directory like "appname.ear". (So, if you name your app "x.ear", it would be deployed to "x.ear.ear".) Therefore, do not just accept Admin Console's default application name, which is just the ear file name.
Do not use spaces or special characters in your application name. Since we host on UNIX, these spaces cause difficulties for shell scripts (it isn't difficult to work around these difficulties, but most shell script writers do not know how to do it).
If you add any application that contains a context root change, or which contains a new .war, you will generally have to Update Web Server Plugin. This will add the new context roots to the plugin-cfg.xml file. Unless this context root is covered by an existing mapping in the file, your web server will not forward requests for this context to the app server. If you are running multiple instances, be aware that you are only updating the plugin-cfg.xml in your $USER_INSTALL_ROOT, and that plugin-cfg.xml file is only used if it is referenced by a web server config file.
Front end web servers do not need to be restarted after deploying new applications, nor after regenerating the plugin-cfg.xml file.
There is a deployment script in the wsadmin section of this document.
wsadmin.sh
wsadmin.sh.sh -help
wsadmin.sh is a JACL shell with access to the WAS Mbeans and four WAS-specific Java extension administration objects. JACL is tcl with Java extensions... it gives you access to both Java language functionalities and to Java objects.
Can run without connecting to server, like: wsadmin.sh -conntype NONE
I know of no way to use wsadmin to "start" an existing application that is currently not running. If you update an app that is currently running and don't save until you are finished, the app will continue to run (there is an example of this below). For an app with a new name, if you want it to run, you will have to use an Admin Console to do that (see next item about visibility), or restart WAS.
Like the Administrative Console, wsadmin does not see changes made by outside means after you enter a shell.
You can not start a (normal standalone) WAS instance with wsadmin.
The four WAS administration objects provided are aliased to variables.
These are all sub-commands of the four Administration objects listed above.
[list $webmodule_dispname $warfile,WEB-INF/web.xml default_host]],
where default_host is the default virtual host).
The following sequence is equal to Console Update + Apply
$AdminApp uninstall {AppName}
$AdminApp install...
$AdminConfig save
OR
$AdminConfig reset
The app continues running!
If you download http://admc.com/blaine/howtos/nextel-util.jacl and run the command
source /app/iws/was/scripts/nextel-util.jacl
in wsadmin, then that jacl shell will have access to the procedures
installApp and updateApp.
installApp ApplicationName path/to/file.ear nodeName serverName
installApp ApplicationName path/to/file.ear nodeName serverName prefix
updateApp ApplicationName path/to/file.ear nodeName serverName
updateApp ApplicationName path/to/file.ear nodeName serverName prefix
The installApp and updateApp procedures can be used from ant. See the -deploy target in the Ant build file http://admc.com/blaine/howtos/nextelapp-build.xml.
If you have not upgraded Ant to 1.5, then see the instructions on that procedure in the installation HOWTO.
See the installation HOWTO for instructions and explanation about creating Oracle data sources. The instructions here are generic.