daemon

type Config struct {
	// DataDir is where the daemon keeps what persists: the definitions of
	// instances, networks, volumes, kernels and tokens, the images, the
	// instances' disks, and the certificate it makes for itself. Unset is
	// /var/lib/dicer.
	DataDir string `yaml:"data_dir,omitempty"`

	// RunDir is where the daemon keeps runtime state: sockets, config disks
	// and the record of what is running. It should be a tmpfs, so that a
	// reboot clears it. Unset is /run/dicer.
	RunDir string `yaml:"run_dir,omitempty"`

	// Server is where the API is served: always on a Unix socket, and over
	// TCP too if server.listen is set.
	Server ServerConfig `yaml:"server"`

	// Resources is how much CPU and memory instances may be given, all
	// together: the host's CPUs times cpu_overcommit, and its memory less
	// reserved_memory_bytes times memory_overcommit. A start that would take
	// more is refused.
	Resources ResourcesConfig `yaml:"resources"`

	// Network is the host's networking.
	Network NetworkConfig `yaml:"network"`

	// Metrics is the Prometheus endpoint, served at `/metrics` without
	// authentication. Metrics are always recorded: this decides only whether
	// they are served.
	Metrics MetricsConfig `yaml:"metrics"`

	// Images is image garbage collection, which removes only images no
	// instance, running guest, guest on standby or snapshot uses. It is off
	// while gc_max_unused_age and gc_max_size are both unset.
	Images ImagesConfig `yaml:"images"`

	// Events bounds the events log that dicer events shows.
	Events EventsConfig `yaml:"events"`

	// Mounts is what instances may mount from the host.
	Mounts MountsConfig `yaml:"mounts"`

	// Registries are the credentials for private registries, by host as an
	// image's name gives it: docker.io, ghcr.io, or a registry's host:port.
	// Images from any other registry are pulled anonymously.
	//
	//	registries:
	//	  ghcr.io:
	//	    username: dicer-bot
	//	    password_file: /etc/dicerd/secrets/ghcr-token
	Registries map[string]RegistryConfig `yaml:"registries,omitempty"`

	// LogLevel is debug, info, warn or error. Unset is info.
	LogLevel string `yaml:"log_level,omitempty"`
}

type EventsConfig struct {
	// MaxCount is how many of the most recent events are kept. Unset is
	// 10000.
	MaxCount int `yaml:"max_count,omitempty"`

	// MaxAge drops events older than this, such as 720h. Unset is no limit.
	MaxAge time.Duration `yaml:"max_age,omitempty"`
}

type ImagesConfig struct {
	// GCMaxUnusedAge removes images unused for longer than this, such as
	// 168h. Unset is no limit.
	GCMaxUnusedAge time.Duration `yaml:"gc_max_unused_age,omitempty"`

	// GCMaxSize removes the least recently used images while the store is
	// larger than this, such as 50GiB. Unset is no limit.
	GCMaxSize byteSize `yaml:"gc_max_size,omitempty"`

	// GCInterval is how often garbage collection runs. Unset is 1h.
	GCInterval time.Duration `yaml:"gc_interval,omitempty"`
}

type KeepaliveConfig struct {
	// Interval is how long a connection may carry nothing before the daemon
	// pings the client. Unset is 30s.
	Interval time.Duration `yaml:"interval,omitempty"`

	// Timeout is how long the daemon waits for the answer to a ping before
	// closing the connection. Unset is 10s.
	Timeout time.Duration `yaml:"timeout,omitempty"`

	// MinClientInterval is how often a client may ping the daemon at most,
	// even with no call in flight. A client pinging more often is
	// disconnected. Dicer's clients ping every 30s unless told otherwise.
	// Unset is 10s.
	MinClientInterval time.Duration `yaml:"min_client_interval,omitempty"`
}

type MetricsConfig struct {
	// Enable serves the endpoint.
	Enable bool `yaml:"enable,omitempty"`

	// Listen is the host:port the endpoint is served on. Unset is
	// 127.0.0.1:9101.
	Listen string `yaml:"listen,omitempty"`
}

type MountsConfig struct {
	// AllowedDirectories are the host directories that instances may mount
	// with `--mount type=directory`, each with everything under it, such as
	// /srv/shared. An instance can share no other host directory, so these
	// are all of the host that the API can reach this way. A symbolic link
	// under one is followed only as far as it. Unset, no instance can mount
	// a host directory.
	AllowedDirectories []string `yaml:"allowed_directories,omitempty"`
}

