Configuration File
tomcat-manager
reads a user configuration file on startup. This file allows
you to:
change settings on startup
create Tomcat server definitions that include the url and authentication credentials
The `--noconfig
command line option prevents tomcat-manager
from
processing the configuration file on startup.
Location
The location of the configuration file is different depending on your operating
system. To see the location of the file on your system, run the following
command from within tomcat-manager
:
tomcat-manager> config file
/Users/kotfu/Library/Application Support/tomcat-manager/tomcat-manager.toml
Editing
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:
tomcat-manager> config edit
Syntax
The configuration file uses the TOML file format. TOML is a simple configuration file format that’s easy for humans to
read. tomcat-manager
doesn’t have complex configuration requirements, so TOML is a great fit. Here’s an example configuration file in TOML
format:
[settings]
prompt = "tm> "
debug = true
editor = "/usr/bin/mg"
echo = false
quiet = false
status_prefix = "--"
[tcl]
url = "http://localhost:8080/manager"
user = "ace"
password = "newenglandclamchowder"
Note
In versions prior to 6.0.0, the configuration file used the Microsoft Windows INI
file format, which is similar to TOML. For the tomcat-manager
configuration
file, the biggest difference between these two formats is that all string values
must be quoted in TOML, and in INI they are accepted without quotes.
When you run tomcat-manager
in interactive mode it will check if the old
configuration file is present. If it is, and if the new configuration file doesn’t
exist, it will let you know.
$ tomcat-manager
--In version 6.0.0 the configuration file format changed from INI to TOML.
--You have a configuration file in the old format. Type 'config convert' to
--migrate your old configuration to the new format.
Convert your configuration file to the new format:
tomcat-manager> config convert
--converting old configuration file to new format
--configuration written to /Users/kotfu/Library/Application Support/tomcat-manager/tomcat-manager.toml
--reloading configuration
Everything is converted to the new format automatically except comments. You’ll have to add your comments back in by hand.
Settings
Create a table called settings
, and use key/value pairs to set values for any of
the available settings. These settings are applied when tomcat-manager
starts,
and applied again after you finish editing the config file. Here’s an example of
settings in the config file:
[settings]
prompt = "tm> "
debug = true
editor = "/usr/bin/mg"
echo = false
quiet = false
status_prefix = "--"
See Settings for documentation on every setting.
Server Definitions
In addition to settings, you can use the configuration file to define Tomcat servers. The definition includes a name, the url, and authentication credentials. Create server definitions in your configuration file to keep the the authentication credentials off of the command line and out of your scripts, which is more secure.
A server definition is contained in a TOML table. The name of the table is the name of the server, and the various items in the table contain the details about that server. Here’s a simple example:
[local]
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 server:
tomcat-manager> connect local
You can also use the server name from the command line instead of providing the url:
$ tomcat-manager local
If you define a user
, but omit password
, you will be prompted for it
when you use the server definition in the connect
command.
Here’s all the properties supported in a server definition:
- url
Url of the server.
- user
User to use for HTTP Basic authentication.
- password
Password to use for HTTP Basic authentication. If user is provided and password is not, you will be prompted for a password.
- cert
File containing certificate and key, or just a certificate, for SSL/TLS client authentication. See SSL/TLS Client Authentication for more information.
- key
File containing private key for SSL/TLS client authentication. See SSL/TLS Client Authentication for more information.
- cacert
File or directory containing a certificate authority bundle used to validate the SSL/TLS certificate presented by the server if the url uses the https protocol. See Encrypted Connections for more information.
- verify
Defaults to
True
to verify server SSL/TLS certificates. IfFalse
, no verification is performed.
When using a server definition, you can override properties from the definition on the command line. For example, if we had a server defined like this:
[prod]
url = "https://www.example.com/manager"
user = "ace"
password = "newenglandclamchowder"
cacert = "/etc/mycacert"
You could use that server definition but temporarily disable verification of server SSL/TLS certificates:
tomcat-manager> connect prod --noverify
Or you could override the user and password:
tomcat-manager> connect prod root Z1ON0101
Some of these properties make no sense when combined together. For example, if your server authenticates with a certificate and key, it almost certainly doesn’t use a user and password. If you don’t want to verify server SSL/TLS certificates, then it makes no sense to provide a certificate authority bundle. See Authentication for complete details of all supported authentication mechanisms.