Running FreeBSD

A Jabber server is an excellent tool for private, secure, reliable communication among workgroups. It’s also great for remote system monitoring and receiving notifications from online todo list services. This a complete howto for setting up a Jabber server on FreeBSD.

Decentralized, Free Clients and Open Source

Jabber is decentralized, so your messages don’t go through servers controlled by others. And there are free Jabber clients, such as Pidgin (*nix, Windows), Adium (OS X) and Psi (cross-platform) available for whatever desktop OS you use. Finally, Jabber is open-source, so if you need to build on it, you can.

We’ll build a Jabber 1.6 server on FreeBSD version 6.2. There are many different Jabber servers and many different platforms, but these two are both free, open-source, easy to work with and highly reliable. I’ll be performing my installation on a jail, which is a minimalist FreeBSD virtualization technology.

Requirements

In order to complete this Jabber install, you will need the following:

1. A FreeBSD server, computer or VPS where you have root access and that is connected to the internet.
2. sshd must be running on the FreeBSD server.
3. A running MySQL or PostgreSQL server on the FreeBSD server.
4. A personal computer able to connect to your FreeBSD server via ssh.
5. Comfort working with the command line interface.
6. A fully qualified domain whose A record in DNS points to your FreeBSD server, such as mydomain.com or im.mydomain.com.
7. Approximately 30-60 minutes.

Once you’re logged in via ssh to your FreeBSD server or VPS and have become root, you start by finding the FreeBSD port for Jabber.

root@16 ~ # whereis jabber
jabber: /usr/ports/net-im/jabber

Install from Ports

Now change to that port’s directory and build it.

root@16 ~ # cd /usr/ports/net-im/jabber
root@16 /usr/ports/net-im/jabber # make install clean

Config Options

Unless you have built Jabber before on this machine, you will promptly see the config options dialog. You can scroll up and down among the options with your up and down arrow keys. To select an option, use the space key. An X appears between the brackets for the respective option when selected.

Unless you know you’re already using IPv6 and plan to use Jabber on that IPv6 network, you can ignore that option. You will want to select one of the SQL server options. If you don’t know which one to pick, MySQL is recommended. To finish this step, just hit the “o” (as in Oliver) button on your keyboard.

Install from Ports Completion

FreeBSD will now automatically download Jabber and all needed dependencies, build and install them. This could easily take 10-20 minutes. Once the process finishes, you should see something like the image below.

Now you’ll need to enable Jabber so the start script will work. Open /etc/rc.conf in your favorite text editor (I like vi) as root and add the following to the last line of the file. Note that this should be on a line all by itself.

jabber_enable="YES"

FQDN and SQL Database

At this point you will need to know the fully qualified domain (FQDN) you wish to use with Jabber. This is often in the form of domain.com or im.domain.com. For this howto I am going to use im.runningfreebsd.com, but for my production Jabber server I use the base domain. Your Jabber nickname will take the form of username@fqdn, so choose well.

You also need your SQL database, SQL username, password and host (usually localhost). I use MySQL for my Jabber servers so that’s what we’ll use in this howto. Installing the SQL server is outside the scope of this document but it’s not difficult. Once you create your MySQL database you need to load the Jabber table structure into it as follows.

mysql -u username -D dbname -p < /usr/local/share/doc/jabber/mysql.sql

This will prompt you to enter your MySQL user’s password. To verify that the tables were loaded correctly, login to MySQL and run the show tables; command. You should see something like the following.

mysql> show tables;
+----------------------------+
| Tables_in_jabber           |
+----------------------------+
| browse                     |
| last                       |
| mailaddresses              |
| messages                   |
| presence                   |
| privacy                    |
| private                    |
| roster                     |
| storedsubscriptionrequests |
| users                      |
| vcard                      |
+----------------------------+
11 rows in set (0.00 sec)

Jabber Configuration File

The Jabber port leaves a sample config file at /usr/local/etc/jabber.xml.sample. We need to copy that to the default location and make it writeable.

root@16 ~ # cp /usr/local/etc/jabber.xml.sample /usr/local/etc/jabber.xml
root@16 ~ # chmod 644 /usr/local/etc/jabber.xml

Now you need to open /usr/local/etc/jabber.xml in your favorite text editor. Around line 71 you will encounter this:

<service id="sessions.localhost">

You need to change it to this:

<service id="sessions.FQDN">

… where FQDN is the fully qualified domain name you selected above.

At line 93, you’ll need to make the following edit.

<host><jabberd:cmdline flag="h">localhost</jabberd:cmdline></host>

<host><jabberd:cmdline flag="h">FQDN</jabberd:cmdline></host>

Around line 357 you will need to make the following edit.

<item category="component" type="s2s" jid="s2s.localhost" name="connections to other servers" acl:if="s2s"/>

<item category="component" type="s2s" jid="s2s.FQDN" name="connections to other servers" acl:if="s2s"/>

Around line 523 you will need to update as follows:

<xdb id="xdbsql.localhost">

<xdb id="xdbsql.FQDN">

At line 532, you need to enter your MySQL username, password, host and database name.

      <mysql>
         <user>jabber</user>
         <password>secret</password>
         <host>localhost</host>
         <database>jabber</database>
       </mysql>

Around line 707 you can comment out the following if you don’t want to allow unencrypted client connections to the Jabber server.

<ip port="5222"/>

To comment it out, add ‘<!–’ before it and ‘–>’ after it.

If you want to allow both encrypted and unencrypted access, or just unencrypted access then you don’t need to do anything here.

Jabber TLS (Secure) Configuration

