Updated Configuration (markdown)

Configuration.md

@@ -4,9 +4,9 @@ PrivateBin comes with a configuration file to enable/disable features, change th
 
 You find an example configuration file at `cfg/conf.ini.sample` with the default settings. If you want to change these, copy the sample file to `cfg/conf.ini` and adapt the values as needed.
 
-The file is in `ini` format, meaning that lines beginning with semicolons (`;`) are comments, configuration options are grouped in sections, marked by square brackets (`[` & `]`) and the option keys are separated by the values with equal signs (`=`).
+The file is in `ini` format, meaning that lines beginning with semicolons (`;`) are comments, configuration options are grouped in sections, marked by square brackets (`[` and `]`) and the option keys are separated by the values with equal signs (`=`).
 
-By default there are 7 sections: `[main]`, `[expire]`, `[expire_options]`, `[formatter_options]`, `[traffic]`, `[purge]`, `[model]` and `[model_options]`.
+By default there are eight sections: `[main]`, `[expire]`, `[expire_options]`, `[formatter_options]`, `[traffic]`, `[purge]`, `[model]` and `[model_options]`.
 
 ## Options
 
@@ -24,11 +24,21 @@ The `password` option enables or disables the password feature, defaults to true
 
 When this option is enabled, users can choose to set a password on their paste. It is used additionally to the randomly generated cipher that is part of the URL. Without the correct password the paste can't be displayed and one can't participate in the discussion (if enabled).
 
+### fileupload
+
+The `fileupload` option enables or disables the file upload feature, defaults to false.
+
+Even with this option enabled, the paste including the file (compressed and encrypted) still need to fit the `sizelimit`. Hence you can control how large the maximum uploaded files can be per paste.
+
+### burnafterreadingselected
+
+Preselect the burn-after-reading feature by default, defaults to false.
+
 ### formatters
 
 In the section `[formatter_options]` a list of enabled formats can be provided. To disable the use of a certain formatter, simply remove it from this list.
 
-The option `defaultformatter` in the `[main]` section allows you to define which of the formats is preselected in the drop down. Make sure that value exists in `[formatter_options]`.
+The option `defaultformatter` in the `[main]` section allows you to define which of the formats is preselected in the drop down. Make sure that value also exists in `[formatter_options]` otherwise no default will be set.
 
 Already existing pastes using disabled formatters will fall back into plain text mode when displayed. Existing pastes from previous versions that did not yet have a format set will be displayed using the `defaultformatter`.
 
@@ -36,47 +46,23 @@ The order of the options in this section is preserved in the display of the drop
 
 ### syntaxhighlightingtheme
 
-If `syntaxhighlighting` is added to the `[formatter_options]` section, syntax highlighting (format option "Source Code") is available as a possible format. The prettify library used for this feature works well with most programming languages.
+If `syntaxhighlighting` is added to the `[formatter_options]` section, syntax highlighting (format option "Source Code") is available as a possible format. The prettify library used for this feature will detecting most programming languages syntaxes automatically.
 
 If no `syntaxhighlightingtheme` is set, the built in theme is used, which works well with the `bootstrap` PrivateBin template. For the `page`, `bootstrap-dark` and `bootstrap-dark-page` PrivateBin templates we suggest using the `sons-of-obsidian` theme.
 
 The `syntaxhighlighting` option in the `[main]` section found in version 0.20 is deprecated and will no longer be required in version 0.21.
 
-### template
-
-PrivateBin template to use, default is `bootstrap`. The templates can be found in the folder `tpl/` and are saved as `html` files, i.e. `tpl/bootstrap.html`.
-
-### burnafterreadingselected
-
-Preselect the burn-after-reading feature by default, defaults to false.
-
-### expiration
-
-The `default` option in the `[expire]` section controls, which expire value is selected by default. Make sure the value exists in the section `[expire_options]`.
-
-Setting the `clone` option to false will hide the clone button in expiring pastes. Note that this only hides the button, simply copying the paste into a new one is still possible.
-
-In `[expire_options]` you can define the expiration options. These define the lifetime of a newly created paste in seconds. The `[expire_labels]` option found in version 0.20 is deprecated and will no longer be required in version 0.21, instead the labels are generated based on the keys in the `[expire_options]`.
-
-Using a value of 0 for the seconds means to never expire this post. Remove this line from the default configuration if you want to enforce that all pastes expire eventually in your system. But be aware that changing this setting only affects newly created pastes.
-
 ### sizelimit
 
 Size limit per paste and comment in bytes, defaults to 2 Mibibytes (2097152 bytes).
 
-### trafficlimit
+### template
 
-In the section `[traffic]` you can add a rate `limit` in seconds. This is the time limit between creating pastes or comments from the same IP address in seconds. Set this to 0 to disable rate limiting.
+PrivateBin template to use, the default one is `bootstrap`. The templates can be found in the folder `tpl/` and are saved as `php` files, i.e. `tpl/bootstrap.php`.
 
-If your site runs behind a reverse proxy or a load balancer, the traffic limiter will see its IP instead of the visitors. Therefore the traffic limit would be global and not per IP. You can set the HTTP `header` to use instead. In most cases this is "X_FORWARDED_FOR", but check your proxy settings to be sure.
+### notice
 
