From 6fa2bfe30e1a4fffa809bce4557cebf186edec5c Mon Sep 17 00:00:00 2001 From: El RIDO Date: Wed, 4 Oct 2017 20:05:46 +0200 Subject: [PATCH] updated documentation, incremented version --- CHANGELOG.md | 2 + INSTALL.md | 159 +++++++++++++++++++++++- README.md | 2 +- css/bootstrap/privatebin.css | 2 +- css/noscript.css | 2 +- css/privatebin.css | 2 +- js/privatebin.js | 2 +- lib/Configuration.php | 2 +- lib/Data/AbstractData.php | 2 +- lib/Data/Database.php | 2 +- lib/Data/Filesystem.php | 2 +- lib/Filter.php | 2 +- lib/I18n.php | 2 +- lib/Json.php | 2 +- lib/Model.php | 2 +- lib/Model/AbstractModel.php | 2 +- lib/Model/Comment.php | 2 +- lib/Model/Paste.php | 2 +- lib/Persistence/AbstractPersistence.php | 2 +- lib/Persistence/PurgeLimiter.php | 2 +- lib/Persistence/ServerSalt.php | 2 +- lib/Persistence/TrafficLimiter.php | 2 +- lib/PrivateBin.php | 4 +- lib/Request.php | 2 +- lib/Sjcl.php | 2 +- lib/View.php | 2 +- lib/Vizhash16x16.php | 2 +- tpl/bootstrap.php | 2 +- tpl/page.php | 2 +- 29 files changed, 188 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 964d4ee..8e77d86 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ * CHANGED: Minimum required PHP version is 5.4 (#186) * CHANGED: Shipped .htaccess files were updated for Apache 2.4 (#192) * CHANGED: Cleanup of bootstrap template variants and moved icons to `img` directory + * **1.1.1 (2017-10-06)** + * CHANGED: Switched to `.php` file extension for configuration file, to avoid leaking configuration data in unprotected installation. * **1.1 (2016-12-26)** * ADDED: Translations for Italian and Russian * ADDED: Loading message displayed until decryption succeeded for slower (in terms of CPU or network) systems diff --git a/INSTALL.md b/INSTALL.md index 7e5fa31..6eebfe9 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1 +1,158 @@ -For installation instructions, see [our wiki](https://github.com/PrivateBin/PrivateBin/wiki/Installation). +# Installation + +**TL;DR:** Download the +[latest release archive](https://github.com/PrivateBin/PrivateBin/releases/latest) +and extract it in your web hosts folder where you want to install your PrivateBin +instance. We try to provide a mostly safe default configuration, but we urge you to +check the [security section](#hardening-and-security) below and the [configuration +options](#configuration) to adjust as you see fit. + +**NOTE:** See [our FAQ](https://github.com/PrivateBin/PrivateBin/wiki/FAQ#how-can-i-securely-clonedownload-your-project) for information how to securely download the PrivateBin release files. + +### Minimal requirements + +- PHP version 5.4 or above +- _one_ of the following sources of cryptographically safe randomness is required: + - PHP 7 or higher + - [Libsodium](https://download.libsodium.org/libsodium/content/installation/) and it's [PHP extension](https://paragonie.com/book/pecl-libsodium/read/00-intro.md#installing-libsodium) + - open_basedir access to `/dev/urandom` + - mcrypt extension + - com_dotnet extension + + Mcrypt needs to be able to access `/dev/urandom`. This means if `open_basedir` is set, it must include this file. +- GD extension +- some disk space or (optionally) a database supported by [PDO](https://secure.php.net/manual/book.pdo.php) +- ability to create files and folders in the installation directory and the PATH defined in index.php +- A web browser with javascript support + +## Hardening and security + +### Changing the path + +In the index.php you can define a different `PATH`. This is useful to secure your +installation. You can move the configuration, data files, templates and PHP +libraries (directories cfg, doc, data, lib, tpl, tst and vendor) outside of your +document root. This new location must still be accessible to your webserver / PHP +process (see also +[open_basedir setting](https://secure.php.net/manual/en/ini.core.php#ini.open-basedir)). + +> #### PATH Example +> Your PrivateBin installation lives in a subfolder called "paste" inside of +> your document root. The URL looks like this: +> http://example.com/paste/ +> +> The full path of PrivateBin on your webserver is: +> /home/example.com/htdocs/paste +> +> When setting the path like this: +> define('PATH', '../../secret/privatebin/'); +> +> PrivateBin will look for your includes / data here: +> /home/example.com/secret/privatebin + +### Transport security + +When setting up PrivateBin, also set up HTTPS, if you haven't already. Without HTTPS +PrivateBin is not secure, as the javascript files could be manipulated during transmission. +For more information on this, see our [FAQ entry on HTTPS setup](https://github.com/PrivateBin/PrivateBin/wiki/FAQ#how-should-i-setup-https). + +## Configuration + +In the file `cfg/conf.php` you can configure PrivateBin. A `cfg/conf.sample.php` +is provided containing all options and default values. You can copy it to +`cfg/conf.php` and adapt it as needed. The config file is divided into multiple +sections, which are enclosed in square brackets. + +In the `[main]` section you can enable or disable the discussion feature, set +the limit of stored pastes and comments in bytes. The `[traffic]` section lets +you set a time limit in seconds. Users may not post more often then this limit +to your PrivateBin installation. + +More details can be found in the +[configuration documentation](https://github.com/PrivateBin/PrivateBin/wiki/Configuration). + +## Advanced installation + +### Web server configuration + +A `robots.txt` file is provided in the root dir of PrivateBin. It disallows all +robots from accessing your pastes. It is recommend to place it into the root of +your web directory if you have installed PrivateBin in a subdirectory. Make sure +to adjust it, so that the file paths match your installation. Of course also +adjust the file if you already use a `robots.txt`. + +A `.htaccess.disabled` file is provided in the root dir of PrivateBin. It blocks +some known robots and link-scanning bots. If you use Apache, you can rename the +file to `.htaccess` to enable this feature. If you use another webserver, you +have to configure it manually to do the same. + +### On using Cloudflare + +If you want to use PrivateBin behind Cloudflare, make sure you have disabled the Rocket +loader and unchecked "Javascript" for Auto Minify, found in your domain settings, +under "Speed". (More information +[in this FAQ entry](https://github.com/PrivateBin/PrivateBin/wiki/FAQ#user-content-how-to-make-privatebin-work-when-using-cloudflare-for-ddos-protection)) + +### Using a database instead of flat files + +In the configuration file the `[model]` and `[model_options]` sections let you +configure your favourite way of storing the pastes and discussions on your +server. + +`Filesystem` is the default model, which stores everything in files in the +data folder. This is the recommended setup for most sites. + +Under high load, in distributed setups or if you are not allowed to store files +locally, you might want to switch to the `Database` model. This lets you +store your data in a database. Basically all databases that are supported by +[PDO](https://secure.php.net/manual/en/book.pdo.php) may be used. Automatic table +creation is provided for `pdo_ibm`, `pdo_informix`, `pdo_mssql`, `pdo_mysql`, +`pdo_oci`, `pdo_pgsql` and `pdo_sqlite`. You may want to provide a table prefix, +if you have to share the PrivateBin database with another application or you want +to use a prefix for +[security reasons](https://security.stackexchange.com/questions/119510/is-using-a-db-prefix-for-tables-more-secure). +The table prefix option is called `tbl`. + +> #### Note +> The `Database` model has only been tested with SQLite, MySQL and PostgreSQL, +> although it would not be recommended to use SQLite in a production environment. +> If you gain any experience running PrivateBin on other RDBMS, please let us +> know. + +For reference or if you want to create the table schema for yourself (replace +`prefix_` with your own table prefix and create the table schema with phpMyAdmin +or the MYSQL console): + +```sql +CREATE TABLE prefix_paste ( + dataid CHAR(16) NOT NULL, + data BLOB, + postdate INT, + expiredate INT, + opendiscussion INT, + burnafterreading INT, + meta TEXT, + attachment MEDIUMBLOB, + attachmentname BLOB, + PRIMARY KEY (dataid) +); + +CREATE TABLE prefix_comment ( + dataid CHAR(16), + pasteid CHAR(16), + parentid CHAR(16), + data BLOB, + nickname BLOB, + vizhash BLOB, + postdate INT, + PRIMARY KEY (dataid) +); +CREATE INDEX parent ON prefix_comment(pasteid); + +CREATE TABLE prefix_config ( + id CHAR(16) NOT NULL, value TEXT, PRIMARY KEY (id) +); +INSERT INTO prefix_config VALUES('VERSION', '1.1'); +``` + +In PostgreSQL, the attachment column needs to be TEXT and not BLOB or MEDIUMBLOB. diff --git a/README.md b/README.md index 802942c..483f081 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![Codacy Badge](https://api.codacy.com/project/badge/Coverage/094500f62abf4c9aa0c8a8a4520e4789)](https://www.codacy.com/app/PrivateBin/PrivateBin) [![Test Coverage](https://codeclimate.com/github/PrivateBin/PrivateBin/badges/coverage.svg)](https://codeclimate.com/github/PrivateBin/PrivateBin/coverage) [![Code Coverage](https://scrutinizer-ci.com/g/PrivateBin/PrivateBin/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/PrivateBin/PrivateBin/?branch=master) -*Current version: 1.1* +*Current version: 1.1.1* **PrivateBin** is a minimalist, open source online pastebin where the server has zero knowledge of pasted data. diff --git a/css/bootstrap/privatebin.css b/css/bootstrap/privatebin.css index ded8259..d2ba47c 100644 --- a/css/bootstrap/privatebin.css +++ b/css/bootstrap/privatebin.css @@ -6,7 +6,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ body { diff --git a/css/noscript.css b/css/noscript.css index 97ef60d..26c6bad 100644 --- a/css/noscript.css +++ b/css/noscript.css @@ -6,7 +6,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.0 + * @version 1.1.1 */ /* When there is no script at all other */ diff --git a/css/privatebin.css b/css/privatebin.css index d3c79b4..077e8ba 100644 --- a/css/privatebin.css +++ b/css/privatebin.css @@ -6,7 +6,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ /* CSS Reset from YUI 3.4.1 (build 4118) - Copyright 2011 Yahoo! Inc. All rights reserved. diff --git a/js/privatebin.js b/js/privatebin.js index 8cf7683..9e626e9 100644 --- a/js/privatebin.js +++ b/js/privatebin.js @@ -6,7 +6,7 @@ * @see {@link https://github.com/PrivateBin/PrivateBin} * @copyright 2012 Sébastien SAUVAGE ({@link http://sebsauvage.net}) * @license {@link https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License} - * @version 1.1 + * @version 1.1.1 * @name PrivateBin * @namespace */ diff --git a/lib/Configuration.php b/lib/Configuration.php index d9d70bf..a9c8a75 100644 --- a/lib/Configuration.php +++ b/lib/Configuration.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin; diff --git a/lib/Data/AbstractData.php b/lib/Data/AbstractData.php index 41260f8..f4960f9 100644 --- a/lib/Data/AbstractData.php +++ b/lib/Data/AbstractData.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin\Data; diff --git a/lib/Data/Database.php b/lib/Data/Database.php index c35df3b..2c844ef 100644 --- a/lib/Data/Database.php +++ b/lib/Data/Database.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin\Data; diff --git a/lib/Data/Filesystem.php b/lib/Data/Filesystem.php index 4100e29..53508e0 100644 --- a/lib/Data/Filesystem.php +++ b/lib/Data/Filesystem.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin\Data; diff --git a/lib/Filter.php b/lib/Filter.php index 951e265..4c0a22e 100644 --- a/lib/Filter.php +++ b/lib/Filter.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin; diff --git a/lib/I18n.php b/lib/I18n.php index 2bee73e..5ae9bad 100644 --- a/lib/I18n.php +++ b/lib/I18n.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin; diff --git a/lib/Json.php b/lib/Json.php index 27993f9..ad96333 100644 --- a/lib/Json.php +++ b/lib/Json.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin; diff --git a/lib/Model.php b/lib/Model.php index d1011f1..b4f084f 100644 --- a/lib/Model.php +++ b/lib/Model.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin; diff --git a/lib/Model/AbstractModel.php b/lib/Model/AbstractModel.php index 55956b7..0ac2317 100644 --- a/lib/Model/AbstractModel.php +++ b/lib/Model/AbstractModel.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin\Model; diff --git a/lib/Model/Comment.php b/lib/Model/Comment.php index b67742d..709cdee 100644 --- a/lib/Model/Comment.php +++ b/lib/Model/Comment.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin\Model; diff --git a/lib/Model/Paste.php b/lib/Model/Paste.php index fae808e..1bac7c8 100644 --- a/lib/Model/Paste.php +++ b/lib/Model/Paste.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin\Model; diff --git a/lib/Persistence/AbstractPersistence.php b/lib/Persistence/AbstractPersistence.php index 64fb530..2e31622 100644 --- a/lib/Persistence/AbstractPersistence.php +++ b/lib/Persistence/AbstractPersistence.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin\Persistence; diff --git a/lib/Persistence/PurgeLimiter.php b/lib/Persistence/PurgeLimiter.php index 2eb0b52..c4affac 100644 --- a/lib/Persistence/PurgeLimiter.php +++ b/lib/Persistence/PurgeLimiter.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin\Persistence; diff --git a/lib/Persistence/ServerSalt.php b/lib/Persistence/ServerSalt.php index 129a099..a4d0686 100644 --- a/lib/Persistence/ServerSalt.php +++ b/lib/Persistence/ServerSalt.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin\Persistence; diff --git a/lib/Persistence/TrafficLimiter.php b/lib/Persistence/TrafficLimiter.php index 914450a..9f35e5d 100644 --- a/lib/Persistence/TrafficLimiter.php +++ b/lib/Persistence/TrafficLimiter.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin\Persistence; diff --git a/lib/PrivateBin.php b/lib/PrivateBin.php index c817445..7b53fa1 100644 --- a/lib/PrivateBin.php +++ b/lib/PrivateBin.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin; @@ -28,7 +28,7 @@ class PrivateBin * * @const string */ - const VERSION = '1.1'; + const VERSION = '1.1.1'; /** * minimal required PHP version diff --git a/lib/Request.php b/lib/Request.php index 37c0bca..f6daa50 100644 --- a/lib/Request.php +++ b/lib/Request.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin; diff --git a/lib/Sjcl.php b/lib/Sjcl.php index 4ed76b4..7efc7b2 100644 --- a/lib/Sjcl.php +++ b/lib/Sjcl.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin; diff --git a/lib/View.php b/lib/View.php index 6c04e47..8b25395 100644 --- a/lib/View.php +++ b/lib/View.php @@ -7,7 +7,7 @@ * @link https://github.com/PrivateBin/PrivateBin * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license http://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 1.1 + * @version 1.1.1 */ namespace PrivateBin; diff --git a/lib/Vizhash16x16.php b/lib/Vizhash16x16.php index e9bd5d0..3baae6d 100644 --- a/lib/Vizhash16x16.php +++ b/lib/Vizhash16x16.php @@ -8,7 +8,7 @@ * @link http://sebsauvage.net/wiki/doku.php?id=php:vizhash_gd * @copyright 2012 Sébastien SAUVAGE (sebsauvage.net) * @license https://www.opensource.org/licenses/zlib-license.php The zlib/libpng License - * @version 0.0.5 beta PrivateBin 1.1 + * @version 0.0.5 beta PrivateBin 1.1.1 */ namespace PrivateBin; diff --git a/tpl/bootstrap.php b/tpl/bootstrap.php index 7993e43..103037e 100644 --- a/tpl/bootstrap.php +++ b/tpl/bootstrap.php @@ -69,7 +69,7 @@ if ($MARKDOWN): - + diff --git a/tpl/page.php b/tpl/page.php index 46b8df1..81d7c1a 100644 --- a/tpl/page.php +++ b/tpl/page.php @@ -47,7 +47,7 @@ if ($MARKDOWN): - +