]> git.p6c8.net - jirafeau_project.git/blob - README.md
[TASK] README.md: client_max_body_size and Nginx
[jirafeau_project.git] / README.md
1 # SECURITY ANNOUNCEMENT
2
3 ## 3th Mai 2018
4
5 Multiple security vulnerabilities has been reported by [Bishopfox team](https://www.bishopfox.com/) on Jirafeau project.
6
7 The next release of Jirafeau (3.4.1) will include security fixes and is planned 12th Mai 2018.
8
9 Upgrading Jirafeau is recommended.
10
11 # Jirafeau
12
13 Welcome to the official Jirafeau project, an [Open-Source software](https://en.wikipedia.org/wiki/Open-source_software).
14
15 Jirafeau allows your to "one-click-filesharing". It makes possible to upload a file in a simple way and give an unique link to it.
16
17 A demonstration of the latest version is available on [jirafeau.net](https://jirafeau.net/).
18
19 ![Screenshot1](http://i.imgur.com/TPjh48P.png)
20
21 Latest CI Status:
22 Master [![Build Status Master](https://gitlab.com/mojo42/Jirafeau/badges/master/build.svg)](https://gitlab.com/mojo42/Jirafeau/commits/master)
23 Next Release [![Build Status Next Release](https://gitlab.com/mojo42/Jirafeau/badges/test/build.svg)](https://gitlab.com/mojo42/Jirafeau/commits/master)
24 [All Branch Builds](https://gitlab.com/mojo42/Jirafeau/pipelines?scope=branches)
25
26 ## Main features
27
28 - One upload → One download link & one delete link
29 - Send any large files (thanks to the HTML5 file API → PHP post_max_size limit not relevant)
30 - Shows progression: speed, percentage and remaining upload time
31 - Preview content in browser (if possible)
32 - Optional password protection (for uploading or downloading)
33 - Set expiration time for downloads
34 - Option to self-destruct after first download
35 - Shortened URLs using base 64 encoding
36 - Maximal upload size configurable
37 - NO database, only use basic PHP
38 - Simple language support :gb: :fr: :de: :it: :nl: :ro: :sk: :hu: :cn: :gr: :ru: :es: :tk: :flag_tr: :flag_pt: :flag_br:
39 - File level [Deduplication](http://en.wikipedia.org/wiki/Data_deduplication) for storage optimization (does store duplicate files only once, but generate multiple links)
40 - Optional data encryption
41 - Small administration interface
42 - CLI script to remove expired files automatically with a cronjob
43 - Basic, adaptable »Terms Of Service« page
44 - Basic API
45 - Bash script to upload files via command line
46 - Themes
47
48 Jirafeau is a fork of the original project [Jyraphe](http://home.gna.org/jyraphe/) based on the 0.5 (stable version) with a **lot** of modifications.
49
50 As it's original project, Jirafeau is made in the [KISS](http://en.wikipedia.org/wiki/KISS_principle) way (Keep It Simple, Stupid).
51
52 Jirafeau project won't evolve to a file manager and will focus to keep a very few dependencies.
53
54 ## Screenshots
55
56 - [Installation - Step 1](http://i.imgur.com/hmpT1eN.jpg)
57 - [Installation - Step 2](http://i.imgur.com/2e0UGKE.jpg)
58 - [Installation - Step 3](http://i.imgur.com/ofAjLXh.jpg)
59 - [Installation - Step 4](http://i.imgur.com/WXqnfqJ.jpg)
60 - [Upload - Step 1](http://i.imgur.com/SBmSwzJ.jpg)
61 - [Upload - Step 2](http://i.imgur.com/wzPkb1Z.jpg)
62 - [Upload - Progress](http://i.imgur.com/i6n95kv.jpg)
63 - [Upload - Confirmation page](http://i.imgur.com/P2oS1MY.jpg)
64 - [Admin Interface](http://i.imgur.com/nTdsVzn.png)
65
66 ## Installation
67
68 This shows how to install Jirafeau by your own, it's quite simple but you can
69 also use a [docker image](https://hub.docker.com/r/mojo42/jirafeau/) or build
70 it yourself. Check [docker folder](docker/README.md) for more informations.
71
72 System requirements:
73 - PHP >= 5.6
74 - Optional, but recommended: Git >= 2.7
75 - No database required, no mail required
76
77 Installation steps:
78 - Clone the [repository](https://gitlab.com/mojo42/Jirafeau/) or download the latest ([release](https://gitlab.com/mojo42/Jirafeau/tags) from GitLab onto your webserver
79 - Set owner & group according to your webserver
80 - A) Setup with the installation wizard (web):
81 - Open your browser and go to your installed location, eg. ```https://example.com/jirafeau/```
82 - The script will redirect to you to a minimal installation wizard to set up all required options
83 - All optional parameters may be set in ```lib/config.local.php```, take a look at ```lib/config.original.php``` to see all default values
84 - B) Setup without the installation wizard (cli):
85 - Just copy ```config.original.php``` to ```config.local.php``` and customize it
86
87 ## Upgrade
88
89 ### General procedure for all versions
90
91 1. Backup your Jirafeau installation!
92 2. Block access to Jirafeau
93 3. Checkout the new version with Git using the [tagged release](https://gitlab.com/mojo42/Jirafeau/tags)
94 * If you have installed Jirafeau just by uploading files on your server, you can download the desired version, overwrite/remove all files and chown/chmod files if needed. Keep a backup of your local configuration file tough.
95 4. With you browser, go to your Jirafeau root page
96 5. Follow the installation wizard, it should propose you the same data folder or even update automatically
97 7. Check your ```/lib/config.local.php``` and compare it with the ```/lib/config.original.php``` to see if new configuration items are available
98
99 ### From version 1.0 to 1.1
100
101 1. The download URL changed
102 * Add a rewrite rule in your web server configuration to rename ```file.php``` to ```f.php``` to make older, still existing links work again
103 1. The default theme changed
104 * Optionally change the theme in ```lib/config.local.php``` to »courgette«
105
106 ### From version 1.2.0 to 2.0.0
107
108 1. The "Terms of Service" text file changed
109 * To reuse previous changes to the ToS, move the old ```/tos_text.php``` file to ```/lib/tos.local.txt``` and remove all HTML und PHP Tags, leaving a regular text file
110
111 ### from version 2.0.0 to 3.4.0
112
113 There is nothing special to do to update from/to the following versions:
114 - 2.0.0 -> 3.0.0
115 - 3.0.0 -> 3.1.0
116 - 3.1.0 -> 3.2.0
117 - 3.2.0 -> 3.2.1
118 - 3.2.1 -> 3.3.0
119 - 3.3.0 -> 3.4.0
120
121 ### Troubleshooting
122
123 If you have some troubles, consider the following cases
124
125 - Check your ```/lib/config.local.php``` file and compare it with ```/lib/config.original.php```, the configuration syntax or a parameter may have changed
126 - Check owner & permissions of your files
127
128 ## Security
129
130 ```var``` directory contain all files and links. It is randomly named to limit access but you may add better protection to prevent un-authorized access to it.
131 You have several options:
132 - Configure a ```.htaccess```
133 - Move var folder to a place on your server which can't be directly accessed
134 - Disable automatic listing on your web server config or place a index.html in var's sub-directory (this is a limited solution)
135
136 If you are using Apache, you can add the following line to your configuration to prevent people to access to your ```var``` folder:
137
138 ```RedirectMatch 301 ^/var-.* http://my.service.jirafeau ```
139
140 If you are using nginx, you can add the following to your $vhost.conf:
141
142 ```nginx
143 location ~ /var-.* {
144 deny all;
145 return 404;
146 }
147 ```
148
149 If you are using lighttpd, you can deny access to ```var``` folder in your configuration:
150
151 ```
152 $HTTP["url"] =~ "^/var-*" {
153 url.access-deny = ("")
154 }
155 ```
156
157 You should also remove un-necessessary write access once the installation is done (ex: configuration file).
158 An other obvious basic security is to let access users to the site by HTTPS (make sure `web_root` in you `config.local.php` is set with https).
159
160 ## Server side encryption
161
162 Data encryption can be activated in options. This feature makes the server encrypt data and send the decryt key to the user (inside download URL).
163 The decrypt key is not stored on the server so if you loose an url, you won't be able to retrieve file content.
164 In case of security troubles on the server, attacker won't be able to access files.
165
166 By activating this feature, you have to be aware of few things:
167 - Data encryption has a cost (cpu) and it takes more time for downloads to complete once file sent.
168 - During the download, the server will decrypt on the fly (and use resource).
169 - This feature needs to have the mcrypt php module.
170 - File de-duplication will stop to work (as we can't compare two encrypted files).
171 - Be sure your server do not log client's requests.
172 - Don't forget to enable https.
173
174 In a next step, encryption will be made by the client (in javascript), see issue #10.
175
176 ## License
177
178 GNU Affero General Public License v3 (AGPL-3.0).
179
180 The GNU Affero General Public License can be found at https://www.gnu.org/licenses/agpl.html.
181
182 Please note: If you decide do make adaptions to the source code and run a service with these changes incorporated,
183 you are required to provide a link to the source code of your version in order to obey the AGPL-3.0 license.
184 To do so please add a link to the source (eg. a public Git repository or a download link) to the Terms of Service page.
185 Take a look at the FAQ to find out about how to change the ToS.
186
187 PS: If you have fixed errors or added features, then please contribute to the project and send a merge request with these changes.
188
189 ## Contribution
190
191 If you want to contribute to project, then take a look at the git repository:
192
193 - https://gitlab.com/mojo42/Jirafeau
194
195 and the Contribution Guidelines
196
197 - https://gitlab.com/mojo42/Jirafeau/blob/master/CONTRIBUTING.md
198
199 ## FAQ
200
201 ### Can I add a new language in Jirafeau?
202
203 Of course ! Translations are easy to make and no technical knowledge is required.
204
205 Simply go to [Jirafeau's Weblate](https://hosted.weblate.org/projects/jirafeau/master/).
206
207 If you want to add a new language in the list, feel free to contact us or leave a comment in ticket #9.
208
209 We would like to thank all anonymous contributors on weblate. :)
210
211 ### How do I upgrade my Jirafeau?
212
213 See upgrade instructions above.
214
215 ### How can I limit upload access?
216
217 There are two ways to limit upload access (but not download):
218 - you can set one or more passwords in order to access the upload interface, or/and
219 - you can configure a list of authorized IP ([CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation)) which are allowed to access to the upload page
220
221 Check documentation of ```upload_password``` and ```upload_ip``` parameters in [lib/config.original.php](https://gitlab.com/mojo42/Jirafeau/blob/master/lib/config.original.php).
222
223 ### How can I automatize the cleaning of old (expired) files?
224
225 You can call the admin.php script from the command line (CLI) with the ```clean_expired``` or ```clean_async``` commands: ```sudo -u www-data php admin.php clean_expired```.
226
227 Then the command can be placed in a cron file to automatize the process. For example:
228 ```
229 # m h dom mon dow user command
230 12 3 * * * www-data php /path/to/jirafeau/admin.php clean_expired
231 16 3 * * * www-data php /path/to/jirafeau/admin.php clean_async
232 ```
233
234 ### I have some troubles with IE
235
236 If you have some strange behavior with IE, you may configure [compatibility mode](http://feedback.dominknow.com/knowledgebase/articles/159097-internet-explorer-ie8-ie9-ie10-and-ie11-compat).
237
238 Anyway I would recommend you to use another web browser. :)
239
240 ### How can I change the theme?
241
242 You may change the default theme to any of the existing ones or a custom.
243
244 Open your ```lib/config.local.php``` and change setting in the »`style`« key to the name of any folder in the ```/media``` directory.
245
246 Hint: To create a custom theme just copy the »courgette« folder and name your theme »custom« (this way it will be ignored by git and not overwritten during updates). You are invited to enhance the existing themes and send pull requests however.
247
248 ### I found a bug, what should I do?
249
250 Feel free to open a bug in the [GitLab's issues](https://gitlab.com/mojo42/Jirafeau/issues).
251
252 ### How to set maximum file size?
253
254 If your browser supports HTML5 file API, you can send files as big as you want.
255
256 For browsers who does not support HTML5 file API, the limitation come from PHP configuration.
257 You have to set [post_max_size](https://php.net/manual/en/ini.core.php#ini.post-max-size) and [upload_max_filesize](https://php.net/manual/en/ini.core.php#ini.upload-max-filesize) in your php configuration. Note that Nginx setups may requiere to configure `client_max_body_size`.
258
259 If you don't want to allow unlimited upload size, you can still setup a maximal file size in Jirafeau's setting (see ```maximal_upload_size``` in your configuration)
260
261 ### How can I edit an option?
262
263 Documentation of all default options are located in [lib/config.original.php](https://gitlab.com/mojo42/Jirafeau/blob/master/lib/config.original.php).
264 If you want to change an option, just edit your ```lib/config.local.php```.
265
266 ### How can I change the Terms of Service?
267
268 The license text on the "Terms of Service" page, which is shipped with the default installation, is based on the »[Open Source Initiative Terms of Service](https://opensource.org/ToS)«.
269
270 To change this text simply copy the file [/lib/tos.original.txt](https://gitlab.com/mojo42/Jirafeau/blob/master/lib/tos.original.txt), rename it to ```/lib/tos.local.txt``` and adapt it to your own needs.
271
272 If you update the installation, then only the ```tos.original.txt``` file may change eventually, not your ```tos.local.txt``` file.
273
274 ### How can I access the admin interface?
275
276 Just go to ```/admin.php```.
277
278 ### How can I use the scripting interface (API)?
279
280 Simply go to ```/script.php``` with your web browser.
281
282 ### My downloads are incomplete or my uploads fails
283
284 Be sure your PHP installation is not using safe mode, it may cause timeouts.
285
286 If you're using nginx, you might need to increase `client_max_body_size` or remove the restriction altogether. In your nginx.conf:
287
288 ```nginx
289 http {
290 # disable max upload size
291 client_max_body_size 0;
292 # add timeouts for very large uploads
293 client_header_timeout 30m;
294 client_body_timeout 30m;
295 }
296 ```
297
298 ### How can I monitor the use of my Jirafeau instance?
299
300 You may use Munin and simple scripts to collect the number of files in the Jirafeau instance as well as the disk space occupied by all the files. You can consult this [web page](https://blog.bandinelli.net/index.php?post/2016/05/15/Scripts-Munin-pour-Jirafeau).
301
302 ### Why forking?
303
304 The original project seems not to be continued anymore and I prefer to add more features and increase security from a stable version.
305
306 ### What can we expect in the future?
307
308 Check [issues](https://gitlab.com/mojo42/Jirafeau/issues) to check open bugs and incoming new stuff. :)
309
310 ### What about this file deduplication thing?
311
312 Jirafeau uses a very simple file level deduplication for storage optimization.
313
314 This mean that if some people upload several times the same file, this will only store one time the file and increment a counter.
315
316 If someone use his/her delete link or an admin cleans expired links, this will decrement the counter corresponding to the file.
317
318 When the counter falls to zero, the file is destroyed.
319
320 ### What is the difference between "delete link" and "delete file and links" in admin interface?
321
322 As explained in the previous question, files with the same md5 hash are not duplicated and a reference counter stores the number of links pointing to a single file.
323 So:
324 - The button "delete link" will delete the reference to the file but might not destroy the file.
325 - The button "delete file and links" will delete all references pointing to the file and will destroy the file.
326
327 ### How to contact someone from Jirafeau?
328
329 Feel free to create an issue if you found a bug.
330
331 ## Release notes
332
333 ### Version 1.0
334
335 The very first version of Jirafeau after the fork of Jyraphe.
336
337 - Security fix
338 - Keep uploader's ip
339 - Delete link for each upload
340 - No more clear text password storage
341 - Simple langage support
342 - Add an admin interface
343 - New Design
344 - Add term of use
345 - New path system to manage large number of files
346 - New option to show a page at download time
347 - Add option to activate or not preview mode
348
349 ### Version 1.1
350
351 - New skins
352 - Add optional server side encryption
353 - Unlimited file size upload using HTML5 file API
354 - Show speed and estimated time during upload
355 - A lot of fixes
356 - A lot of new langages
357 - Small API to upload files
358 - Limit access to Jirafeau using IP, mask, passwords
359 - Manage (some) proxy headers
360 - Configure your maximal upload size
361 - Configure file's lifetime durations
362 - Preview URL
363 - Get Jirafeau's version in admin interface
364
365 ## Version 1.2.0
366
367 - Link on API page to generate bash script
368 - More informative error codes for API
369 - Security Fix: Prevent authentication bypass for admin interface
370 - CLI script to remove expired files automatically with a cronjob
371 - SHA-256 hash the admin password
372 - New theme "elegantish"
373 - Fix for JavaScript MIME-Type, prevents blocking the resource on some servers
374 - Show download link for a file in admin interface
375 - Default time for expiration (set to 'month' by default)
376 - New expiration time: 'quarter'
377 - A lof of translation contributions
378 - Code cleanups
379
380 ## Version 2.0.0
381
382 - Various documentation improvements
383 - Simplify automatic generation of local configuration file
384 - Set a custom title
385 - Bash Script: Enhanced help, show version, return link to web view as well
386 - »Terms of Service« refactored - Enable admin to overwrite the ToS, without changing existing source code → breaking, see upgrade notes
387
388 ## Version 3.0.0
389
390 - Remove XHTML doctype, support HTML5 only → breaking change for older browsers
391 - Remove redundant code
392 - Remove baseurl usage and set absolute links instead, which for example fixes SSL issues
393 - Extend contribution guide
394 - Switch to PSR-2 code style (fix line endings, indentations, whitespaces, etc)
395 - Declare system requirements
396 - Catch API errors in upload form
397 - Allow clients to upload files depending on IP or password
398 - Set UTC as timezone to prevent date/time issues
399 - Show readable date & time information
400 - Fix UI glitches in admin panel and upload form
401
402 ## Version 3.1.0
403
404 - Fix regression on user authentication (see #113)
405 - Some cosmetic change
406
407 ## Version 3.2.0
408
409 - Update translations from Update translations from weblate
410 - Better style
411 - Fix regression on admin password setting
412
413 ## Version 3.2.1
414
415 - fix download view after an upload
416
417 ## Version 3.3.0
418
419 - Added Docker Support
420 - Added a copy button next to links to copy URLs in clipboard
421 - Now use a delete page to confirm file deletion (#136)
422 - Fixed object ProgressEvent Error (#127)
423 - Added configuration tips for web servers
424 - More translations
425 - Style fixes
426 - Removed useless alias API support (some old toy)
427
428 ## Version 3.4.0
429
430 - Add encryption support in bash script
431 - Refactoring of lang system for simpler management
432 - Removed installation step asking for language
433 - Merged weblate contributions
434 - Fixed some spelling issues

patrick-canterino.de