Command Line¶
You’ve already read about Interactive Use right? If not, this part will feel kind of hollow.
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
Using Shell Scripts¶
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 Interactive Use. 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
Server Shortcuts¶
You can use Server Shortcuts 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 define shortcut(s) with credentials for the server(s) you want to manage, and reference the shortcuts 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 Settings 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 |
---|---|---|
-e, --echo |
echo |
Add the command to the output stream. |
-q, --quiet |
quiet |
Don’t show non-essential feedback. |
-s, --status-to-stdout |
status_to_stdout |
Send status information to stdout
instead of stderr . |
-d, --debug |
debug |
Show detailed exception and stack
trace, even if quiet is True. |
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 shortcut 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:
$ tm 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)'))