It’s a common question at IgniteRealtime.org (forums or chat room) – “Is there a guide to setup everything?”. Better yet, this guide should be easy to follow. There is no such guide. Well, at least from the community itself. I’ve seen a few guides in the wild. One of the recent ones is about combining Openfire with ClearOS and Openfire Meetings, which is an overkill for a novice user wanting to just setup an IM server. Some other guides are lacking details or are old. There are hundreds of possible setups, with different network schemes, operating systems, etc. It is impossible to write a simple guide and combine all this information. It will be hundreds of pages long. So i will take a very simple scenario and write a guide based on it. I hope one would be able to use it as a base for other scenarios. I will touch some crucial complex parts a little just to point that they are there and are important, but i won’t go into much detail (especially that i don’t have deep expertize on them).
This guide is for the latest official version of Openfire (4.1.3) and Spark (2.8.3) at the point when writing this guide. Based on Windows operating system (both server and clients). No LDAP integration. No external database. Just as simple as possible internal IM server.
0 – Environment
- Windows AD based network – domain name: tempico.local;
- Server OS: Windows Server 2008 (should work the same on newer);
- Server’s name: aruba; server’s full name (FQDN): aruba.tempico.local
- Chat server’s domain should be: corpchat.
1 – Installing Openfire
- Download the installer (exe) for 4.1.3 version from the Downloads page;
- Copy the installer to your server and run it;
- You can install into C:\Openfire to not ever run into UAC protection issues, but as you will later install Openfire’s service there shouldn’t be a problem with installing it to C:\Program fiels (x86)\Openfire. Do not leave “Run Openfire” checked on the last screen before pressing Finish.
2 – Installing and running Openfire’s service
- Hit Start button, type cmd, right click the Command Prompt entry and select Run as administrator;
- Navigate to Openfire’s bin folder (if it was installed in the default location, it will be C:\Program files (x86)\Openfire\bin);
- Run command: openfire-service.exe /install (this will install Openfire’s system service);
- Hit Start button, type services, click on the Services entry;
- Scroll to the Openfire service, right click it and press Start.
Update: since 4.1.5 version Openfire installs the service automatically and runs it, if you select that on the last step of the installer.
3 – Configuring Openfire
- Open a browser window on the same server (not remotely) and go to http://localhost:9090 (it should open Openfire’s web setup);
- Select a language you prefer (for the purpose of this guide we will choose English) and press Continue;
- Next is a very (if not the most) important part that many people are not thinking through.
Partly so because of Openfire usually suggesting IP addresses in this form for a faster setup (a program can’t know how you want to name your server and domain though). But using IP addresses in XMPP is bad. All communication in XMPP is based on domains. Your user is user@domain and if you try to use user@IP it will just create many problems. We have established above, that our XMPP domain should be corpchat. So we put:
- corpchat into XMPP Domain Name field;
- aruba.tempico.local into Server Host Name (FQDN);
- Will leave everything else as is and press Continue;
- Select Embedded Database option and press Continue;
- Leave the Default option and press Continue;
- You can enter some real email address for the admin user, though this is not required (unless you will setup email notifications for admin via some plugin). Also enter and repeat a password for the admin user. Admin’s username is just admin, not the email address! Press Continue.
- At this point the setup will finish (and generate SSL certificates for the domain name you have entered). Press “Login to the admin console” button once it appears. Openfire’s login window should appear.
- Try putting username admin and the password you have created and press Login. It should successfully login and show the home page of Admin Console.
4 – Setting up domain name resolution
- Domain name corpchat won’t be automatically recognized in your network. So putting it in the client won’t work. Do not go the easiest route and do not use IP address instead (or server’s name, which will be recognizable). You need to setup your network so the clients will find what stands behind the corpchat name.
- As this is a Windows AD based network in our scenario there should be a DNS panel on the domain controller, where you can create new records. You may also have other means of names recognition in your network, like a separate DHCP/DNS server, router or even using hosts files on the client computers (though this is not very convenient). In this example we will use the standard DNS panel on Windows Server 2008.
- Open DNS panel (located at All Programs > Administrative Tools);
- Expand Forward Lookup Zones, right click the tempico.local tree and select:
- New Alias (CNAME) and put corpchat as a name for it and aruba.tempico.local as a target host;
- Or you can create New Host (A or AAAA) and put corpchat as a name and server’s IP address in the second field (this might be an option for not a Windows AD based network, but one would have to fix that record when server’s IP changes, whereas first option will work automatically – so we will use first one for this example);
- Additionally one can also create an additional record of SRV type, which will look like:
_xmpp-client._tcp.corpchat. 18000 IN SRV 0 5 5222 aruba.tempico.local.
That would get rid of a warning on the home page of Admin Console, but that warning is mostly informational and SRV records are mostly needed when serving services to the internet. It’s not required for the local setup.
5 – Configuring Spark and logging in
- When Openfire completes its web setup it automatically generates self-signed certificates for the provided domain name. One can see them going into TLS/SSL Certificates menu in Admin Console and pressing on a first Manage Store Contents link. It will show two certificates for the corpchat domain name. This is important as when you put something into Spark’s Domain field, it then checks if the domain provided by a user matches the domain that certificates were generated for. If it doesn’t match, you get the Certificate hostname verification failed error. You can still play around this by going into Advanced menu on Spark’s login screen and checking the Disable certificate hostname verification (not recommended) option. Obviously it is not recommended as this will render your SSL setup weak (as an attacker can make Spark connect to a false server and it won’t warn users). Note, that you will still need to check the Accept all certificates (self-signed/expired/not trusted) as Spark 2.8.3 doesn’t have any method of accepting a single certificate as an exception. As Openfire generates self-signed certificates, they are not trusted and Spark won’t connect without checking that option.
- If you don’t have a DNS, there is an option to make it work by going into Spark’s Advanced menu on the login screen, deselecting the Automatically discover host and port setting and putting server’s IP address into Host field. You should still put corpchat into Domain field on the login screen. This way you will login into your server using its domain name. It is much better for communication/services discovery/file transfer/etc. than just putting IP address into Domain field. And you won’t get the certificate error either. Of course, when server’s IP changes, every user will have to change it in the Advanced settings.
6 – Other information
- When upgrading Openfire don’t forget to stop the service first;
- Never run the Launcher and don’t forget to deselect the option Run Openfire, when doing upgrades;
- Always use 9091 port and https for connecting to Admin Console from a remote computer, so the connection will be encrypted (e.g. https://corpchat:9091);
- If firewall is enabled on the server, you need to add an inbound rule to allow traffic to TCP 5222 port;
- ADDED 2017.10.18 (this and below): when upgrading from 4.1.5 or newer version, it is not required to stop the service. It will stop and start it automatically.
- Since 4.1.6 there are x64 installers for Openfire, which will install into C:\Program Files\ by default. They also can use x64 Java, so it may use more RAM.
- You can upgrade x86 installation with x64 installer since 4.1.5. When running x64 installer, point it to your x86 installation folder. It should then uninstall older version and install new one to the same folder retaining config, local database and other settings.