Project naming

community, freesoftware 6 Comments

Number two in an occasional series of “time I wish I could have back” topics related to releasing proprietary software projects as free software.

What’s in a name?

It was famously said that there are 2 hard problems in computer programming: Cache invalidation, naming things, and off by one errors.

Naming a project is a pain. Everyone has their favourite, everyone’s an expert, and there are a dozen different creative processes that people will suggest. Also, project names are subject to approval by legal and brand departments often, which are 2 departments most engineers don’t want anything to do with. So how do you come up with an acceptable name without spending weeks talking about it? Here are some guidelines.

Avoid anything related to the company name or products

You don’t want to have corporate trademark guidelines, certification programmes, etc impacting the way your community can use the project name, and avoiding names related to company assets will make it easier to transfer trademark ownership to an independent non-profit, should you decide to do that in the future. In terms of maintaining a clear separation in people’s minds between the community project and your company’s products, it’s also a good idea to avoid “line extension” by reusing a product name

Outside of that, the number one thing to remember is:

Projects names are not the most important thing about your project

What’s important is what problems you solve, and how well you solve them. The name will grow on people if they’re using the project regularly. You can even end up with interesting discussions like “is it pronounced Lee-nooks or Lie-nucks?” which can galvanise a nascent community. Also, remember that:

Project names can be changed

How many projects fall foul of existing trademarks, end up rebranding soon after launch, or are forced to change names because of a change of corporate sponsor or a fork? Firefox, Jitsi, WildFly, Jenkins, LibreOffice, Joomla, Inkscape all started life under different names, and a rename has not prevented them from going on to be very successful projects. The important thing, in an open source project, is to start small so that you don’t have a huge amount invested in the old name, if circumstances require you to change it.

Avoid a few pitfalls

Avoid using anything which is related to the trademarks of competing companies or projects, unless it is pretty abstract (Avid to Diva, Mozilla to Mosaic Killer, Eclipse to Sun).

That said, don’t worry too much about trademarks. Yes, do a quick search for related projects when you have a shortlist, and check out USPTO. But just because there is a Gnome Chestnut Farms in Bend, Oregon doesn’t mean you can’t call your free software desktop environment GNOME. Domain of use is a powerful constraint, take advantage of it.

Avoid potentially politically incorrect or “bad language” words. Also, avoid artificially smart acronyms. The Flexible Add-on Release Tracker might seem like a good idea, but… don’t.  GIMP is a notable exception here to both rules, and countless days have been spent defending the choice of name over the years.

Do worry about the domain name. This will be the primary promotion mechanism. People shouldn’t spend time trying to figure out if your project is hosted at “” or “” or “”. Make sure you get a good domain name.

Empower a small group to choose

The decision on a name should belong to 1, 2 or 3 people. No more. Once you realise that names are not the most important thing, and that the name can be changed if you mess up badly, that frees you from getting buy-in from everyone on the development team. The “committee” should include the project leaders (the person or people who will be identified as the maintainers afterwards), and one person who is good at facilitating naming discussions (perhaps someone from your Brand department to ensure their buy-in for the result). Beyond that, do not consider surveys, general calls for names, or any other process which gives a sense of ownership of the process to more than 2 or 3 people. This way lies many weeks and months of bikeshedding arguments.

Have a process

  1. Start with a concept and work from there. Break out the Thesaurus, make a list of related concepts.
  2. Names can be abstract or prosaic, it doesn’t really matter. Discourse is one of the most wonderfully prosaic project names I’ve seen, but StackOverflow has nothing to do with a questions & answers forum. Ansible is a made up word, Puppet and Chef both evoke wonderfully orchestration while being dictionary words.
  3. Keep the shortlist to names which are short and pronounceable in multiple languages.
  4. Cull ruthlessly – don’t keep “maybe” names. If you get to the end, go back to the concepts list and start again.
  5. If you get to a shortlist of 2 or 3 and can’t decide, use random() to pick the winner or go with the choice of the project leader.

In general, don’t spend too much time on it. You should be able to get a couple of candidate names in a few days of discussion, submit them to Legal for a trademark review, and spend your time on what really matters, understanding your users’ problems and solving them as well as you can.

Of course, this is easier said than done – good luck!

Choosing a license

