« Back to documentation index

Openfire is a powerful instant messaging (IM) and chat server that implements the XMPP protocol. This document will guide you through installing Openfire. For a full list of features and more information, please visit the Openfire website: http://www.igniterealtime.org/projects/openfire/

Installation

Setup Overview

To complete the installation of Openfire, you'll need to perform each of the following steps:

  1. Database - if you choose to use an external database, you must prepare your database for Openfire.
  2. Setup - Use the built-in web-based setup tool to setup and verify the server configuration.
  3. Admin Console - use the web-based admin tool to manage the server.

This document also includes information on:

Files in the Distribution

The files in your distribution should be as follows (some sub-directories omitted for brevity): 

openfire/
 |- readme.html
 |- license.html
 |- conf/
 |- bin/
 |- jre/
 |- lib/
 |- plugins/
     |- admin/
 |- resources/
     |-database/
     |-security/
 |- documentation/

Setup the Database

Openfire can store its data in an embedded database or you can choose to use an external database such as MySQL or Oracle. If you would like to use an external database, you must prepare it before proceeding with installation. View the database setup documentation for more information.

Setup the Server

A web-based, "wizard" driven setup and configuration tool is built into Openfire. Simply launch Openfire (platform-specific instructions below) and use a web browser to connect to the admin console. The default port for the web-based admin console is 9090. If you are on the same machine as Openfire, the following URL will usually work: http://127.0.0.1:9090. Initial setup and administration can also be done from a remote computer using LAN IP address instead or hostname if it is resolvable by the remote computer. Windows Server administrators should add http://127.0.0.1 address to Internet Explorer's Trusted Sites list, if Enhanced Security configuration is enabled in Internet Explorer. Otherwise they will get a blank screen.

Autosetup

As an alternative to the web-based "wizard" driven setup described above, Openfire can be configured by provisioning it with a specially crafted openfire.xml file.

