Starting from v0.0.6, Burp-UI supports Gunicorn in order to handle multiple users simultaneously because some operations (like the online restoration) may take some time and thus may block any further requests. With Gunicorn, you have several workers that can proceed the requests so you can handle more users.

You need to install gunicorn and gevent:

pip install "burp-ui[gunicorn]"

You will then be able to launch Burp-UI this way:

gunicorn -k gevent -w 4 'burpui:create_app(conf="/path/to/burpui.cfg")'


If you decide to use gunicorn AND the embedded websocket server, you’ll need to use the geventwebsocket.gunicorn.workers.GeventWebSocketWorker worker name (ie. -k geventwebsocket.gunicorn.workers.GeventWebSocketWorker). For this worker to be available, you need to install the gevent-websocket pip package.

This will listen to by default. See the gunicorn documentation for details.

You will need to add the -b option in order to listen on all interfaces on port 5000 for instance.

When using gunicorn, the command line options are not available. Instead, you run the Burp-UI create_app method directly. Here are the parameters you can play with:

  • conf: Path to the Burp-UI configuration file
  • verbose: Verbosity level between 0 and 4
  • logfile: Path to a logfile in order to log Burp-UI internal messages
  • reverse_proxy: Whether we are behind a reverse-proxy or not (defaults to True)


You MUST set the appsecret option in your configuration file when using gunicorn. The default magic value ‘random’ cannot be used. If you don’t change the settings the default value will be ‘none’ and your cookies won’t be secured.

Advanced usage

Gunicorn supports further settings (see its documentation for details). For instance, you would probably like to use the -c flag with the sample configuration file bundled with Burp-UI in contrib/gunicorn/

Usage example:

gunicorn -c 'burpui:create_app(conf="/etc/burp/burpui.cfg",logfile="/var/log/gunicorn/burp-ui_info.log")'


If you wish to run Burp-UI as a daemon process, the recommanded way is to use Gunicorn.


First of all, you’ll need a dedicated user.

# create the burpui user
useradd -m -r -d /var/lib/burpui -c 'Burp-UI daemon user' burpui
mkdir /etc/burp
# copy the burp-ui sample configuration file
cp /usr/local/share/burpui/etc/burpui.sample.cfg /etc/burp/burpui.cfg
mkdir -p /var/log/gunicorn
chown -R burpui: /var/log/gunicorn

You will also need a custom client configuration and you will have to create the certificates accordingly:

# create the configuration file used by burp-ui
cat >/var/lib/burpui/burp.conf<<EOF
mode = client
port = 4971
status_port = 4972
server =
password = abcdefgh
cname = bui-agent1
pidfile = /var/lib/burpui/
syslog = 0
stdout = 1
progress_counter = 1
ca_burp_ca = /usr/sbin/burp_ca
ca_csr_dir = /var/lib/burpui/CA-client
ssl_cert_ca = /var/lib/burpui/ssl_cert_ca-client.pem
ssl_cert = /var/lib/burpui/ssl_cert-client.pem
ssl_key = /var/lib/burpui/ssl_cert-client.key
ssl_peer_cn = burpserver
# generate the certificates
burp_ca --name bui-agent1 --ca burpCA --key --request --sign --batch
cp /etc/burp/ssl_cert_ca.pem /var/lib/burpui/ssl_cert_ca-client.pem
cp -a /etc/burp/CA/bui-agent1.crt /var/lib/burpui/ssl_cert-client.pem
cp -a /etc/burp/CA/bui-agent1.key /var/lib/burpui/ssl_cert-client.key
chown -R burpui: /var/lib/burpui/

Now you need to add the bui-agent1 client to the authorized clients:

echo "password = abcdefgh" >/etc/burp/clientconfdir/bui-agent1
echo "restore_client = bui-agent1" >>/etc/burp/burp-server.conf

You will also need to increase the number of status clients by setting max_status_children to 15:

echo "max_status_children = 15" >>/etc/burp/burp-server.conf

Finally, make sure you set bconfcli: /var/lib/burpui/burp.conf in your Burp-UI configuration file (/etc/burp/burpui.cfg).

If you want to take advantage of advanced features such as client add/removal and configuration files edition, you should set the permissions accordingly Burp-side.