community, freesoftware 10 Comments

One in a series of indeterminate length I am calling “mostly unimportant questions which take an inordinate amount of time to resolve when releasing a project as free software”. For the next topic, I’m hesitating between “naming”, “logo/icon/mascot design” and “mailing lists or forums”.


Choosing a license

Free software projects need licenses. But choosing a license is such a pain that most github projects don’t even bother (resulting in an initiative by Github to rectify this). And when taking a closed source project and making it free software, the topic of license choice will take a huge amount of time and effort.

I have found the following questions accelerate things nicely.

  1. Does the project exist as part of a greater ecosystem (eg. Apache, Eclipse, GNOME, Perl, Ruby)?
  2. If so, is there a predominant license in that ecosystem (eg EPL for Eclipse, MPL for Mozilla, MIT for Ruby gems)? Then use that license.
  3. Does your business model depend on you having total control of the project for the foreseeable future? (Aside: If so, consider changing your business model) Consider GPL v3+/proprietary dual license
  4. Do you want to grow a vibrant developer community around your project? If not, why not? Avoid dual license, copyright assignment
  5. Do you want to grow a vibrant service partner/extensions ecosystem, including proprietary extensions, around your project? Avoid GPL v2+ or v3+ – prefer MPL v2 or Apache v2
  6. Do you have any dependencies whose licenses you must comply with (eg. GPL v2 hard dependency)? Ensure you can distribute result under a compliant license
  7. Do you have concerns about the patent portfolios of potential project contributors? Choose from GPL v3, MPL v2, Apache v2 for stronger patent protection for contributors
  8. Do you believe that all contributors to the project, including extensions, should be subject to the same rules? Choose GPL v3
  9. Do you believe that the source code is free, and people should do whatever they want with it as long as they give you credit? Choose MIT or Apache v2
  10. After answering these questions, are you considering a license outside of (L)GPL v3, MPL v2, Apache v2 or MIT? Don’t.

After all of this, there are still situations which can lead to different outcomes – perhaps you want to join a specific non-profit later, and your license choice will be influenced by that. Perhaps you have a dependency currently which you plan to work around later, and you might dual license source code contributions under multiple free software licenses to allow relicensing easily (as and Mozilla have done). But the answers to the 10 questions above will at least reduce the scope of your search to one or two licenses.

Any considerations I have missed? Comments welcome!

The value of open source (for customers)

freesoftware, General, openstack, red hat, work 1 Comment

Over at, the Red Hat community blog, I have posted an article detailing some of the value I see to customers of companies who support and build on free software. The article is basically notes from a presentation I will be giving next Wednesday at the Red Hat Summit, “Community Catalysts: The Value of Open Source Community Development”. The problem statement?

It’s not always obvious, however, what the value of that is to our customers. The four freedoms of the free software definition which personify open source software – the freedom to use, study, modify and share modified copies of the software – at first glance appear to benefit only participants in open source communities. If you are a customer of a company like Red Hat, does it really matter that you have access to the source code, or that you can share the software with others? Aren’t customers, in some sense, paying us to “just take care of all of that stuff?”

This line of thought is not original, but it’s one I’ve had for a long time – and others such as Simon Phipps have given voice to similar insights in the past. Hopefully I can give it a fresh treatment for Red Hat Summit attendees next week!

Open Source Parenting at OSCON 2013?

community, freesoftware 5 Comments

The OSCON 2013 Call for Participation just opened and the list of tracks this year is mostly the same as last year. I am a touch disappointed, because I suggested to some of the conference chairs that a track I’d love to see, and which I think would get lots of attention, would be on how we grown-up hackers ensure that we’re growing the next generation of open source hackers. In other words, as a parent, tips on sharing our passion for technology and the open source, free software, hacker ethos with our kids.

This generally fits into the “Geek lifestyle” theme, which is the most marginal of the tracks, but I bet that if there’s a critical mass of quality proposals on the topic, that we could have a separate open source parenting track at OSCON – and it would be standing room only all week.

Some things I would love to talk about or hear people talk about:

  • Hackable living space – teaching kids they can control their environments
  • Preschool engineering – toys and games that teach your child to hack before they can walk
  • My First Electronics Kit – How my son and I learned how to make a solar powered car from scavenged parts
  • Teaching kids to hack – coding literacy in K12