If <setup>true<>/setup> does not exist in openfire.xml (i.e. setup is not complete, and a block does exist called <autosetup> with a <run>true</run> property inside it, that looks like this:

    <autosetup>
        <run>true</run>
        <locale>en</locale>
        <xmpp>
            <domain>localhost</domain>
            <fqdn>localhost</fqdn>
            <auth>
                <anonymous>true</anonymous>
            </auth>
            <socket>
                <ssl>
                    <active>true</active>
                </ssl>
            </socket>
        </xmpp>
        <encryption>
            <algorithm>AES</algorithm>
            <key>some-key</key>
        </encryption>
        <database>
            <mode>standard</mode>
            <defaultProvider>
                <driver>org.postgresql.Driver</driver>
                <serverURL>jdbc:postgresql://localhost:5432/a-database</serverURL>
                <username>a-database</username>
                <password>a-password</password>
                <minConnections>5<minConnections>
                <maxConnections>25<maxConnections>
                <connectionTimeout>1.0<connectionTimeout>
            </defaultProvider>
        </database>
        <admin>
            <email>admin@example.com</email>
        <password>admin</password>
        </admin>
        <authprovider>
            <mode>default</mode>
        </authprovider>
        <users>
            <user1> <!-- Use incremental numbers for more users, eg: user2, user3 -->
                <username>jane</username> <!-- Required -->
                <password>secret</password> <!-- Required -->
                <name>Jane Doe</name>
                <email>user1@example.org</email>
                <roster>
                    <item1> <!-- Use incremental numbers for more items, eg: item2, item3 -->
                        <jid>john@example.com</jid>
                        <nickname>John</nickname>
                    </item1>
                </roster>
            </user1>
        </users>
    </autosetup>

Then setup will be run on first launch, and the <autosetup/> section will be deleted from openfire.xml

Note that autosetup provides less options to setup Openfire as compared to using the setup wizard.

Admin Console

After completing the above steps, Openfire will be configured and you can use the web-based admin console to administer the server. The URL should be the same as you used to setup the server unless you changed the port during the setup.

Running Openfire on Windows

Since 4.1.5 version Openfire automatically installs and runs the service (and opens the browser with the web setup page). But you can also use the launcher, if you need to (service has to be stopped before running the launcher). If you used the Openfire installer, a shortcut for starting the graphical launcher is provided in your Start Menu. Otherwise, run openfire.exe in the bin/ directory of your Openfire installation. A button on the launcher allows you to automatically open your web browser to the correct URL to finish setting up the server:

Windows Service

As of 4.1.5 Openfire installs the service automatically. But if you are using older version or want to reinstall the service, you can use the openfire-service.exe executable in the bin directory of the installation to install or uninstall the service.

From a console window, you can run the following commands:

Windows Service

You can also use the Services tool in the Windows Control Panel to start and stop the service.

Note: the graphical launcher is not compatible with the Windows service. If you install the service, you should use service controls as described above to control the server rather than the graphical launcher.

Upgrading Note: you should stop Openfire service before running the installer to upgrade to the newer version. Starting with 4.1.5 version Openfire will automatically stop and reinstall the service when upgrading with the installer.

Custom Parameters

Advanced users may wish to pass in parameters to the Java virtual machine (VM) to customize the runtime environment of Openfire. You can do this by creating openfire.vmoptions files in the bin/ directory of your Openfire installation. For the Windows service, you'd create a new text file called openfire-service.vmoptions. Each parameter to the VM should be on a new line of the file. For example, to set the minimum heap size to 512 MB and max VM heap size to 1024 MB, you'd use: 

-Xms512m
-Xmx1024m
To create parameters for the normal launcher, create a file called openfired.vmoptions (since the openfire.exe launcher invokes the openfired.exe executable to actually start the server).

Running Openfire in Linux/Unix

If you are running on a Red Hat or Red Hat like system (CentOS, Fedora, etc), we recommend using the RPM as it contains some custom handling of the standard Red Hat like environment. Assuming that you have used the RPM, you can start and stop Openfire using the /etc/init.d/openfire script.

# /etc/init.d/openfire
Usage /etc/init.d/openfire {start|stop|restart|status|condrestart|reload}
# /etc/init.d/openfire start
Starting openfire:

If you are running on a different Linux/Unix varient, and/or you have used the .tar.gz 'installer', you can start and stop Openfire using the bin/openfire script in your Openfire installation:

# ./openfire
Usage: ./openfire {start|stop}
# ./openfire start
Starting openfire

If you would like to install Openfire as a service, two scripts are provided in the bin/extra directory: It is not recommended that you use either of these scripts if you installed via RPM. The RPM has already taken care of what these scripts take care of.

Custom Parameters

Advanced users may wish to pass in parameters to the Java virtual machine (VM) to customize the runtime environment of Openfire. If you installed via RPM, you can customize this by editing /etc/sysconfig/openfire and looking at the OPENFIRE_OPTS option. If you installed via .tar.gz, you will need to tweak your startup script to fit your needs.

Plugins

Plugins add additional features and protocol support to Openfire. After setting up your Openfire installation, you may want to download and install plugins to enhance your server. Plugins can be downloaded from the plugins page on igniterealtime.org or directly inside the administration console.

Installing Plugins

If you download a plugin from inside the Openfire administration console, it will automatically be installed. If you manually download the plugin (packaged as a .jar file), you can deploy it by copying the plugin file to the plugins/ directory of your Openfire installation. A plugin monitor will automatically extract the plugin into a directory and install the plugin in Openfire. You may also use the "upload plugin" feature in the admin console (under the Plugins tab) to load a plugin from your local file system to the server.

Note: For nearly all plugins, a restart of the Openfire server software is not required. You should be able to install and remove plugins on-demand without impacting Openfire.

Managing Plugins

Plugins can be managed inside the Openfire admin console. You can also manually delete a plugin at any time by deleting its JAR file (Openfire will automatically remove the plugin from memory and delete it's directory when you do so).

Firewall

Server's administrator should open TCP port 5222 for incoming connections for XMPP clients to be able to connect to Openfire. Additionally an administrator can also open TCP 9090 (for http) and TCP 9091 (for https), if there is a need to remotely administrate Openfire connecting to its Admin Console. We recommend only using 9091 port as it is an encrypted connection. For server to server connections one should also open TCP 5269 port and for secure HTTP-BIND connections TCP 7443 port. Port number can be different, if the default configuration has been changed by an administrator. All ports used by Openfire can be found on the first page of Admin Console in the Server Ports section.