install-guide.html 10.7 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2

Matt Tucker's avatar
Matt Tucker committed
3 4
<html>
<head>
5
<title>Openfire: Installation Guide</title>
6
<link href="style.css" rel="stylesheet" type="text/css">
Matt Tucker's avatar
Matt Tucker committed
7 8
</head>
<body>
9 10 11 12 13 14 15 16 17 18 19 20 21 22

<div id="pageContainer">

<a name="top"></a>

	<div id="pageHeader">
		<div id="logo"></div>
		<h1>Installation Guide</h1>
	</div>
	<div class="navigation">
		<a href="index.html">&laquo; Back to documentation index</a>
	</div>
	
	<div id="pageBody">
Matt Tucker's avatar
Matt Tucker committed
23

24
<p>Openfire is a powerful instant messaging (IM) and chat
Matt Tucker's avatar
Matt Tucker committed
25
server that implements the XMPP protocol. This document will guide 
26
you through installing Openfire. For a full list of features and more information, please
Gaston Dombiak's avatar
Gaston Dombiak committed
27 28
visit the Openfire website: <a href="http://www.igniterealtime.org/projects/openfire/"
 target="_top">http://www.igniterealtime.org/projects/openfire/</a></p>
Matt Tucker's avatar
Matt Tucker committed
29

Matt Tucker's avatar
Matt Tucker committed
30
<h2>Installation</h2>
Matt Tucker's avatar
Matt Tucker committed
31
<ul>
Matt Tucker's avatar
Matt Tucker committed
32
<h3>Windows</h3>
33
Run the Openfire installer. The application will be installed to <tt>c:\Program Files\Openfire</tt> by default.
Matt Tucker's avatar
Matt Tucker committed
34 35 36
 
 <h3>Linux/Unix</h3>
 
37
 Choose either the RPM or tar.gz build. If using the RPM, run it using your package manager to install Openfire to <tt>/opt/openfire</tt>:
Matt Tucker's avatar
Matt Tucker committed
38

39
 <p><tt>rpm -ivh openfire_3_0_0.rpm</tt></p>
40

Matt Tucker's avatar
Matt Tucker committed
41 42
 
 If using the .tar.gz, extract the archive to <tt>/opt</tt> or <tt>/usr/bin</tt>:
Matt Tucker's avatar
Matt Tucker committed
43

44 45
 <p><tt>tar -xzvf openfire_3_0_0.tar.gz<br>
 mv openfire /opt</tt></p>
Matt Tucker's avatar
Matt Tucker committed
46

Matt Tucker's avatar
Matt Tucker committed
47
 <p><b>Note:</b> the .tar.gz build does not contain a bundled Java runtime (JRE). Therefore, you must have JDK or JRE 1.5.0 (Java 5) or later installed on your system. You can check your java version by typing "java -version" at the command line and (if necessary) upgrade your Java installation by visiting http://java.sun.com.</p>
Matt Tucker's avatar
Matt Tucker committed
48

Matt Tucker's avatar
Matt Tucker committed
49
  </ul>
Matt Tucker's avatar
Matt Tucker committed
50
<h2>Setup Overview</h2>
51
<p>To complete the installation of Openfire, you'll need to
Matt Tucker's avatar
Matt Tucker committed
52 53
perform each of the following steps: </p>
<ol>
Matt Tucker's avatar
Matt Tucker committed
54
  <li><a href="#database">Database</a> - if you choose to use an external database, you must
55
 prepare your database for Openfire. </li>
Matt Tucker's avatar
Matt Tucker committed
56
  <li><a href="#config">Setup</a> - Use the built-in web-based setup
Matt Tucker's avatar
Matt Tucker committed
57
tool to setup and verify the server configuration.</li>
58

Matt Tucker's avatar
Matt Tucker committed
59
  <li><a href="#tools">Admin Console</a> - use the web-based admin tool to
Matt Tucker's avatar
Matt Tucker committed
60 61
manage the server.</li>
</ol>
Matt Tucker's avatar
Matt Tucker committed
62 63 64 65 66 67

<p>This document also includes information on:</p>

<ul>
    <li><a href="#windows">Running under Windows</a>
    <li><a href="#unix">Running under Unix/Linux</a>
68

Matt Tucker's avatar
Matt Tucker committed
69
    <li><a href="#plugins">Installing and using plugins</a>
Matt Tucker's avatar
Matt Tucker committed
70 71
</ul>

Matt Tucker's avatar
Matt Tucker committed
72 73 74
<h2><a name="distribution">Files in the Distribution</a></h2>
<p> The files in your distribution should be as follows (some
sub-directories omitted for brevity): </p>
Gaston Dombiak's avatar
Gaston Dombiak committed
75
<pre>openfire/
Matt Tucker's avatar
Matt Tucker committed
76 77 78 79
 |- readme.html
 |- license.html
 |- conf/
 |- bin/
Matt Tucker's avatar
Matt Tucker committed
80
 |- jre/