And anything else which gives me ideas for projects I can do with the kids and their friends, or that I can bring to the local school.

Wouldn’t that be the coolest track *ever*? All it needs to happen is to totally blind-side the conference chairs with a dozen high quality proposals that no-one could possibly refuse! Who’s with me? Won’t somebody please think of the children?!?


Open Source communities

community, freesoftware 1 Comment

I was re-reading one of my favourite blog posts on running an Open Source community today, and thought I would share it.

Max Kanat-Alexander is the Bugzilla Release Manager, and put a variety of thoughts on leading an Open Source community together – Open Source Community, Simplified.

The TL;DR version, for those too lazy to click through, is:

  1. Don’t freeze your trunk for long periods
  2. Turnover is inevitable, so recruitment is vital
  3. Respond to contributions immediately
  4. Be extremely kind and appreciative
  5. Encourage a total absence of personal negativity

His own tl;dr version of this is: “be really, abnormally, really, really kind, and don’t be mean”.

He then talks about removing barriers to contribution, promoting your project and getting new contributors interested.

All in all, an excellent contribution, and well worth the read.

“Community citizenship” survey

community, freesoftware 1 Comment

I spoke to Kevin Carillo about what makes a good community citizen a few months ago – he had already been working for some time on his research at that point, and I thought that his approach and ideas were interesting.

Recently, he blogged about his work, and released a survey targeting recent contributors to a variety of projects, including Debian, GNOME and Mozilla.

As a long-time participant in various open source projects, I regularly see sociologists posting announcements for surveys to lists asking for developers time without first trying to get a feel for the communities involved, and figuring out how their work can benefit the community. They are zoologists, studying the behaviour of strange and wondrous beasts they don’t understand.

Kevin, like Evangelia Berdou and Malgorzata Ciesielska in the past, has adopted another approach – talking to people one-on-one and crafting a survey after building an understanding of community dynamics. I have high hopes that his resulting research will be as valuable to us as Evangelia and Gosia’s work was in the past.

I encourage anyone who fits the target profile to participate in his survey.

Humanitarian Free & Open Source Software meeting place

community, freesoftware Comments Off

This year, we hosted a Humanitarian Free and Open source software track at the Open World Forum for the third time. The track has been of great value to participants as a way of communicating with other practitioners in the space, and exchanging best practices and experiences around funding, community, and working with NGOs.

Once again, we had great participation from representatives of a wide range of projects, in crisis management, healthcare, social enterprise and microfinance. And the quality of the presentations was excellent – when discussing after the conference with Leslie Hawthorn what our favourite presentations were, the short answer was “all of them”. My personal favourites were Mark Prutsalis’s description of the EUROSHA project, Heather Blanchard’s experiences from working closely with aid agencies, and Leslie’s presentation with Julius Awakame of the great work that OpenMRS is doing in electronic medical record management targeting the poorest communities in the world.

The number one request I have had for the track is to turn it into more of a conversation – part presentations to establish a baseline for discussion, but mostly workshops or discussion forums on issues common to projects in HFOSS. Some organisations have funding, but have not succeeded in developing a commercial ecosystem of partners to support the deployment of the software. Other organisations have a partner ecosystem, but have not succeeded in growing an active community or identifying a sustainable funding model. Others have vibrant communities, but do not have either the funding or the organisational infrastructure to have a full time staff, or to bid for projects with aid agencies.

How would you feel about making next year’s Humanitarian track at the Open World Forum a worldwide meeting place of leaders of HFOSS projects, over two days, with a more traditional conference component including presentations, round-tables and workshops, and a Humanitarian BarCamp the day afterwards in Paris? I bet that if we can get critical mass for the idea that we could make this a regular meeting place for these projects. If there is somewhere else more appropriate as a meeting of minds, I’m happy to point people there instead, but I do not have the impression that there is. It has become obvious to me that there is a need for such a meeting place, and Paris in the Autumn seems like the ideal place to have it – central location, easy accessibility internationally from Europe, America, Asia and Africa.

Is there interest in making a real Humanitarian FOSS conference in Paris next year?



Attention! Speed bump ahead!

community, freesoftware, General 13 Comments
Speed bump ahead

Speed bump ahead!

