]> git.p6c8.net - jirafeau_project.git/blob - README.md
[BUFIX] fix bash script to send files
[jirafeau_project.git] / README.md
1 # Jirafeau
2
3 Welcome to the official Jirafeau project, an [Open-Source software](https://en.wikipedia.org/wiki/Open-source_software).
4
5 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.
6
7 A demonstration of the latest version is available on [jirafeau.net](https://jirafeau.net/).
8
9 ![Screenshot1](http://i.imgur.com/TPjh48P.png)
10
11 Latest CI Status:
12 Master [![Build Status Master](https://gitlab.com/mojo42/Jirafeau/badges/master/build.svg)](https://gitlab.com/mojo42/Jirafeau/commits/master)
13 Next Release [![Build Status Next Release](https://gitlab.com/mojo42/Jirafeau/badges/test/build.svg)](https://gitlab.com/mojo42/Jirafeau/commits/master)
14 [All Branch Builds](https://gitlab.com/mojo42/Jirafeau/pipelines?scope=branches)
15
16 ## Main features
17
18 - One upload → One download link & one delete link
19 - Send any large files (thanks to the HTML5 file API → PHP post_max_size limit not relevant)
20 - Shows progression: speed, percentage and remaining upload time
21 - Preview content in browser (if possible)
22 - Optional password protection (for uploading or downloading)
23 - Set expiration time for downloads
24 - Option to self-destruct after first download
25 - Shortened URLs using base 64 encoding
26 - Maximal upload size configurable
27 - NO database, only use basic PHP
28 - Simple language support with a lot of langages (help us on [weblate](https://hosted.weblate.org/engage/jirafeau/)!)
29 - File level [Deduplication](http://en.wikipedia.org/wiki/Data_deduplication) for storage optimization (does store duplicate files only once, but generate multiple links)
30 - Optional data encryption
31 - Small administration interface
32 - CLI script to remove expired files automatically with a cronjob
33 - Basic, adaptable »Terms Of Service« page
34 - Basic API
35 - Bash script to upload files via command line
36 - Themes
37
38 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.
39
40 As it's original project, Jirafeau is made in the [KISS](http://en.wikipedia.org/wiki/KISS_principle) way (Keep It Simple, Stupid).
41
42 Jirafeau project won't evolve to a file manager and will focus to keep a very few dependencies.
43
44 ## Screenshots
45
46 - [Installation - Step 1](http://i.imgur.com/hmpT1eN.jpg)
47 - [Installation - Step 2](http://i.imgur.com/2e0UGKE.jpg)
48 - [Installation - Step 3](http://i.imgur.com/ofAjLXh.jpg)
49 - [Installation - Step 4](http://i.imgur.com/WXqnfqJ.jpg)
50 - [Upload - Step 1](http://i.imgur.com/SBmSwzJ.jpg)
51 - [Upload - Step 2](http://i.imgur.com/wzPkb1Z.jpg)
52 - [Upload - Progress](http://i.imgur.com/i6n95kv.jpg)
53 - [Upload - Confirmation page](http://i.imgur.com/P2oS1MY.jpg)
54 - [Admin Interface](http://i.imgur.com/nTdsVzn.png)
55
56 ## Installation
57
58 This shows how to install Jirafeau by your own, it's quite simple but you can
59 also use a [docker image](https://hub.docker.com/r/mojo42/jirafeau/) or build
60 it yourself. Check [docker folder](docker/README.md) for more informations.
61
62 System requirements:
63 - PHP >= 5.6
64 - Optional, but recommended: Git >= 2.7
65 - No database required, no mail required
66
67 Installation steps:
68 - Clone the [repository](https://gitlab.com/mojo42/Jirafeau/) or download the latest [release](https://gitlab.com/mojo42/Jirafeau/tags) from GitLab onto your webserver
69 - Set owner & group according to your webserver
70 - A) Setup with the installation wizard (web):
71 - Open your browser and go to your installed location, eg. ```https://example.com/jirafeau/```
72 - The script will redirect to you to a minimal installation wizard to set up all required options
73 - All optional parameters may be set in ```lib/config.local.php```, take a look at ```lib/config.original.php``` to see all default values
74 - B) Setup without the installation wizard (cli):
75 - Just copy ```lib/config.original.php``` to ```lib/config.local.php``` and customize it
76
77 ### Troubleshooting
78
79 If you have some troubles, consider the following cases
80
81 - Check your ```/lib/config.local.php``` file and compare it with ```/lib/config.original.php```, the configuration syntax or a parameter may have changed
82 - Check owner & permissions of your files
83 - set `debug` option to `true` to check any warning or error
84
85 ## Security
86
87 ```var``` directory contains all files and links. It is randomly named to limit access but you may add better protection to prevent un-authorized access to it.
88 You have several options:
89 - Configure a ```.htaccess```
90 - Move var folder to a place on your server which can't be directly accessed
91 - Disable automatic listing on your web server config or place a index.html in var's sub-directory (this is a limited solution)
92
93 If you are using Apache, you can add the following line to your configuration to prevent people to access to your ```var``` folder:
94
95 ```RedirectMatch 301 ^/var-.* http://my.service.jirafeau ```
96
97 If you are using nginx, you can add the following to your $vhost.conf:
98
99 ```nginx
100 location ~ /var-.* {
101 deny all;
102 return 404;
103 }
104 ```
105
106 If you are using lighttpd, you can deny access to ```var``` folder in your configuration:
107
108 ```
109 $HTTP["url"] =~ "^/var-*" {
110 url.access-deny = ("")
111 }
112 ```
113
114 You should also remove un-necessessary write access once the installation is done (ex: configuration file).
115 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).
116
117 ## Server side encryption
118
119 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).
120 The decrypt key is not stored on the server so if you loose an url, you won't be able to retrieve file content.
121 Encryption is configured to use AES256 in OFB mode.
122 In case of security troubles on the server, attacker won't be able to access files.
123
124 By activating this feature, you have to be aware of few things:
125 - Data encryption has a cost (cpu) and it takes more time for downloads to complete once file sent.
126 - During the download, the server will decrypt on the fly (and use resource).
127 - This feature needs to have the mcrypt php module.
128 - File de-duplication will stop to work (as we can't compare two encrypted files).
129 - Be sure your server do not log client's requests.
130 - Don't forget to enable https.
131
132 In a next step, encryption will be made by the client (in javascript), see issue #10.
133
134 ## License
135
136 GNU Affero General Public License v3 (AGPL-3.0).
137
138 The GNU Affero General Public License can be found at https://www.gnu.org/licenses/agpl.html.
139
140 Please note: If you decide do make adaptions to the source code and run a service with these changes incorporated,
141 you are required to provide a link to the source code of your version in order to obey the AGPL-3.0 license.
142 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.
143 Take a look at the FAQ to find out about how to change the ToS.
144
145 PS: If you have fixed errors or added features, then please contribute to the project and send a merge request with these changes.
146
147 ## Contribution
148
149 If you want to contribute to project, then take a look at the git repository:
150
151 - https://gitlab.com/mojo42/Jirafeau
152
153 and the Contribution Guidelines
154
155 - https://gitlab.com/mojo42/Jirafeau/blob/master/CONTRIBUTING.md
156
157 ## FAQ
158
159 ### Can I add a new language in Jirafeau?
160
161 Of course ! Translations are easy to make and no technical knowledge is required.
162
163 Simply go to [Jirafeau's Weblate](https://hosted.weblate.org/engage/jirafeau/).
164
165 If you want to add a new language in the list, feel free to contact us or leave a comment in ticket #9.
166
167 Thanks to all contributors ! :)
168
169 ### How do I upgrade my Jirafeau?
170
171 See change log and upgrade procedure in [CHANGELOG.md](https://gitlab.com/mojo42/Jirafeau/blob/master/CHANGELOG.md).
172
173 ### How can I limit upload access?
174
175 There are two ways to limit upload access (but not download):
176 - you can set one or more passwords in order to access the upload interface, or/and
177 - 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
178
179 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).
180
181 ### How can I automatize the cleaning of old (expired) files?
182
183 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```.
184
185 Then the command can be placed in a cron file to automatize the process. For example:
186 ```
187 # m h dom mon dow user command
188 12 3 * * * www-data php /path/to/jirafeau/admin.php clean_expired
189 16 3 * * * www-data php /path/to/jirafeau/admin.php clean_async
190 ```
191
192 ### I have some troubles with IE
193
194 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).
195
196 Anyway I would recommend you to use another web browser. :)
197
198 ### How can I change the theme?
199
200 You may change the default theme to any of the existing ones or a custom.
201
202 Open your ```lib/config.local.php``` and change setting in the »`style`« key to the name of any folder in the ```/media``` directory.
203
204 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.
205
206 ### I found a bug, what should I do?
207
208 Feel free to open a bug in the [GitLab's issues](https://gitlab.com/mojo42/Jirafeau/issues).
209
210 ### How to set maximum file size?
211
212 If your browser supports HTML5 file API, you can send files as big as you want.
213
214 For browsers who does not support HTML5 file API, the limitation come from PHP configuration.
215 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`.
216
217 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)
218
219 ### How can I edit an option?
220
221 Documentation of all default options are located in [lib/config.original.php](https://gitlab.com/mojo42/Jirafeau/blob/master/lib/config.original.php).
222 If you want to change an option, just edit your ```lib/config.local.php```.
223
224 ### How can I change the Terms of Service?
225
226 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)«.
227
228 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.
229
230 If you update the installation, then only the ```tos.original.txt``` file may change eventually, not your ```tos.local.txt``` file.
231
232 ### How can I access the admin interface?
233
234 Just go to ```/admin.php```.
235
236 ### How can I use the scripting interface (API)?
237
238 Simply go to ```/script.php``` with your web browser.
239
240 ### My downloads are incomplete or my uploads fails
241
242 Be sure your PHP installation is not using safe mode, it may cause timeouts.
243
244 If you're using nginx, you might need to increase `client_max_body_size` or remove the restriction altogether. In your nginx.conf:
245
246 ```nginx
247 http {
248 # disable max upload size
249 client_max_body_size 0;
250 # add timeouts for very large uploads
251 client_header_timeout 30m;
252 client_body_timeout 30m;
253 }
254 ```
255
256 ### How can I monitor the use of my Jirafeau instance?
257
258 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).
259
260 ### Why forking?
261
262 The original project seems not to be continued anymore and I prefer to add more features and increase security from a stable version.
263
264 ### What can we expect in the future?
265
266 Check [issues](https://gitlab.com/mojo42/Jirafeau/issues) to check open bugs and incoming new stuff. :)
267
268 ### What about this file deduplication thing?
269
270 Jirafeau uses a very simple file level deduplication for storage optimization.
271
272 This mean that if some people upload several times the same file, this will only store one time the file and increment a counter.
273
274 If someone use his/her delete link or an admin cleans expired links, this will decrement the counter corresponding to the file.
275
276 When the counter falls to zero, the file is destroyed.
277
278 In order to know if a newly uploaded file already exist, Jirafeau will hash the file using md5 by default but other methods are available (see `file_hash` documentation in `lib/config.original.php`).
279
280 ### What is the difference between "delete link" and "delete file and links" in admin interface?
281
282 As explained in the previous question, files with the same hash are not duplicated and a reference counter stores the number of links pointing to a single file.
283 So:
284 - The button "delete link" will delete the reference to the file but might not destroy the file.
285 - The button "delete file and links" will delete all references pointing to the file and will destroy the file.
286
287 ### How to contact someone from Jirafeau?
288
289 Feel free to create an issue if you found a bug.

patrick-canterino.de