Commit c942d6bc authored by Ziirish's avatar Ziirish

doc: new websocket feature

parent 3b6f1159
......@@ -153,6 +153,40 @@ follow:
ratio = 60/minute
WebSocket
---------
The ``[WebSocket]`` section defines specific options for the WebSocket server.
You will find details on how to use this feature in the
`WebSocket <websocket.html>`_ page.
::
[WebSocket]
## This section contains WebSocket server specific options.
# whether to embed the websocket server or not
# if set to "true", you should have only *one* gunicorn worker
# see here for details:
# https://flask-socketio.readthedocs.io/en/latest/#gunicorn-web-server
embedded = false
# what broker to use to interact between websocket servers
# may be a redis url like: redis://localhost:6379/0
# if set to "true" or "redis" or "default", the url defaults to:
# redis://<redis_host>:<redis_port>/4
# where <redis_host> is the host part, and <redis_port> is the port part of
# the above "redis" setting
# set this to none to disable the broker
broker = redis
# if you choose to run a dedicated websocket server (with embedded = false)
# you can specify here the websocket url. You'll need to double quote your
# string though.
# example:
# url = "document.domain + ':5001'"
url = none
# whether to enable verbose websocket server logs or not (for development)
debug = false
Experimental
------------
......
......@@ -27,6 +27,7 @@ Documentation
advanced_usage
manage
celery
websocket
gunicorn
docker
buiagent
......
......@@ -59,14 +59,18 @@ The tool provides some inline help too:
--help Show this message and exit.
Commands:
compile_translation Compile translations.
compile_translation Compile translations.
create_user Create a new user.
db Perform database migrations.
diag Check Burp-UI is correctly setup.
init_translation Initialize a new translation for the given...
run Runs a development server.
legacy Legacy server for backward compatibility.
run Runs a local development server for the...
setup_burp Setup burp client for burp-ui.
shell Runs a shell in the app context.
sysinfo Returns a couple of system informations to...
update_translation Update translation files.
websocket Start a new websocket server.
Database
......@@ -193,11 +197,36 @@ The docker image uses this script like this:
-r $REDIS_SERVER -d $DATABASE_URL
WebSocket
---------
.. note::
This tool first appeared with `Burp-UI`_ *v0.6.0*.
Launch a dedicated websocket server so you can have more than one worker.
You may need a dedicated reverse-proxy though.
Example:
::
bui-manage websocket --help
Usage: flask websocket [OPTIONS]
Start a new websocket server.
Options:
-b, --bind TEXT Which address to bind to for the websocket server
-p, --port INTEGER Which port to listen on for the websocket server
-d, --debug Whether to start the websocket server in debug mode
--help Show this message and exit.
Sysinfo
-------
.. note::
This tool first appeard with `Burp-UI`_ *v0.5.0*.
This tool first appeared with `Burp-UI`_ *v0.5.0*.
This tool will help you to gather system informations in order to make a
detailed bug report.
......
......@@ -17,6 +17,7 @@ v0.6.0
granted on both clients on the two agents. You can disable this behavior with
the `legacy` option. See the `BASIC ACL <advanced_usage.html#basic-acl>`_
documentation for details.
- **New** - WebSocket support for better/smarter notifications.
v0.5.0
------
......
WebSocket
=========
Since *v0.6.0*, `Burp-UI`_ supports WebSockets for better/smarter notifications.
In order to use this feature, you need some extra requirements:
::
pip install "burp-ui[websocket]"
It is highly recommended to use a `Redis`_ *Broker* for the websocket server to
interact with the celery workers and other pieces of the code.
It is also advised to run one or several dedicated WebSocket servers behind a
reverse-proxy because *gunicorn* does not play well with it.
The details of the configuration may be found in the `WebSocket
<advanced_usage.html#websocket>`__ section.
Dedicated Server
----------------
You can choose to either run an embedded WebSocket server though this is not
recommended in production or you can run one or several dedicated WebSocket
servers through the ``bui-manage`` command like this:
::
bui-manage websocket --bind 0.0.0.0 --port 5001
If you are running the above command, you'll need to set the ``url`` option
under the ``[WebSocket]`` section to ``"document.domain + ':5001'"``.
.. warning:: The quotes are **MANDATORY** in this case.
Alternatively, you can setup a reverse-proxy as explained bellow.
.. note:: A systemd service example file is shiped in the *contrib* directory
Reverse-proxy
-------------
Running one or several dedicated WebSocket server is the recommended setup in
production.
You will find more details on this in the
`Flask-SocketIO <https://flask-socketio.readthedocs.io/en/latest/#deployment>`_
documentation.
Running a dedicated server on a dedicated port and/or IP may be a pain. That's
the reason why you can/should setup a reverse-proxy in front of this using a
configuration like:
::
server {
listen 80;
server_name _;
location / {
proxy_pass http://127.0.0.1:5000;
}
location /socket.io {
proxy_http_version 1.1;
proxy_buffering off;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_pass http://127.0.0.1:5001/socket.io;
}
}
If you ran several servers, you can use this config:
::
upstream socketio_nodes {
ip_hash;
server 127.0.0.1:5001;
server 127.0.0.1:5002;
# to scale the app, just add more nodes here!
}
server {
listen 80;
server_name _;
location / {
proxy_pass http://127.0.0.1:5000;
}
location /socket.io {
proxy_http_version 1.1;
proxy_buffering off;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_pass http://socketio_nodes/socket.io;
}
}
.. _Burp-UI: https://git.ziirish.me/ziirish/burp-ui
.. _Redis: http://redis.io/
......@@ -90,7 +90,16 @@ embedded = false
# redis://<redis_host>:<redis_port>/4
# where <redis_host> is the host part, and <redis_port> is the port part of
# the above "redis" setting
broker = none
# set this to none to disable the broker
broker = redis
# if you choose to run a dedicated websocket server (with embedded = false)
# you can specify here the websocket url. You'll need to double quote your
# string though.
# example:
# url = "document.domain + ':5001'"
url = none
# whether to enable verbose websocket server logs or not (for development)
debug = false
[Security]
## This section contains some security options. Make sure you understand the
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment