# Sample configuration file for Zeitgitter
# (Section names are optional and were added just for clarity)
#
# :warning: PARAMETER PRIORITY
#
# Please note that `zeitgitterd` (and many other programs relying on
# [ConfigArgParse](https://pypi.org/project/ConfigArgParse/) will
# enforce the following parameter priority:
#
# 1. (Highest) Command line supplied parameters
# 2. Parameters from environment variables (`ZEITGITTER_*`)
#    **including environment variables supplied by Docker**,
#    if running within a container
# 3. The options provided in this file
# 4. Defaults provided in the program
#
# So, if a change in this file seems to be ignored, check if you (or Docker)
# provides an environment variable overriding settings in here.

[Maintainer]
# HTML file substitution parameters
#
# These will be used to substitute
# `ZEITGITTER_DOMAIN`, `ZEITGITTER_CONTACT`, `ZEITGITTER_OWNER`,
# and `ZEITGITTER_COUNTRY` in the HTML files served; mostly REQUIRED.
# - ZEITGITTER_DOMAIN defaults to the host part of `own-url` below.
# - ZEITGITTER_OWNER should list everyone with access to the private key
#   (i.e., who could issue fake timestamps).
# - ZEITGITTER_CONTACT should have some contact information.
# - ZEITGITTER_COUNTRY should name the jurisdiction the server is operated in.
# They are all required except ZEITGITTER_DOMAIN.
; domain = hagrid.snakeoil
## EASYCONFIG: Add your (real) name
; owner = Rubeus Hagrid
## EASYCONFIG: Add contact information (HTML possible)
; contact = <a href="mailto:rubeus@hagrid.snakeoil">Rubeus Hagrid</a><br/>Hogwarts
## EASYCONFIG: Add your server's jurisdiction
; country = Scotland


[Server]
# Our own URL; REQUIRED
## EASYCONFIG: Specify the URL of this server
; own-url = https://hagrid.snakeoil

# Debugging level
# Comma-separated list of [name=]value pairs.
# Specifies the log level for a particular subsystem:
# - The empty name (`root`): Default log level
# - `config`: Processing configuration
# - `server`: Man loop and request processing
# - `stamper`: Timestamping itself (server-side)
# - `commit`: Committing the timestamping log and requesting cross-timestamps
# - `gnupg`: Cryptographic operations performed by gnupg
# - `mail`: PGP Timestamping Server-related mail processing
# The log level can be one of the following: WARN, INFO, or DEBUG.
# Default: INFO
; debug-level = INFO
; debug-level = DEBUG,gnupg=INFO

# Webroot, if it needs to serve any web pages
# Default: Look inside the package
; webroot = /var/lib/zeitgitter/web

# Listening address and port
#
# Default: 127.0.0.1 (as some systems have IPv6 disabled) and 15177
# Note: systemd startup defaults to 127.0.0.1:15177
# Note: Docker containers default to 0.0.0.0:15177
; listen-address = ::1
; listen-port = 15177

# `Cache-Control` HTTP header for static pages
#
# Default: max-age=86400, stale-while-revalidate=86400, stale-if-error=86400
; cache-control-static = max-age=86400, stale-while-revalidate=86400, stale-if-error=86400

[GIT]
# The GIT repository to use
#
# Default: $HOME/repo
; repository = /var/lib/zeitgitter/repo

# Rotate/commit/publish interval and offset
#
# `commit-interval`: Duration of the interval.
# `commit-offset`: Time relative to the start of the interval.
#
# It is important that the activity times do not cluster up, so please use
# an offset which nobody else uses; and an offset of 0 is generally not
# advisable, as other systems will already have activity then.
#
# So chose an interval reflecting the frequency you want to commit and publish,
# and chose a seemingly random offset in that period. Try to avoid the full
# hours and/or minutes, whenever possible; i.e., specify non-zero
# minutes/seconds. See `.../doc/ServerList.md` for additional advice.
#
# The interval and offset are relative to UTC (actually, relative to the Epoch,
# i.e., 1970-01-01 00:00:00 UTC)
#
# :warning: If you are using the PGP Timestamper as an upstream
# commitment, please make sure that this does not trigger more than once
# an hour. (The PGP Timestamper can delay the commit by 5 minutes and
# more and Zeitgitter will wait for an answer for up to 15 minutes
# before continuing, so anything more frequent than this will cause
# chaos in your repository.)
#
# Time format: (Fractional) days, hours, minutes, and seconds,
# optionally separated by spaces, e.g. "1.5d", "3h 7m 3.5s", "8h20m17s".
# The `s` for seconds can be omitted.
#
# Examples:
# - commit-interval=1d, commit-offset=7h37m16s
# - commit-interval=4h, commit-offset=1h18m44s
# - commit-interval=1h, commit-offset=23m17s
# Default: 4h
; commit-interval = 4h

# Assigning no value will pick a random offset at every service start.
#
# Default: random in [0, commit-interval), avoiding the first/last 5%.
; commit-offset =

# Space-separated list of repositories to push to
#
# Setting this enables automatic push
; push-repository = origin
; push-repository = repo1 repo2 repo3

# Space-separated list of branches to push
#
# If empty, the GIT default value is used.
# Applies to all repositories specified above.
# Note: You cannot specify `--all` or a list due to ConfigArgParse limitations,
# use the special value `*` instead (without the quotes), which will be
# translated to `--all`.
#
# Default: * (meaning `--all`)
; push-branch = master gitta-timestamps dumbledore-timestamps


