You've already read about Interactive Use <interactive>
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
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 <interactive>
. 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 succesfully
1 = command had an error
2 = incorrect usage
127 = unknown command
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
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.
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 <interactive>
. 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. |
|
|
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 shortcut
<server_shortcuts>
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)'))