Matt Tucker's avatar
Matt Tucker committed
81 82 83 84 85 86 87 88 89
 |- lib/
 |- plugins/
     |- admin/
 |- resources/
     |-database/
     |-security/
 |- documentation/</pre>

<ul> 
90
	 <li>The <tt>conf</tt> directory is where Openfire stores
Matt Tucker's avatar
Matt Tucker committed
91
configuration files.</li>
92

Matt Tucker's avatar
Matt Tucker committed
93 94
  <li>The <tt>bin</tt> directory contains the server executables. Depending
on which distribution you installed, different executables will be available.</li>
95
  <li>The <tt>jre</tt> directory contains a Java 5 runtime that is bundled with the Windows and RPM versions of Openfire.</li>
Matt Tucker's avatar
Matt Tucker committed
96
  <li>The <tt>lib</tt> directory contains libraries necessary for
97
running Openfire.</li>
98

Matt Tucker's avatar
Matt Tucker committed
99
  <li>The <tt>plugins</tt> directory contains server plugins. By
100
default, Openfire ships with a web-based admin console plugin.</li>
Matt Tucker's avatar
Matt Tucker committed
101
  <li>The <tt>resources/database</tt> directory contains SQL schema files to
102
create new Openfire databases, as well as upgrade scripts for
Matt Tucker's avatar
Matt Tucker committed
103
existing installations. </li>
104
  <li>The <tt>resources/security</tt> directory is where Openfire
Matt Tucker's avatar
Matt Tucker committed
105
maintains keystores to support SSL connection security.</li>
106

Matt Tucker's avatar
Matt Tucker committed
107 108 109 110
  <li>The <tt>documentation</tt> directory contains server
documentation.</li>
</ul><p>

Matt Tucker's avatar
Matt Tucker committed
111
<h2><a name="database">Setup the Database</a></h2>
112
<p>Openfire can store its data in an embedded database or you can choose to use
Matt Tucker's avatar
Matt Tucker committed
113
an external database such as MySQL or Oracle. If you would like to use an external database,
Matt Tucker's avatar
Matt Tucker committed
114
you must prepare it before proceeding with installation. View the <a href="database.html">database
Matt Tucker's avatar
Matt Tucker committed
115 116
setup</a> documentation for more information.</p>

Matt Tucker's avatar
Matt Tucker committed
117
<h2><a name="config"></a>Setup the Server</h2>
Matt Tucker's avatar
Matt Tucker committed
118
<p>A web-based, "wizard" driven setup and configuration tool is built
119
into Openfire. Simply launch Openfire (platform-specific instructions below) and use a web browser to
Matt Tucker's avatar
Matt Tucker committed
120
connect to the admin console. The default port for the
121
web-based admin console is 9090. If you are on the same machine as Openfire, the
Matt Tucker's avatar
Matt Tucker committed
122
following URL will usually work: 
123 124 125 126
<a href="http://127.0.0.1:9090">http://127.0.0.1:9090</a>. 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.</p>
Matt Tucker's avatar
Matt Tucker committed
127

Matt Tucker's avatar
Matt Tucker committed
128
<h2><a name="tools">Admin Console</a></h2>
129
<p>After completing the above steps, Openfire will be configured
Matt Tucker's avatar
Matt Tucker committed
130 131 132 133 134 135 136
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.<br>
</p>

<hr>

137
<h2><a name="windows">Running Openfire in Windows</a></h2>
Matt Tucker's avatar
Matt Tucker committed
138

139 140 141
<p>If you used the Openfire installer, a shortcut for starting the
a graphical launcher is provided in your Start Menu. Otherwise, run openfire.exe in the <tt>bin/</tt> directory of your
Openfire installation. A button on the on the launcher allows
Matt Tucker's avatar
Matt Tucker committed
142 143
you to automatically open your web browser to the correct URL to finish 
setting up the server: 
Matt Tucker's avatar
Matt Tucker committed
144 145

<p>
Matt Tucker's avatar
Matt Tucker committed
146
<div align="center">
147
<img src="images/launcher.png" alt="Openfire Launcher" width="400" height="300" align="center">
Matt Tucker's avatar
Matt Tucker committed
148 149
</div>
</p>
Matt Tucker's avatar
Matt Tucker committed
150 151

<h3>Windows Service</h3>
152 153
<p>If you're running Openfire on Windows, you will likely want to
run Openfire as a standard Windows service after initial setup.
Gaston Dombiak's avatar
Gaston Dombiak committed
154
If you used the Windows installer, a <tt>openfire-service.exe</tt> file
Matt Tucker's avatar
Matt Tucker committed
155
will be in the <tt>bin</tt> directory of the installation. You can use
156
this executable to install and control the Openfire service.
157

Matt Tucker's avatar
Matt Tucker committed
158 159 160 161
</p>

