Mailing-List: contact dev-help@tomcat.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Tomcat Developers List" <dev@tomcat.apache.org>
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
From: Apache Wiki <wikidiffs@apache.org>
To: Apache Wiki <wikidiffs@apache.org>
Date: Sat, 26 May 2012 20:32:29 -0000
Message-ID: <20120526203229.97722.78095@eos.apache.org>
Subject: 
 =?utf-8?q?=5BTomcat_Wiki=5D_Update_of_=22ClusteringOverview=22_by_MarkEgg?=
 =?utf-8?q?ers?=
Auto-Submitted: auto-generated

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Tomcat Wiki" for ch=
ange notification.

The "ClusteringOverview" page has been changed by MarkEggers:
http://wiki.apache.org/tomcat/ClusteringOverview

New page:
=3D From Zero to Clustered - an Overview =3D

This overview document is based on a posting to the mailing list concerning=
 clustering. This document gives a general overview of the issues and steps=
 that are needed in order to set up a small cluster on a single Linux syste=
m. Further documents will add detail and expand on this overview.

=3D=3D General Thoughts and the Mailing List =3D=3D

At each stage of the setup, I recommend testing before moving on to the nex=
t section. The mailing list is a good source of helpful information for whe=
n you have problems, provided that you do the following.

 * Ask simple, focused questions
 * Provide all of the requested information (inline, since the mailing list=
 strips most attachments)
 * Try to format configuration files reasonably
   * Remove comments
   * Be aware of word wrap
   * Don't use rich text / html text

Be aware that people on the mailing list are '''volunteers'''. Do not expec=
t homework answers, complete web applications, or systems architecture from=
 the list. Do expect to put in at least as much effort on solving the probl=
em as the people helping you are.

Also, there is a lot of misleading, incomplete, and just flat wrong informa=
tion concerning Tomcat floating around on the Internet. You might get accur=
ate information elsewhere, but from what I've seen this is not very likely.=
 The authoritative source for information is always:

http://tomcat.apache.org/

=3D=3D Linux in General =3D=3D

You'll find that Linux is a different beast than Windows (even Windows 7). =
In particular file permissions, file ownerships, and SELinux present quite =
a different security model than the typical Windows installation. It's best=
 to be aware of this from the start.

=3D=3D Purpose =3D=3D

The first question to answer is what is the purpose of this setup?

If you're running a test or production platform then set up a service accou=
nt and install all Tomcats there. A service account is an unprivileged acco=
unt used only for configuring and running Tomcat servers. Make this account=
 inaccessible from the network, and give the account its own group.

If you're setting up a development platform, then just create a directory a=
nd unpack multiple Tomcat servers in that directory. This will make dealing=
 with permissions easier, which is an important consideration when integrat=
ing Tomcat servers with IDEs such as Eclipse or NetBeans.

=3D=3D Apache HTTPD =3D=3D

Rather than building your own Apache HTTPD, I recommend that you get and in=
stall the distribution package for Apache HTTPD. This will place files in l=
ine with the rest of your system, and it will also have a serviceable defau=
lt configuration.

On Fedora, the Apache HTTPD packages include:

 * apr
 * apr-util
 * apr-devel
 * apr-util-devel
 * httpd
 * httpd-devel
 * httpd-tools

The -devel packages are very important, since you will be building mod_jk f=
rom source.

Most package managers will pull in the correct dependencies, however you wi=
ll have to specify the development packages separately.

=3D=3D Java =3D=3D

There are several versions and several ways to install Java on a Linux plat=
form. While both OpenJDK and Oracle's Java are reported to work well with T=
omcat, some people have reported problems when using GJC. Make sure you hav=
e a reasonable version of Java installed, and that it's used by default.

Type:

{{{
java -version
javac -version
}}}

to make sure you get the version you expect.

While the Tomcat startup scripts will do a good job at finding the desired =
Java, it's advantageous to set an environment variable to point to the desi=
red JRE.

In a bash shell, just type the following:

{{{
export JRE_HOME=3D[where your JRE is installed]
}}}

This will ensure that Tomcat uses the Java you want it to use. It's also a =
useful way to try new versions of Java.

=3D=3D Tomcat =3D=3D

As I've noted above if you're setting up a pure development environment it'=
s just best to create a directory in your home directory and unpack a Tomca=
t there. For now, just start with one.

If you have Java installed correctly, Tomcat comes ready to run out of the =
box. Just unpack it, cd to the bin directory, and run startup.sh. You shoul=
d be able to browse to localhost:8080/ and see the Tomcat welcome page.

Now stop the Tomcat server with shutdown.sh and set up the manager applicat=
ion. This involves editing the tomcat-users.xml file found in the conf dire=
ctory. Instructions for editing that file (for Tomcat 7) can be found here:

http://tomcat.apache.org/tomcat-7.0-doc/manager-howto.html#Configuring_Mana=
ger_Application_Access =


Once it's running and you can access the manager application, then associat=
e the installation with your IDE (if you're setting up a development enviro=
nment). Now you can develop, debug, test, and deploy from within your IDE w=
ithout running into permission issues.

{{{#!wiki important
Unlike Apache HTTPD, most people on the mailing list do NOT recommend that =
you use the Linux distribution packaged versions of Tomcat. In general peop=
le have found that these are much more difficult to work with than just get=
ting a stock Tomcat from http://tomcat.apache.org/
}}}