If you don’t need a secure connection between your Jabber client and the server, you can skip this section. Otherwise, you first need to create a file that contains both a certificate and private key. The commands below will create that file at /usr/local/etc/cert_and_key.pem. Be sure to either save the jabber.xml file and quit your editor or open a new ssh session before running these commands.

openssl req -new > sslcert.csr

This will prompt you for some information. At the “Enter PEM pass phrase:” prompt, enter any string you consider a strong password and make note of it as you will need it again for the next command. And at the “Common Name (eg, YOUR name)” prompt it is critical that you enter the FQDN you selected. Don’t enter http:// in front of the domain either. I recommend you skip the following two prompts:

• A challenge password []:
• An optional company name []:

Now, run these commands.

openssl rsa -in privkey.pem -out sslcert.key

openssl x509 -in sslcert.csr -out sslcert.cert -req -signkey sslcert.key -days 365

cat sslcert.key > /usr/local/etc/cert_and_key.pem

cat sslcert.cert >> /usr/local/etc/cert_and_key.pem

chmod 600 /usr/local/etc/cert_and_key.pem

chown jabber /usr/local/etc/cert_and_key.pem

rm privkey.pem sslcert.key sslcert.csr sslcert.cert

You’ll now need to re-open /usr/local/etc/jabber.xml in your editor and around line 747 insert this line:

<tls port='5223'>127.0.0.1</tls>

You’ll want to replace 127.0.0.1 with the IP address your Jabber server will listen on.

Around line 1029 you’ll find the opening <tls> tag. Between it and the closing tag insert:

<key id='127.0.0.1'>/usr/local/etc/cert_and_key.pem</key>

You’ll want to replace 127.0.0.1 with the appropriate IP address again here.

Also within the <tls> tag you will want to comment out the following line, unless you are using a CA-backed certificate, in which case you will want to create the file /usr/local/etc/cacerts.pem and put your certificate authority’s certificate in it.

<cacertfile>/usr/local/etc/cacerts.pem</cacertfile>

To comment it out, add ‘<!–’ before it and ‘–>’ after it.

Starting Jabber

Now you should be able to start Jabber, using the FreeBSD start script.

root@16 ~ # /usr/local/etc/rc.d/jabber start

Jabber will run as the user ‘jabber’ so you can run the following command to ensure jabber has started.

root@16 ~ # top -U jabber

If all is working, you should see two jabberd14 processes. You can verify that Jabber is running on the ports and IP(s) you expect by checking the sockstat output.

root@16 ~ # sockstat -4 | grep jabber
jabber   jabberd14  76702 9  tcp4   127.0.0.1:5222     *:*
jabber   jabberd14  76702 10 tcp4   127.0.0.1:5223     *:*
jabber   jabberd14  76644 9  tcp4   127.0.0.1:5222     *:*
jabber   jabberd14  76644 10 tcp4   127.0.0.1:5223     *:*
jabber   jabberd14  76644 11 tcp4   127.0.0.1:5269     *:*

You may have fewer processes but the important part is that it is listening on ports 5222, 5223 and 5269.

Open Ports in the Firewall

If you’re using a firewall, you’ll need to open ports 5222, 5223 and 5269. Ports 5222 and 5223 are for client connections and 5269 is for connections to other Jabber servers. If you don’t need to connect to other Jabber servers then you don’t need to open that port.

Here’s an example PF stanza to open these ports:

pass in quick on $ext_if inet proto tcp from any to any port { 5222, 5223, 5269 } flags S/SA keep state

You can define $ext_if as follows, at the top of your /etc/pf.conf file.

ext_if="em0"

Note that your interface identifier may be different. You can get yours by running the ifconfig command. Also, this does not constitute a complete pf.conf.

Client Configuration

Your Jabber server is running now and it’s able to communicate with the outside world so it’s time to configure your Jabber client. I like Pidgin, a free multi-protocol IM client for Windows and Unix platforms, so that’s what I’ll use. The configuration for other clients is quite similar.

Once you have Pidgin installed and running, open the Accounts screen and click the Add button. For Protocol, select XMPP. Where it asks for Screen name, enter the username you want. This will be the ‘handle’ of your Jabber nickname. So if you select ‘me’ as the screen name and your FQDN is ‘im.runningfreebsd.com’, then your Jabber nickname will be ‘me@im.runningfreebsd.com’. Under Domain, put your FQDN. Enter your desired (strong) password twice and be sure to tick the boxes for “Remember password” and “Create this new account on the server”.

Under the Advanced tab, tick the box for “Force old (port 5223) SSL” and change the “Connect port” box to ‘5223′ if you want to encrypt the connection between your client and the server.

Now click the Save button. Pidgin will prompt you for some information the Jabber server wants and will create your account. Once the registration process completes, tick the Enabled box next to your account in the Accounts screen to login and start using it!

Disable Registration

Once you have created your users you can disable registration by commenting out the username, name and email tags in the register stanza around line 154 in /usr/local/etx/jabber.xml.

      <register xmlns="jabber:iq:register" notify="yes">
        <instructions>Choose a username and password to register with this server.</instructions>
        <username/>
        <name/>
        <email/>
      </register>

To comment out a line, add ‘<!–’ before it and ‘–>’ after it.

And then restart Jabber to make the change effective. You can reverse this at any time to re-enable new user registration.

/usr/local/etc/rc.d/jabber restart

Further Development

Other topics include Jabber chatrooms, debugging, advanced DNS records and large installations. We might work on these in future howtos if there is interest.

How did it Go?

Did you meet with success? Run into any problems? Let me know in the comments section below.

Related Links

• Jabber :: About :: Overview
• Jabber @Wikipedia
• Planet Jabber

Technorati Tags: adium, communication, freebsd, im, jabber, pidgin, psi, workgroups