Zettelstore startup configuration

The configuration file, as specified by the -c CONFIGFILE command line option, allows you to specify some startup options. These options cannot be stored in a configuration zettel because either they are needed before Zettelstore can start or because of security reasons. For example, Zettelstore need to know in advance, on which network address is must listen or where zettel are stored. An attacker that is able to change the owner can do anything. Therefore only the owner of the computer on which Zettelstore runs can change this information.

The file for startup configuration must be created via a text editor in advance.

The syntax of the configuration file is the same as for any zettel metadata. The following keys are supported:

admin-port

Specifies the TCP port through which you can reach the administrator console. A value of “0” (the default) disables the administrator console. The administrator console will only be enabled if Zettelstore is started with the run sub-command.

On most operating systems, the value must be greater than “1024” unless you start Zettelstore with the full privileges of a system administrator (which is not recommended).

Default: “0”

asset-dir

Allows to specify a directory whose files are allowed be transferred directly with the help of the web server. The URL prefix for these files is /assets/. You can use this if you want to transfer files that are too large for a note to users. Examples would be presentation files, PDF files, music files or video files.

Files within the given directory will not be managed by Zettelstore.1

If you specify only the URL prefix, then the contents of the directory are listed to the user. To avoid this, create an empty file in the directory named “index.html”.

Default: “”, no asset directory is set, the URL prefix /assets/ is invalid.

base-url

Sets the absolute base URL for the service.

Note: url-prefix must be the suffix of base-url, otherwise the web service will not start. Default: “http://127.0.0.1:23123/”.

box-uri-X, where X is a number greater or equal to one

Specifies a box where zettel are stored. During startup X is counted up, starting with one, until no key is found. This allows to configure more than one box.

If no box-uri-1 key is given, the overall effect will be the same as if only box-uri-1 was specified with the value “dir://.zettel”. In this case, even a key box-uri-2 will be ignored.

debug-mode

Allows to debug the Zettelstore software (mostly used by the developers) if set to true Disables any timeout values of the internal web server and does not send some security-related data. Sets log-level to “debug”.

Do not enable it for a production server.

Default: “false”

default-dir-box-type

Specifies the default value for the (sub-) type of directory boxes. Zettel are typically stored in such boxes.

Default: “notify”

insecure-cookie

Must be set to true, if authentication is enabled and Zettelstore is not accessible not via HTTPS (but via HTTP). Otherwise web browser are free to ignore the authentication cookie.

Default: “false”

insecure-html

Allows to use HTML, e.g. within supported markup languages, even if this might introduce security-related problems. However, HTML containing the <script> or the <iframe> tag is always ignored. But due to “clever” ways of combining HTML, CSS, JavaScript, there might be some negative security consequences. Please be aware of this!

Allowed values: “html” (allow zettel with syntax “html”), “markdown” (“html”, plus allow inline HTML for Markdown markup only), “zettelmarkup” (“markdown”, plus allow inline HTML for Zettelmarkup). Any other value is interpreted as “secure”.

Default: “secure”.

listen-addr

Configures the network address, where the Zettelstore service is listening for requests. Syntax is: [NETWORKIP]:PORT, where NETWORKIP is the IP-address of the networking interface (or something like “0.0.0.0” if you want to listen on all network interfaces, and PORT is the TCP port.

Default value: “127.0.0.1:23123”

log-level

Specify the logging level for the whole application or for a given (internal) service, overwriting the level “debug” set by configuration debug-mode. Can be changed at runtime, even for specific internal services, with the log-level command of the administrator console.

Several specifications are separated by the semicolon character (“;”, U+003B). Each specification consists of an optional service name, together with the colon character (“:”, U+003A), followed by the logging level.

Default: “info”.

Examples: “error” will produce just error messages (e.g. no “info” messages); “error;web:debug” will emit debugging messages for the web component of Zettelstore while still producing error messages for all other components.

When you are familiar to operate the Zettelstore, you might set the level to “error” to receive less noisy messages from the Zettelstore.

max-request-size

Limits the maximum byte size of a web request body to prevent clients from accidentally or maliciously sending a large request and wasting server resources. The minimum value is 1024.

Default: 16777216 (16 MiB).

owner

Identifier of a zettel that contains data about the owner of the Zettelstore. The owner has full authorization for the Zettelstore. Only if owner is set to some value, user authentication is enabled.

Ensure that key secret is set to a value of at least 16 bytes. Otherwise the Zettelstore will not start for security reasons.

persistent-cookie

A boolean value to make the access cookie persistent. This is helpful if you access the Zettelstore via a mobile device. On these devices, the operating system is free to stop the web browser and to remove temporary cookies. Therefore, an authenticated user will be logged off.

If “true”, a persistent cookie is used. Its lifetime exceeds the lifetime of the authentication token (see option token-lifetime-html) by 30 seconds.

Default: “false”

read-only-mode

Puts the Zettelstore service into a read-only mode, if set to a true value. No changes are possible.

Default: “false”.

secret

A string value to make the communication with external clients strong enough so that sessions of the web user interface or API access token cannot be modified by some external unfriendly party. The string must have a length of at least 16 bytes.

It is only needed to set this value, if authentication is enabled by setting key owner to some user identification.

token-lifetime-api, token-lifetime-html

Define lifetime of access tokens in minutes. Values are only valid if authentication is enabled, i.e. key owner is set.

token-lifetime-api is for accessing Zettelstore via its API. Default: “10”.

token-lifetime-html specifies the lifetime for the HTML views. It is automatically extended, when a new HTML view is rendered. Default: “60”.

url-prefix

Add the given string as a prefix to the local part of a Zettelstore local URL/URI when rendering zettel representations. Must begin and end with a slash character (“/”, U+002F).

Note: url-prefix must be the suffix of base-url, otherwise the web service will not start.

Default: “/”.

This allows to use a forwarding proxy server in front of the Zettelstore.

verbose-mode

Be more verbose when logging data, if set to a true value.

Default: “false”

  1. They will be managed by Zettelstore just in the case that the directory is one of the configured boxes. ↩︎