[FEATURE] add LDAP authentication support for uploaders

[jirafeau_mojo42.git] / README.md

diff --git a/README.md b/README.md
index 8e6fe31c93b4ee4cec2d829bc01fd185168b31bd..405185c2d89e5eb8c36af118117298fcb8bba802 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,18 +1,18 @@
 # Jirafeau
 
 # Jirafeau
 

+![Build Status](https://img.shields.io/gitlab/pipeline/mojo42/Jirafeau/master.svg)
+![Made With](https://img.shields.io/badge/made_with-php-blue.svg)
+![License](https://img.shields.io/badge/license-agpl--3.0-blue.svg)
+![Contribution](https://img.shields.io/badge/contributions_welcome-brightgreen.svg?labelColor=brightgreen)
+

 Welcome to the official Jirafeau project, an [Open-Source software](https://en.wikipedia.org/wiki/Open-source_software).
 
 Welcome to the official Jirafeau project, an [Open-Source software](https://en.wikipedia.org/wiki/Open-source_software).
 

-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.
+Jirafeau is a "one-click-filesharing": Select your file, upload, share a link. That's it.

 
 

-A demonstration of the latest version is available on [jirafeau.net](https://jirafeau.net/).
+See [jirafeau.net](https://jirafeau.net/) for a demo.

 
 ![Screenshot1](http://i.imgur.com/TPjh48P.png)
 
 
 ![Screenshot1](http://i.imgur.com/TPjh48P.png)
 

-Latest CI Status:
-Master [![Build Status Master](https://gitlab.com/mojo42/Jirafeau/badges/master/build.svg)](https://gitlab.com/mojo42/Jirafeau/commits/master)
-Next Release [![Build Status Next Release](https://gitlab.com/mojo42/Jirafeau/badges/test/build.svg)](https://gitlab.com/mojo42/Jirafeau/commits/master)
-[All Branch Builds](https://gitlab.com/mojo42/Jirafeau/pipelines?scope=branches)
-

 ## Main features
 
 - One upload → One download link & one delete link
 ## Main features
 
 - One upload → One download link & one delete link


@@ -20,6 +20,7 @@ Next Release [![Build Status Next Release](https://gitlab.com/mojo42/Jirafeau/ba
 - Shows progression: speed, percentage and remaining upload time
 - Preview content in browser (if possible)
 - Optional password protection (for uploading or downloading)
 - Shows progression: speed, percentage and remaining upload time
 - Preview content in browser (if possible)
 - Optional password protection (for uploading or downloading)

+- LDAP authentication for uploaders

 - Set expiration time for downloads
 - Option to self-destruct after first download
 - Shortened URLs using base 64 encoding
 - Set expiration time for downloads
 - Option to self-destruct after first download
 - Shortened URLs using base 64 encoding


@@ -72,67 +73,11 @@ Installation steps:
   - The script will redirect to you to a minimal installation wizard to set up all required options
   - All optional parameters may be set in ```lib/config.local.php```, take a look at ```lib/config.original.php``` to see all default values
 - B) Setup without the installation wizard (cli):
   - The script will redirect to you to a minimal installation wizard to set up all required options
   - All optional parameters may be set in ```lib/config.local.php```, take a look at ```lib/config.original.php``` to see all default values
 - B) Setup without the installation wizard (cli):

-  - Just copy ```config.original.php``` to ```config.local.php``` and customize it
-
-## Upgrade
-
-### General procedure for all versions
-
-1. Backup your Jirafeau installation!
-2. Block access to Jirafeau
-3. Checkout the new version with Git using the [tagged release](https://gitlab.com/mojo42/Jirafeau/tags)
-   * 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.
-4. With you browser, go to your Jirafeau root page
-5. Follow the installation wizard, it should propose you the same data folder or even update automatically
-7. Check your ```/lib/config.local.php``` and compare it with the ```/lib/config.original.php``` to see if new configuration items are available
-
-### From version 1.0 to 1.1
-
-1. The download URL changed
-   * Add a rewrite rule in your web server configuration to rename ```file.php``` to ```f.php``` to make older, still existing links work again
-1. The default theme changed
-   * Optionally change the theme in ```lib/config.local.php``` to »courgette«
-
-### From version 1.2.0 to 2.0.0
-
-1. The "Terms of Service" text file changed
-   * 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
-
-### From version 2.0.0 to 3.4.1
-
-There is nothing special to do to update from/to the following versions:
-- 2.0.0 -> 3.0.0
-- 3.0.0 -> 3.1.0
-- 3.1.0 -> 3.2.0
-- 3.2.0 -> 3.2.1
-- 3.2.1 -> 3.3.0
-- 3.3.0 -> 3.4.0
-- 3.4.0 -> 3.4.1
+  - Just copy ```lib/config.original.php``` to ```lib/config.local.php``` and customize it

 
 

-### From 3.4.1 to 4.0.0
-
-You may have to change your administrator password in your config file as admin password are only stored using sha256 (SHA2).
-To do so, edit `lib/config.local.php` and update `admin_password` option using `echo -n MyNewPassw0rd | sha256sum` command.
-
-Subfolder division changed in Jirafeau storage. You can either start from a fresh `var-` folder or you need to migrate your data.
-
-In order to migrate your existing data:
-1. Be sure to have a working backup of your Jirafeau instance and/or the rest of your hosting before any operation
-2. Go to `var-` folder
-3. Be sure you have read and write permissions on files and folders with your current user
-4. Run the following commands:
-```bash
-# Migrate files folder
-find files -type f ! -name "*_count" | while read f; do bn="$(basename "$f")"; dst="files/${bn:0:8}/${bn:8:8}/${bn:16:8}/${bn:24:8}/"; mkdir -p "$dst"; mv "$f" "$dst" ; mv "${f}_count" "$dst"; done; find files -maxdepth 1 -type d -iname "?" -exec rm -rf {} \;
-# Migrate links folder
-find links -type f | while read link; do bn="$(basename "$link")"; mkdir "links/$bn"; mv "$link" "links/$bn/"; done; find links -maxdepth 1 -type d -iname "?" -exec rm -rf {} \;
-```
-
-### From 4.0.0 to 4.1.1
-
-There is nothing special to do to update from/to the following versions:
-- 4.0.0 -> 4.1.0
-- 4.1.0 -> 4.1.1
+💡 Hint: How to
+[install & configure Jirafeau](https://www.howtoforge.com/how-to-setup-a-file-sharing-website-with-jirafeau-on-debian-10/)
+on Debian 10 from scratch, with Nginx and PHP-FPM.

 
 ### Troubleshooting
 
 
 ### Troubleshooting
 


@@ -140,10 +85,11 @@ If you have some troubles, consider the following cases
 
 - Check your ```/lib/config.local.php``` file and compare it with ```/lib/config.original.php```, the configuration syntax or a parameter may have changed
 - Check owner & permissions of your files
 
 - Check your ```/lib/config.local.php``` file and compare it with ```/lib/config.original.php```, the configuration syntax or a parameter may have changed
 - Check owner & permissions of your files

+- set `debug` option to `true` to check any warning or error

 
 ## Security
 
 
 ## Security
 

-```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.
+```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.

 You have several options:
 - Configure a ```.htaccess```
 - Move var folder to a place on your server which can't be directly accessed
 You have several options:
 - Configure a ```.htaccess```
 - Move var folder to a place on your server which can't be directly accessed


@@ -227,7 +173,7 @@ Thanks to all contributors ! :)
 
 ### How do I upgrade my Jirafeau?
 
 
 ### How do I upgrade my Jirafeau?
 

-See upgrade instructions above.
+See change log and upgrade procedure in [CHANGELOG.md](https://gitlab.com/mojo42/Jirafeau/blob/master/CHANGELOG.md).

 
 ### How can I limit upload access?
 
 
 ### How can I limit upload access?
 


@@ -265,6 +211,8 @@ Hint: To create a custom theme just copy the »courgette« folder and name your
 ### I found a bug, what should I do?
 
 Feel free to open a bug in the [GitLab's issues](https://gitlab.com/mojo42/Jirafeau/issues).
 ### I found a bug, what should I do?
 
 Feel free to open a bug in the [GitLab's issues](https://gitlab.com/mojo42/Jirafeau/issues).

+If you can, please copy-paste informations related to bug opening provided in admin interface.
+Admin interface can be reached by accessing `/admin.php`.

 
 ### How to set maximum file size?
 
 
 ### How to set maximum file size?
 


@@ -326,7 +274,7 @@ Check [issues](https://gitlab.com/mojo42/Jirafeau/issues) to check open bugs and
 
 ### What about this file deduplication thing?
 
 
 ### What about this file deduplication thing?
 

-Jirafeau uses a very simple file level deduplication for storage optimization.
+Jirafeau can use a very simple file level deduplication for storage optimization.

 
 This mean that if some people upload several times the same file, this will only store one time the file and increment a counter.
 
 
 This mean that if some people upload several times the same file, this will only store one time the file and increment a counter.
 


@@ -334,149 +282,34 @@ If someone use his/her delete link or an admin cleans expired links, this will d
 
 When the counter falls to zero, the file is destroyed.
 
 
 When the counter falls to zero, the file is destroyed.
 

+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`).
+
+This feature is disabled by default and can be enabled through the `file_hash` option.
+

 ### What is the difference between "delete link" and "delete file and links" in admin interface?
 
 ### What is the difference between "delete link" and "delete file and links" in admin interface?
 

-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.
+When file deduplication feature is enabled, files with the same hash are not duplicated and a reference counter stores the number of links pointing to a single file.

 So:
 - The button "delete link" will delete the reference to the file but might not destroy the file.
 - The button "delete file and links" will delete all references pointing to the file and will destroy the file.
 
 So:
 - The button "delete link" will delete the reference to the file but might not destroy the file.
 - The button "delete file and links" will delete all references pointing to the file and will destroy the file.
 

-### How to contact someone from Jirafeau?
+### How can I setup LDAP authentication?

 
 

-Feel free to create an issue if you found a bug.
+LDAP authentication is disabled by default. To use it, you will need to install [PHP LDAP extension](https://www.php.net/manual/en/book.ldap.php) and edit your `lib/config.local.php` to set those options:
+- `upload_ldap_auth`: set it to `true`
+- `upload_ldap_host`: set it to your ldap host
+- `upload_ldap_base_dn`: set it to your base DN

 
 

-## Release notes
-
-### Version 1.0
-
-The very first version of Jirafeau after the fork of Jyraphe.
-
-- Security fix
-- Keep uploader's ip
-- Delete link for each upload
-- No more clear text password storage
-- Simple langage support
-- Add an admin interface
-- New Design
-- Add term of use
-- New path system to manage large number of files
-- New option to show a page at download time
-- Add option to activate or not preview mode
-
-### Version 1.1
-
-- New skins
-- Add optional server side encryption
-- Unlimited file size upload using HTML5 file API
-- Show speed and estimated time during upload
-- A lot of fixes
-- A lot of new langages
-- Small API to upload files
-- Limit access to Jirafeau using IP, mask, passwords
-- Manage (some) proxy headers
-- Configure your maximal upload size
-- Configure file's lifetime durations
-- Preview URL
-- Get Jirafeau's version in admin interface
-
-## Version 1.2.0
-
-- Link on API page to generate bash script
-- More informative error codes for API
-- Security Fix: Prevent authentication bypass for admin interface
-- CLI script to remove expired files automatically with a cronjob
-- SHA-256 hash the admin password
-- New theme "elegantish"
-- Fix for JavaScript MIME-Type, prevents blocking the resource on some servers
-- Show download link for a file in admin interface
-- Default time for expiration (set to 'month' by default)
-- New expiration time: 'quarter'
-- A lof of translation contributions
-- Code cleanups
-
-## Version 2.0.0
-
-- Various documentation improvements
-- Simplify automatic generation of local configuration file
-- Set a custom title
-- Bash Script: Enhanced help, show version, return link to web view as well
-- »Terms of Service« refactored - Enable admin to overwrite the ToS, without changing existing source code → breaking, see upgrade notes
-
-## Version 3.0.0
-
-- Remove XHTML doctype, support HTML5 only → breaking change for older browsers
-- Remove redundant code
-- Remove baseurl usage and set absolute links instead, which for example fixes SSL issues
-- Extend contribution guide
-- Switch to PSR-2 code style (fix line endings, indentations, whitespaces, etc)
-- Declare system requirements
-- Catch API errors in upload form
-- Allow clients to upload files depending on IP or password
-- Set UTC as timezone to prevent date/time issues
-- Show readable date & time information
-- Fix UI glitches in admin panel and upload form
-
-## Version 3.1.0
-
-- Fix regression on user authentication (see #113)
-- Some cosmetic change
-
-## Version 3.2.0
-
-- Update translations from Update translations from weblate
-- Better style
-- Fix regression on admin password setting
-
-## Version 3.2.1
+More details in [config.original.php](lib/config.original.php)'s documentation.

 
 

-- fix download view after an upload
+Note that you can test around LDAP with [docker-compose example](./docker/docker-compose-examples/ldap/).

 
 

-## Version 3.3.0
-
-- Added Docker Support
-- Added a copy button next to links to copy URLs in clipboard
-- Now use a delete page to confirm file deletion (#136)
-- Fixed object ProgressEvent Error (#127)
-- Added configuration tips for web servers
-- More translations
-- Style fixes
-- Removed useless alias API support (some old toy)
-
-## Version 3.4.0
-
-- Add encryption support in bash script
-- Refactoring of lang system for simpler management
-- Removed installation step asking for language
-- Merged weblate contributions
-- Fixed some spelling issues
-
-## Version 3.4.1
-
-- Security fixes, thanks [Bishopfox Team](https://www.bishopfox.com/)
-- Translation fixes
-- Docker fix
-- Advertise javascript license for LibreJS compatibility
-- other minor fixes
-
-## Version 4.0.0
-
-- Removed plain-text password support for admin auth (breaking change).
-- Default folder sub-division to 8 characters (breaking change).
-- New option `upload_ip_nopassword` to allow a list of IP to access Jirafeau without password
-- Bugfix with LibreJS
-- Other minor bug fixes
-- More languages supported
-
-## Version 4.1.0
+### How to contact someone from Jirafeau?

 
 

-- Fix upload password and allowed ip (#201)
-- Code refactorisation of IP checking
-- Fix expiration dates
-- Add better support for Accept-Language
-- Cosmetic fixes
-- More languages supported and language fixes
+Feel free to create an issue if you found a bug.

 
 

-## Version 4.1.1
+Also, you can come have a chat on [libera.chat](https://web.libera.chat/) in `#jirafeau` channel.

 
 

-- Fix lang sanity check
+### Can I buy you a coffee?

 
 

+You can [drop few bucks](https://www.paypal.com/paypalme/jeromejutteau) to help the [demo web site](https://jirafeau.net) to stay alive.