This week I was reminded that the first step in an Open Source project is often the hardest. We’ve been using MediaWiki for a project at work, with the “ConfirmAccount” extension to deal with spammers – a very nice extension indeed! It adds account creation requests to a queue where they can be handled by members of the bureaucrat group.

We had one wishlist item. We wanted to have a notification email sent out to every member of the group when a new request was received. There is an existing feature to send a notification email to a configurable email address, but not to the whole bureaucrat group.

So I said to myself, how hard can that be? And I rolled up my sleeves and set aside an afternoon to make the change, and submit it upstream. After a few false-starts which were nothing to do with MediaWiki, I got down to it.

First task: Upgrade to the latest version of MediaWiki – the version on Fedora 17 is MediaWiki 1.16.5, and the latest stable version is 1.19.2. So I download the latest version, and follow the upgrade instructions to over-write the system MediaWiki install in /usr/share/mediawiki with the upstream version. Unfortunately, the way that $IP (the Install Path) is set changed in version  1.17, in a way that took a little time to work around.

Once that was done, I downloaded the HEAD of the trunk branch from SVN which was linked from the old version of the extension home page, and got the extension working. That needed a few additional modules, and some configuration to get the email notifications working locally, but eventually, I was good to go.

I got to work making my change. It took a while, but once I figured out how to turn on debugging and the general idiom for database queries, it was easy enough. After a couple of hours hacking and testing, I was happy with the result.

The first date

I headed back to the extension home page to figure out how to submit a patch. At the same time, out of habit, I joined the project IRC channel, #mediawiki on Freenode, reasoning that if I got lost I could ask for help there. No indication on the Extension page, but a web search showed me that MediaWiki uses Bugzilla. So I registered for Yet Another Bugzilla Account, and confirmed my email address a few minutes later. Then I created a bug on Bugzilla, and attached my patch to the report.

Simultaneously, on IRC, I was asking for help and was told by a very nice community guy called Dereckson that the preferred way to submit patches was through Gerrit. It turned out that the extension home page should have been pointing to the more recent Git repository all along, and I had been developing against the wrong version of MediaWiki. Dereckson updated the extension page with the right repository information as soon as he discovered it hadn’t been updated before. No big deal, I cloned the Git repository, and tried to apply the patch from svn to git. Unfortunately, it didn’t work – some other changes related to translatable strings had changed code in the same area, and I had to re-do the change, but that was pretty easy.

I did try to submit a patch by following the procedure in the git workflow document, but without an account on Gerrit it didn’t work, of course. Dereckson convinced me to apply to developer access. After some initial resistance, because I really didn’t want to be a MediaWiki developer just to submit a drive-by patch, I requested developer access with the comment “I just wanted to submit one patch to an extension I use, Extension:ConfirmAccount.” Half an hour later, jeremyb approved my request with the comment “That’s what you think now!” :-)

Then I went to the documentation on getting access and followed the instructions there until I was directed to upload my ssh key to labs and found I did not have access to that resource. Thanks again to Dereckson (once more to the rescue!) on IRC, I found my way to getting set up for git and Gerrit, and got an SSH key set up for Gerrit. Then I went back to the instructions for submitting a patch and a quick “git review” later, I had submitted my first patch ever to Gerrit.

Jumping through hoops

Jumping through hoops (CC by-sa, rwp-roger@flickr)

Pretty quickly, the first couple of reviews came in. First comment: “There’s some whitespace issues here.” Gee, thanks. Second comment, from Dereckson (again!) started with a “Thank you”, said the idea was a good one, and then gave me an example of the project norms for commit comments,  and made one comment on the code suggesting I use an option.

As a first time user of Gerrit, I noticed a few issues with it for newbies. It’s not at all clear to me how to distinguish “important” commenters from trivial-to-change things like whitespace issues. It’s also not clear whether a -1 blocks a commit, or how to have a discussion with someone about the approach taken in a patch. Also, it was unclear what the suggested way to update a patch was and propose a new, improved version. My first try, I made some changes, committed them into a new revision on my local branch, and pushed the lot for review (normal git workflow, I daresay). Unfortunately, this was not correct. I ended up squashing the two commits with a “rebase -i”, and since then I have been using “commit –amend”.