type NetworkConfig struct {
	// DefaultSubnet is the subnet of the default network, which the daemon
	// creates when it first starts and an instance joins when it names no
	// network. It must not overlap a subnet the host is on. Changing it
	// later does not change the network. Unset is 172.20.0.0/16.
	DefaultSubnet string `yaml:"default_subnet,omitempty"`

	// UplinkInterface is the interface NAT traffic leaves by. Unset detects
	// it from the default route.
	UplinkInterface string `yaml:"uplink_interface,omitempty"`

	// UploadBurstMultiplier is how far an instance may briefly exceed its
	// upload rate limit, as a multiple of it. Unset is 4.
	UploadBurstMultiplier int `yaml:"upload_burst_multiplier,omitempty"`

	// DownloadBurstMultiplier is how far an instance may briefly exceed its
	// download rate limit, as a multiple of it. Unset is 4.
	DownloadBurstMultiplier int `yaml:"download_burst_multiplier,omitempty"`

	// DNS answers guests' DNS queries on each network's gateway address, so
	// that an instance can reach another on its network by name; other names
	// are forwarded to the network's nameservers. Off, guests ask those
	// nameservers directly. Unset is true.
	DNS bool `yaml:"dns"`
}

type RegistryConfig struct {
	// Username is the user to log in as.
	Username string `yaml:"username,omitempty"`

	// Password is the password or token to log in with, and PasswordFile a
	// file holding it, readable only by root. Give one or the other.
	Password     string `yaml:"password,omitempty"`
	PasswordFile string `yaml:"password_file,omitempty"`

	// CredentialHelper names a `docker-credential-<name>` program on the
	// daemon's PATH, such as ecr-login, that gives the credentials instead of
	// username and password: for a registry whose tokens expire.
	CredentialHelper string `yaml:"credential_helper,omitempty"`
}

type ResourcesConfig struct {
	// CPUOvercommit is how many vCPUs instances may be given per host CPU.
	// Unset is 4.
	CPUOvercommit float64 `yaml:"cpu_overcommit,omitempty"`

	// MemoryOvercommit multiplies the memory available to instances: 1 never
	// promises more memory than the host has. Unset is 1.
	MemoryOvercommit float64 `yaml:"memory_overcommit,omitempty"`

	// ReservedMemoryBytes is the memory, in bytes, kept back for the host and
	// the hypervisors' overhead. Unset is 1073741824, 1 GiB.
	ReservedMemoryBytes int64 `yaml:"reserved_memory_bytes,omitempty"`
}

type ServerConfig struct {
	// Listen is the host:port to serve the API on over TCP, such as
	// 0.0.0.0:7443. Unset, the API is served on the socket alone. Over TCP,
	// every connection uses TLS 1.3, and every call needs a token, which
	// `dicer token create` makes. Guests cannot reach it, on any of the
	// host's addresses.
	Listen string `yaml:"listen,omitempty"`

	// CrtFile is the PEM certificate the API is served with over TCP. It
	// must name the address clients connect to, and is reloaded when it
	// changes on disk. Unset, the daemon makes a certificate of its own and
	// keeps it in data_dir. Every token then carries its fingerprint, so
	// clients need nothing else to check the daemon by.
	CrtFile string `yaml:"crt_file,omitempty"`

	// KeyFile is the PEM private key of crt_file. It is reloaded when it
	// changes on disk.
	KeyFile string `yaml:"key_file,omitempty"`

	// Socket is the local Unix socket. Anyone who can open it has full
	// control of the daemon.
	Socket SocketConfig `yaml:"socket"`

	// Keepalive is how the daemon finds clients that have gone without
	// closing their connection, because their host lost power or the network
	// between dropped, and how often clients may check the same of it. Such
	// a connection otherwise lasts until the kernel gives up on it, which
	// can take a quarter of an hour.
	Keepalive KeepaliveConfig `yaml:"keepalive"`
}

type SocketConfig struct {
	// Path is the socket's path. Unset is /run/dicer/dicer.sock.
	Path string `yaml:"path,omitempty"`

	// Mode is the socket's permission bits. Unset is 0660.
	Mode uint32 `yaml:"mode,omitempty"`

	// Group is the group the socket belongs to, by name or ID. Its members
	// can use the API as far as mode lets the group, which is as much as root
	// on this host. Unset leaves the socket root's alone.
	Group string `yaml:"group,omitempty"`
}