Command Line Clients to Manage Atlassian Software

Atlassian software such as JIRA and Confluence not only let user interact with them with a web interface: they both expose an API which can invoked remotely via JAX-RPC or SOAP protocols. Such an API is ideal if you need to batch execute some work on an instance or if you want to build a client of your own around it. Nowadays, with the help of modern IDEs and frameworks, it's pretty easy to build a JAX-RPC or SOAP client. The excellent Netbeans, for example, will build a Web Service client for you in just a couple of clicks: more than once I wrapped such a client inside some shell scripts just for their ease of use and for automation's sake.

Nevertheless, if what you need is just a wrapper around these remote APIs, you may consider using the Atlassian Command Line Interfaces instead of building your own client. Atlassian Command Line Interfaces are shell scripts about a Java client and the only requirement to run them is having Java in your $PATH which, probably, you already have. Their syntax respects the typical UNIX shell script conventions and you'll really feel at home with them.

There is an Atlassian Command Line Interface for almost every Atlassian product on the market:

• Bamboo Command Line Interface
• Confluence Command Line Interface
• Crowd Command Line Interface
• Crucible Command Line Interface
• FishEye Command Line Interface
• JIRA Command Line Interface

If you're using more than one product, consider downloading the Atlassian Command Line Interface bundle instead:

• Atlassian Command Line Interface

Happy scripting and enjoy a better experience with your Atlassian products.

Changing Confluence attachment storage

By default, Confluence will store attachments in the attachments subdirectory of its home directory but Confluence not only supports local file systems as attachment storage: it also supports database storage. The only drawback you should be aware of is obvious: database required capacity is going to increase. But not more than you would anyway be using in the local filesystem.

Advantages of using database storage are ease of administration as far as it concerns backing up and restoring a Confluence instance. Using your database to save files will also shield you from problems that might arise from invalid characters in file names for the file systems you're using to host the Confluence home directory.

To change Confluence attachment storage, just go to the Administration Console, open the Attachment Storage panel and select the storage type you want:

Take into account that you can switch to database attachment storage any time you need it: even though your Confluence instance is already storing attachments in the local file systems, Confluence will perform a migration of the attachments to the new storage and will soon be back online.

Backing up JIRA and Confluence taking advantage of ZFS snapshots

If you're running an instance of JIRA or Confluence (or many other software packages as well) you probably want to make sure that your data is properly and regularly backed. If you've got some experience with JIRA or Confluence you surely have noticed the bundled XML backup facility: a scheduled backup service which takes advantage of it it's even running by default in your instances.

The effectiveness of such a backup facility depends on the size of your installation but the rule of thumb is that it's a mechanism that does not scale well as the amount of data stored in your instances grows up. In fact, XML backup was thought for small-scale installations and is not a recommended backup strategy for larger scale deployments.

In the case of JIRA I still continue to run automated XML backups since they do not store attachments in them but as far as it concerns Confluence, I always disable the automated XML backup and rely on native database backup and attachment storage backup. The database backup must be performed with the native database tools such as pg_dump for PostgreSQL. The backup of your instance's attachments will depend on the type of storage in use. If you're storing your attachment in the database, your attachments will be backed up automatically during your database backup. If you store your attachments in a file systems, as it's the case for both JIRA and Confluence default installations, there's plenty of tools out there to get the job done such as tar, pax, cpio and rsync (to name just a few). Each one of these have advantages and drawbacks and I won't enter in a detailed discussion: it suffices to say that none can beat a Solaris ZFS-based JIRA or Confluence installation. 

Since ZFS inception I've been taking advantage of its characteristics more and more often and snapshots are a ZFS killer feature that will considerably ease your administration duties. Whenever I install a new instance on a Solaris Zone, I set up a ZFS file system for hosting both the database files and JIRA or Confluence home directories:

# zfs create my-pool/my/db/files

# zfs create my-pool/jira/or/confluence/home

Taking a snapshot of a ZFS file system is a one-liner:

# zfs snapshot file-system-name@snapshot-name