After a few more rounds of comments (another whitespace comment, and a suggestion to avoid hard-coding the group name), I am currently on the 5th patchset, which I think does what it says it should, and will pass review muster, when someone gets around to reviewing it. I’ve been told that the review time for a small patch like this can be up to 5 or 10 days, and I don’t know exactly how I know that the process is over and it’s good to commit.

Sunk costs

The end result is that for a small change to a fairly simple MediaWiki extension, I spent about 2 hours coding, and about 4 or 5 hours (a full afternoon) going through the various hoops involved in submitting the change for review upstream.

I’m aware that this is a one-off cost – that now that I have a Bugzilla account, and a git and Gerrit account, it will be easier next time. Now that I have spent the time reading the MediaWiki coding conventions, git workflow, and have spent time understanding how to use Gerrit, I won’t have these issues again. The next patch will only take a few minutes to submit, and I won’t be wondering if I did something wrong if I don’t get a review in the first 10 minutes.

But along with some installation and firewall issues, I ended up spending slightly more than a full day on this. In hindsight, I’m saying to myself “was it  really worth a full day of work to avoid maintaining this 20 line patch over time?”

I think it’s important that projects make newcomers jump through some hoops when joining your project – the tools you use and the community processes you follow are an important part of your culture. Sometimes, however, the initial investment that you have to put into the first-time use of a tool – the investment that regular contributors never see any more – is big.

If you’ve never used Bugzilla, git, Gerrit, or SSH, how long would it take you to submit a first patch to a project? How many hurdles does someone have to jump through to submit a patch for your project? Is there a way to ease people into it? I could imagine something like an email based process for newcomers, and only after they’ve made a few contributions, insist that all of the community’s preferred tools and processes be used. Or having true single sign-on, where you have only one account-creation process for all of your interactions with the project, so that you don’t end up creating a wiki account, a Bugzilla account, a Labs account and configuring a Gerrit account.

I want to make clear – I am not picking on MediaWiki here. I rate the project well above average in the speed and friendliness with which I was helped at every turn. But they, like every project, have adopted tools to make it easier for regular contributors, and to help ensure that no patches get dropped on the floor because of poor processes. Here’s the $64,000 question: are the tools and processes which make it easier for regular contributors making it harder for first-time contributors?

Joining Red Hat

community, freesoftware, work 30 Comments

I’m joining Red Hat on May 2nd, where I’ll be working with the Open Source and Standards team. We’ll be working hard to help all of the projects that Red Hat contributes to kick ass at growing community. I have known several of the team from years gone past, and interviewing for the position was frankly a pleasure.

I’d like to thank Karsten Wade for thinking of me and making the connections back in February. When my future boss described the position and the team to me around then, and asked me whether I might be interested, I couldn’t help myself from saying “I think you just described my dream job”. I know you’re supposed to show restraint and play hard to get in these situations, but I got carried away.

Red Hat is one of the few companies out there that could tempt me away from independent consulting. They have a range of projects covering the server, desktop, middleware, cloud services and virtualisation. They are the top, or one of the top, corporate contributors to dozens of projects I use every day. I love the Red Hat philosophy of working with communities to make great Free and Open Source software.

Of course, that doesn’t mean that everything is roses. There are projects within Red Hat (or that Red Hat contributes heavily to) which need to improve their community processes, that could do a better job of promoting themselves, or that have hung on to former business models post-acquisition, at the expense of community growth. And it’ll be our job to fix those issues. It’ll be challenging, it’ll be a slow, incremental process. But I have no doubt that it will be very rewarding. I’m looking forward to it!

Connecting Apache httpd to Tomcat with mod_jk: The bare minimum

freesoftware, General, work 3 Comments

Earlier this week, I wrote:

I hate docs that tell you what to do, but not why. As soon as a package name or path changes, you’re dust. This is maybe the 4th time I’ve been configuring Apache to delegate stuff to Tomcat using mod_jk, and every time is just like the first.

For those who don’t know, mod_jk is a module inplementing the wire protocol AJP/13, which allows a normal HTTP web server to forward on certain requests to a second server. In this case, we want to forward requests for JSP pages and servlets to Tomcat 6. This allows you to do neat things like serve static content with Apache and only forward on the dynamic Java stuff to Tomcat. The user sees a convenient URL (no port :8080 on the hostname) and the administrator gets to serve multiple web scripting languages on the same server, or load balance requests for Java server resources across several hosts.

