Command Line
You’ve already read about interactive use right? If not, this part will feel kind of hollow.
Any interactive command can be run from the command line. The first positional
argument to tomcat-manager
is the url of the server. The rest of the arguments are
any commands and their arguments from Available Commands. Here’s a few examples:
$ tomcat-manager --user ace --password newenglandclamchowder \
http://localhost:8080/manager deploy server /tmp/myfancyapp.war /fancy
$ tomcat-manager --user ace --password newenglandclamchowder \
http://localhost:8080/manager list --state running --by path
Using Shell Scripts
Say you want to find out how many active sessions there are in the oldest version of
our shiny
app (told you it would feel kind of hollow). You could use interactive
mode:
$ tomcat-manager
tomcat-manager>connect https://www.example.com/manager ace newenglandclamchowder
--connected to https://www.example.com/manager as ace
tomcat-manager>list
Path Status Sessions Directory
------------------------ ------- -------- ------------------------------------
/ running 0 ROOT
/manager running 0 manager
/shiny running 17 shiny##v2.0.6
/shiny running 6 shiny##v2.0.5
If you need to automate a more complex sequence of commands or parse the
output, you might choose to use tomcat-manager
from within a shell script:
#!/usr/bin/env bash
#
URL=https://www.example.com/manager
USERID=ace
PASSWD=newenglandclamchowder
COMMAND="list --raw"
TOMCAT="tomcat-manager --quiet --user=$USERID --password=$PASSWD $URL $COMMAND"
# get the output of the list into a shell variable
LIST=$($TOMCAT)
# if the tomcat command completed successfully
TOMCAT_EXIT=$?
if [ "$TOMCAT_EXIT" -eq 0 ]; then
echo "$LIST" | grep '^/shiny' | awk -F ':' '{ print $4":"$3}' | \
sort | head -1 | awk -F ':' '{ print #2 }'
else
# list has an error message, not the list of tomcat apps
echo -n "$LIST"
exit $TOMCAT_EXIT
fi
Save this script as ~/bin/oldshiners.sh
, and then run it:
$ ~/bin/oldshiners.sh
6
This script builds a tomcat-manager
command which includes authentication
credentials, the url where the Tomcat Manager web app is deployed, as well as the
command from Available Commands.
In this example, we used list
as our command. Any command that works in the
interactive mode works on the command line.
Note how we check the exit code in the shell. tomcat-manager
knows whether
the command to the tomcat server completed successfully or not, and sets the
shell exit code appropriately. The exit codes are:
0 = command completed succesfully1 = command had an error2 = incorrect usage127 = unknown command
Timeout
By default, network operations timeout in 10 seconds. You can change this value in the configuration file. You can also override it on the command line.
$ tomcat-manager --timeout=2.5 http://localhost:8080/manager list
This command line option allows you to override the timeout
setting.
Authentication
Use the user you created when you Configured Tomcat on the command line:
$ tomcat-manager --user=ace http://localhost:8080/manager list
Password:
and you will be prompted for the password. You can also specify the password on the command line, but this is not secure:
$ tomcat-manager --user=ace --password=newenglandclamchowder \
http://localhost:8080/manager list
Password:
See Authentication for complete details of all supported authentication mechanisms.
If you want unattended authenticated access, server definitions are a better option.
Server Definitions
You can use Server Definitions from the command line with or without commands:
$ tomcat-manager localhost
--connected to http://localhost:8080/manager as ace
tomcat-manager>list
Path Status Sessions Directory
------------------------ ------- -------- ------------------------------------
/ running 0 ROOT
/manager running 0 manager
Or:
$ tomcat-manager localhost list
--connected to http://localhost:8080/manager as ace
Path Status Sessions Directory
------------------------ ------- -------- ------------------------------------
/ running 0 ROOT
/manager running 0 manager
This mechanism allows you to keep all authentication credentials out of your scripts. Simply create server definitions with credentials for the server(s) you want to manage, and reference the definitions in your scripts. Instead of this:
TOMCAT="tomcat-manager --user=$USERID --password=$PASSWD $URL $COMMAND"
you might use this:
TOMCAT="tomcat-manager example $COMMAND"
with the following in your configuration file:
[example]
url = "https://www.example.com"
user = "ace"
password = "newenglandclamchowder"
Piped Input
tomcat-manager
will process lines from standard input as though they were
entered at the interactive prompt. There is no mechanism to check for errors
this way, the commands are blindly run until the pipe is closed. The shell exit
code of tomcat-manager
will be the exit code of the last command run.
If you want to see what the exit codes are, you can either use $?
in your
shell, or you can use the interactive command exit_code
($?
works too)
to see the result.
If you want more sophisticated error checking, then you should probably write a
shell script and invoke tomcat-manager
seperately for each command you want
to execute. That will allow you to use the shell script for checking exit
codes, logic branching, looping, etc.
Controlling Output
When using tomcat-manager
from the command line, you have fine grained
control of what you want included in the output. As a well-behaved shell
program it sends output to stdout
and errors to stderr
. If you are
using bash
or one of the other sh
variants, you can easily co-mingle
them into a single stream:
$ tomcat-manager localhost list > myapps.txt 2>&1
In addition to redirecting with the shell, there are several command line switches
that change what’s included in the output. These options correspond to Setting you can change in interactive use. All of the settings default to False
, but be aware
that you may have altered them your configuration file, which is read on startup.
Option |
Setting |
Description |
---|---|---|
|
|
Add the command to the output stream. |
|
|
Don’t show non-essential feedback. |
|
|
Send status information to |
|
|
Show detailed exception and stack
trace, even if |
Some commands show additional status information during their execution which
is not part of the output. If quiet=True
then all status output is
suppressed. If quiet=False
then status information is sent to stderr
.
If status_to_stdout=True
then status information is sent to stdout
, as
long as quiet=False
.
Here’s a couple of examples to demonstrate, using a server definition of localhost
, which we assume gets you
authenticated to a Tomcat Server web application:
These two commands yield the same output, but by different mechanisms: the
first one uses the shell to redirect status messages to the bitbucket, the
second one uses the --quiet
switch to instruct tomcat-manager
to
suppress status messages.
$ tomcat-manager localhost list 2>/dev/null
Path Status Sessions Directory
------------------------ ------- -------- ------------------------------------
/ running 0 ROOT
/manager running 0 manager
$ tomcat-manager --quiet localhost list 2>/dev/null
Path Status Sessions Directory
------------------------ ------- -------- ------------------------------------
/ running 0 ROOT
/manager running 0 manager
If you pipe commands into tomcat-manager
instead of providing them as
arguments, the --echo
command line switch can be included which will print
the prompt and command to the output:
$ echo list | tomcat-manager --echo localhost
--connected to https://home.kotfu.net/manager as ace
tomcat-manager> list
Path Status Sessions Directory
------------------------ ------- -------- ------------------------------------
/ running 0 ROOT
/manager running 0 manager
For most common errors, like failed authorization, connection timeouts, and DNS
lookup failures, tomcat-manager
catches the exceptions raised by those
errors, and outputs a terse message describing the problem. For example, if my
Tomcat container is not currently running, or if the HTTP request fails for any
other reason, you will see something like this:
$ tomcat-manager vm list
connection error
If you want all the gory detail, give the --debug
command line switch or
set debug=True
. Then you’ll see something like this (stack trace truncated
with ‘…’):
$ tm --debug vm list
Traceback (most recent call last):
File "/Users/kotfu/.pyenv/versions/3.6.2/envs/tomcatmanager-3.6/lib/python3.6/site-packages/urllib3/connection.py", line 141, in _new_conn
(self.host, self.port), self.timeout, **extra_kw)
File "/Users/kotfu/.pyenv/versions/3.6.2/envs/tomcatmanager-3.6/lib/python3.6/site-packages/urllib3/util/connection.py", line 83, in create_connection
raise err
File "/Users/kotfu/.pyenv/versions/3.6.2/envs/tomcatmanager-3.6/lib/python3.6/site-packages/urllib3/util/connection.py", line 73, in create_connection
sock.connect(sa)
socket.timeout: timed out
...
requests.exceptions.ConnectTimeout: HTTPConnectionPool(host='192.168.13.66', port=8080): Max retries exceeded with url: /manager/text/serverinfo (Caused by ConnectTimeoutError(<urllib3.connection.HTTPConnection object at 0x103180a20>, 'Connection to 192.168.13.66 timed out. (connect timeout=2)'))