In an instant your snapshot will be done and you will be able to send it to another device for permanent storage. ZFS snapshots, combined (or not...) with another tool such as rsync, will incredibly simplify backing up your files and, also, maintaining a cheap history (in terms of storage overhead) of changes in case you need to roll back your file systems (and hence the data stored in your application) in case you needed it.

Take into account that, to recover a single file from a snapshot in case your original pool crashes, you will need to ZFS receive the snapshot in another pool for files to be accessible. That's why I still rely on a scheduled rsync backup together with ZFS snapshots just in case, although with a much lower frequency than in the pre-ZFS epoch.

JIRA Security Advisory 2010-04-16

Atlassian has published a Security Advisory for JIRA on 2010, April the 16th. The Security Advisory alerts about Privilege Escalation and XSS vulnerabilities. Patches to these vulnerabilities are distributed with JIRA 4.1.1. 

JIRA: Creating issues from TLS-encrypted mail

As you know I'm extensively using Atlassian JIRA and one of the features my current client uses most is automatically creating issues from received email. The ability of automatically parsing an email and creating an issue is a nice built-in JIRA feature which sometimes can spare you a lot of work.

Configuring this service is straightforward:

• Configure a mail server.
• Configure the mail service.

Configuring a Mail Server

The mail server configuration screen, that you can access from your JIRA Administration section, is a simple screen where you can configure the basic properties of your mail server:

• Name.
• Default From: address.
• Email Subject: prefix.
• SMTP configuration:
• Host.
• Port.
• (Optional) User credentials.
• JNDI location of a JavaMail Session, in case you're running JIRA on a Java EE Application Server.

Once you've set up a mail server, you can proceed and configure the service that will read your mail box and create issues for you.

Configuring a "Create Issues From Mail" Service

The Services configuration tab lets you define JIRA services, which are the JIRA equivalent of an UNIX cron job. JIRA ships with some predefined services two of which are:

• Create Issues from POP.
• Create Issues from IMAP.

Depending on the protocol you're accessing you mail server with, you'll choose the appropriate service. In my case, I always choose IMAP if available. The following screenshot is the configuration screen of the "Create Issues from POP/IMAP" service:

There are different handlers you can choose from: you can find detailed information in the JIRA Documentation. The "Create issue or comment" is probably what you're looking for. The handler parameters lets you fine tune your handler with parameters such as:

• project: the project new issues will be created for.
• issuetype: the type of issues that will be created.
• createusers: a boolean flag that sets whether JIRA will create new users when a mail is received from an unknown address. Generally, you want this to be false.
• reporterusername: the name of the issue reporter when the address of the email doesn't match the address of any of the configured JIRA users.

Usually I set this parameter to something like: project=myProjId,issuetype=1,createusers=false,bulk=forward,reporteruserame=myuser

The Uses SSL combo box lets you choose whether you mailbox will be accessed using an encrypted connection. If you're planning to use SSL to access you mailbox you will probably need to import your mail server certificate into your certificate file, as explained later.

The Forward Email parameter lets you specify the address where errors or email that could not be processed will be forwarded to.

The Server and Port parameters lets you choose the mail server this service will connect to. The Delay parameter lets you specify the interval between every service execution.

Connecting to an SSL Service

If you're going to access your mail server using SSL, you will probably need to import the mail server public key into your certificate file, otherwise you'll receive some javax.net.ssl.SSLHandshakeException. In a previous post I explained how you can retrieve a server public key using OpenSSL. Once you have got the public key, you can add it to your key store by using the keytool program. The location of your key store may depend on your environment or application server configuration. The default location of the system-wide key store is $JAVA_HOME/jre/lib/security/cacerts. To add a key to your key store you can run the following command:

# keytool -import -alias your.certificate.alias -keystore path/to/keystore -file key-file

Additional Considerations for Solaris Sparse Zones

I'm often using Solaris 10 Sparse Zones to quickly deploy instances of software such as JIRA. In this case, please note that the system wide Java key store won't be writable in a zone. Instead of polluting the global zone key store, I ended up installing Java SE on every zone I deploy to avoid ending up with application trusting some certificates just because other applications do.