# REST Server

BorgStore includes a simple REST server that can be used to provide remote access to any BorgStore backend.

It can do some stuff server-side, which is usually not possible when using other cloud storage servers:

- enforcing permissions

- server rejects store operation if content hashsum does not match expected hashsum (from http header X-Content-hash-sha256)

- server-side hash computation (e.g. sha256) for item content

- server-side defragmentation helper (copies blocks to new items)

## Running the server on host:port

Run a server with a file: backend (for a local directory), using HTTP Basic Authentication:

    borgstore-server-rest --host 127.0.0.1 --port 5618 \
        --username user --password pass \
        --backend file:///tmp/teststore

For production deployments, consider using systemd socket activation (see contrib/server/nginx-systemd/README.md).

## Running the server via stdio

Run a server with a file: backend (for a local directory), talking http via stdin/stdout, logging via stderr:

> borgstore-server-rest –stdio

>   –backend file:///tmp/teststore

## Accessing the server from a client

The borgstore REST client can then access via:

    http://user:pass@127.0.0.1:5618/

or (when using http over stdio):

> rest://user@host:port//tmp/teststore # via ssh, abs. path rest://user@host:port/teststore # via ssh, rel. path rest:////tmp/teststore # locally, without ssh, abs. path rest:///teststore # locally, without ssh, rel. path

## Permissions

The REST server, when used with the `posixfs` backend, supports the same permissions system as that backend (see above).

If `--permissions` is omitted, all operations are allowed. To restrict permissions, pass a JSON-encoded permissions mapping via `--permissions`.

Examples:

Read-only access:

    borgstore-server-rest --host 127.0.0.1 --port 5618 \
        --username user --password pass \
        --backend file:///tmp/teststore \
        --permissions '{"": "lr"}'

No-delete, no-overwrite (allow adding new items):

    borgstore-server-rest --host 127.0.0.1 --port 5618 \
        --username user --password pass \
        --backend file:///tmp/teststore \
        --permissions '{"": "lrw"}'

Full access:

    borgstore-server-rest --host 127.0.0.1 --port 5618 \
        --username user --password pass \
        --backend file:///tmp/teststore \
        --permissions '{"": "lrwWD"}'

### BorgBackup shortcuts

Instead of hand-crafting a JSON mapping, you can use a named shortcut tailored for BorgBackup repositories:

`borgbackup-all`

  No permission restrictions — all operations are allowed (equivalent to omitting `--permissions`).

`borgbackup-no-delete`

  Prevent deletion and overwriting of existing objects; new objects may still be added.

`borgbackup-write-only`

  Clients may store new data but cannot read existing data back (except for caches and metadata that borg needs internally).

`borgbackup-read-only`

  Clients may only list and read objects.

Example — restrict a backup server to no-delete access:

    borgstore-server-rest --host 127.0.0.1 --port 5618 \
        --username user --password pass \
        --backend file:///home/user/repos/repo1 \
        --permissions borgbackup-no-delete

### Custom JSON permissions

You can also pass an arbitrary JSON-encoded permissions mapping directly.

Hierarchical rules (list-only at root, read/write in `data/`):

    borgstore-server-rest --host 127.0.0.1 --port 5618 \
        --username user --password pass \
        --backend file:///tmp/teststore \
        --permissions '{"": "l", "data": "lrw"}'

## Quota

The REST server, when used with the `file:` backend, optionally supports quota tracking and enforcement.

Use the `--quota` argument to set a maximum storage size in bytes (default is no quota tracking and enforcement).

When the quota is exceeded, `store` operations are rejected with HTTP 507 (Insufficient Storage).

Example — limit storage to 1 GiB:

    borgstore-server-rest --host 127.0.0.1 --port 5618 \
        --username user --password pass \
        --backend file:///tmp/teststore \
        --quota 1073741824