improve overall documentation

parent 21b116ff
......@@ -22,6 +22,9 @@ indent_size = 4
[Makefile]
indent_style = tab
[*.rst]
indent_style = space
indent_size = 4
[.gitlab-ci.yml}]
indent_style = space
......
......@@ -10,9 +10,14 @@ Current
- Add percent done in `overview <https://git.ziirish.me/ziirish/burp-ui/issues/55>`_
- Add the ability to `chain multiple authentication backends <https://git.ziirish.me/ziirish/burp-ui/issues/79>`_
- Add display versions `within the interface <https://git.ziirish.me/ziirish/burp-ui/issues/89>`_
- Add support for `zip64 <https://git.ziirish.me/ziirish/burp-ui/issues/97>`_
- Add Basic HTTP Authentication
- Add full documented API
- Fix issue `#81 <https://git.ziirish.me/ziirish/burp-ui/issues/81>`_
- Fix issue `#87 <https://git.ziirish.me/ziirish/burp-ui/issues/87>`_
- Fix issue `#88 <https://git.ziirish.me/ziirish/burp-ui/issues/88>`_
- Fix issue `#92 <https://git.ziirish.me/ziirish/burp-ui/issues/92>`_
- Fix issue `#95 <https://git.ziirish.me/ziirish/burp-ui/issues/95>`_
- `demo <https://demo.ziirish.me/>`_
- API refactoring
- Security fixes
......
......@@ -68,6 +68,17 @@ The architecture is described bellow:
+--------------------+
Requirements
------------
The agent is powered by gevent. In order to install it, you can run the
following command:
::
pip install "burp-ui[agent]"
Configuration
-------------
......@@ -122,13 +133,13 @@ Here is a full usage example:
::
# On the server called 'agent1'
agent1:~$ python path/to/bui-agent -c path/to/buiagent.cfg
agent1:~$ bui-agent -c path/to/buiagent.cfg
# On the server called 'agent2'
agent2:~$ python path/to/bui-agent -c path/to/buiagent.cfg
agent2:~$ bui-agent -c path/to/buiagent.cfg
# On the server called 'front'
front:~$ python path/to/burp-ui -c path/to/burpui.cfg
front:~$ burp-ui -c path/to/burpui.cfg
This example uses three servers. You then only need to point your browser to
......
......@@ -52,7 +52,7 @@ master_doc = 'index'
# General information about the project.
project = u'Burp-UI'
copyright = u'2015, Ziirish'
copyright = u'2016, Ziirish'
author = u'Ziirish'
# The version info for the project you're documenting, acts as replacement for
......@@ -213,7 +213,7 @@ html_logo = '_static/logo.png'
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'Burp-UIdoc'
htmlhelp_basename = 'Burp-UI doc'
# -- Options for LaTeX output ---------------------------------------------
......@@ -280,7 +280,7 @@ man_pages = [
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'Burp-UI', u'Burp-UI Documentation',
author, 'Burp-UI', 'One line description of project.',
author, 'Burp-UI', 'Burp-UI is a web-ui for burp backup written in python with Flask and jQuery/Bootstrap.',
'Miscellaneous'),
]
......
......@@ -27,6 +27,7 @@ Documentation
contributing
changelog
faq
step-by-step
developer
......
......@@ -27,8 +27,8 @@ By default `Burp-UI`_ ships with a sample file located in
virtualenv)
.. note::
It is advised to copy the sample configuration in ``/etc/burp/burpui.cfg``
and to edit this file so that it is not overwritten on every upgrade.
It is advised to copy the sample configuration in ``/etc/burp/burpui.cfg``
and to edit this file so that it is not overwritten on every upgrade.
Then you can run ``burp-ui``: ``burp-ui``
......
......@@ -9,13 +9,21 @@ The project also provides a full documented `API <api.html>`_ so that you can
develop any front-end you like on top of it. The core will take care of the
communication with the burp server(s) for you.
.. note::
Although the `Burp`_'s author and I exchange a lot, our products are totally
distinct. So I would like people to understand some issues might be related
to `Burp-UI`_, but some other might be related to `Burp`_ and I may not be
able to help you in the later case.
There is a dedicated mailing-list for `Burp`_ related issues. You can find
details `here <http://burp.grke.org/contact.html>`_
Known Issues
------------
Because it's an Open Source project, people are free (and encouraged) to open
issues in the `bug-tracker <https://git.ziirish.me/ziirish/burp-ui/issues>`_.
You will find there the current opened issues.
issues in the `bug-tracker <https://git.ziirish.me/ziirish/burp-ui/issues>`_
where will find there the current opened issues.
There are also a few issues unrelated to the code itself:
......
......@@ -4,6 +4,10 @@ Requirements
Please note that, `Burp-UI`_ must be running on the same server that runs the
burp-server for some features.
.. note::
At the moment, `Burp-UI`_ and this doc is mostly debian-centric but feel
free to contribute for other distributions!
LDAP
----
......@@ -27,10 +31,29 @@ On Debian:
aptitude install python-openssl
Alternatively, you can install the python package using the following command:
::
pip install "burp-ui[ssl]"
Burp1
-----
The `burp1 backend <usage.html#burp1>`__ supports burp versions from 1.3.48 to
1.4.40.
With these versions of burp, the status port is only listening on the machine
loopback (ie. ``localhost`` or ``127.0.0.1``). It means you *MUST* run
`Burp-UI`_ on the same host that is running your burp server in order to be able
to access burp's statistics.
Alternatively, you can use a `bui-agent <buiagent.html>`__.
Burp2
-----
The `burp2 backend <usage.html#burp2>`_ supports only burp 2.0.18 and above.
The `burp2 backend <usage.html#burp2>`__ supports only burp 2.0.18 and above.
If you are using an older version of burp2 `Burp-UI`_ will fail to start.
.. _Burp-UI: https://git.ziirish.me/ziirish/burp-ui
......@@ -4,24 +4,27 @@ Usage
`Burp-UI`_ has been written with modularity in mind. The aim is to support
`Burp`_ from the stable to the latest versions. `Burp`_ exists in two major
versions: 1.x.x and 2.x.x.
The version 2.x.x is currently in heavy development and should bring a lot of
improvements, but also a lot of rework especially regarding the ``status port``
which is the main communication system between `Burp`_ and `Burp-UI`_.
.. note::
The version 2.x.x of `Burp`_ is currently in heavy development and should
bring a lot of improvements, but also a lot of rework especially regarding
the ``status port`` which is the main communication system between `Burp`_
and `Burp-UI`_.
Both `Versions`_ are supported by `Burp-UI`_ thanks to its modular design.
The consequence is you have various options in the configuration file to suite
every bodies needs.
everybody needs.
There are also different modules to support `Authentication`_ and `ACL`_ within
the web-interface.
.. warning::
`Burp-UI`_ tries to be the less intrusive as possible, nevertheless it ships
with the ability to manage `Burp`_'s configuration files.
This feature **requires** `Burp-UI`_ to be launched on the **same** server
that hosts your `Burp`_ instance.
You also have to make sure the user that runs `Burp-UI`_ has **enough**
privileges to edit those files.
`Burp-UI`_ tries to be as less intrusive as possible, nevertheless it ships
with the ability to manage `Burp`_'s configuration files.
This feature **requires** `Burp-UI`_ to be launched on the **same** server
that hosts your `Burp`_ instance.
You also have to make sure the user that runs `Burp-UI`_ has **enough**
privileges to edit those files.
Configuration
......@@ -215,13 +218,19 @@ Versions
These backends allow you to either connect to a `Burp`_ server version 1.x.x or
2.x.x.
If you are using a `Burp`_ server version 2.x.x you **have** to use the `Burp2`_
backend, no matter what `Burp`_'s protocol you are using.
.. note::
If you are using a `Burp`_ server version 2.x.x you **have** to use the
`Burp2`_ backend, no matter what `Burp`_'s protocol you are using.
Burp1
^^^^^
.. note::
Make sure you have read and understood the `requirements
<requirements.html#burp1>`__ first.
The *burp-1* backend can be enabled by setting the *version* option to *1* in
the ``[Global]`` section of your `burpui.cfg`_ file:
......@@ -269,6 +278,10 @@ Each option is commented, but here is a more detailed documentation:
Burp2
^^^^^
.. note::
Make sure you have read and understood the `requirements
<requirements.html#burp2>`__ first.
The *burp-2* backend can be enabled by setting the *version* option to *2* in
the ``[Global]`` section of your `burpui.cfg`_ file:
......@@ -332,9 +345,9 @@ LDAP
^^^^
The *ldap* authentication backend has some dependencies, please refer to the
`requirements <requirements.html>`_ page. To enable this backend, you need to
set the *auth* option of the ``[Global]`` section of your `burpui.cfg`_ file to
*ldap*:
`requirements <requirements.html#ldap>`_ page. To enable this backend, you need
to set the *auth* option of the ``[Global]`` section of your `burpui.cfg`_ file
to *ldap*:
::
......@@ -413,7 +426,9 @@ Now you can add *basic* specific options:
user1: otherpassword
.. note:: Each line defines a new user with the *key* as the username and the *value* as the password
.. note::
Each line defines a new user with the *key* as the username and the *value*
as the password
ACL
......
......@@ -190,7 +190,7 @@ setup(
author=author,
author_email=author_email,
url=url,
keywords='burp web ui',
keywords='burp web ui backup monitoring',
packages=find_packages(),
include_package_data=True,
package_data={
......@@ -213,10 +213,12 @@ setup(
],
install_requires=requires,
extras_require={
'ssl': ['pyOpenSSL'],
'ldap_authentication': ['ldap3'],
'extra': ['ujson'],
'gunicorn': ['gevent'],
'gunicorn-extra': ['redis', 'Flask-Session'],
'agent': ['gevent'],
'test': test_requires,
'dev': dev_requires,
},
......
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