[GnuPG]
# The place where to look for the GnuPG files
#
# Default: $GNUPGHOME or $HOME/.gnupg
# (variable substition not supported in this config file, sorry!)
; gnupg-home = /var/lib/zeitgitter/.gnupg

# Our own PGP key used to timestamp with
#
# This key should be created for this purpose only!
# Use a long signing key, see ../doc/Cryptography.md for more information.
#
# Normally, this should be set to the (hexadecimal) key ID of a key which you
# previously created for exactly this purpose. However, if you specify a valid
# PGP UID, such as "Hagrid Timestomping Service <timestomping@hagrid.snakeoil>"
# (without the quotes), then a fresh (Ed25519) key will be created for you on
# first launch.
#
# When using a full address to create a new key for you, the address for each
# timestamper should be unique; and you may want to refer to "stamping"
# instead of "stomping" in a non-test environment.
#
# Changing the ID later is not recommended, as all clients will record the
# key ID, typically in their "global" git configuration (often,
# `~/.gitconfig`). Changing the Key ID will require all of them to remove
# the key before trusting the new key. (Just changing the primary UID name by
# adding an additional UID will not have this problem.) In case you are
# changing the key due to (potential) key compromise, it is recommended to
# set up a new server at a new URL instead.
## EASYCONFIG: Set this to the (unique) PGP UID of your service, e.g.
## "Service Name <service@email.address>" (without the quotes) to
## autogenerate a key by that name.
; keyid = 0123456789ABCDEF

# Maximum of simultaneous signature operations
#
# Please note that GnuPG normally serializes all private key operations through
# a single, single-threaded gpg-agent, resulting in almost no parallelism
# gain. So increasing this probably does not start using significantly more
# than one core, unless you also activate the following hack, sorry!
#
# Default: 2
; max-parallel-signatures = 2

# Number of separate gpg-agents to run
#
# This is a (ugly) hack to work around the limitation above by "convincing"
# GnuPG that it should run several `gpg-agent`s and use them in round-robin
# fashion. This allows increasing `max-parallel-signatures` above.
#
# This is done by creating a copy of the `gnupg-home` directory; symlinks used
# by previous versions will be upgraded (GnuPG became too clever for them).
#
# :warning: If you ever make modifications to any of the directories, make
# sure that all others are updated as well. (If the modification was done to
# the "main" directory (the one specified by `gnupg-home`), then the
# automatically created copies can be removed and will be recreated on the
# next start.
#
# :warning: Updating or (especially) removing the directories while Zeitgitter
# is running may result in requests which cannot be handled and should
# therefore only be done after it has been terminated.
#
# To maximize the use of available processor cores, set this to slightly
# higher than the number of actual cores and set `max-parallel-signatures`
# slightly higher than this.
#
# If you set this higher than 1, you also need to set `gnupg-home` above.
#
# Default: 1
; number-of-gpg-agents = 1

# Maximum waiting time for a signature operation slot
#
# When `max-parallel-signatures` signatures are already being signed,
# *additional* requests will wait up to `max-parallel-timeout` seconds
# for an available signature process before being rejected.
#
# Can be set to a floating-point value to define the number of seconds
#
# Default: None (forever)
; max-parallel-timeout = 3.14


[Zeitgitter Upstream]
# Space separated list of upstream Zeitgitter servers
#
# Should not include itself
# Any number of <branch>=<URL> tuples or server names only. For server-name
# only, the branch name is determined by `git timestamp`.
# Examples:
# - gitta-timestamps=https://gitta.zeitgitter.net
# - diversity-timestamps=https://diversity.zeitgitter.net
# - more-diversity-timestamps=diversity
# - my-personal-server.example.com
#
# Default: gitta diversity (which is the same as
#   gitta-timestamps=https://gitta.zeitgitter.net
#   diversity-timestamps=https://diversity.zeitgitter.net)
; upstream-timestamp = gitta diversity


[PGP Timestamper]
# Our email address to use when communicating with the PGP timestamper
#
# Setting this activates using the PGP timestamper as an upstream
; stamper-own-address = timestomper@hagrid.snakeoil

# The key ID the stamper uses
#
# :warning: Needs to have been imported into the public keyring!
# Default: 70B61F81
; stamper-keyid = 70B61F81

# The email address of the timestamping service
# when sending messages to it.
#
# Default: clear@stamper.itconsult.co.uk
; stamper-to = clear@stamper.itconsult.co.uk

# The email address of the timestamping service
# when receiving replies.
#
# Default: mailer@stamper.itconsult.co.uk
; stamper-from = mailer@stamper.itconsult.co.uk

# IMAP and SMTP server names to use, username and password for
# authentication.
#
# IMAP and SMTP servers names may optionally be suffixed by `:<port>`.
# That port (or the default ports 143 and 587, respectively) *must*
# support STARTTLS. Direct TLS connections are not supported.
#
# `stamper-username` defaults to the value of `stamper-own-address`
; stamper-imap-server = imap.hagrid.snakeoil
; stamper-smtp-server = smtp.hagrid.snakeoil
; stamper-username = timestomper@hagrid.snakeoil
; stamper-password = OlympeMaxime62ca7b338c73f2d
