Interactive Use¶
After installation, you will have a new tool called tomcat-manager
. Run
this with no command line arguments to invoke an interactive, line-oriented
command interpreter:
Use the exit
or quit
command to exit the interpreter and return to your
operating system shell.
Built In Help¶
The interactive shell has a built-in list of all available commands:
As well as help for each command:
This document does not include detailed explanations of every command. It does show how to connect to a Tomcat server and deploy a war file, since there are quite a few options for both of those commands. For everything else, the built-in help should be sufficient.
Connect To A Tomcat Server¶
Before you can do anything to a Tomcat server, you need to enter the connection information, including the url and the authentication credentials. You can pass the connection information on the command line:
Or:
You can also enter this information into the interactive prompt:
Or:
Deploy applications¶
Tomcat applications are usually packaged as a WAR file, which is really just a
zip file with a different extension. The deploy
command sends a WAR file to
the Tomcat server and tells it which URL to deploy that application at.
The WAR file can be located in one of two places: some path on the computer
that is running Tomcat, or some path on the computer where the command line
tomcat-manager
program is running.
If the WAR file is located on the same server as Tomcat, we call that
server
. If the WAR file is located where tomcat-manager
is running, we
call that local
. If the file is already on the server, then we have to tell
Tomcat where to go find it. If it’s local
, then we have to send the WAR
file over the network so Tomcat can deploy it.
For all of these examples, lets assume I have a Tomcat server running far away
in a data center somewhere, accessible at https://www.example.com
. I’m
running the command line tomcat-manager
program on my laptop. We’ll also
assume that we have already connected to the Tomcat server, using one of the
methods just described in Connect To A Tomcat Server.
For our first example, let’s assume we have a WAR file already on our server,
in /tmp/fancyapp.war
. To deploy this WAR file to
https://www.example.com/fancy
:
Now let’s say I just compiled a WAR file on my laptop for an app called
shiny
. It’s saved at ~/src/shiny/dist/shinyv2.0.5.war
. I’d like to
deploy it to https://www.example.com/shiny
:
Sometimes when you deploy a WAR you want to specify additional configuration information. You can do so by using a context file. The context file must reside on the same server where Tomcat is running.
This command will deploy the WAR file specified in the docBase
attribute of
the Context
element so it’s available at
https://www.example.com/sample
.
Note
When deploying via context files, be aware of the following:
- The
path
attribute of theContext
element is ignored by the Tomcat Server when deploying from a context file. - If the
Context
element specifies adocBase
attribute, it will be used even if you specify a war file on the command line.
Parallel Deployment¶
Tomcat supports a parallel deployment feature which allows multiple versions of the same WAR to be deployed simultaneously at the same URL. To utilize this feature, you need to deploy an application with a version string. The combination of path and version string uniquely identify the application.
Let’s revisit our shiny
app. This time we will deploy with a version
string:
Later today, I make a bug fix to ‘shiny’, and build version 2.0.6 of the app. Parallel deployment allows me to deploy two versions of that app at the same path, and Tomcat will migrate users to the new version over time as their sessions expire in version 2.0.5.
Once all the sessions have been migrated to version 2.0.6, I can undeploy version 2.0.5:
The following commands support the -v
or --version
option, which makes
parallel deployment possible:
- deploy
- undeploy
- start
- stop
- reload
- sessions
- expire
Readline Editing¶
You can edit current or previous commands using standard readline
editing
keys. If you aren’t familiar with readline
, just know that you can use your
arrow keys, home
to move to the beginning of the line, end
to move to
the end of the line, and delete
to forward delete characters.
Command History¶
Interactive mode keeps a command history, which you can navigate using the up
and down arrow keys. and search the history of your commands with
<control>+r
.
You can view the list of previously issued commands:
And run a previous command by string search:
Or by number:
The history
command has many other options, including the ability to save
commands to a file and load commands from a file. Use help history
to get
the details.
Settings¶
The show
or settings
(they do exactly the same thing) commands display
a list of settings which control the behavior of tomcat-manager
:
You can change any of these settings using the set
command:
Quotes around values are not required unless they contain spaces or other quotes.
Configuration File¶
tomcat-manager
reads a user configuration file on startup. This file allows
you to:
- change settings on startup
- define shortcuts for connecting to Tomcat servers
The location of the configuration file is different depending on your operating system. To see the location of the file:
You can edit the file from within tomcat-manager
too. Well, it really just
launches the editor of your choice, you know, the one specified in the
editor
setting. Do that by typing:
This file uses the INI file format. If you create a section called
settings
, you can set the values of any of the available settings. My
config file contains:
[settings]
prompt='tm> '
debug=True
editor=/usr/local/bin/zile
Server Shortcuts¶
You can also use the configuration file to set up shortcuts to various Tomcat
servers. Define a section named the shortcut, and then include a property for
url
, user
, and password
. Here’s a simple example:
[localhost]
url=http://localhost:8080/manager
user=ace
password=newenglandclamchowder
With this defined in your configuration file, you can now connect using the name of the shortcut:
If you define a user
, but omit password
, you will be prompted for it
when you use the shortcut in the connect
command.
Shell-style Output Redirection¶
Save the output of the list
command to a file:
Search the output of the vminfo
command:
Or the particularly useful:
Clipboard Integration¶
You can copy output to the clipboard by redirecting but not giving a filename:
You can also append output to the clipboard using a similar method:
Run shell commands¶
Use the shell
or !
commands to execute operating system commands (how
meta):
Of course tab completion works on shell commands.
Python Interpreter¶
You can launch a python interpreter:
As you can see, if you have connected to a Tomcat server, then you will have a
self.tomcat
object available. See Use from Python for more information about
what you can do with this object.