DOCSEARCHbyAlgolia
Submit Docs

restic Rest Server

repository·master·Indexed 23 days ago

https://github.com/restic/rest-server

A high-performance HTTP server implementing the restic REST backend API. It enables remote backups via the `rest:` URL scheme and features support for TLS, .htpasswd authentication, proxy-based authentication, append-only mode, and Prometheus metrics for observability.

Tokens
6.3K
Snippets
14
Records
34
Agent score
76%

What's inside rest-server

  1. Use append-only mode for security

    master
    The --append-only flag enables a mode where new backups can be created, but existing backups cannot be deleted or modified. This provides a layer of protection against attackers who might gain access to the server and attempt to wipe existing backups.

  2. Restrict users to private repositories

    master

    Use the --private-repos flag to prevent users from accessing each other's repositories. When this flag is enabled, a user can only access a repository if the subdirectory in the URL matches their username.

    Example:

    • User foo accessing rest:https://host:8000/foo is granted access.
    • User foo accessing rest:https://host:8000/ or rest:https://host:8000/foobar/ is denied access.

    Users can still create their own sub-repositories, such as /foo/bar/.

  3. Configure Grafana Data Source for Rest Server Dashboard

    master

    Once the stack is running, access Grafana at http://localhost:8030/ (default credentials: username admin, password admin).

    To use the pre-configured Rest Server dashboard, you must add a Prometheus data source. Crucially, you must name the data source prometheus, as the dashboard configuration expects this exact name.

    • Grafana URL: http://localhost:8030/
    • Dashboard URL: http://localhost:8030/dashboard/file/rest-server.json
    • Prometheus URL: http://localhost:8020/
    • Data Source Name: prometheus

  4. Deploy Rest Server with Prometheus and Grafana via Docker Compose

    master

    This setup uses Docker Compose to deploy a full observability stack for rest-server, including Prometheus for metrics collection and Grafana for visualization.

    1. Build the Rest Server image

    First, build the rest-server Docker image from the repository root:

    cd ../..
make docker_build
cd -

    2. Start the stack

    Run the Docker Compose stack in detached mode:

    docker-compose build
docker-compose up -d

    3. Verify deployment

    Check the status of the containers:

    docker-compose ps
    cd ../..
make docker_build
cd -
docker-compose build
docker-compose up -d
docker-compose ps

  5. Make repositories group-accessible

    master

    The --group-accessible-repos flag allows repositories to be accessed by the filesystem group.

    Implementation details:

    • This flag does not modify the permissions of existing files.
    • To allow the group to read and write files, use a umask of 007.
    • To grant only read access, use a umask of 027.
    • To make an existing repository group-accessible, manually run: chmod -R g+rwX /path/to/repo.

  6. Delegate authentication to a proxy

    master

    To use a proxy for authentication instead of .htpasswd, use the --proxy-auth-username flag. You must specify the name of the HTTP header that contains the username (e.g., X-Forwarded-User).

    Warning: When this flag is set, Basic Authentication is disabled. The server trusts the username provided in the specified header; it is the responsibility of your proxy to ensure this header is secure and cannot be forged.

  7. Enable Prometheus metrics

    master

    To expose Prometheus metrics at the /metrics endpoint, start the server with the --prometheus flag.

    If authentication is enabled, the /metrics endpoint requires authentication for a user named metrics. You can bypass this requirement by using the --prometheus-no-auth flag.

  8. Set up authentication with .htpasswd

    master

    Rest Server uses a .htpasswd file for user authentication. By default, it looks for this file in the root of the --path directory. You can change the location using --htpasswd-file.

    To create a new password file with a user, use the htpasswd utility. Use the -B flag for secure bcrypt encryption:

    htpasswd -B -c .htpasswd username

    To append a user to an existing file, omit the -c argument.

    Important: If you do not specify the --no-auth flag and the .htpasswd file cannot be opened, the server will refuse to start.

  9. Enable TLS support

    master

    To secure communications using TLS, add the --tls flag. You can provide specific certificate and key paths using --tls-cert and --tls-key. You can also enforce a minimum TLS version (e.g., 1.3) using --tls-min-ver 1.3.

    For testing with self-signed certificates, you can generate unsigned keys using openssl:

    openssl req -newkey rsa:2048 -nodes -x509 -keyout private_key -out public_key -days 365 -addext "subjectAltName = IP:127.0.0.1,DNS:yourdomain.com"

    Client Configuration: When using self-signed certificates, you must distribute the public_key to every restic client and use the --cacert public_key flag in the restic command.

  11. Run rest-server with Docker

    master

    Rest Server is available as a Docker image (restic/rest-server).

    Start the server

    docker pull restic/rest-server:latest
docker run -p 8000:8000 -v /my/data:/data --name rest_server restic/rest-server

    Docker-specific defaults and configuration:

    • Data Path: Unlike the binary default, the persistent data volume is located at /data inside the container.
    • Authentication: Enabled by default. Disable it by setting the environment variable DISABLE_AUTHENTICATION to any value.
    • Password File: The .htpasswd file is loaded from /data/.htpasswd by default. Change this using the PASSWORD_FILE environment variable.
    • Extra Flags: Pass additional flags to the server using the OPTIONS environment variable.

    Manage users via Docker

    Use docker exec to manage users within a running container:

    # Add a user
docker exec -it rest_server create_user myuser

# Add a user with a password
docker exec -it rest_server create_user myuser mypassword

# Delete a user
docker exec -it rest_server delete_user myuser

  12. Configure Prometheus metrics and access control

    master

    The rest-server can expose Prometheus metrics via the /metrics endpoint. Access control for this endpoint is governed by two flags:

    • Public Metrics: If Prometheus is enabled and PrometheusNoAuth is true, the /metrics endpoint is accessible without authentication.
    • Authenticated Metrics: If Prometheus is enabled and PrometheusNoAuth is false, the endpoint requires authentication. If PrivateRepos is also enabled, only the user named metrics is allowed to access the endpoint.