I have spent enough time on it at this point, I think, that I understand all of the steps in the process, and have stripped it down to the bare minimum that one would need to do in terms of configuration to get things working. And so I’m putting my money where my mouth is, and this is my attempt to write a nice explanation of how mod_jk does its thing, and how to avoid some of the common mistakes I had.

First, a remark: Apache is one of those pieces of software that has gotten harder, rather than easier, to configure as time has gone on. Distributions each package it differently, with different “helpful” mechanisms that make common tasks like enabling a module easier, and to enable convenient packaging of modules like PHP, independent of the core package. But the overall effect is that a lot of magic done by distributions makes it much harder to follow the upstream documentation. Config files are called different names, or stored in different places. Different distributions handle the inclusion of config file snippets differently. And so on.

This is not to say that Apache, Tomcat and mod_jk don’t have some nice docs – they do, but often the docs don’t correspond to the distros, or haven’t been updated in a while, and often they don’t explain why you have to do something, putting emphasis instead on what you need to do. After all my reading, I finally found the Holy Grail I was looking for – the simple document of how to configure mod_jk – but even this has its shortcomings. The article doesn’t mention Tomcat, for example, which left me digging around for information on the configuration I needed to do to Tomcat, which led me to this, which led me to over-write the sample file in the simple set-up document.

But if you understand the First Principles, you can figure out what’s going on with any organisation of configuration. That’s what I’m hoping to get across here.

How does mod_jk do its thing?

The first issue I had trouble getting my head around was how, exactly, all this was supposed to work. In particular, I didn’t quite understand how the configuration worked on the Tomcat size of things.

As I understand it, here’s what happens:

  • A GET request comes in to httpd for http://localhost/examples/jsp/num/numguess.jsp
  • Apache processes the request, and find a matching pattern for the URL among JkMount directives
  • Apache then reads the file specified by the JkWorkersFile option to figure out what to do with the request. Let’s say that config file says to forward to localhost:8009 using the protocol ajp13
  • Tomcat has a Connector listening on port 8009, with the protocol AJP/13, which handles the request and replies on the wire. Apache httpd sends the reply back to the client

Apache httpd configuration

There are two steps to configuring Apache:

  1. Enabling the module
  2. Configuring mod_jk

Apache provides a handy utility called “a2enmod” which will enable a module for you, once it’s installed. What happens behind the scenes for modules depends on the distribution. On Ubuntu, module load instructions are put in a file called /etc/apache2/mods-available/<module>.load optionally alongside a sample configuration file /etc/apache2/mods-available/<module>.conf. To enable the module, you create a symlink to the .load file in /etc/apache2/mods-enabled.

On my Ubuntu laptop, my jk.load contains:

LoadModule jk_module /usr/lib/apache2/modules/

On OpenSuse, on the other hand, a line similar to this is explicitly added to the file /etc/apache2/sysconfig.d/loadmodule by sysconfig, based on the contents of a field in the configuration file /etc/sysconfig/apache2 – remember how I said that distro packaging makes things harder? If you added the line directly to the loadmodule file, the change would be lost the next time Apache restarts.