=3D=3D mod_jk build =3D=3D

While other people have had difficulty (search the mailing list) building m=
od_jk on various platforms, I've never had much trouble. The steps are quit=
e simple, provided you have the appropriate packages installed on your syst=
em.

 1. Download the source from http://tomcat.apache.org/download-connectors.c=
gi
 2. Unpack it into a directory
 3. cd to [tomcat-connectors-1.xx]/native
 4. Read BUILDING.txt

Following BUILDING.txt:

 1.  ./configure --with-apxs=3D/usr/sbin/apxs
 2. make
 3. su to root
 4. cd back to where you were
 5. make install

This will put everything in the right place.

=3D=3D mod_jk configuration =3D=3D

Recent versions of mod_jk come with some very nice and well-commented examp=
les. They can be found in [tomcat-connectors-1.xx]/conf. Read them, follow =
them, use them.

The defaults have been chosen to work in most general use cases.

In order to test mod_jk, map all of the examples (not just the *.jsp files).

Restart Apache HTTPD, and then start Apache Tomcat. You should be able to b=
rowse to localhost/examples and get the Apache Tomcat examples.

{{{#!wiki important
Do '''NOT''' proceed with clustering until you successfully connect one Apa=
che HTTPD with one Tomcat, and execute the examples.
}}}

Note that if you place all of your mappings in a uriworkermap.properties fi=
le, Apache HTTPD will reread this once per minute (by default). This is nic=
e if you tend to add and delete Tomcat applications. It's probably not quit=
e as nice for a production system (but I don't know what the overhead is).

=3D=3D Clustering =3D=3D

There are a lot of pieces to put together in order to get clustering to wor=
k. As noted in the introduction, this Wiki article just gives the lay of th=
e land. Future articles will go into more detail.

=3D=3D=3D Linux =3D=3D=3D

You have to ensure that multicast is enabled, and that multicast routing is=
 set up. If you run iptables, you may run into firewall issues, but on the =
same system probably not.

=3D=3D=3D mod_jk =3D=3D=3D

Each Tomcat gets at least one worker. This worker must be configured to tal=
k to a particular Tomcat on the correct AJP/1.3 port.

There are some other constraints for load balancing workers that should be =
noted. In workers.properties:

 1. Each worker name in a cluster must be unique
 2. The worker name must be the same as the jvmRoute attribute set in the E=
ngine element of the target Tomcat
 3. The worker name must be in a list of worker names for a loadbalancer

The mapping in uriworkermap.properties should point to the new loadbalancer=
 worker instead of an individual worker.

See the following for documentation on worker name versus jvmRoute attribut=
e:

http://tomcat.apache.org/tomcat-7.0-doc/cluster-howto.html#Cluster_Basics =


See the following for mod_jk loadbalancer configuration:

http://tomcat.apache.org/connectors-doc/reference/workers.html

=3D=3D=3D Another Tomcat =3D=3D=3D

While the easiest way to get started with clustering is just to unpack anot=
her copy of Tomcat in another directory, it's probably far more useful to u=
se the concept of CATALINA_HOME and CATALINA_BASE. See RUNNING.txt in the T=
omcat directory for details.

However another Tomcat is installed, the following needs to be done.

 1. Change the SHUTDOWN port to not conflict with the first Tomcat
 2. Change the HTTP/1.1 port to not conflict with the first Tomcat (useful =
for testing)
 3. Change the AJP/1.3 port to match that configured in workers.properties
 4. Change the jvmRoute attribute of the Engine element to match the correc=
t worker name
 5. Configure the manager application (useful for testing)

=3D=3D=3D Tomcat clustering configuration =3D=3D=3D

The basic clustering documentation can be found here:

http://tomcat.apache.org/tomcat-7.0-doc/cluster-howto.html =


It's long, involved, and needs to be read carefully. However, as a first pa=
ss the following will work.

 1. Make sure that each Tomcat has a unique jvmRoute in the Engine element =
(see above)
 2. Make sure that the jvmRoute matches the correct worker name (see above)
 3. Make sure that each Tomcat has a unique shutdown port (see above)
 4. Make sure that each Tomcat has a unique AJP/1.3 port (see above)
 5. Make sure that each AJP/1.3 port matches the correctly named worker in =
workers.properties (see above)
 6. Make sure that each HTTP/1.1 port is unique (nice for manager access)
 7. Copy the example configuration from:

http://tomcat.apache.org/tomcat-7.0-doc/cluster-howto.html

to inside the Host element in each server.xml, but omit (for now) the Deplo=
yer element. The cluster configuration can be placed inside the Host or Eng=
ine element. However, the Farm Deployer element will only work if the clust=
er configuration is inside the Host element.

Start up your Tomcat servers. If everything is set up correctly, cluster no=
tifications will appear in the logs.

It's also useful to have the access log enabled for your Tomcat servers. Yo=
u can then tell which Tomcat is receiving the request from Apache HTTPD.

----

This overview should point you in the right direction to get a two node clu=
ster up and running.

Again, start simply.

 1. Stock Apache HTTPD installation (and verify)
 2. Stock Apache Tomcat installation (and verify)
 3. mod_jk installation (and verify)
 4. Second Apache Tomcat installation (and verify)
 5. Cluster

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org