mirror of https://github.com/perkeep/perkeep.git
108 lines
3.6 KiB
Markdown
108 lines
3.6 KiB
Markdown
# 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`.
|