Documentation for JIRA 6.3 EAP developer (EAP) releases only. Not using this? See below:
(JIRA 6.2.x documentation | JIRA OnDemand documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

The following outlines some basic techniques to secure an Apache Tomcat instance. This is a basic must-do list and should not be considered comprehensive. For more advanced security topics see the "Further Information" section below.

User Permissions

Tomcat should never be run as a privileged user (root on UNIX or Admistrator or Local System on Windows).

Tomcat should be run as a low-privilege user. Ideally it should be run as a user created only for the purpose of running one application.

In practice this means you can't run it on port 80. If you need to run Tomcat on port 80, you should put it behind a webserver such as Apache; see Integrating JIRA with Apache for an example configuration.

Unix/Linux cheat-sheet

  • Create a JIRA user:
    sudo adduser jira-tomcat
  • Run Tomcat as a specific user:
    sudo -u jira-tomcat ${CATALINA_HOME}/bin/catalina.sh run

Windows cheat-sheet

  • Create an unprivileged account (if your host is part of an Active Directory there may be already a template for service users). The user should have "Log on as a service" rights assigned to it.
  • Make sure the Apache Tomcat service is set to run as that user. If Tomcat was installed using the JIRA Windows Installer, the system tray utility lets you set this via Configuration -> Log On:

Tomcat Installation Permissions

The Tomcat installation directory (sometimes referred to as CATALINA_HOME) should be installed as a user that is different to the one it will be run as. Under Linux, unpacking the Tomcat distribution as root is the simplest method of doing this.

Unfortunately, Tomcat does require write access to some directories in the distribution directory, but they should be enabled only as needed.

Tomcat ships with some default admin applications in its webapps directory. Unless you need these they should be disabled.

Unix/Linux cheat-sheet

  • Unpack Tomcat as root:
    sudo tar xzvf apache-tomcat-6.0.20.tar.gz
  • Remove the default webapps:
    sudo rm -rf apache-tomcat-6.0.20/webapps/*
  • Remove write permissions:
    sudo chmod -R go-w apache-tomcat-6.0.20
  • Allow write on needed directories only:
    cd apache-tomcat-6.0.20/; sudo chown -R jira-tomcat work/ temp/ logs/

Windows cheat-sheet

Note: If your host is part of a Domain/Active Directory, consult your Windows system administrator sysadmins to get the right permissions.

  • Unpack and install Tomcat, and update the permissions on CATALINA_HOME to be writeable by Administrators and System only. The Tomcat service user should have read, execute and directory traverse privileges


  • Under CATALINA_HOME, the work, temp and logs directories need write and delete access for the Tomcat user. Make sure it does not have permissions to change permission or take ownership.

Web-Application Installation Permissions

The directory you unpack the application WAR into should not be writable by the Tomcat user (i.e. jira-tomcat in the examples above). Again, the simplest method to do this is to unpack the WAR as root.

Unix/Linux cheat-sheet

  • Unpack the war as root:
    sudo unzip confluence-webapp-3.2.war

Windows cheat-sheet

  • Unpack the war as your user and confirm that the Tomcat user does not have write access to the webapp.

Further Information

8 Comments

  1. Anonymous

    mkdir database
    [root@mediator-integration jira]# chown jira:jira database/

    Under "Unix/Linux cheat-sheet"

    You also need a "database" dir owned by your jira user, otherwise it doesn't start up and you get a confusing messages on startup about the database being in use because it canNOT find a .lck file. WTF?

    cd apache-tomcat-6.0.20/; sudo mkdir database; sudo chown -R jira-tomcat:jira-tomcat work/ temp/ logs/ database/;

    1. Please note that this only applies to HSQL, which isn't supported for production instances.

  2. Anonymous

    conf/server.xml

    change password from SHUTDOWN to something else

  3. These directions seem to be aimed at Tomcat, but I'd really like to see them updated for those that have stand-alone installs of JIRA and Confluence.  Seems that nothing will take down an instance faster then wrong permission being set and I feel this document leaves a little too much guess work.

    1. Hi Troy,

      While the practices described in this documentation are recommended, they are optional.

      Having said that, we've now updated the JIRA archive installation instructions with a specific step that provides high-level steps for creating and running JIRA under a dedicated user account. These instructions indicate which JIRA/Tomcat directories this user account needs write access to.

      Cheers,
      Giles.

      P.S. We're also implementing similar instructions for the WAR distribution installation documentation.

    2. Just to make sure I understand this correctly.

      So when it states "Allow write on needed directories only", meaning to the dedicated user account (e.g. 'jira'), and assuming the following:

      • JIRA installation is /usr/local/jira
      • JIRA home is /var/jira-data
      • dedicated account is 'jira'

      Based on this, I'd execute the following commands to setup the permissions as you outline:

      1. Shouldn't it be:

  4. Anonymous

    If you are looking for tomcat security on UNIX, you can refer - Tomcat Harden and Security Guide