Configuring a client

The various clients (pk put, pk-get, pk-mount…) use a common JSON config file. This page documents the configuration parameters in that file. Run pk env clientconfig to see the default location for that file ($HOME/.config/perkeep/client-config.json on linux). In the following let $CONFIGDIR be the location returned by pk env configdir.

Generating a default config file

Run pk put init.

On unix,

cat $CONFIGDIR/client-config.json

should look something like:

{
  "identity": "43AD73B1",
  "ignoredFiles": [
    ".DS_Store"
  ],
  "servers": {
    "localhost": {
      "auth": "localhost",
      "default": true,
      "server": "http://localhost:3179"
    }
  }
}

Configuration Keys & Values

Top-level keys

• identity: your GPG fingerprint. Run pk put init for help on how to generate a new keypair.

• identitySecretRing: Optional. If non-empty, it specifies the location of your GPG secret keyring. Defaults to $CONFIGDIR/identity-secring.gpg. Run pk put init for help on how to generate a new keypair.

• ignoredFiles: Optional. The list of of files that pk put should ignore and not try to upload.

Servers

servers: Each server the client connects to may have its own configuration section under an alias name as the key. The servers key is the collection of server configurations. For example:

  "servers": {
    "localhost": {
      "server": "http://localhost:3179",
      "default": true,
      "auth": "userpass:foo:bar"
    },
    "backup": {
      "server": "https://some.remote.com",
      "auth": "userpass:pony:magic",
      "trustedCerts": ["ffc7730f4b"]
    }
  }

• trustedCerts: Optional. This is the list of TLS server certificate fingerprints that the client will trust when using HTTPS. It is required when the server is using a self-signed certificate (as Perkeep generates by default) instead of a Root Certificate Authority-signed cert (sometimes known as a “commercial SSL cert”). The format of each item is the first 20 hex digits of the SHA-256 digest of the cert. Example: "trustedCerts": ["ffc7730f4bf00ba4bad0"]

• auth: the authentication mechanism to use. Only supported for now is HTTP basic authentication, of the form: userpass:alice:secret. Username “alice”, password “secret”.

  If the server is not on the same host, it is highly recommended to use TLS or another form of secure connection to the server.

• server: The perkeepd server to connect to, of the form: “[http[s]://]host[:port][/prefix]”. Defaults to https. This option can be overridden with the “-server” command-line flag.

  Most client commands are meant to communicate with a blobserver. For such commands, instead of the client relying on discovery to choose the actual URL, the server URL can point directly to a specific blobserver handler, of the form: “[http[s]://]host[:port][/prefix][/handler/]”.

  For example, to speed up syncing with pk sync, one could write directly to the destination’s blobserver, instead of the default, which is to write to both the destination blobserver and index. The above configuration sample can be extended by adding the following alias, where “/bs/” is the handler of the primary blobserver:

  "servers": {
    ...
    "backup-bs": {
      "server": "https://some.remote.com/bs/",
      "auth": "userpass:pony:magic",
      "trustedCerts": ["ffc7730f4b"]
    }
  }
  

  And the alias backup-bs can then be used as a destination by pk sync.