From 3a13ebf5186651658d41c488c2b6ccca476ce571 Mon Sep 17 00:00:00 2001 From: Juerd Waalboer Date: Sun, 12 Mar 2023 22:53:10 +0100 Subject: [PATCH] docs(site): added control credentials to example (#2807) - Added server control credentials to `kopia server start` example - Reformatted `kopia server start` to avoid excessive horizontal scrolling - Moved pre-v0.8 information to quoted notes to reduce confusion --- site/content/docs/Repository Server/_index.md | 80 ++++++------------- 1 file changed, 26 insertions(+), 54 deletions(-) diff --git a/site/content/docs/Repository Server/_index.md b/site/content/docs/Repository Server/_index.md index 9b6fd99af..365ece17a 100644 --- a/site/content/docs/Repository Server/_index.md +++ b/site/content/docs/Repository Server/_index.md @@ -19,7 +19,7 @@ Repository Server should be started on a dedicated server in LAN, such that all Before we can start repository server, we must first create a list of usernames and passwords that will be allowed access. -## Configuring Allowed Users - Kopia v0.8 +## Configuring Allowed Users Starting in Kopia v0.8, allowed repository users can be configured using `kopia server user` commands. Each user is identified by its lowercase `username@hostname` where hostname by default is the name of the computer the client is connecting from (without domain name suffix). @@ -40,65 +40,34 @@ Other commands are also available: * `kopia server user set` - changes password * `kopia server user delete` - deletes user account -## Configuring Allowed Users - Kopia v0.7 - ->NOTE: This method is still supported in v0.8, but it's recommended to use `kopia server user` to manage users -instead. - -In Kopia v7.0 the user list must be put in a text file formatted using the [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) utility from Apache. - -Each username must be named: - -``` -@ -``` - -where `` 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. - -```shell -$ 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: - -```shell -$ 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. +>__Prior to Kopia v0.8__, the user list must be put in a text file formatted using the [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) utility from Apache. This method is still supported in v0.8, but it's recommended to use `kopia server user` to manage users instead. +> To create password file for two users: +> ```shell +> $ 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 +> ``` ### Auto-Generated TLS Certificate To start repository server with auto-generated TLS certificate for the first time: ```shell -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 +kopia server start \ + --tls-generate-cert \ + --tls-cert-file ~/my.cert \ + --tls-key-file ~/my.key \ + --address 0.0.0.0:51515 \ + --server-control-username control \ + --server-control-password PASSWORD_HERE ``` -or when using repository users in Kopia v0.8 and newer: - -```shell -kopia server start --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: ```shell @@ -107,6 +76,8 @@ SERVER CERT SHA256: 48537cce585fed39fb26c639eb8ef38143592ba4b4e7677a84a31916398d Note that when starting the server again the `--tls-generate-cert` must be omitted, otherwise the server will fail to start. +>__Prior to Kopia v0.8,__ the command line for `kopia server start` also needs `--htpasswd-file ~/password.txt` + ### 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. @@ -143,7 +114,7 @@ $ kopia repo connect server --url=http://11.222.111.222:51515 --override-usernam Kopia server will check permissions when users try to access contents and manifests based on rules we call ACLs (access control list). -Prior to v0.8, the rules were non-configurable and each user could only read and write their own +>__Prior to Kopia v0.8,__ the rules were non-configurable and each user could only read and write their own snapshot manifests. Starting in Kopia v0.8 the ACLs can be controlled by using `kopia server acl` commands. If no ACLs are explicitly defined, Kopia will use a set of built-in access control rules, which grants all authenticated users identified by `username@hostname` ability to: @@ -277,7 +248,8 @@ Kopia server will refresh its configuration by fetching it from repository perio ```shell $ kopia server refresh \ --address=https://server:port [--server-cert-fingerprint=FINGERPRINT] \ - --server-username=U --server-password=P + --server-username=control \ + --server-password=PASSWORD_HERE ``` To authenticate, pass any valid username and password configured on the server.