diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 45c0b9de..e557e182 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -174,7 +174,7 @@ Current - Fix: issue `#99 `_ - Fix: issue `#100 `_ - Fix: issue `#101 `_ -- `demo `_ +- `demo `_ - API refactoring - Security fixes - Bugfixes diff --git a/README.rst b/README.rst index f3d70e2d..cf7daaab 100644 --- a/README.rst +++ b/README.rst @@ -29,7 +29,8 @@ Demo A screenshot is worth a thousand words, but a Demo is worth a thousand screenshots. -You can now play with ``Burp-UI`` at `demo.ziirish.me `_ +You can now play with ``Burp-UI`` at +`demo.burp-ui.org `_ Credentials: @@ -60,20 +61,17 @@ Documentation ------------- The documentation is hosted on `readthedocs `_ at the -following address: `burp-ui.readthedocs.io -`_ +following address: `burp-ui.readthedocs.io`_ FAQ --- -A `FAQ `_ is available with -the documentation. +A `FAQ`_ is available with the documentation. Community --------- -Please refer to the `Contributing -`_ page. +Please refer to the `Contributing`_ page. Notes ----- @@ -83,10 +81,8 @@ Feel free to report any issues on my `gitlab I have closed the *github tracker* to have a unique tracker system. -Also please, read the `Contributing -`_ -page before reporting any issue to make sure we have all the informations to -help you. +Also please, read the `Contributing`_ page before reporting any issue to make +sure we have all the informations to help you. See also -------- @@ -142,3 +138,6 @@ would not exist without `Burp`_. .. _License: https://git.ziirish.me/ziirish/burp-ui/blob/master/LICENSE .. _Burp: http://burp.grke.org/ .. _burpui.cfg: https://git.ziirish.me/ziirish/burp-ui/blob/master/share/burpui/etc/burpui.sample.cfg +.. _burp-ui.readthedocs.io: https://burp-ui.readthedocs.io/en/latest/ +.. _FAQ: https://burp-ui.readthedocs.io/en/latest/faq.html +.. _Contributing: https://burp-ui.readthedocs.io/en/latest/contributing.html diff --git a/docs/faq.rst b/docs/faq.rst index 17e7ba94..db2b3b64 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -4,7 +4,7 @@ FAQ Is there a demo somewhere? -------------------------- -Yes, you can play with `Burp-UI`_ at `demo.ziirish.me`_. Credentials are: +Yes, you can play with `Burp-UI`_ at `demo.burp-ui.org`_. Credentials are: - *admin* / *admin* to play with `Burp-UI`_ as an administrator - *demo* / *demo* to play with `Burp-UI`_ as a regular user @@ -81,6 +81,9 @@ How can I start Burp-UI as a daemon? There are several *init scripts* provided by some users available `here `__. +.. note:: I do not (and cannot) support these scripts. Only the `Gunicorn`_ way + is supported. + The recommended way to run `Burp-UI`_ in production is to use `Gunicorn`_. You can refer to the `gunicorn `__ section of this documentation for more details. @@ -134,8 +137,18 @@ Why using SQL? -------------- The SQL database is currently used to keep a track of several meta-data. +Since *v0.5.0*, the SQL database is able to store user preferences. Again, it is totally optional to use it. +Why using Celery? +----------------- + +Celery is used to run some asynchronous jobs such as reports computations or +online restorations. + +Computing reports asynchronously allows faster answer especially when you manage +several dozens of clients. + Burp-UI does not seem to understand the *bind* and *port* options anymore, what should I do? -------------------------------------------------------------------------------------------- @@ -160,6 +173,16 @@ section. Alternatively, you can choose an other compression module by selecting an other extension while proceeding the restoration. +I see a lot of *cannot spawn burp process* errors, what can I do? +----------------------------------------------------------------- + +This error means `Burp-UI`_ is not able to communicate with the burp server. +You should check your logs (both `Burp-UI`_'s and burp server's) to understand +what is wrong. +If you are using `Gunicorn`_, it is possible you reached the limit of *status +children*. You can safely increase the ``max_status_children`` setting in your +*burp-server.conf* file to 15 (the default is 5). + How can I contribute? --------------------- @@ -172,4 +195,4 @@ documentation. .. _Burp-UI: https://git.ziirish.me/ziirish/burp-ui .. _Gunicorn: http://gunicorn.org/ .. _README: https://git.ziirish.me/ziirish/burp-ui/blob/master/README.rst -.. _demo.ziirish.me: https://demo.ziirish.me/ +.. _demo.burp-ui.org: https://demo.burp-ui.org/ diff --git a/docs/gunicorn.rst b/docs/gunicorn.rst index 32932e71..9d07075f 100644 --- a/docs/gunicorn.rst +++ b/docs/gunicorn.rst @@ -20,9 +20,16 @@ You will then be able to launch `Burp-UI`_ this way: gunicorn -k gevent -w 4 'burpui:create_app(conf="/path/to/burpui.cfg")' +This will listen to 127.0.0.1:8000 by default. See the ``gunicorn`` +`documentation `__ for +details. + +You will need to add the ``-b 0.0.0.0:5000`` option in order to listen on all +interfaces on port 5000 for instance. + When using ``gunicorn``, the command line options are not available. Instead, -run the `Burp-UI`_ ``create_app`` method directly. Here are the parameters you -can play with: +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 @@ -40,7 +47,7 @@ Advanced usage -------------- `Gunicorn`_ supports further settings (see its `documentation -`_ for details). +`__ 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/burpui_gunicorn.py*. @@ -113,6 +120,14 @@ Now you need to add the *bui-agent1* client to the authorized clients: 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*). @@ -293,11 +308,20 @@ 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: + +- `Why using redis? `_ +- `Why using SQL? `_ +- `Why using Celery? `_ + See the `production `_ section of the `usage `_ page. .. _Gunicorn: http://gunicorn.org/ .. _Burp-UI: https://git.ziirish.me/ziirish/burp-ui -.. _demo: https://demo.ziirish.me/ +.. _demo: https://demo.burp-ui.org/ .. _Redis: http://redis.io/ diff --git a/docs/running.rst b/docs/running.rst index 865af470..b75f16b2 100644 --- a/docs/running.rst +++ b/docs/running.rst @@ -6,7 +6,7 @@ Flask's `development server `_ or you can use any of the `deployement options `_ provided by Flask. -.. note:: I personaly focus on ``gunicorn`` support for production deployments +.. note:: I personally focus on ``gunicorn`` support for production deployments Sandboxing diff --git a/docs/step-by-step.rst b/docs/step-by-step.rst index b3b01091..dcaa9957 100644 --- a/docs/step-by-step.rst +++ b/docs/step-by-step.rst @@ -16,7 +16,6 @@ describe the steps to setup your server from Scratch. 1. `Burp1 server`_ with `Burp-UI`_ 2. `Burp2 server`_ with `Burp-UI`_ -3. `Multiple servers`_ with `bui-agents `_ Burp1 server