Installation Guide

Windows

Select Openfire installer that is better suiting you (x86 or x64). Run the installer. The application will be installed to C:\Program Files\Openfire by default.

Note: On Windows systems we suggest using a service to run Openfire (read the Windows Service section below). When using Openfire Launcher on Windows Vista or newer with UAC protection enabled, it has to be run with Run as administrator option, to be able to write changes to config and embedded database (if used) stored in C:\Program files\Openfire\ folder. If Openfire is running via the launcher without the 'Run as administrator' option from Program files, it can't get proper permissions to write changes. It shows errors (in red) when running the launcher and during the setup will require the current password for the administrator account (although this is a new installation. Normally it doesn't ask for it). This is an effect of missing permissions and Openfire not being able to initialize the database and other resources.

Since 4.1.5 Openfire installs and runs the service automatically (also opens the browser and loads the web setup page). The launcher (if one wants to use it) is also made to run in elevated mode, so one don't need to run it as administrator manually. But you shouldn't use the launcher, if the service is running. Because this will create a conflict.

Linux

Choose one of the provided installers (x86 or x64, rpm, deb or tar.gz).

If using rpm, run it using your package manager to install Openfire to /opt/openfire:

rpm -ivh openfire_X_Y_Z.rpm

If using deb, run it to install Openfire to /usr/share/openfire:

dpkg -i openfire_X_Y_Z.deb

If using the tar.gz, extract the archive to /opt or /usr/bin:

tar -xzvf openfire_X_Y_Z.tar.gz
mv openfire /opt

macOS

Install Openfire using dmg installer. This should install Openfire into /usr/local/openfire. Then you can run it via cmd or with the launcher.

Files in the Distribution

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

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

• The conf directory is where Openfire stores configuration files.
• The bin directory contains the server executables. Depending on which distribution you installed, different executables will be available.
• The jre directory contains a Java runtime that is bundled with the Windows and RPM versions of Openfire.
• The lib directory contains libraries necessary for running Openfire.
• The plugins directory contains server plugins. By default, Openfire ships with a web-based admin console plugin and a search plugin.
• The resources/database directory contains SQL schema files to create new Openfire databases, as well as upgrade scripts for existing installations.
• The resources/security directory is where Openfire maintains keystores to support SSL connection security.
• The documentation directory contains server 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 might need to add the http://127.0.0.1 address to browser's Trusted Sites list, if Enhanced Security Configuration is enabled, to prevent getting 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 fewer options to setup Openfire as compared to using the setup wizard.

Admin Console

After completing the above steps, Openfire will be configured through, 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.

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:

openfire-service /install

installs the service.

openfire-service /uninstall

uninstalls the service.

openfire-service /start

starts the service

openfire-service /stop

stops the 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 a openfire.vmoptions file 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).

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.

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 its directory when you do so).