tomcatmanager 2.0.0

A command line tool and python library for managing a tomcat server.

If you use Apache Tomcat for any sort of development work you’ve probably deployed lots of applications to it. There are a several ways to get your war files deployed:

• use the Tomcat Manager application in your browser

• use the Tomcat Ant Tasks included with Tomcat

• use Cargo and its plugins for ant and maven

Here’s another way: a command line tool and python library for managing a Tomcat server.

What Can It Do?

This package installs a command line utility called tomcat-manager. It’s easily scriptable using your favorite shell:

$ tomcat-manager --user=ace --password=newenglandclamchowder \
http://localhost:8080/manager deploy local sample.war /sampleapp
$ echo $?
0

There is also an interactive mode:

$ tomcat-manager
tomcat-manager>connect http://localhost:8080/manager ace
Password:
--connected to http://localhost:8080/manager as ace
tomcat-manager>list
Path                     Status  Sessions Directory
------------------------ ------- -------- ------------------------------------
/                        running        0 ROOT
/sampleapp               stopped        0 sampleapp##9
/sampleapp               running        0 sampleapp##8
/host-manager            running        0 /usr/share/tomcat8-admin/host-manage
/manager                 running        0 /usr/share/tomcat8-admin/manager

And for the ultimate in flexibility, you can use the python package directly:

>>> import tomcatmanager as tm
>>> tomcat = tm.TomcatManager()
>>> r = tomcat.connect(url='http://localhost:8080/manager',
... user='ace', password='newenglandclamchowder')
>>> tomcat.is_connected
True
>>> r = tomcat.stop('/someapp')
>>> r.ok
False
>>> r.status_message
'No context exists named /someapp'

Installation

You’ll need Python >= 3.6. Install using pip:

$ pip install tomcatmanager

Works on Windows, macOS, and Linux.

Works with Tomcat >= 7 and <= 10.

Tomcat Configuration

This library and associated tools do their work via the Tomcat Manager web application included in the Tomcat distribution. You will need to configure authentication in tomcat-users.xml with access to the manager-script role:

<tomcat-users>
  ...
  <role rolename="manager-script"/>
  <user username="ace" password="newenglandclamchowder" roles="manager-script"/>
  ...
</tomcat-users>

Features

The tomcat-manager command line tool supports the following commands:

• deploy - deploy a war file containing a tomcat application in the tomcat server

• redeploy - remove the application currently installed at a given path and install a new war file there

• undeploy - remove an application from the tomcat server

• start - start a tomcat application that has been deployed but isn’t running

• stop - stop a tomcat application and leave it deployed on the server

• reload - stop and start a tomcat application

• sessions - show active sessions for a particular tomcat application

• expire - expire idle sessions

• list - show all installed applications

• serverinfo - show information about the server, including tomcat version, OS version and architecture, and jvm version

• status - show server status information in xml format

• vminfo - show diagnostic information about the jvm

• sslconnectorciphers - show ssl/tls ciphers configured for each connector

• threaddump - show a jvm thread dump

• resources - show the global jdni resources configured in tomcat

• findleakers - show tomcat applications that leak memory

Documentation

Complete documentation for the last released version is available at http://tomcatmanager.readthedocs.io/en/stable/. It includes material showing how to use tomcat-manager from the command line or using interactive mode. There is also a walkthrough of how to use the API and an API reference.

Documentation is also built from the develop branch, and published at https://tomcatmanager.readthedocs.io/en/develop/. The develop branch may not yet be released to PyPi, but you can see the documentation for what’s coming up in the next release.