kopia/site/content/docs/Repository Server/_index.md

title, linkTitle, weight

title	linkTitle	weight
Repository Server	Repository Server	44

By default every user of Kopia repository directly connects to a underlying storage using read-write access. If the users who share repository don't completely trust each other, some malicious actors can delete repository data structures causing data loss for others.

Repository Server allows an instance of kopia to proxy access to the underlying storage and has Kopia clients proxy all access through it, only requiring username and password to talk to server without any knowledge of repository storage credentials.

In repository server mode, each user is limited to seeing their own snapshots and policy manifest without being able to access those from another user account.

NOTE: Only snapshot and policy manifests are access-controlled, not the underlying contents. If two users shared the same file, it will be backed using exactly the same same content IDs. The consequence of this is that if a third user can guess the content ID of files in the repository, they will be able to access the files. Because content IDs are one-way salted hashes of contents, in principle it should be impossible to guess content ID without possessing original content.

Starting Repository Server

Repository Server should be started on a dedicated server in LAN, such that all clients can directly connect to it.

Before we can start repository server, we must first create a list of usernames and passwords that will be allowed access. The list must be put in a text file formatted using the htpasswd utility from Apache. Each username must be named:

<client-username>@<client-host-name-lowercase-without-domain>

where <client-host-name-lowercase-without-domain> is the host name of the client computer in lowercase and without domain component. On Linux clients, the client host name can be found with the following command. Notice that this is not the server host name, but the client host name instead.

$ cat /etc/hostname

NOTE: The use of htpasswd tool is only temporary. In future releases Kopia may introduce its own password management options and ACL management without having to rely on external utility.

To create password file for two users:

$ htpasswd -c password.txt user1@host1
New password: 
Re-type new password: 
Adding password for user user1@host1

$ htpasswd password.txt user2@host1
New password: 
Re-type new password: 
Adding password for user user2@host1

The contents of password file will store hashes of provided passwords and not passwords themselves:

user1@host1:$apr1$8yF23v/9$Su9NdzkBp.r456/qcgJBF.
user2@host1:$apr1$KbY23BUf$xtzBjaMnrOBOfPePIfS//.

It is recommended to use TLS to ensure security of connections to the server.

Auto-Generated TLS Certificate

To start repository server with auto-generated TLS certificate for the first time:

kopia server start --htpasswd-file ~/password.txt --tls-generate-cert --tls-cert-file ~/my.cert --tls-key-file ~/my.key --address 0.0.0.0:51515

This will generate TLS certificate and key files and store them in the provided paths (~/my.cert and ~/my.key respectively). It will also print certificate SHA256 fingerprint, which will be used later:

SERVER CERT SHA256: 48537cce585fed39fb26c639eb8ef38143592ba4b4e7677a84a31916398d40f7

Note that when starting the server again the --tls-generate-cert must be omitted, otherwise the server will fail to start.

Custom TLS Certificates

If a user has obtained custom certificate (for example from LetsEncrypt or another CA), using it is simply a matter of providing PEM-formatted certificate and key files on server startup.

To get SHA256 certificate of existing file use:

$ openssl x509 -in ~/my.cert -noout -fingerprint -sha256 | sed 's/://g' | cut -f 2 -d =
48537CCE585FED39FB26C639EB8EF38143592BA4B4E7677A84A31916398D40F7

On Client Computer

Assuming we're on another machine running as user1@host1, we can now run the following command to connect to the repository (notice we're using fingerprint obtained before without : separators)

kopia repository connect server --url https://<address>:51515 \
  --server-cert-fingerprint 48537cce585fed39fb26c639eb8ef38143592ba4b4e7677a84a31916398d40f7

Once connected, all snapshot and policy kopia commands should work for the current user, but low-level commands such as repo status will fail:

$ kopia repository status
kopia: error: operation supported only on direct repository, try --help

You can override username and hostname with this command :

$ kopia repo connect server --url=http://11.222.111.222:51515 --override-username=johndoe --override-hostname=my-laptop