diff --git a/hst/config.go b/hst/config.go index f5689a4..4fd3fa9 100644 --- a/hst/config.go +++ b/hst/config.go @@ -18,86 +18,91 @@ const ( MaxWaitDelay = 30 * time.Second ) -// Config is used to seal an app implementation. type ( + // Config configures an application container, implemented in internal/app. Config struct { - // reverse-DNS style arbitrary identifier string from config; - // passed to wayland security-context-v1 as application ID - // and used as part of defaults in dbus session proxy + // Reverse-DNS style configured arbitrary identifier string. + // Passed to wayland security-context-v1 and used as part of defaults in dbus session proxy. ID string `json:"id"` - // absolute path to executable file + // Pathname to executable file in the container filesystem. Path *container.Absolute `json:"path,omitempty"` - // final args passed to container init + // Final args passed to the initial program. Args []string `json:"args"` - // system services to make available in the container + // System services to make available in the container. Enablements *Enablements `json:"enablements,omitempty"` - // session D-Bus proxy configuration; - // nil makes session bus proxy assume built-in defaults + // Session D-Bus proxy configuration. + // If set to nil, session bus proxy assume built-in defaults. SessionBus *dbus.Config `json:"session_bus,omitempty"` - // system D-Bus proxy configuration; - // nil disables system bus proxy + // System D-Bus proxy configuration. + // If set to nil, system bus proxy is disabled. SystemBus *dbus.Config `json:"system_bus,omitempty"` - // direct access to wayland socket; when this gets set no attempt is made to attach security-context-v1 - // and the bare socket is mounted to the sandbox + // Direct access to wayland socket, no attempt is made to attach security-context-v1 + // and the bare socket is made available to the container. DirectWayland bool `json:"direct_wayland,omitempty"` - // passwd username in container, defaults to passwd name of target uid or chronos + // String used as the username of the emulated user, validated against the default NAME_REGEX from adduser. + // Defaults to passwd name of target uid or chronos. Username string `json:"username,omitempty"` - // absolute path to shell + // Pathname of shell in the container filesystem to use for the emulated user. Shell *container.Absolute `json:"shell"` - // directory to enter and use as home in the container mount namespace + // Directory in the container filesystem to enter and use as the home directory of the emulated user. Home *container.Absolute `json:"home"` - // extra acl ops to perform before setuid + // Extra acl update ops to perform before setuid. ExtraPerms []*ExtraPermConfig `json:"extra_perms,omitempty"` - // numerical application id, used for init user namespace credentials + // Numerical application id, passed to hsu, used to derive init user namespace credentials. Identity int `json:"identity"` - // list of supplementary groups inherited by container processes + // Init user namespace supplementary groups inherited by all container processes. Groups []string `json:"groups"` - // abstract container configuration baseline + // High level configuration applied to the underlying [container.Params]. Container *ContainerConfig `json:"container"` } - // ContainerConfig describes the container configuration baseline to which the app implementation adds upon. + // ContainerConfig describes the container configuration to be applied to an underlying [container.Params]. ContainerConfig struct { - // container hostname + // Container UTS namespace hostname. Hostname string `json:"hostname,omitempty"` - // duration to wait for after interrupting a container's initial process in nanoseconds; - // a negative value causes the container to be terminated immediately on cancellation + // Duration in nanoseconds to wait for after interrupting the initial process. + // Defaults to [DefaultWaitDelay] if less than or equals to zero, + // or [MaxWaitDelay] if greater than [MaxWaitDelay]. WaitDelay time.Duration `json:"wait_delay,omitempty"` - // disable project-specific filter extensions + // Emit Flatpak-compatible seccomp filter programs. SeccompCompat bool `json:"seccomp_compat,omitempty"` - // allow ptrace and friends + // Allow ptrace and friends. Devel bool `json:"devel,omitempty"` - // allow userns creation in container + // Allow userns creation and container setup syscalls. Userns bool `json:"userns,omitempty"` - // share host net namespace + // Share host net namespace. HostNet bool `json:"host_net,omitempty"` - // share abstract unix socket scope + // Share abstract unix socket scope. HostAbstract bool `json:"host_abstract,omitempty"` - // allow dangerous terminal I/O + // Allow dangerous terminal I/O (faking input). Tty bool `json:"tty,omitempty"` - // allow multiarch + // Allow multiarch. Multiarch bool `json:"multiarch,omitempty"` - // initial process environment variables + // Initial process environment variables. Env map[string]string `json:"env"` - // map target user uid to privileged user uid in the user namespace; - // some programs fail to connect to dbus session running as a different uid, - // this option works around it by mapping priv-side caller uid in container + + /* Map target user uid to privileged user uid in the container user namespace. + + Some programs fail to connect to dbus session running as a different uid, + this option works around it by mapping priv-side caller uid in container. */ MapRealUID bool `json:"map_real_uid"` - // pass through all devices + // Mount /dev/ from the init mount namespace as-is in the container mount namespace. Device bool `json:"device,omitempty"` - // container mount points; - // if the first element targets /, it is inserted early and excluded from path hiding + + /* Container mount points. + + If the first element targets /, it is inserted early and excluded from path hiding. */ Filesystem []FilesystemConfigJSON `json:"filesystem"` } )