From a console window, you can run the following commands:
<ul>
Gaston Dombiak's avatar
Gaston Dombiak committed
162 163 164 165
		<li><tt>openfire-service /install</tt> -- installs the service.
		<li><tt>openfire-service /uninstall</tt> -- uninstalls the service.
		<li><tt>openfire-service /start</tt> -- starts the service
		<li><tt>openfire-service /stop</tt> -- stops the service.
166

Matt Tucker's avatar
Matt Tucker committed
167 168 169 170 171 172
</ul>

<p>
<div align="center">
<img src="images/windows_service.png" alt="Windows Service" width="557" height="223" align="center">
</div>
Matt Tucker's avatar
Matt Tucker committed
173 174
</p>

Matt Tucker's avatar
Matt Tucker committed
175 176 177 178 179
<p>You can also use the Services tool in the Windows Control Panel to start and
stop the service.</p>

<p>Note: the graphical launcher is not compatible with the Windows service
at this time. If you install the service, you should use service controls
180 181 182 183
as described above to control the server rather than the graphical launcher.</p>

<h3>Custom Parameters</h3>

Matt Tucker's avatar
Matt Tucker committed
184
<p>Advanced users may wish to pass in parameters to the Java virtual machine (VM) to customize
185
    the runtime environment of Openfire. You can do this by creating openfire.vmoptions files in the bin/
186 187
    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
Matt Tucker's avatar
Matt Tucker committed
188
    the file. For example, to set the minimum heap size to 512 MB and max VM heap size to 1024 MB, you'd use:
189

Matt Tucker's avatar
Matt Tucker committed
190 191
<pre>-Xms512m
-Xmx1024m</pre>
192

193 194
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).</p>
Matt Tucker's avatar
Matt Tucker committed
195

196
<h2><a name="unix">Running Openfire in Linux/Unix</a></h2>
Matt Tucker's avatar
Matt Tucker committed
197

Daniel Henninger's avatar
Daniel Henninger committed
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
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 <tt>/etc/init.d/openfire</tt> script.

<p>
<tt>
# /etc/init.d/openfire<br>
Usage /etc/init.d/openfire {start|stop|restart|status|condrestart|reload}<br>
# /etc/init.d/openfire start<br>
Starting openfire:
</tt>
</p>


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 <tt>bin/openfire</tt> script in your Openfire installation:
Matt Tucker's avatar
Matt Tucker committed
214 215 216

<p>
<tt>
217
# ./openfire<br>
218

219 220 221
Usage: ./openfire {start|stop}<br>
# ./openfire start<br>
Starting openfire
Matt Tucker's avatar
Matt Tucker committed
222 223
</tt></p>

224
If you would like to install Openfire as a service, two scripts are provided in the <tt>bin/extra</tt>
Matt Tucker's avatar
Matt Tucker committed
225 226
directory:
<ul>
Daniel Henninger's avatar
Daniel Henninger committed
227
    <li>redhat-postinstall.sh --   automatically installs Openfire as a service on Red Hat. It does so by creating a "jive" user and then copying the openfired script to your init.d directory. This script must be run as root. Please see the comments in the script for additional information.</li>
228
    <li>openfired -- script to run Openfire as a service. You must manually configure this script. See the comments in
Matt Tucker's avatar
Matt Tucker committed
229
the script for additional details.</li>
Matt Tucker's avatar
Matt Tucker committed
230
</ul>
Daniel Henninger's avatar
Daniel Henninger committed
231 232 233 234 235 236 237 238
<b>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.</b>

<h3>Custom Parameters</h3>

<p>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.</p>
Matt Tucker's avatar
Matt Tucker committed
239 240 241

<h2><a name="plugins">Plugins</a></h2>

242 243
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
Matt Tucker's avatar
Matt Tucker committed
244
server. Plugins can be downloaded from the
Gaston Dombiak's avatar
Gaston Dombiak committed
245
<a href="http://www.igniterealtime.org/projects/openfire/plugins.jsp">plugins page</a> on igniterealtime.org
Matt Tucker's avatar
Matt Tucker committed
246
or directly inside the administration console.
Matt Tucker's avatar
Matt Tucker committed
247 248 249

<h3>Installing Plugins</h3>

250
If you download a plugin from inside the Openfire administration console, it will automatically
Matt Tucker's avatar
Matt Tucker committed
251
be installed. If you manually download the plugin (packaged as a .jar file), you can deploy it
252 253
by copying the plugin file to the <tt>plugins/</tt> directory of your Openfire installation. A
plugin monitor will automatically extract the plugin into a directory and install the plugin in Openfire.
Daniel Henninger's avatar
Daniel Henninger committed
254 255
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.
Matt Tucker's avatar
Matt Tucker committed
256 257 258 259


<h3>Managing Plugins</h3>

260 261
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
Matt Tucker's avatar
Matt Tucker committed
262
do so).
Matt Tucker's avatar
Matt Tucker committed
263

264 265 266 267
	</div>

</div>

Matt Tucker's avatar
Matt Tucker committed
268 269
</body>
</html>