First of all, add the following lines in your /etc/burp/burp-server.conf:

user = burpui
group = burpui

Then you need to fix some permissions:

chown -R burpui: /etc/burp/{burp-server.conf,burpui.cfg,CA,CA.cnf,clientconfdir,dhfile.pem,ssl_cert_ca.pem,ssl_cert-server.key,ssl_cert-server.pem} /var/spool/burp
chgrp burpui /etc/burp
chmod g+rwx /etc/burp

Finally you can restart your burp-server.


The above commands are meant for default setup. You may need to adapt the paths.


When installing the gunicorn package on debian, there is a handler script that is able to start several instances of Gunicorn as daemons.

All you need to do is installing the gunicorn package and adding a configuration file in /etc/gunicorn.d/.

There is a sample configuration file available here.

# install the gunicorn package
apt-get install gunicorn
# copy the gunicorn sample configuration
cp /usr/local/share/burpui/contrib/gunicorn.d/burp-ui /etc/gunicorn.d/
# now restart gunicorn
service gunicorn restart


If you are not running on debian or you prefer not to use the gunicorn debian package, the handler script may not be available. You will then have to create your own service. We can do this for systemd for example:

# copy the gunicorn configuration file
cp /usr/local/share/contrib/gunicorn/ /etc/burp/
# create the service file
cat >/etc/systemd/service/bui-gunicorn.service<<EOF
Description=Burp-UI gunicorn service

ExecStart=/usr/local/bin/gunicorn -c /etc/burp/ 'burpui:create_app(conf="/etc/burp/burpui.cfg",logfile="/var/log/gunicorn/burp-ui_info.log")'

# enable the new service
systemctl enable bui-gunicorn.service
# start the service
systemctl start bui-gunicorn.service


You may want to add a reverse-proxy so Burp-UI can be accessed on port 80 (or 443) along with other applications.

Here is a sample configuration for Nginx:

server {
    listen 80;

    access_log  /var/log/nginx/burpui.access.log;
    error_log   /var/log/nginx/burpui.error.log;

    location / {

        # you need to change this to "https", if you set "ssl" directive to "on"
        proxy_set_header   X-FORWARDED_PROTO http;
        proxy_set_header   Host              $http_host;
        proxy_set_header   X-Forwarded-For   $remote_addr;

        proxy_read_timeout 300;
        proxy_connect_timeout 300;

        proxy_pass http://localhost:5000;

Sub-root path

You can host Burp-UI behind a sub-root path. For instance /burpui. To accomplish this, you can either setup your reverse-proxy to announce the desired prefix, or you can use the prefix option in your Burp-UI configuration file (see usage for details).

If you want to configure this reverse-proxy side, you need to announce the HTTP Header X-Script-Name.

Here is a sample configuration for Nginx:

server {
    listen 80;

    access_log  /var/log/nginx/burpui.access.log;
    error_log   /var/log/nginx/burpui.error.log;

    location /burpui {

        # you need to change this to "https", if you set "ssl" directive to "on"
        proxy_set_header   X-FORWARDED_PROTO http;
        proxy_set_header   Host              $http_host;
        proxy_set_header   X-Forwarded-For   $remote_addr;
        # Our service is hosted behind the "/burpui" prefix
        proxy_set_header   X-Script-Name     /burpui;

        proxy_read_timeout 300;
        proxy_connect_timeout 300;

        proxy_pass http://localhost:5000;

Apache sample:

ProxyPass /burp/ http://localhost:5000/burp/
ProxyPassReverse /burp/ http://localhost:5000/burp/
<Location /burp/>
    SetOutputFilter proxy-html
    ProxyPassReverse /burp/
    ProxyHTMLURLMap  http://localhost:5000/     /
    Require all granted


If your prefix does not start with a ‘/’, it will be ignored.


We can consider the demo as a production example of what you can setup/expect in your environment. It is using Gunicorn along with Nginx as described above.

In order to improve performances, Redis can be used to cache sessions and various API calls. You can also enable the celery worker for asynchronous jobs. Additionally, you can enable the SQL storage.

The FAQ answers these questions:

See the production section of the usage page.