1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
# Overview
Apache Tomcat is an open source implementation of the Java Servlet and
JavaServer Pages (JSP) specifications, and provides a "pure Java" HTTP
web server environment for Java web applications to run.
Apache Tomcat 7 implements the Java Servlet 3.0 and JSP 2.0 specification
from Sun Microsystems/Oracle.
<http://tomcat.apache.org>
# Usage
## General
A tomcat deployment consists of a Tomcat service:
juju deploy tomcat
By default, this is Tomcat version 7. You can deploy Tomcat 6 by specifying
the version at deployment. First create a [YAML](http://www.yaml.org/) file
with the contents:
tomcat:
tomcat_version: tomcat6
Then deploy:
juju deploy --config config.yaml tomcat
Once deployed, you can specify what http port to use:
# use port 80 for http
juju set tomcat http_port=80
(NOTE: You could also do this at deployment with the `--config` switch)
The Tomcat manager applications, enabled by default, are protected by HTTP basic
password protection. To access the applications you must set a password for
either the `admin` or `status` roles. The admin role has full access to
configure Tomcat whereas the status role may only see server status. To set
passwords:
juju set tomcat admin_password=<password>
juju set tomcat status_password=<password>
To expose Tomcat to the Internet:
juju expose tomcat
Open web browser to http://<host>/manager or http://<host>/manager/status
using your admin or status username/password respectively.
(Note: Passwords will be sent to the manager in plain text, so it is
recommended to enable HTTPS as follows)
To enable HTTPS:
# enable https connector
juju set tomcat https_enabled=True
# use port 443 for https
juju set tomcat https_port=443
Open web browser to https://<host>/manager or https://<host>/manager/status.
A self-signed certificate will be generated for HTTPS use by default. You can
specify your own private key and certificate as a PKCS12 file as follows:
# set pkcs12 file
juju set tomcat keystore=`base64 < <pkcs12 file>`
# set pkcs12 file password
juju set tomcat keystore_password=<password>
The PKCS12 file is transmitted securely to your Juju cluster and subsequently
used by all service units (added with `juju add-unit`) for easy certificate
management. Should you remove your certificate by setting `keystore` to an
empty string, a new self-signed certificate will be generated for use.
While the manager applications are a useful way of testing a Tomcat
installation there is no real usage for them when deploying applications using
a Juju subordinate charm like `j2ee-deployer`. Therefore as a security
precaution, it is recommended you disable them in a production environment:
# disable manager applications
juju set tomcat manager_enabled=False
Tomcat offers two pure Java HTTP connectors, Blocking I/O ("bio") and
Non-Blocking I/O ("nio").
- **bio** is the default connector and uses a thread per connection.
- **nio** uses a single thread to read connections asynchronously.
If you have enough traffic to be concerned about performance of each,
it is recommended you benchmark both. Better performance can be achieved with
either depending on conditions. Traditionally, Java application traffic favors
the bio connector and serving of static content with the nio connector.
You may set either as follows:
# set nio connector
juju set tomcat http_connector=nio
# set bio connector
juju set tomcat http_connector=bio
## Java Debugger (JDB)
Remote debugging can be useful for application development and diagnositing
problems with a deployed application. There are many debugging tools,
including jdb, and most Integrated Development Environments (IDEs) provide
the ability to attach to remote servers and step through code line by line.
The tomcat charm provides the ability to attach remote debuggers by using the
`debug_enabled` configuration option. The default port 8000 is open when
`True` and closed when `False` (default).
## Java Management Extenstion (JMX)
JMX monitoring is disabled by default, but you can enable it with the
following commands:
juju set tomcat jmx_enabled=True
juju set tomcat jmx_control_password=<password>
juju set tomcat jmx_monitor_password=<password>
The control role (username = `controlRole`) allows read/write access, the
monitor role (username = `monitorRole`) read only access. If a password is
empty, it disables access for that role.
There is a further JMX option, `jmx_localhost`. This determines what hostname
is given to the JMX client to connect to. If false, the internal hostname or
private IP address of the unit will be used, meaning connection is suited to
either LXC based deployments or cloud deployments where you have VPN access:
JConsole or VisualVM connect to <private unit address>:10001 with
username/password
For cloud deployments, setting this to `True` uses hostname `localhost`, which
allows you to connect over a ssh tunnel:
ssh -L 10001:localhost:10001 -L 10002:localhost:10002 <public unit address>
JConsole or VisualVM connect to localhost:10001 with username/password
The latter is much more typical of out of the box deployment, so `jmx-localhost`
defaults to True.
## Java Naming and Directory Interface (JNDI)
Tomcat supports adding arbitrary configuration parameters for JNDI lookup by
deployed applications. This enables you to develop applications that discover
configuration details at runtime simply by referencing pre-determined JNDI
names. This charm supports lookup of different Juju services, each of which
may be configured using the appropriate `jndi_<type>_config` option. Unless
specified otherwise, options are generally a comma separated list of JNDI name,
service and type specific colon separated values:
<name>:<service>,<name>:<service>
This allows you to map Juju services to JNDI names as follows:
# map the JNDI name 'param/Memcached' to the Juju service named 'memcached'
juju set tomcat jndi_memcached_config="param/Memcached:memcached"
# map the JNDI name 'param/Terracotta' to the Juju service named 'terracotta'
juju set tomcat jndi_terracotta_config="param/Terracotta:terracotta"
The charm will take care of mapping the JNDI name with the private addresses
of the Juju services. If you add units of memcached or terracotta the charm
will add the new addresses appropriately. A brief description of the available
JNDI relations is below.
Memcached (`jndi_memcached_config`) - Provides a space separated string of all
unit addresses for specified memcached service. This can be used directly
in instantiating an instance of a Memcached client such as spymemcached
(see <http://code.google.com/p/spymemcached/> for more details).
Terracotta (`jndi_terracotta_config`) - Provides a comma separated string of all
unit addresses for the specified Terracotta service. This can be injected
directly into EHCache or Quartz configuration (see <http://www.terracotta.org> for
more details).
## Scale out Usage
### Clustering
Tomcat supports session clustering, allowing a group of Tomcat units to
replicate J2EE session information to each other. This is useful for HA
deployments where session contents are important. To enable clustering across
units:
# enable clustering
juju set tomcat cluster_enabled=True
# add 2 more units to cluster
juju add-unit -n 2 tomcat
By default, static membership is used over multicast based membership which
means units depend on local cluster configuration to determine cluster groups.
Multicast uses multicast UDP packets on a pre-determined address/port to
determine cluster groups. Where a cloud provider such as EC2 disables multicast
traffic between instances, static membership must be used. Where multicast
traffic is allowed, it is preferred and may be enabled as follows:
# enable multicast clustering
juju set tomcat multicast=True
# set multicast address
juju set tomcat multicast_address=228.0.0.4
# set multicast port
juju set tomcat multicast_port=34569
For maximum performance with clustering, it is recommended you use a load
balancer in front of Tomcat that supports "sticky sessions".
# Contact Information
This charm was originally written by Robert Ayres <robert.ayres@ubuntu.com>
and is maintained by Matthew Bruzek <matthew.bruzek@canonical.com>. If you
encounter a bug with the tomcat charm please open a
[bug](https://bugs.launchpad.net/charms/+source/tomcat).
## Apache Tomcat Project Information
- [Apache Tomcat home page](http://tomcat.apache.org)
- [Apache Tomcat Mailing Lists](http://tomcat.apache.org/lists.html)
- [Tomcat Wiki](http://wiki.apache.org/tomcat/FrontPage)
- [Tomcat 7.0 Documentation](http://tomcat.apache.org/tomcat-7.0-doc/index.html)
- [Tomcat 6.0 Documentation](http://tomcat.apache.org/tomcat-6.0-doc/index.html)
- [Reporting Apache Tomcat Bugs](http://tomcat.apache.org/bugreport.html)
|