(((meta (@ (content . "Zettelstore startup configuration") (name . "title"))) (meta (@ (content . "manual") (name . "role"))) (meta (@ (content . "#configuration #manual #zettelstore") (name . "tags"))) (meta (@ (content . "zmk") (name . "syntax"))) (meta (@ (content . "00001003300000 00001003310000 00001004000000 00001004050000 00001004051100 00001005000000 00001005090000 00001006020000 00001007031200 00001007040310 00001008010000 00001008010500 00001010070200 00001012050200 00001012054600 00001012920000 00001017000000 00001018000000") (name . "back"))) (meta (@ (content . "00001003300000 00001003310000 00001004000000 00001004011200 00001004011400 00001004050000 00001004051000 00001004051100 00001004100000 00001005000000 00001005090000 00001006020000 00001007031200 00001007040310 00001008000000 00001008010000 00001008010500 00001010000000 00001010040100 00001010040700 00001010070200 00001010090100 00001012050200 00001012054600 00001012920000 00001017000000 00001018000000") (name . "backward"))) (meta (@ (content . "1") (name . "box-number"))) (meta (@ (content . "(c) 2020-present by Detlef Stern <ds@zettelstore.de>") (name . "copyright"))) (meta (@ (content . "20210126175322") (name . "created"))) (meta (@ (content . "00001004011200 00001004011400 00001004020000 00001004051000 00001004059700 00001004100000 00001004101000 00001006030500 00001006050000 00001008000000 00001010000000 00001010040100 00001010040700 00001010090100 00001012000000 00001014000000") (name . "forward"))) (meta (@ (content . "en") (name . "lang"))) (meta (@ (content . "EUPL-1.2-or-later") (name . "license"))) (meta (@ (content . "20240220190138") (name . "modified"))) (meta (@ (content . "20240220190138") (name . "published"))) (meta (@ (content . "public") (name . "visibility")))) (p "The" " " "configuration" " " "file," " " "as" " " "specified" " " "by" " " "the" " " (kbd "-c CONFIGFILE") " " (a (@ (href . "00001004051000")) "command" " " "line" " " "option") "," " " "allows" " " "you" " " "to" " " "specify" " " "some" " " "startup" " " "options." " " "These" " " "options" " " "cannot" " " "be" " " "stored" " " "in" " " "a" " " (a (@ (href . "00001004020000")) "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.") (p "The" " " "file" " " "for" " " "startup" " " "configuration" " " "must" " " "be" " " "created" " " "via" " " "a" " " "text" " " "editor" " " "in" " " "advance.") (p "The" " " "syntax" " " "of" " " "the" " " "configuration" " " "file" " " "is" " " "the" " " "same" " " "as" " " "for" " " "any" " " "zettel" " " "metadata." " " "The" " " "following" " " "keys" " " "are" " " "supported:") (dl (dt (a (@ (id . "admin-port")) (kbd "admin-port"))) (dd (p "Specifies" " " "the" " " "TCP" " " "port" " " "through" " " "which" " " "you" " " "can" " " "reach" " " "the" " " (a (@ (href . "00001004100000")) "administrator" " " "console") "." " " "A" " " "value" " " "of" " " (@L (@H "&ldquo;") "0" (@H "&rdquo;")) " " "(the" " " "default)" " " "disables" " " "the" " " "administrator" " " "console." " " "The" " " "administrator" " " "console" " " "will" " " "only" " " "be" " " "enabled" " " "if" " " "Zettelstore" " " "is" " " "started" " " "with" " " "the" " " (a (@ (href . "00001004051000")) (kbd "run") " " "sub-command") ".") (p "On" " " "most" " " "operating" " " "systems," " " "the" " " "value" " " "must" " " "be" " " "greater" " " "than" " " (@L (@H "&ldquo;") "1024" (@H "&rdquo;")) " " "unless" " " "you" " " "start" " " "Zettelstore" " " "with" " " "the" " " "full" " " "privileges" " " "of" " " "a" " " "system" " " "administrator" " " "(which" " " "is" " " "not" " " "recommended).") (p "Default:" " " (@L (@H "&ldquo;") "0" (@H "&rdquo;")))) (dt (a (@ (id . "asset-dir")) (kbd "asset-dir"))) (dd (p "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" " " (kbd "/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.") (p "Files" " " "within" " " "the" " " "given" " " "directory" " " "will" " " "not" " " "be" " " "managed" " " "by" " " "Zettelstore." (sup (@ (id . "fnref:1")) (a (@ (class . "zs-noteref") (href . "#fn:1") (role . "doc-noteref")) "1"))) (p "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" " " (@L (@H "&ldquo;") "index.html" (@H "&rdquo;")) ".") (p "Default:" " " (@L (@H "&ldquo;" "&rdquo;")) "," " " "no" " " "asset" " " "directory" " " "is" " " "set," " " "the" " " "URL" " " "prefix" " " (kbd "/assets/") " " "is" " " "invalid.")) (dt (a (@ (id . "base-url")) (kbd "base-url"))) (dd (p "Sets" " " "the" " " "absolute" " " "base" " " "URL" " " "for" " " "the" " " "service.") (p "Note:" " " (a (@ (href . "#url-prefix")) (kbd "url-prefix")) " " "must" " " "be" " " "the" " " "suffix" " " "of" " " (kbd "base-url") "," " " "otherwise" " " "the" " " "web" " " "service" " " "will" " " "not" " " "start." " " " " "Default:" " " (@L (@H "&ldquo;") "http://127.0.0.1:23123/" (@H "&rdquo;")) ".")) (dt (a (@ (id . "box-uri-x")) (kbd "box-uri-X")) "," " " "where" " " (em "X") " " "is" " " "a" " " "number" " " "greater" " " "or" " " "equal" " " "to" " " "one") (dd (p "Specifies" " " "a" " " (a (@ (href . "00001004011200")) "box") " " "where" " " "zettel" " " "are" " " "stored." " " "During" " " "startup" " " (em "X") " " "is" " " "counted" " " "up," " " "starting" " " "with" " " "one," " " "until" " " "no" " " "key" " " "is" " " "found." " " "This" " " "allows" " " "to" " " "configure" " " "more" " " "than" " " "one" " " "box.") (p "If" " " "no" " " (kbd "box-uri-1") " " "key" " " "is" " " "given," " " "the" " " "overall" " " "effect" " " "will" " " "be" " " "the" " " "same" " " "as" " " "if" " " "only" " " (kbd "box-uri-1") " " "was" " " "specified" " " "with" " " "the" " " "value" " " (@L (@H "&ldquo;") "dir://.zettel" (@H "&rdquo;")) "." " " "In" " " "this" " " "case," " " "even" " " "a" " " "key" " " (kbd "box-uri-2") " " "will" " " "be" " " "ignored.")) (dt (a (@ (id . "debug-mode")) (kbd "debug-mode"))) (dd (p "Allows" " " "to" " " "debug" " " "the" " " "Zettelstore" " " "software" " " "(mostly" " " "used" " " "by" " " "the" " " "developers)" " " "if" " " "set" " " "to" " " (a (@ (href . "00001006030500")) "true") " " "Disables" " " "any" " " "timeout" " " "values" " " "of" " " "the" " " "internal" " " "web" " " "server" " " "and" " " "does" " " "not" " " "send" " " "some" " " "security-related" " " "data." " " "Sets" " " (a (@ (href . "#log-level")) (kbd "log-level")) " " "to" " " (@L (@H "&ldquo;") "debug" (@H "&rdquo;")) ".") (p "Do" " " "not" " " "enable" " " "it" " " "for" " " "a" " " "production" " " "server.") (p "Default:" " " (@L (@H "&ldquo;") "false" (@H "&rdquo;")))) (dt (a (@ (id . "default-dir-box-type")) (kbd "default-dir-box-type"))) (dd (p "Specifies" " " "the" " " "default" " " "value" " " "for" " " "the" " " "(sub-)" " " "type" " " "of" " " (a (@ (href . "00001004011400#type")) "directory" " " "boxes") "." " " "Zettel" " " "are" " " "typically" " " "stored" " " "in" " " "such" " " "boxes.") (p "Default:" " " (@L (@H "&ldquo;") "notify" (@H "&rdquo;")))) (dt (a (@ (id . "insecure-cookie")) (kbd "insecure-cookie"))) (dd (p "Must" " " "be" " " "set" " " "to" " " (a (@ (href . "00001006030500")) "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.") (p "Default:" " " (@L (@H "&ldquo;") "false" (@H "&rdquo;")))) (dt (a (@ (id . "insecure-html")) (kbd "insecure-html"))) (dd (p "Allows" " " "to" " " "use" " " "HTML," " " "e.g." " " "within" " " "supported" " " "markup" " " "languages," " " "even" " " "if" " " "this" " " "might" " " "introduce" " " "security-related" " " "problems." " " "However," " " "HTML" " " "containing" " " "the" " " (code "<script>") " " "or" " " "the" " " (code "<iframe>") " " "tag" " " "is" " " "always" " " "ignored." " " "But" " " "due" " " "to" " " (@L (@H "&ldquo;") "clever" (@H "&rdquo;")) " " "ways" " " "of" " " "combining" " " "HTML," " " "CSS," " " "JavaScript," " " "there" " " "might" " " "be" " " "some" " " "negative" " " "security" " " "consequences." " " "Please" " " "be" " " "aware" " " "of" " " "this!") (p "Allowed" " " "values:" " " (@L (@H "&ldquo;") "html" (@H "&rdquo;")) " " "(allow" " " "zettel" " " "with" " " (a (@ (href . "00001008000000#html")) "syntax" " " (@L (@H "&ldquo;") "html" (@H "&rdquo;"))) ")," " " (@L (@H "&ldquo;") "markdown" (@H "&rdquo;")) " " "(" (@L (@H "&ldquo;") "html" (@H "&rdquo;")) "," " " "plus" " " "allow" " " "inline" " " "HTML" " " "for" " " "Markdown" " " "markup" " " "only)," " " (@L (@H "&ldquo;") "zettelmarkup" (@H "&rdquo;")) " " "(" (@L (@H "&ldquo;") "markdown" (@H "&rdquo;")) "," " " "plus" " " "allow" " " "inline" " " "HTML" " " "for" " " "Zettelmarkup)." " " "Any" " " "other" " " "value" " " "is" " " "interpreted" " " "as" " " (@L (@H "&ldquo;") "secure" (@H "&rdquo;")) ".") (p "Default:" " " (@L (@H "&ldquo;") "secure" (@H "&rdquo;")) ".")) (dt (a (@ (id . "listen-addr")) (kbd "listen-addr"))) (dd (p "Configures" " " "the" " " "network" " " "address," " " "where" " " "the" " " "Zettelstore" " " "service" " " "is" " " "listening" " " "for" " " "requests." " " "Syntax" " " "is:" " " (kbd "[NETWORKIP]:PORT") "," " " "where" " " (kbd "NETWORKIP") " " "is" " " "the" " " "IP-address" " " "of" " " "the" " " "networking" " " "interface" " " "(or" " " "something" " " "like" " " (@L (@H "&ldquo;") "0.0.0.0" (@H "&rdquo;")) " " "if" " " "you" " " "want" " " "to" " " "listen" " " "on" " " "all" " " "network" " " "interfaces," " " "and" " " (kbd "PORT") " " "is" " " "the" " " "TCP" " " "port.") (p "Default" " " "value:" " " (@L (@H "&ldquo;") "127.0.0.1:23123" (@H "&rdquo;")))) (dt (a (@ (id . "log-level")) (kbd "log-level"))) (dd (p "Specify" " " "the" " " (a (@ (href . "00001004059700")) "logging" " " "level") " " "for" " " "the" " " "whole" " " "application" " " "or" " " "for" " " "a" " " "given" " " "(internal)" " " "service," " " "overwriting" " " "the" " " "level" " " (@L (@H "&ldquo;") "debug" (@H "&rdquo;")) " " "set" " " "by" " " "configuration" " " (a (@ (href . "#debug-mode")) (kbd "debug-mode")) "." " " "Can" " " "be" " " "changed" " " "at" " " "runtime," " " "even" " " "for" " " "specific" " " "internal" " " "services," " " "with" " " "the" " " (kbd "log-level") " " "command" " " "of" " " "the" " " (a (@ (href . "00001004101000#log-level")) "administrator" " " "console") ".") (p "Several" " " "specifications" " " "are" " " "separated" " " "by" " " "the" " " "semicolon" " " "character" " " "(" (@L (@H "&ldquo;") (kbd ";") (@H "&rdquo;")) "," " " "U+003B)." " " "Each" " " "specification" " " "consists" " " "of" " " "an" " " "optional" " " "service" " " "name," " " "together" " " "with" " " "the" " " "colon" " " "character" " " "(" (@L (@H "&ldquo;") (kbd ":") (@H "&rdquo;")) "," " " "U+003A)," " " "followed" " " "by" " " "the" " " "logging" " " "level.") (p "Default:" " " (@L (@H "&ldquo;") "info" (@H "&rdquo;")) ".") (p "Examples:" " " (@L (@H "&ldquo;") "error" (@H "&rdquo;")) " " "will" " " "produce" " " "just" " " "error" " " "messages" " " "(e.g." " " "no" " " (@L (@H "&ldquo;") "info" (@H "&rdquo;")) " " "messages);" " " (@L (@H "&ldquo;") "error;web:debug" (@H "&rdquo;")) " " "will" " " "emit" " " "debugging" " " "messages" " " "for" " " "the" " " "web" " " "component" " " "of" " " "Zettelstore" " " "while" " " "still" " " "producing" " " "error" " " "messages" " " "for" " " "all" " " "other" " " "components.") (p "When" " " "you" " " "are" " " "familiar" " " "to" " " "operate" " " "the" " " "Zettelstore," " " "you" " " "might" " " "set" " " "the" " " "level" " " "to" " " (@L (@H "&ldquo;") "error" (@H "&rdquo;")) " " "to" " " "receive" " " "less" " " "noisy" " " "messages" " " "from" " " "the" " " "Zettelstore.")) (dt (a (@ (id . "max-request-size")) (kbd "max-request-size"))) (dd (p "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.") (p "Default:" " " "16777216" " " "(16" " " "MiB).")) (dt (a (@ (id . "owner")) (kbd "owner"))) (dd (p (a (@ (href . "00001006050000")) "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" " " (a (@ (href . "00001010000000")) "authentication") " " "is" " " "enabled.") (p "Ensure" " " "that" " " "key" " " (a (@ (href . "#secret")) (kbd "secret")) " " "is" " " "set" " " "to" " " "a" " " "value" " " "of" " " "at" " " "least" " " "16" " " "bytes." " " "Otherwise" " " "the" " " "Zettelstore" " " "will" " " "not" " " "start" " " "for" " " "security" " " "reasons.")) (dt (a (@ (id . "persistent-cookie")) (kbd "persistent-cookie"))) (dd (p "A" " " (a (@ (href . "00001006030500")) "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.") (p "If" " " (@L (@H "&ldquo;") "true" (@H "&rdquo;")) "," " " "a" " " "persistent" " " "cookie" " " "is" " " "used." " " "Its" " " "lifetime" " " "exceeds" " " "the" " " "lifetime" " " "of" " " "the" " " "authentication" " " "token" " " "(see" " " "option" " " (kbd "token-lifetime-html") ")" " " "by" " " "30" " " "seconds.") (p "Default:" " " (@L (@H "&ldquo;") "false" (@H "&rdquo;")))) (dt (a (@ (id . "read-only-mode")) (kbd "read-only-mode"))) (dd (p "Puts" " " "the" " " "Zettelstore" " " "service" " " "into" " " "a" " " "read-only" " " "mode," " " "if" " " "set" " " "to" " " "a" " " (a (@ (href . "00001006030500")) "true" " " "value") "." " " "No" " " "changes" " " "are" " " "possible.") (p "Default:" " " (@L (@H "&ldquo;") "false" (@H "&rdquo;")) ".")) (dt (a (@ (id . "secret")) (kbd "secret"))) (dd (p "A" " " "string" " " "value" " " "to" " " "make" " " "the" " " "communication" " " "with" " " "external" " " "clients" " " "strong" " " "enough" " " "so" " " "that" " " "sessions" " " "of" " " "the" " " (a (@ (href . "00001014000000")) "web" " " "user" " " "interface") " " "or" " " (a (@ (href . "00001010040700")) "API" " " "access" " " "token") " " "cannot" " " "be" " " "modified" " " "by" " " "some" " " "external" " " "unfriendly" " " "party." " " "The" " " "string" " " "must" " " "have" " " "a" " " "length" " " "of" " " "at" " " "least" " " "16" " " "bytes.") (p "It" " " "is" " " "only" " " "needed" " " "to" " " "set" " " "this" " " "value," " " "if" " " (a (@ (href . "00001010040100")) "authentication" " " "is" " " "enabled") " " "by" " " "setting" " " "key" " " (a (@ (href . "#owner")) (kbd "owner")) " " "to" " " "some" " " "user" " " "identification.")) (dt (a (@ (id . "token-lifetime-api")) (kbd "token-lifetime-api")) "," " " (a (@ (id . "token-lifetime-html")) (kbd "token-lifetime-html"))) (dd (p "Define" " " "lifetime" " " "of" " " "access" " " "tokens" " " "in" " " "minutes." " " "Values" " " "are" " " "only" " " "valid" " " "if" " " "authentication" " " "is" " " "enabled," " " "i.e." " " "key" " " (kbd "owner") " " "is" " " "set.") (p (kbd "token-lifetime-api") " " "is" " " "for" " " "accessing" " " "Zettelstore" " " "via" " " "its" " " (a (@ (href . "00001012000000")) "API") "." " " "Default:" " " (@L (@H "&ldquo;") "10" (@H "&rdquo;")) ".") (p (kbd "token-lifetime-html") " " "specifies" " " "the" " " "lifetime" " " "for" " " "the" " " "HTML" " " "views." " " "It" " " "is" " " "automatically" " " "extended," " " "when" " " "a" " " "new" " " "HTML" " " "view" " " "is" " " "rendered." " " "Default:" " " (@L (@H "&ldquo;") "60" (@H "&rdquo;")) ".")) (dt (a (@ (id . "url-prefix")) (kbd "url-prefix"))) (dd (p "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" " " "(" (@L (@H "&ldquo;") (kbd "/") (@H "&rdquo;")) "," " " "U+002F).") (p "Note:" " " (kbd "url-prefix") " " "must" " " "be" " " "the" " " "suffix" " " "of" " " (a (@ (href . "#base-url")) (kbd "base-url")) "," " " "otherwise" " " "the" " " "web" " " "service" " " "will" " " "not" " " "start.") (p "Default:" " " (@L (@H "&ldquo;") "/" (@H "&rdquo;")) ".") (p "This" " " "allows" " " "to" " " "use" " " "a" " " "forwarding" " " "proxy" " " (a (@ (href . "00001010090100")) "server") " " "in" " " "front" " " "of" " " "the" " " "Zettelstore.")) (dt (a (@ (id . "verbose-mode")) (kbd "verbose-mode"))) (dd (p "Be" " " "more" " " "verbose" " " "when" " " "logging" " " "data," " " "if" " " "set" " " "to" " " "a" " " (a (@ (href . "00001006030500")) "true" " " "value") ".") (p "Default:" " " (@L (@H "&ldquo;") "false" (@H "&rdquo;"))))))