From dbf002296b27ac88c3c7cabd4017799427232ef0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20B=C5=93sch?= Date: Fri, 27 Aug 2021 12:59:39 +0200 Subject: [PATCH 1/4] README: set language for command block quotes Better semantic, allowing syntax coloring when appropriate (such as strings argument in case of sh). --- README.md | 82 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 51 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 89806a7..b908762 100644 --- a/README.md +++ b/README.md @@ -29,50 +29,60 @@ a usable container. To build the binary along with the container run: - docker build -t restic/rest-server:latest . +```sh +docker build -t restic/rest-server:latest . +``` ### Pull image - docker pull restic/rest-server +```sh +docker pull restic/rest-server +``` ## Usage To learn how to use restic backup client with REST backend, please consult [restic manual](https://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html#rest-server). - $ rest-server --help +```console +$ rest-server --help - Run a REST server for use with restic +Run a REST server for use with restic - Usage: - rest-server [flags] +Usage: + rest-server [flags] - Flags: - --append-only enable append only mode - --cpu-profile string write CPU profile to file - --debug output debug messages - -h, --help help for rest-server - --listen string listen address (default ":8000") - --log string log HTTP requests in the combined log format - --max-size int the maximum size of the repository in bytes - --no-auth disable .htpasswd authentication - --path string data directory (default "/tmp/restic") - --private-repos users can only access their private repo - --prometheus enable Prometheus metrics - --prometheus-no-auth disable auth for Prometheus /metrics endpoint - --tls turn on TLS support - --tls-cert string TLS certificate path - --tls-key string TLS key path - -V, --version output version and exit +Flags: + --append-only enable append only mode + --cpu-profile string write CPU profile to file + --debug output debug messages + -h, --help help for rest-server + --listen string listen address (default ":8000") + --log string log HTTP requests in the combined log format + --max-size int the maximum size of the repository in bytes + --no-auth disable .htpasswd authentication + --path string data directory (default "/tmp/restic") + --private-repos users can only access their private repo + --prometheus enable Prometheus metrics + --prometheus-no-auth disable auth for Prometheus /metrics endpoint + --tls turn on TLS support + --tls-cert string TLS certificate path + --tls-key string TLS key path + -V, --version output version and exit +``` By default the server persists backup data in `/tmp/restic`. To start the server with a custom persistence directory and with authentication disabled: - rest-server --path /user/home/backup --no-auth +```sh +rest-server --path /user/home/backup --no-auth +``` To authenticate users (for access to the rest-server), the server supports using a `.htpasswd` file to specify users. You can create such a file at the root of the persistence directory by executing the following command (note that you need the `htpasswd` program from Apache's http-tools). In order to append new user to the file, just omit the `-c` argument. Only bcrypt and SHA encryption methods are supported, so use -B (very secure) or -s (insecure by today's standards) when adding/changing passwords. - htpasswd -B -c .htpasswd username +```sh +htpasswd -B -c .htpasswd username +``` If you want to disable authentication, you must add the `--no-auth` flag. If this flag is not specified and the `.htpasswd` cannot be opened, rest-server will refuse to start. @@ -82,8 +92,10 @@ By default the server uses HTTP protocol. This is not very secure since with Ba Signed certificate is normally required by the restic backend, but if you just want to test the feature you can generate unsigned keys with the following commands: - openssl genrsa -out private_key 2048 - openssl req -new -x509 -key private_key -out public_key -days 365 -addext "subjectAltName = IP:127.0.0.1,DNS:yourdomain.com" +```sh +openssl genrsa -out private_key 2048 +openssl req -new -x509 -key private_key -out public_key -days 365 -addext "subjectAltName = IP:127.0.0.1,DNS:yourdomain.com" +``` Omit the `IP:127.0.0.1` if you don't need your server be accessed via SSH Tunnels. No need to change default values in the openssl dialog, hitting enter every time is sufficient. To access this server via restic use `--cacert public_key`, meaning with a self-signed certificate you have to distribute your `public_key` file to every restic client. @@ -105,7 +117,9 @@ Persistent data volume is located to `/data`. #### Start server - docker run -p 8000:8000 -v /my/data:/data --name rest_server restic/rest-server +```sh +docker run -p 8000:8000 -v /my/data:/data --name rest_server restic/rest-server +``` It's suggested to set a container name to more easily manage users (see next section). @@ -115,15 +129,21 @@ You can set environment variable `OPTIONS` to any extra flags you'd like to pass ##### Add user - docker exec -it rest_server create_user myuser +```sh +docker exec -it rest_server create_user myuser +``` or - docker exec -it rest_server create_user myuser mypassword +```sh +docker exec -it rest_server create_user myuser mypassword +``` ##### Delete user - docker exec -it rest_server delete_user myuser +```sh +docker exec -it rest_server delete_user myuser +``` ## Prometheus support and Grafana dashboard From 101ad07999d3b9d2582decbb247085bd01942b32 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20B=C5=93sch?= Date: Fri, 27 Aug 2021 13:02:58 +0200 Subject: [PATCH 2/4] README: update usage output with recent changes --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b908762..6f8a80c 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,7 @@ Flags: --log string log HTTP requests in the combined log format --max-size int the maximum size of the repository in bytes --no-auth disable .htpasswd authentication + --no-verify-upload do not verify the integrity of uploaded data. DO NOT enable unless the rest-server runs on a very low-power device --path string data directory (default "/tmp/restic") --private-repos users can only access their private repo --prometheus enable Prometheus metrics @@ -69,7 +70,7 @@ Flags: --tls turn on TLS support --tls-cert string TLS certificate path --tls-key string TLS key path - -V, --version output version and exit + -v, --version version for rest-server ``` By default the server persists backup data in `/tmp/restic`. To start the server with a custom persistence directory and with authentication disabled: From f8db1312267c3d7fa21b36aef2bbb104bec3e965 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20B=C5=93sch?= Date: Fri, 27 Aug 2021 13:04:14 +0200 Subject: [PATCH 3/4] README: remove trailing whitespaces --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6f8a80c..e556dd4 100644 --- a/README.md +++ b/README.md @@ -97,8 +97,8 @@ Signed certificate is normally required by the restic backend, but if you just w openssl genrsa -out private_key 2048 openssl req -new -x509 -key private_key -out public_key -days 365 -addext "subjectAltName = IP:127.0.0.1,DNS:yourdomain.com" ``` - -Omit the `IP:127.0.0.1` if you don't need your server be accessed via SSH Tunnels. No need to change default values in the openssl dialog, hitting enter every time is sufficient. To access this server via restic use `--cacert public_key`, meaning with a self-signed certificate you have to distribute your `public_key` file to every restic client. + +Omit the `IP:127.0.0.1` if you don't need your server be accessed via SSH Tunnels. No need to change default values in the openssl dialog, hitting enter every time is sufficient. To access this server via restic use `--cacert public_key`, meaning with a self-signed certificate you have to distribute your `public_key` file to every restic client. The `--append-only` mode allows creation of new backups but prevents deletion and modification of existing backups. This can be useful when backing up systems that have a potential of being hacked. From ac8e95c8a4f57c91f1a93fc31d0f28617577129f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20B=C5=93sch?= Date: Fri, 27 Aug 2021 13:10:09 +0200 Subject: [PATCH 4/4] README: propose a single openssl command instead of 2 --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index e556dd4..c527dd5 100644 --- a/README.md +++ b/README.md @@ -94,8 +94,7 @@ By default the server uses HTTP protocol. This is not very secure since with Ba Signed certificate is normally required by the restic backend, but if you just want to test the feature you can generate unsigned keys with the following commands: ```sh -openssl genrsa -out private_key 2048 -openssl req -new -x509 -key private_key -out public_key -days 365 -addext "subjectAltName = IP:127.0.0.1,DNS:yourdomain.com" +openssl req -newkey rsa:2048 -x509 -keyout private_key -out public_key -days 365 -addext "subjectAltName = IP:127.0.0.1,DNS:yourdomain.com" ``` Omit the `IP:127.0.0.1` if you don't need your server be accessed via SSH Tunnels. No need to change default values in the openssl dialog, hitting enter every time is sufficient. To access this server via restic use `--cacert public_key`, meaning with a self-signed certificate you have to distribute your `public_key` file to every restic client.