-
Notifications
You must be signed in to change notification settings - Fork 10
/
readme.html
387 lines (320 loc) · 15.4 KB
/
readme.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
<!DOCTYPE HTML>
<html lang="en">
<head>
<title>HTTP File Upload Plugin Readme</title>
<style type="text/css">
BODY {
font-size : 100%;
}
BODY, TD, TH {
font-family : tahoma, verdana, arial, helvetica, sans-serif;
font-size : 0.8em;
}
TH {
text-align: right;
}
H3 {
font-size : 10pt;
font-style: italic;
color: #004444;
}
H2 {
font-size : 2em;
font-weight : bold;
}
A:hover {
text-decoration : none;
}
H1 {
font-family : tahoma, arial, helvetica, sans-serif;
font-size : 1.4em;
font-weight: bold;
border-bottom : 1px #ccc solid;
padding-bottom : 2px;
}
TT {
font-family: courier new, monospace;
font-weight : bold;
color : #060;
}
PRE {
font-family: courier new, monospace;
font-size : 100%;
}
#datatable TH {
color : #fff;
background-color : #2A448C;
text-align : left;
}
#datatable TD {
background-color : #FAF6EF;
}
</style>
</head>
<body>
<h1>HTTP File Upload Plugin Readme
</h1>
<h2>Overview</h2>
<p>
The HTTP File Upload plugin adds functionality to Openfire that allows compliant clients to exchange files. The
protocol implemented by this plugin is defined in <a href="https://xmpp.org/extensions/xep-0363.html">XEP-0363:
HTTP File Upload</a>.
</p>
<p>
<strong>Note: </strong> This plugin requires the HTTP bind option in Openfire to be enabled:
<br>Server -> Server Settings -> HTTP Binding
</p>
<h2>Installation</h2>
<p>
Copy httpfileupload.jar into the plugins directory of your Openfire installation. The plugin will then be
automatically deployed. To upgrade to a new version, copy the new httpfileupload.jar file over the existing file.
</p>
<h2>Using the Plugin</h2>
<p>
After installation, the functionality provided by the plugin is automatically available to clients. While exchanging
files, the plugin by default stores the files that are being transferred in a temporary directory that is removed
when Openfire is shut down. The content of this directory is purged when its total size is larger than the remaining
disc space.
</p>
<h2 id="configuration">Configuration</h2>
<p>
Most configuration options can be controlled by two different properties. Apart from using regular Openfire properties,
controlled in the Openfire admin console, XML properties can be used. XML properties are properties stored in
the <samp>openfire.xml</samp> file.
</p>
<p>
Regular properties are stored in the database. This will ensure that a property value is equal on all
servers in a cluster of Openfire servers. When it is desirable to have a property values that are <em>different</em>
on each server, an XML property can be used (as the content of the <samp>openfire.xml</samp> file can be different
on each server).
</p>
<p>
When both a regular and an XML property is defined, then the XML property value will take precedence.
</p>
<h3>Configuration admin page</h3>
<p>
To support the administration, an admin page has been provided which can be found at Server - Server settings -
Http File Upload Settings. The page does not support all available settings but compares the configured announced URL with the actual URL.
</p>
<h3>Storage of data on filesystem</h3>
<table>
<tr><th>XML property</th> <td><samp>plugin.httpfileupload.serverspecific.fileRepo</samp></td></tr>
<tr><th>System Property</th> <td><samp>plugin.httpfileupload.fileRepo</samp></td></tr>
</table>
<p>
By default, the plugin will store all uploaded files in a temporary directory that is provided by the Operating System.
This directory is configured to be deleted, after Openfire quits. Some Operating Systems are known to periodically
purge these temporary directories, which is another potential source of data loss. This plugin can be configured to
use any other directory for data storage, by providing the path for that directory in either property listed above.
Note that the directory is expected to exist (this plugin will not attempt to create it if it is missing). Be sure
that the process owner of the Openfire process has enough permissions to read and write in that directory.
</p>
<h3>Maximum file size</h3>
<table>
<tr><th>XML property</th> <td><samp>plugin.httpfileupload.serverspecific.maxFileSize</samp></td></tr>
<tr><th>System Property</th> <td><samp>plugin.httpfileupload.maxFileSize</samp></td></tr>
</table>
<p>
To configure the maximum allowable file size to be uploaded by clients, the property defined above can be set to a
value in bytes. If not set, a default value is used. To disable the file size limitation, set a property to a value
of <samp>-1</samp>.
</p>
<h3>Announced web endpoint</h3>
<p>
The plugin will send URLs to the client that are to be used to upload or download data. To following properties can
be used to control the composition of the URLs that are generated.
</p>
<p>
To change the HTTP server protocol from the default value of "https" to "http" for example, use these properties:
</p>
<table>
<tr><th>XML property</th> <td><samp>plugin.httpfileupload.serverspecific.announcedWebProtocol</samp></td></tr>
<tr><th>System Property</th> <td><samp>plugin.httpfileupload.announcedWebProtocol</samp></td></tr>
</table>
<p>
To change the HTTP server hostname from the default value used by Openfire, use these properties:
</p>
<table>
<tr><th>XML property</th> <td><samp>plugin.httpfileupload.serverspecific.announcedWebHost</samp></td></tr>
<tr><th>System Property</th> <td><samp>plugin.httpfileupload.announcedWebHost</samp></td></tr>
</table>
<p>
To change the HTTP server port from the default value (7443) used by Openfire, use these properties
</p>
<table>
<tr><th>XML property</th> <td><samp>plugin.httpfileupload.serverspecific.announcedWebPort</samp></td></tr>
<tr><th>System Property</th> <td><samp>plugin.httpfileupload.announcedWebPort</samp></td></tr>
</table>
<p>
To change the web context root as announced to clients from the default value (<samp>/httpfileupload</samp>) used by
use these properties:
</p>
<table>
<tr><th>XML property</th> <td><samp>plugin.httpfileupload.serverspecific.announcedWebContextRoot</samp></td></tr>
<tr><th>System Property</th> <td><samp>plugin.httpfileupload.announcedWebContextRoot</samp></td></tr>
</table>
<h3>ClamAV Malware Scanner Integration</h3>
<p>
The plugin can be integrated with an external malware scanner (<a href="#malware-scanning">read more below</a>).
These properties are used for that.
</p>
<p>
To enable or disable the integration, use this property. When the ClamAV daemon cannot be reached while the feature
is enabled, all file uploads will be rejected.
</p>
<table>
<tr><th>System Property</th> <td><samp>plugin.httpfileupload.clamavEnabled</samp></td></tr>
</table>
<p>
Controls the host that is used to integrate with an external (third-party) ClamAV malware scanner daemon.
</p>
<table>
<tr><th>System Property</th> <td><samp>plugin.httpfileupload.clamavHost</samp></td></tr>
</table>
<p>
Controls the port that is used to integrate with an external (third-party) ClamAV malware scanner daemon.
</p>
<table>
<tr><th>System Property</th> <td><samp>plugin.httpfileupload.clamavPort</samp></td></tr>
</table>
<p>
Defines the duration (in milliseconds) after which Openfire giving up trying to establish a TCP connection to the
ClamAV scanner daemon.
</p>
<table>
<tr><th>System Property</th> <td><samp>plugin.httpfileupload.clamavConnectionTimeout</samp></td></tr>
</table>
<h2 id="malware-scanning">Scanning for Malware</h2>
<p>
To facilitate virus scanning, you can configure the application to use ClamAV. ClamAV is a third-party, open source
(GPLv2) anti-virus toolkit, available at <a href="https://www.clamav.net/">www.clamav.net</a>
</p>
<p>
To configure this application to use ClamAV, install, configure and run clamav-daemon, the scanner daemon of ClamAV.
Configure the daemon in such a way that Openfire can access it via TCP.
</p>
<p>
Note: ClamAV is configured with a maximum file size. Ensure that this is at least as big as the
<samp>maxFileSize</samp> that is provided as an argument to the HTTP File Upload Plugin.
</p>
<p>
Then, start the HTTP File Upload Plugin application with the <samp>clamavHost</samp> and <samp>clamavPort</samp>
arguments. When these are provided, the application will supply each file that is being uploaded to the ClamAV
daemon for scanning. A file upload will fail when the ClamAV daemon could not be reached, or, obviously, when it
detects malware.
</p>
<p>
While malware scanning can offer some protection against distributing unwanted content, it has limitations. Particularly
when the uploaded data is encrypted, the scanner is unlikely able to detect any malware in it.
</p>
<h2>When using in an Openfire cluster</h2>
<p>
Special consideration needs to be given to the deployment of this plugin in a cluster of Openfire instances. This
section outlines the main concerns.
</p>
<h3>Background: how clients interact with the servers</h3>
<p>
Unlike most other XMPP-related functionality, this 'HTTP File Upload' functionality uses an additional data path:
not only is the XMPP connection itself used; HTTP requests are also made. The HTTP protocol is used to upload and
download data. The URLs for these interactions are sent over the XMPP data channel.
</p>
<p>
In a typical scenario, a client that wants to send a file requests an 'upload slot' through XMPP. When assigned a
slot, its URL (as well as other metadata) is returned to the client by the server. Using this information, the client
will then upload the data using an HTTP PUT request. After the upload has succeeded, the client will send, over XMPP,
send the URL to the intended recipients of the data. Their clients will receive that URL (over XMPP) and subsequently
perform an HTTP GET request to download the data from the web server.
</p>
<h3>Configuration A: Using multiple service endpoint addresses</h3>
<p>
When each of the Openfire cluster node servers is connected directly to the internet, accessible to clients through
their fully qualified domain name, then no configuration might be needed to make HTTP File Upload functionality
available on all cluster nodes, for all clients.
</p>
<h4>Option 1: Each Openfire manages a unique set of data</h4>
<figure>
<img src="doc-diagram-option-1.png" alt="Diagram illustrating option 1: each Openfire uses it's own data store."/>
<figcaption>Diagram illustrating option 1: each Openfire uses its own data store.</figcaption>
</figure>
<p>
<em>pros & cons:</em> This solution requires no configuration, provides adequate scalability, but does not offer
much data redundancy or flexibility in network architecture.
</p>
<p>
Since version 1.2.0 of this plugin, the definition of a Slot is shared across all XMPP cluster nodes. This slot
defines the endpoint addresses to be used by the uploader, as well as the recipients of the data.
</p>
<p>
In the scenario described by this configuration option, each Openfire cluster node will issue slots that contain
endpoint URLs that are specific to the server that issued the slot. This means that the upload, as well as all
downloads, will be directed to URL on that same server.
</p>
<h3>Configuration B: Using one service endpoint address</h3>
<p>
In certain environments it is undesirable or unpractical to expose more than one endpoint URL to chat clients. This
is frequently the case when the network architecture includes a load balancer. For this or other reasons, it might
have been necessary to reconfigure the 'announced' endpoints (using the configuration options defined in the
<a href="#configuration">Configuration paragraph</a> of this document) to use the same endpoint address for all
requests.
</p>
<h4>Option 2: Use only one server for file upload/download</h4>
<figure>
<img src="doc-diagram-option-2.png" alt="Diagram illustrating option 2: One Openfire used for all file storage."/>
<figcaption>Diagram illustrating option 2: One Openfire used for all file storage.</figcaption>
</figure>
<p>
<em>pros & cons:</em> This solution is typically easy to configure, but provides poor redundancy and
scalability.
</p>
<p>
In this scenario, the singular endpoint address could be mapped to exactly one Openfire cluster node. This can be
achieved by directly mapping the 'announced' endpoint details to the address of one of the Openfire nodes,
(as described in the <a href="#configuration">Configuration paragraph</a> of this document) or by configuring the
load balancer to 'balance' the traffic to just one of the nodes.
</p>
<h4>Option 3: Use every cluster node for file upload/download</h4>
<figure>
<img src="doc-diagram-option-3.png" alt="Diagram illustrating option 3: Cluster uses centralized file storage."/>
<figcaption>Diagram illustrating option 3: Cluster uses centralized file storage.</figcaption>
</figure>
<p>
<em>pros & cons:</em> More complex to configure, but provides better redundancy and scalability.
</p>
<p>
When a singular endpoint address is used, then this option typically involves a load balancer that distributes the
HTTP requests over all cluster nodes. This comes with some complexities:
</p>
<ul>
<li>
It is hard to ensure that the cluster node used by the XMPP connection of the client sharing/uploading the data
is the same cluster node used when performing the HTTP upload.
</li>
<li>
It is often impossible to guaranteed that HTTP requests made by intended recipients of the uploaded data end up
at the same cluster node as the one that was used to upload the data to.
</li>
</ul>
<p>
When using this configuration option, it should be assured that every XMPP cluster node can fulfill HTTP upload and
download requests for all slots.
</p>
<p>
Since version 1.2.0 of this plugin, the definition of a Slot is shared across all XMPP cluster nodes. To ensure that
all data is accessible, all cluster nodes should use the same shared network folder for file storage. This network
folder should be available on the filesystem of each of your Openfire servers, using the same path name. This plugin
should be configured to use this directory for data storage, by using the <samp>plugin.httpfileupload.fileRepo</samp>
property, as described in the <a href="#configuration">Configuration paragraph</a> of this document.
</p>
<p>
Realisation of a shared network folder is likely highly specific to the operating system used for your Openfire
servers, and is out of scope for this document.
</p>
<h2>Attribution</h2>
<p>
Icons made by <a href="https://www.flaticon.com/authors/smashicons" title="Smashicons">Smashicons</a> from
<a href="https://www.flaticon.com/" title="Flaticon">www.flaticon.com</a> is licensed by
<a href="http://creativecommons.org/licenses/by/3.0/" title="Creative Commons BY 3.0" target="_blank">CC 3.0 BY</a>.<br/>
Diagrams created on <a href="https://diagrams.net" title="diagrams.net/draw.io">diagrams.net/draw.io</a>.
</p>
</body>
</html>