-Note that malicious visitors may set a different header in every request, so only enable this in a proxy installation and set it to the header you know your proxy sets or these visitors would circumvent the traffic limiter.
+This is an optional notice message displayed above the text input. Disabled by default.
-
-The option `dir` controls where the lock file is stored. Note that this directory needs to be writable for the process running PHP (i.e. your webserver, FPM or CGI process).
-
-### base64version
-
-The base64.js library version, defaults to `2.1.9`. Use `1.7` if you are upgrading from a PrivateBin Alpha 0.19 installation for compatibility with your existing pastes.
 
 ### languageselection / languagedefault
 
@@ -89,24 +75,51 @@ When `languageselection` is disabled and `languagedefault` is set, then the `lan
 `languageselection` | `languagedefault` | cookie  | behaviour
 --------------------|-------------------|---------|----------
 false               | not set           | not set | uses browser language, if possible
-false               | set, i.e. to "en" | set     | will always be in the `languagedefault` language
+false               | set, e.g. to "en" | set     | will always be in the `languagedefault` language
-true                | not set           | set     | uses browser language or the one last selected and stores it in the cookie
+true                | not set           | set     | uses browser language or the one last selected one stored in the cookie
-true                | set, i.e. to "fr" | set     | uses browser language or the one last selected and stores it in the cookie and uses "fr" as the fallback for unknown browser languages
+true                | set, e.g. to "fr" | set     | uses browser language or the one last selected and stored in the cookie and uses "fr" as the fallback for unknown browser languages
 
 ### urlshortener
 
-Optionally PrivateBin can offer a link to a URL shortener service after a new paste is created. It is strongly suggested to only use this with self-hosted shortener services as this will leak the pastes encryption key to the service entered here.
+Optionally PrivateBin can offer a link to a URL shortener service after a new paste is created. It is strongly suggested to only ever use this with self-hosted shortener services as this will leak the pastes encryption key to the service entered here.
 
-### vizhash
+Users are advised to _use a password_ when using a URL shortener so the paste can't be decrypted by third parties using the URL based key alone.
 
-PrivateBin creates avatars (with "visual hashes" = vizhashes) for users commenting on PrivateBins. These avatars are generated from the IP of the user commenting, which is a potential vulnerability, which may allow an attacker to guess the IP of the user, who published the comment. This issue has been found in a [security audit](https://defuse.ca/audits/zerobin.htm) (2.4.).
+### icon
-For privacy reason you can therefore disable this feature.
 
-#### zerobincompatibility
+PrivateBin creates avatars for users commenting with a nickname on pastes. These avatars are generated from the IP of the user commenting, which is a potential vulnerability, which may allow an attacker to guess the IP of the user, who published the comment. This issue has been found in a [security audit](https://defuse.ca/audits/zerobin.htm) (2.4.). For maximum security you can therefore disable this feature.
 
-This option as introduced with the name switch of ZeroBin to PrivateBin. By default it is disabled and therefore prevents the use of some depreciated, outdated features of PrivateBin, which were used in ZeroBin.
+The possible settings for this option are `identicon` (the default), `vizhash` and `none`. Classic ZeroBin always used `vizhash`. With release 1.0 we switched to the better supported `identicon` library.
-For full compatibility with ZeroBin, you can enable this option. However this is not recommend as it weakens the security of your PrivateBin instance.
+
-<!-- NOTE: Please add what happens when this option is disabled. (Cannot access old ZeroBins?) -->
+### cspheader
+
+The default [Content Security Policy](https://scotthelme.co.uk/content-security-policy-an-introduction/) header set here restricts the loading of most resources to the same domain. If you want to allow access of third-party scripts it is best to allow explicit access to those domains here. To disable all protection (not advised), you would set the header to just `default-src *;`.
+
+### zerobincompatibility
+
+This option as introduced with the name switch of ZeroBin to PrivateBin. By default it is disabled and therefore prevents the use of some depreciated, outdated features of PrivateBin, which were used in ZeroBin. For full compatibility with ZeroBin and to be able to decrypt old pastes, you would enable this option. However this is not recommend for new installations as it weakens the security of your PrivateBin instance.
+
+The `base64version` option in the `[main]` section found in version 0.20 to 0.22 is deprecated and is replaced by the simpler `zerobincompatibility`.
+
+### expiration
+
+The `default` option in the `[expire]` section controls, which expire value is selected by default. Make sure the value exists in the section `[expire_options]`.
+
+Setting the `clone` option to false will hide the clone button in expiring pastes. Note that this only hides the button, simply copying the paste into a new one is still possible.
+
+In `[expire_options]` you can define the expiration options. These define the lifetime of a newly created paste in seconds. The `[expire_labels]` option found in version 0.20 is deprecated and will no longer be required in version 0.21, instead the labels are generated based on the keys in the `[expire_options]`.
+
+Using a value of 0 for the seconds means to never expire this post. Remove this line from the default configuration if you want to enforce that all pastes expire eventually in your system. But be aware that changing this setting only affects newly created pastes.
+
+### trafficlimit
+
+In the section `[traffic]` you can add a rate `limit` in seconds. This is the time limit between creating pastes or comments from the same IP address in seconds. Set this to 0 to disable rate limiting.
+
+If your site runs behind a reverse proxy or a load balancer, the traffic limiter will see its IP instead of the visitors. Therefore the traffic limit would be global and not per IP. You can set the HTTP `header` to use instead. In most cases this is "X_FORWARDED_FOR", but check your proxy settings to be sure.
+
+Note that malicious visitors may set a different header in every request, so only enable this in a proxy installation and set it to the header you know your proxy sets or these visitors would circumvent the traffic limiter.
+
+The option `dir` controls where the lock file is stored. Note that this directory needs to be writable for the process running PHP (i.e. your webserver, FPM or CGI process).
 
 ### model