PrivateBin comes with a configuration file to enable/disable features, change themes, etc.
Structure
You find an example configuration file at cfg/conf.sample.php with the default settings. If you want to change these, copy the sample file to cfg/conf.php 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 ]) and the option keys are separated by the values with equal signs (=).
By default there are eight sections: [main], [expire], [expire_options], [formatter_options], [traffic], [purge], [model] and [model_options].
Options
name
The name option allows you to replace the default "PrivateBin" title on the website and in messages with something your own name.
If no name is set, the built in "PrivateBin" title will be used.
discussion / opendiscussion
The discussion option enables or disables the discussion feature, defaults to true.
If disabled users can't create new pastes with discussions or post replies to existing pastes with discussions. Already existing discussions will remain visible.
The opendiscussion flag allows to preselect the discussion option, defaults to false.
password
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 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.
The order of the options in this section is preserved in the display of the drop down and the labels can be adjusted. Don't forget to add any newly added or changed labels to the translation files in the i18n directory.
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 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.
sizelimit
Size limit per paste and comment in bytes, defaults to 2 Mibibytes (2097152 bytes).
template
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.
Currently supported templates are (Preview):
- bootstrap
- bootstrap-page
- bootstrap-dark
- bootstrap-dark-page
- bootstrap-compact
- bootstrap-compact-page
- page
notice
This is an optional notice message displayed above the text input. Disabled by default.
languageselection / languagedefault
By default PrivateBin tries to detect the browser language of the visitors if such a HTTP header is sent and falls back to English language or to the one selected in languagedefault, if no such header is present or no matching translation was found.
Optionally languageselection enables drop down can be enabled. It is disabled by default, as it makes use of a session cookie named "lang" to persist the selected language between calls. It is deleted when the browser is closed.
When languageselection is disabled and languagedefault is set, then the languagedefault will be the only language used and this will be communicated to the browser via the session cookie named "lang". Here is a matrix of the possible effects of the language configurations:
languageselection |
languagedefault |
cookie | behaviour |
|---|---|---|---|
| false | not set | not set | uses browser language, if possible |
| 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 one stored in the cookie |
| 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 ever use this with self-hosted shortener services as this will leak the pastes encryption key to the service entered here.
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.
icon
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 (2.4.). For maximum security you can therefore disable this feature.
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.
cspheader
The default Content Security Policy 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 that systems IP instead of the visitors IP. 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 overrides or such visitors could 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).
purge
The section [purge] controls how frequently the system should look for expired pastes to remove. If an expired paste is accessed it will be immediately deleted, but if nobody accesses it any more the purge will eventually find and remove it.
As this operation can take a bit of time it is only done when a paste is created and not more frequently then the time in seconds given in the limit option. It defaults to running the purge at most once every 5 minutes.
To further reduce the delay caused by the purge, not more then batchsize pastes are purged at once.
It is suggested to only adjust the limit down if your installation has many users and the automatic purge isn't able to keep up with the expiration, when only a maximum of 10 pastes per 5 minutes are purged. On systems storing their data in a database instead of the filesystem (see model section below) the batchsize can safely be increased to 100 or more. The filesystem data structure is not optimized for searching, hence in that case even finding up to 10 pastes to delete can take a couple of seconds, as it needs to randomly open pastes to check their expiration time. In the database this is done with a single, simple query.
model
The sections [model] and [model_options] control how your pastes are stored. Currently PrivateBin stores its pastes as flat files by default ([model] section, class = Filesystem) and the option dir in the section [model_options] tells it in what folder to store them. Note that this directory needs to be writable for the process running PHP (i.e. your webserver, FPM or CGI process).
Alternatively you can store the pastes in a relational database ([model] section, class = Database). This is tested with MySQL, PostgreSQL and SQLite and examples for these MySQL and SQLite databases are provided in commented form. A more detailed explanation of the database feature can be found in the installation instructions.