diff --git a/README.md b/README.md index 085e9c9..db32ae0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Burp in Docker +# Burp Backup in Docker -This repo contains Docker images with [burp 2.x](http://burp.grke.org/) server, client and a [web ui](https://git.ziirish.me/ziirish/burp-ui). All images are available at Docker Hub: +This repository contains Docker images for the [Burp 2.x](http://burp.grke.org/) server, client, and [web UI](https://git.ziirish.me/ziirish/burp-ui). All images are available at Docker Hub: https://hub.docker.com/r/pschiffe/burp-server/ @@ -14,23 +14,23 @@ https://hub.docker.com/r/pschiffe/burp-ui/ https://hub.docker.com/r/pschiffe/burp-server/ -Burp server image with optional encryption, secure rsync to remote location and a [bui-agent](https://burp-ui.readthedocs.io/en/latest/buiagent.html) (for web ui). +The Burp server image includes optional encryption, secure rsync to a remote location, and a [bui-agent](https://burp-ui.readthedocs.io/en/latest/buiagent.html) for the web UI. ### Persistent data -The container uses two persistent volumes - `/etc/burp` for configuration and `/var/spool/burp` for storing backups. +The container utilizes two persistent volumes: `/etc/burp` for configuration files and `/var/spool/burp` for storing backups. -### Sytemd +### Systemd -Systemd is used to manage multiple processes inside of the container, so a couple of special requirements are needed when running it: `/run` and `/tmp` must be mounted on tmpfs, and (sadly) container must be running as privileged for now. Example Docker run bit when running on Red Hat based distro: `--tmpfs /run --tmpfs /tmp --privileged` +Systemd is used to manage multiple processes within the container. This requires `/run` and `/tmp` to be mounted on `tmpfs`, and currently, the container must run with privileged access. Example Docker run bit when running on Red Hat based distro: `--tmpfs /run --tmpfs /tmp --privileged` If you are using SELinux on the host, you need to enable the `container_manage_cgroup` variable with `setsebool -P container_manage_cgroup 1`. -Besides that, if you want to see the logs with `docker logs` command, allocate tty for the container with `-t, --tty` option. +Additionally, if you want to see the logs with the `docker logs` command, allocate a tty for the container with the `-t, --tty` option. ### Adding clients -The client configuration can be automatically pre-created on server with `BURP_CLIENTS_CONFIG` env var. The format of this variable is: `'client1-hostname:client1-password client2-hostname:client2-password ...'` +The client configuration can be automatically generated on the server using the `BURP_CLIENTS_CONFIG` environment variable. The format of this variable is: `'client1-hostname:client1-password client2-hostname:client2-password ...'` ### Example @@ -45,11 +45,11 @@ docker run -dt -p 4971:4971 --name burp-server \ ### Encryption -It's possible to encrypt backed up data with `encfs`. To use it, simply provide encryption password in `ENCRYPT_PASSWORD` env var. Because of the encfs fuse fs, you need to expose the `/dev/fuse` to the container with `--device /dev/fuse`, provide additional capability and possibly disable selinux (or apparmor) confinement with `--cap-add SYS_ADMIN --security-opt label:disable`. +You can encrypt backup data using `EncFS`. To use it, simply provide encryption password in `ENCRYPT_PASSWORD` env var. Because the EncFS is fuse fs, you need to expose the `/dev/fuse` to the container with `--device /dev/fuse`, provide additional capability and possibly disable selinux (or apparmor) confinement with `--cap-add SYS_ADMIN --security-opt label:disable`. ### Rsync to remote location -If you want to regularly sync your backed up data to a remote location, you can use the built-in support for rsync. With `RSYNC_DEST` env var specify remote location in format `rsync://user@server/path`. Password for rsync user can be provided in `RSYNC_PASS` env var. If the remote location provides rsync secured with stunnel, you can use that as well. Specify remote server and port in `STUNNEL_RSYNC_HOST` env var in format `server:port` and then, change the server part of the `RSYNC_DEST` to `localhost`, as in `rsync://user@localhost/path`. +To regularly synchronize your backup data with a remote location, you can utilize the built-in Rsync support. With `RSYNC_DEST` env var specify remote location in format `rsync://user@server/path`. Password for rsync user can be provided in `RSYNC_PASS` env var. If the remote location provides rsync secured with stunnel, you can use that as well. Specify remote server and port in `STUNNEL_RSYNC_HOST` env var in format `server:port` and then, change the server part of the `RSYNC_DEST` to `localhost`, as in `rsync://user@localhost/path`. If at least `RSYNC_DEST` env var is set, timer script in the container will try to rsync the local data to the remote location at around 6 AM every morning (this can be modified in `/etc/systemd/system/rsync-sync.timer` file). @@ -61,7 +61,7 @@ And that's not all, there is one more feature - if you set `RESTORE_FROM_RSYNC` https://hub.docker.com/r/pschiffe/burp-ui/ -Burp UI image contains awesome [web ui for Burp created by Ziirish](https://git.ziirish.me/ziirish/burp-ui). If running this container on the same host as the Burp server, you can just link this container to the Burp server with alias `burp` and more or less that's it. The web service is listening on port `5000`. If you want to manage Burp server on a different host, at first you need to specify `BUI_AGENT_PASSWORD` env var and expose port `10000` of **burp-server** container, then you need to manually edit the `/etc/burp/burpui.cfg.tpl` file in the burp-ui container and add the new `[Agent:name]` section to it. Be sure to update the template file `burpui.cfg.tpl` as the `burpui.cfg` file is overwritten every time the container starts. +The Burp UI image contains an awesome [web UI for Burp created by Ziirish](https://git.ziirish.me/ziirish/burp-ui). If you're running this container on the same host as the Burp server, you can link this container to the Burp server using the alias `burp`. This is essentially all you need to do. The web service is listening on port `5000`. If you want to manage the Burp server on a different host, you first need to specify the `BUI_AGENT_PASSWORD` environment variable and expose port `10000` of the **burp-server** container. Then, you need to manually edit the `/etc/burp/burpui.cfg.tpl` file in the burp-ui container and add a new `[Agent:name]` section to it. Be sure to update the template file `burpui.cfg.tpl` as the `burpui.cfg` file is overwritten every time the container starts. ### Persistent data @@ -82,7 +82,7 @@ docker run -d -p 5000:5000 --name burp-ui \ https://hub.docker.com/r/pschiffe/burp-client/ -To backup data and send them to the Burp server, you need Burp client. Usage of this image is pretty simple. With `BURP_SERVER` and `BURP_SERVER_PORT` env vars you can specify an address and port of the Burp server, client password goes in `BURP_CLIENT_PASSWORD` env var and everything you need to backup just mount to `/tobackup` directory in the container. Be aware, however, that you might need to use the `--security-opt label:disable` option when accessing various system directories on the host. It's also possible to link to Burp server container with alias `burp` and I would recommend setting the container hostname to something meaningful, as the client will be identified with its hostname in the Burp server configuration. +To back up data and send it to the Burp server, you need the Burp client. Usage of this image is pretty simple. With the `BURP_SERVER` and `BURP_SERVER_PORT` environment variables, you can specify the address and port of the Burp server. The client password goes in the `BURP_CLIENT_PASSWORD` environment variable, and everything you need to back up should be mounted to the `/tobackup` directory in the container. Be aware, however, that you might need to use the `--security-opt label:disable` option when accessing various system directories on the host. It's also possible to link the client to the Burp server container with the alias `burp`. I recommend setting the container hostname to something meaningful, as the client will be identified by its hostname in the Burp server configuration. ### Persistent data @@ -103,15 +103,11 @@ docker run -d --name burp-client \ pschiffe/burp-client ``` -Once this container is created, it will backup the specified data and exit. After that, it's recommended to start the container ~ every 20 minutes with `docker start burp-client`, so it can check with the server and backup new files if scheduled. The schedule is determined by the server, not the client. +Once this container is started, it backs up the specified data and exits. After that, I recommend starting the container approximately every 20 minutes using `docker start burp-client`. This allows the container to check with the server and back up new files if scheduled. Please note that the backup schedule is determined by the server, not the client. ### Data recovery -You may also use it to recover data from a distant server. -You just have to provide arguments as you would to a regular burp client CLI. - -for example: - +You can also use this container to recover data from a remote server. You simply need to provide arguments in the same way you would for a regular Burp client CLI, for example: ``` docker run -d --name burp-client \ -e BURP_SERVER=some-server.host \