How to specify the root dir for kopia server

I am in the process of setting up a kopia server on a VM. I do have a separate filesystem /backup where all backups should go for all the hosts that connect to that kopia server.

I have read the documentation, but clouldn’t find a paramter or a config file where I could specify the root directory for backups/snapshots/… created by all the hosts that connect to this kopia server.

So how do I specify the root dir for backups?

Ps.: Also, is there more info available than on The information is rather sparse. e.g. in what are the HTTP server username and Server control username for?

Basically, you create a local repo using kopia and then use that in the config file that is then passed to Kopia server. Somewhat like this:

  "storage": {
    "type": "filesystem",
    "config": {
      "path": "/mnt/kopia/ST7A",
      "dirShards": null,
      "fileMode": 384,
      "dirMode": 448

Along with all the other stuff, that goes into the config, if you want to run a Kopia server. Then start your Kopia server something like this:

# start Kopia server in the background
/usr/bin/kopia server start \
 --password=<repo password> \
 --tls-cert-file /path/to/cert \
 --tls-key-file /path/to/key \
 --address \
 --config-file="/path/to/server.config" \
 --server-username <main repo user> \
 --log-level=error \
 --file-log-level=error \
 --log-dir="/path/to/logdir" &
1 Like

Thank you very much for the reply.

Wow, this approach seems overly awkward. I think this should be added to the documentation. This might all seem very logical to the designers/developers of kopia, but it is not in fact the standard way of how services and servers work.
Yes, servers have a config file, but it’s usually one that is written and modified by the admin and not by the service (at least initially).

The deb and rpm packages do not create a separate user kopia should run under, there is no /etc/kopia.conf with default entries, no systemd unit file, nothing, except the binary.

Along with all the other stuff, that goes into the config

What would that be? I seriously don’t know. I am new to kopia and this sentence makes me even more hesitant to even start using kopia. There are so many unknowns, because the documentation just doesn’t tell you.
Another thing that is not entirely clear: How am I supposed to create users on the kopia server, if there’s no default admin user? Or do I just circumvent all security by using the kopia command locally on the server?

--password=<repo password>
--server-username <main repo user>

What is the main repo user? The admin of the repo? I am not very keen on having a password in the process command line, especially if it is the admin password which can be seen by everyone doing a simple ps -ef.

Don’t take this the wrong way, kopia might be a great software and work very well, but I don’t think that an admim should have to go through many trial and error runs to figure out how this thing works.

Well, this nitty-gritty stuff is usually taken care of when running KopiaUI, where you can specify all these things via the dialog(s). However, if you want to run headless Kopia server, you’d have to feed it a config file.

Kopia in “server mode” does allow for adding repo users. You can check out the help pages for that like this:

kopia server --help

I am pretty sure you can also omit the password, but then you’d have to enter it, when you start Kopia server. You can also store your repo password in the ENV var KOPIA_PASSWORD and use that, but Kopia server needs to know the repo password somehow.

I can understand that Kopia server can look a bit daunting, but it really isn’t and Kopia is a remarkable tool - in fact its one of my favorites. Please feel free to ask for more advice, though.


Yeah, I admit though, that Kopia docs could be better. I have been hanging in here for quite a while and mostly seen all changes since 0.6 or so. But hey… Jarek always welcomes contributions to the docs, if you’re up for it. I guess most of us are too busy to do that, though - which also applies to Jarek.

I am not up for it, because otherwise I wouldn’t ask these questions. :wink: The person who has answers to my questions can actually write the documentation.

It’s like asking the student to run the class and teach the prof.

Hm. You’ve rather strange attitude towards a free, github program. This is a community effort, after all. Not a one men, commercial show. Everybody can help, if an able too. I’m not, but I’m not complaining either. If I don’t know something about Kopia, I’ve just setup a test backup and run with different options, switches, configurations, test files etc.

I was asking for documentation that explains what the options mean and what they are used for. What’s strange about an attitude where I want to know how the SW works?

Because this is a work in progress… There are answers, sure, you can browse forums, documentation, but if you cant find a right one, well, just test, test, test and find this way a correct one. Or not, this is a 0.12 version of software… 0.12. Not even 0.2. Anyway, this is my take on the problem of not having a perfect documentation. Your mileage may vary…

Agreed…! A lot of the newer functions/options have been discussed in this forum - a lot of them explained by Jarek, when they were released.

Thanks again.

Of course I can spend a few days trying all different permutations of things and arguments, but this is why I hoped there is a proper documentation how to run a kopia server. Since it is a server it should be headless.

It’s not that I have a crazy setup. All I want is to run a kopia server on a machine tnat all clients are using to send their backups to. On the server all the backups from the clients should go into /data/backups. The admin user should be called admin and the password should be adminpwd. A client user user1 with password client1pwd should be allowed to send backups from machine host1 to the server. This is all I want.

Is there a step-by-step guide how to set this up?

If you know the topics in this forum that have that info, I am more than happy to read them, but I can’t read all the topics nor did I find the info by searching for it.

I will also try a few things (your first reply with a few changes since the arguments seem different from the reference) in the next few days, but as mentioned before I don’t think one should be left to a trial-and-error game.

I went through my notes and compiled a little step-by-step. However, my notes are really outdated, so I can not guarantee, that the isn’t something that has changed over the last two years, but it may serve you as a reference. Here we go:

First create a repo:

kopia repository create filesystem /
--path /path/to/repo /
--encryption=AES256-GCM-HMAC-SHA256 /
--block-hash=BLAKE3-256-128 /
--object-splitter=DYNAMIC-4M-BUZHASH /
--override-username=<server-user> /
--override-hostname=<hostname> /
--password=<your password>

Example repo config file:

  "storage": {
    "type": "filesystem",
    "config": {
      "path": "/path/to/repo",
      "dirShards": null,
      "fileMode": 384,
      "dirMode": 448
  "caching": {
    "cacheDirectory": "</path/to/cache dir>",
    "maxCacheSize": 34359738368,
    "maxMetadataCacheSize": 274877906944,
    "maxListCacheDuration": 86400
  "hostname": "<kopia hostname",
  "username": "server-user",
  "description": "Repository in Filesystem: <path/to/repo>",
  "enableActions": false,
  "formatBlobCacheDuration": 900000000000

Be aware that all numbers may be need to be adjusted to your needs, as they depend on the size of the repo.

Start Kopia Server from the cli:

kopia server start \
 --tls-cert-file /path/to/my.cert \
 --tls-key-file /path/to/my.key \
 --address \
 --config-file=/path/to/repo.config \
 --log-level=error \
 --file-log-level=error \
 --log-dir="/path/to/log folder" \
 --server-username <server-user> \
 --password=u<your password> &

There are multiple ways to do this and I do know that some people are not comfortable writing the password in a shell script, but I actually don’t care.

Add a remote repo user:

kopia server user add /
--password=<server user password> /
--user-password=<new repo user password> /
  <news user@new host>

Hope this helps a bit.

1 Like

Yes, thanks. I will use your guide and make notes. I’ll post my notes after I have set it up.
I hope I will get to it in the next few days. I also have to setup a dedicated Kopia VM with a 4TB iSCSI disk as my backup storage.