Configuration

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 nine sections: [main], [expire], [expire_options], [formatter_options], [traffic], [purge], [model], [model_options] and [yourls].

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.

basepath

The full URL, with the domain name and directories that point to the PrivateBin files. For example, if your instance is accessed at https://privatebin.example.com/ or https://example.com/privatebin/ that is what you'd have to set it to.

The instance will work without this setting, but it is required to allow Opengraph images to be displayed on social networks, when a link is shared on such a site.

discussion / opendiscussion / discussiondatedisplay

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.

The discussiondatedisplay flag allows to disable the display of dates & times in the comments of discussions, defaults to false. Note that internally the creation time will still get tracked in order to sort the comments by creation time, but you can choose not to display them to allow your commenters some additional privacy.

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 10 Mibibytes (10485760 bytes).

Note: Remember that both PHP and the webserver must be configured, so uploads of the requested size are possible. Adjust upload_max_filesize, post_max_size and memory_limit (it should be set 2x value of upload_max_filesize to process received data!) in the php.ini if needed. PrivateBin includes displaying an error message, when the size is too large, but when the size is larger than the limits configured in the PHP or the webserver it won't reach the PHP code and you get a generic error 500 from the webserver instead:

  ┌──────────────┐
  │ POST request │
  └──────┬───────┘
         │
   ┌─────▼──────┐
   │ webserver  │
   │ POST limit ├─────────────────┐
   └─────┬──────┘      ┌──────────▼─────────────┐
         │             │ HTTP response code 500 │
   ┌─────▼───────┐     └──────────▲─────────────┘
   │ PHP request ├────────────────┘
   │    limit    │
   └─────┬───────┘
         │
   ┌─────▼──────┐
   │ PrivateBin │
   │ size limit ├──────────────────┐
   └─────┬──────┘      ┌───────────▼───────────────┐
         │             │ message "Paste is limited │
┌────────▼──────────┐  │ to %s of encrypted data." │
│ upload successful │  └───────────────────────────┘
└───────────────────┘

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.

The URL shortener integration now works in following way once you set the urlshortener value in conf.php:

Assume the value set in urlshortener looks like https://example.com/rest/v1/short-urls/shorten?apiKey=00000-0000-0000-0000000&format=txt&longUrl=, a CORS GET request without referrer will be send from within browser when user click on url shortener button as https://example.com/rest/v1/short-urls/shorten?apiKey=00000-0000-0000-0000000&format=txt&longUrl=https://privatebin.net/?2fd4f1f9d591a587#AHHhtSykTTTeLEsdeKoKsnwFzvnU7UPDLzjQGaoEene7

• When external URL shortener support CORS, the URL shortener is expected to immediately process the request and replace the URL displayed, this will allow seamless integration with bit.ly(before their V3 API deprecated on March 1, 2020) or self hosted solutions such as YOURLS, Polr or Shlink. The response doesn't have to be plain text, it can also be json, PrivateBin will automatically find url alike values and extract the shortest one.

• When external URL shortener doesn't support CORS or cannot be reached directly, it will open the link pointing to the URL shortener in new browser tab/window.

1. For YOURLS, the configured value of urlshortener should be formated like following:

https://yourls.org/yourls-api.php?username=admin&password=pass&action=shorturl&format=json&url=

or

https://yourls.org/yourls-api.php?signature=1002a612b4&action=shorturl&format=json&url=

2. For Shlink, the configured value of urlshortener should be formated like following:

https://shlink.io/rest/v1/short-urls/shorten?apiKey=00000-0000-0000-0000000&format=txt&longUrl=

3. For Polr, the configured value of urlshortener should be formated like following:

https://polrproject.org/api/v2/action/shorten?key=12345&response_type=json&url=

4. For Bit.ly(API V3 will be deactivated on March 1, 2020), the configured value of urlshortener should be formated like following:

https://api-ssl.bitly.com/v3/shorten?access_token=12345&longUrl=

You must enable CORS support if you choose self hosted solution. Taking Nginx as an example, this can be done by setting a header in PHP-related fields in YOURLS' Nginx conf, like this:

location ~ \.php$ {
    add_header Access-Control-Allow-Origin "https://your.privatebin.domain" always;
}

The equivalent for Apache, in .htaccess, is:

<IfModule mod_headers.c>
   <FilesMatch "\.php$">
      Header set Access-Control-Allow-Origin "https://your.privatebin.domain"
   </FilesMatch>
</IfModule>

The value of urlshortener will be accessible within PrivateBin users' browser, handle with caution.

yourls

When using YOURLS as a "urlshortener" config item:

• By default, urlshortener will point to the YOURLS API URL, with or without credentials, and will be visible in public on the PrivateBin web page. Only use this if you allow short URL creation without credentials.
• Alternatively, using the parameters in this section (signature and apiurl), urlshortener needs to point to the base URL of your PrivateBin instance with ?shortenviayourls&link= appended. For example: urlshortener = "${basepath}?shortenviayourls&link=" This URL will in turn call YOURLS on the server side, using the URL from apiurl and the "access signature" from the signature parameters below.

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), "jdenticon", "vizhash" and "none". Classic ZeroBin always used vizhash. With release 1.0 we switched to the better supported identicon library.

Important: When setting this option to "none", make sure the string is quoted as otherwise it will be interpreted as False and therefore reset to the default value.

cspheader

The default Content Security Policy header set here restricts the loading of most additional 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 *;.

Notes:

• If you use a bootstrap theme, you can remove the allow-popups from the sandbox restrictions.
• By default this disallows to load images from third-party servers, e.g. when they are embedded in pastes. If you wish to allow that, you can adjust the policy here. See the FAQ for details.
• The unsafe-eval is used in two cases; to check if the browser supports async functions and display an error if not and for Chrome to enable webassembly support (used for zlib compression). You can remove it if Chrome doesn't need to be supported and old browsers don't need to be warned.

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 deprecated, 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.

NOTE: the community has developed patches for old ZeroBin to turn it into readonly mode. This is a better alternative to enabling this option, as you then can start a new fresh instance of PrivateBin.

httpwarning

By default, PrivateBin displays a warning when it is accessed over an insecure URL. Usually, this includes HTTP URLs, but we e.g. try to consider .onion URLs or local dev setups (localhost etc.) secure too. The exact behaviour, however, depends on your browser.

For more information see this FAQ entry. It is not recommend to disable this warning/setting, as a secure connection is required for a secure instance of PrivateBin.

compression

By default PrivateBin will compress pastes and comments using the deflate algorithm (using "zlib") before encrypting them. Optionally this can be turned off, if you have security concern about this or if you intend to mostly store already compressed file attachments like PNG and JPEG images or office documents (using "none").

Important: When setting this option to "none", make sure the string is quoted as otherwise it will be interpreted as False and therefore reset to the default value.

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.

Viewing pastes is not affected by this limit. If you want to rate limit both views and paste creation and commenting, we recommend to use your webserver's features or the use of an application firewall solution.

There are two optional settings that both accept a comma separated list of IP addresses (IPv4 or IPv6) or subnets in CIDR notation. Both of these will ignore invalid IPs and when left unset, will remain disabled:

• exempted: IPs and subnets which are exempted from the traffic limit and can create pastes and comments as quickly as they like. Other visitors are still subject to the limit in seconds.
• creators: IPs and subnets that are the only ones allowed to create pastes or comments, without any rate limit. Other visitors are not allowed to create pastes or comment in discussions. When using this, the limit setting is ignored and no records of the creators need to be persisted.

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.

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.