In both cases, these files (on Ubuntu, the mods-available/*.load files, and on OpenSuse the sysconfig.d/* files) are loaded by the main Apache config file (httpd.conf) at start-up.

Configuring mod_jk

The minimum configuration that mod_jk needs is a pointer to a Workers definition config file (JkWorkersFile). Other useful configuration options are a path to a log file (JkLogFile – which should be writable by the user ID which owns the httpd process) and a desired log level – I set JkLogLevel to “debug” while getting things set up. On OpenSuse, I also needed to set JkShmFile, since for the default file location (/srv/www/logs/jk-runtime-status) the directory didn’t exist and wasn’t writable by wwwrun, the user that owns the httpd process.

This configuration, and the configuration of paths below, is usually in a separate config file – in both Ubuntu and OpenSuse, it’s jk.conf in /etc/apache2/conf.d (files ending in .conf in this directory are automatically parsed at start-up). To avoid errors in the case where mod_jk is not present or loaded, you can surround all Jk directives with an “<IfModule mod_jk.c>…</IfModule>” check if you’d like.

The JkMount directive configures what will get handled by which worker (more on workers later). It takes two arguments: a path, and the name of the worker to handle requests matching the path. Unix wildcards (globs) are accepted, so

JkMount /examples/*.jsp ajp13_worker

will match all files under /examples ending in .jsp and will pass them off to the ajp13_worker worker.

If you want Apache to serve any static content under your webapps, you’ll also need either a Directory or Alias entry to handle them. Putting together with the previous section, the following (from Ubuntu) was the jk.conf file I used to pass the handling of JSPs and servlets off to Tomcat, and serves static stuff through Apache:

<IfModule mod_jk.c>

JkWorkersFile   /etc/libapache2-mod-jk/
JkLogFile       /var/log/apache2/mod_jk.log
JkLogLevel      debug
Alias /examples /usr/share/tomcat6-examples/examples
JkMount /examples/*.jsp ajp13_worker
JkMount /examples/servlets/* ajp13_worker


I should use Directory to prevent Apache from serving anything it shouldn’t, like Tomcat config files under WEB-INF – I could also just use “JkMount /examples/* ajp13_worker” to have everything handled by Tomcat.

Now that Apache’s config is done, we need to configure mod_jk itself, via the file we set in the JkWorkersFile parameter.

Sample files contain a lot of stuff you probably don’t need. The basic, unavoidable parameters you will need are the name of a worker (which you’ve already used as the 2nd argument for JkMount above), and a hostname and port to send requests to, and a protocol type (there are several options for worker type besides AJP/1.3 – “lb” for “load balancer” is the most important to read up on). For the above jk.conf, the simplest possible file is:


And that’s it! The last step is to set up Tomcat to handle AJP 1.3 requests on port 8009.

Configuring Tomcat

In principle, Tomcat doesn’t need to know anything about mod_jk.It just needs to know that requests are coming in on a given port, with a given protocol.

Typically, an AJP 1.3 connector is already defined in te default server.xml (in /usr/tomcat6 on both Ubuntu and OpenSuse) when you install Tomcat. The format of the connector configuration is:

<Connector port=”8009″ protocol=”AJP/1.3″ redirectPort=”8443″ />

I am pretty sure that this will work without the redirectPort option, but I haven’t tried it. It basically allows requests received with security constraints specifying encryption to be handled over SSL, rather than unencrypted.

In addition to this, Tomcat does provide a facility to auto-create the appropriate mod_jk configuration on the fly. To do so, you need to specify an ApacheConfig in the Tomcat connector, and point it at the file. This facility looks pretty straightforward, but I know I found it confusing in the past when I lost edits to the jk.conf file – I prefer manual configuration myself.


I have had quite a few gotchas while figuring all this out – I may as well share for the benefit of future people having the same problems.

  • All the documentation for mod_jk installedd with the packages refers to Tomcat5 paths – for example, on OpenSuse, in the readme, I was asked to copy workers.config into /etc/tomcat5/base – a directory which doesn’t exist (even when you change the 5 to a 6)
  • If your apache web server uses virtual hosts (and, on Ubuntu, it does by default) then JkMounts are not picked up from the global configuration file! You need to either add “JkMountCopy true” to the VirtualHost section, or have JkMounts per VirtualHost. If you used Alias as I did above, and you try to run a servlet, the error message is just a 404. If you try to load a JSP, you will see the source.
  • If you make a mistake in your file (I had a typo “workers.list=ajp13_worker” for several hours) and your worker name is not found in a “worker.list” entry, you will see no error message at all with warnings set to error or info. With the warning level set to debug, you will see the error message “jk_translate::mod_jk.c (3542): no match for /examples/ found” The chances are you have a typo in either your jk.conf file (check that the name of the worker corresponds to the name you use in, or you have a typo somewhere in your file (is it really work.list? Does the worker name match? Is it the same as the worker name in the .host, .port and .type configuration?
  • Make sure you get Tomcat working correctly first and working perfectly on port 8080 – or you won’t know whether errors you’re seeing are Tomcat errors, Apache errors or mod_jk errors.

I’m sure I’ve made mistakes and forgotten important stuff – I’m happy to get feedback in the comments.

« Previous Entries