Kopia as Windows Service

Kopia as Windows Service.md

Pre-requisites:

1. Install Kopia. In this example, I have installed KopiaUI to C:\Program Files\KopiaUI.
2. Download Shawl from https://github.com/mtkennerly/shawl.
3. Place shawl.exe in a suitable directory. In this example, shawl was placed to C:\Program Files\Shawl\shawl.exe.
4. Create a directory to store Kopia data files. In this example, we are using C:\ProgramData\kopia

First, we will set up Kopia and check that it's working as a regular application:

1. Create a htpasswd file, with a user called kopia and a secure password. Place the file in C:\ProgramData\kopia\htpasswd. Creating a htpasswd file on Windows is not very straightforward. If you have access to a Linux system, you can generate it there and copy it to your Windows machine

   $ htpasswd -c ./htpasswd kopia

2. Start Kopia for the first time, with a --tls-generate-cert parameter:

   C:\>kopia server start --tls-cert-file C:\ProgramData\kopia\kopia.cert --tls-key-file C:\ProgramData\kopia\kopia.key --htpasswd-file C:\ProgramData\kopia\htpasswd --address https://0.0.0.0:51515 --tls-generate-cert

   This will generate a TLS certificate in C:\ProgramData\kopia.

   If you have Windows Firewall enabled, it should now pop up with a window asking you to allow network access for Kopia. This is needed for Kopia web-based UI to be accessible from other machines; if you don't need that, you can ignore the Firewall pop-up and close it.

3. Open your web browser, navigate to https://localhost:51515. The TLS certificate will be self-signed, so your browser will warn you about it not being secure. This is expected, you can safely ignore the warning and add an exception.

   You should be able to log in with the kopia user and the password you stored in the htpasswd file, and then see the Kopia UI in your browser.

4. Stop Kopia by pressing Ctrl+C.

Next we will configure Shawl to run Kopia as a Windows service.

1. Start a command line as Administrator. You need to have Administrator rights to install and maintain Windows services.

2. Add Kopia as a Windows service using Shawl:

   C:\>"C:\Program Files\Shawl\shawl.exe" add --cwd C:\ProgramData\kopia --log-dir C:\ProgramData\kopia\logs --name Kopia -- "C:\Program Files\KopiaUI\resources\server\kopia.exe" server start --tls-cert-file kopia.cert --tls-key-file kopia.key --htpasswd-file htpasswd --address https://0.0.0.0:51515

   (add --enable-actions to the command line if you wish to enable actions)

3. Configure the service to start automatically during boot, and then start it immediately.

   C:\>sc config Kopia start=auto
   C:\>sc start Kopia

4. Check if the service is running:

   C:\>sc query Kopia
   
   SERVICE_NAME: Kopia
           TYPE               : 10  WIN32_OWN_PROCESS
           STATE              : 4  RUNNING
                                   (STOPPABLE, NOT_PAUSABLE, ACCEPTS_SHUTDOWN)
           WIN32_EXIT_CODE    : 0  (0x0)
           SERVICE_EXIT_CODE  : 0  (0x0)
           CHECKPOINT         : 0x0
           WAIT_HINT          : 0x0

5. Open your web browser, again navigate to https://localhost:51515. You should be able to log in to Kopia running as a Windows service. Now proceed to configure Kopia using the web UI as usual.

6. (Optional) Reboot your computer and verify that Kopia starts automatically as a service.

(consider this text public domain)

Hi @matushorvath,

First of all, thanks for putting this quick tutorial together as it's been just thing I was interested in setting up. I was able to follow the instructions to a T and got the server up and running as a windows service...I had a question though, did try adding a user to the server and if so, were you successful?

I tried running the following command but got the below error:

Command:
kopia server user add localuser@server-hostname

Error

Enter new password for user localuser@server-hostname:
Re-enter new password for verification:
ERROR error setting user profile: error looking for user profile: access denied

P.S - I had to change the "user" name in htpasswd from "kopia" to "kopia@server-hostname" since it wouldn't let me "connect" to the server otherwise, not sure if you ran into the same issue.

Also, you have a minor typo where you instruct creating "htpassword" file in C:\ProgramData\kopia\htpassword but then refer to the file as htpasswd in the subsequent command

@matushorvath A follow-up question, which user are you running the windows service as? SYSTEM (a.k.a LOCAL_SYSTEM) or are you running it as a local user that you created?

@abjoseph I did not try adding users to the server. This is for a home setup so I am not taking security as seriously as I perhaps should. If you manage to get it working, please let me know and I will update the steps.

The user I added to htpasswd is "kopia", not "kopia@server-hostname" - I just checked to be sure. Honestly I am new to kopia and a bit lost in the user management still. Also I am only using the web UI to manage kopia, did not play with the command line yet, that may be the reason I did not find the issues you found.

The service is running as "SYSTEM" user, I did not try running it under it's own user. What I was originally trying to do is to get VSS working using Kopia actions, but that was not successful yet. But for that reason I am OK with running it as SYSTEM, that way it has access to VSS and the whole filesystem. And in a home setup I am not worried about giving minimum privileges to the service.

I fixed the "htpassword" mistake in the text, thank you for pointing it out.

@abjoseph I tried to reproduce the bug when adding a user, but it seems to work for me:

1. Open an elevated command prompt. (I think this is one potential issue you could have, since the service stores its file in directories that are not writable by regular users).
2. The exact command I tried:

C:\WINDOWS\system32>"C:\Program Files\KopiaUI\resources\server\kopia.exe" --config-file=C:\WINDOWS\system32\config\systemprofile\AppData\Roaming\kopia\repository.config server user add delme@core
Enter password to open repository:

Enter new password for user delme@core:
Re-enter new password for verification:

Updated user credentials will take effect in 5-10 minutes or when the server is restarted.
To refresh credentials in a running server use 'kopia server refresh' command.


C:\WINDOWS\system32>

I can then list users and the user is included:

C:\WINDOWS\system32>"C:\Program Files\KopiaUI\resources\server\kopia.exe" --config-file=C:\WINDOWS\system32\config\systemprofile\AppData\Roaming\kopia\repository.config server user list
Enter password to open repository:

delme@core

C:\WINDOWS\system32>

@matushorvath I appreciate you taking to the time to respond and with such detail as well. After reading the above I have 2 follow-up questions:

1. Did you run/execute the repository connect server" command before running the above command to add the user? e.g kopia repository connect server --url https://localhost:51515 --server-cert-fingerprint <cert-sha1-fingerprint>

2. Where did you read (in docs) or knew that you needed to include --config-file in the above command to add the user? One of the shortcomings of this project is the steep learning curve for newcomers which isn't helped by the lack of proper documentation and the somewhat convoluted design of the tool.

@abjoseph

1. I did not run that command. I guess the way I ran that command, it probably launched another instance of the kopia server and performed the command (so it did not connect to the instance it was already running). But that's literally just a guess, I don't know enough about kopia to understand what the "repository connect server" command does.
2. I copied the command line from the web UI. On most pages there is the small yellow button that reveals a command line, see attached screenshot.