hst

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 11, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package hst exports stable shared types for interacting with hakurei.

Index

Constants

View Source 
const (
	// WaitDelayDefault is used when WaitDelay has the zero value.
	WaitDelayDefault = 5 * time.Second
	// WaitDelayMax is used when WaitDelay exceeds its value.
	WaitDelayMax = 30 * time.Second
)
View Source 
const (
	// ExitFailure is returned if the container fails to start.
	ExitFailure = iota + 1
	// ExitCancel is returned if the container is terminated by a shim-directed
	// signal which cancels its context.
	ExitCancel
	// ExitOrphan is returned when the shim is orphaned before priv side process
	// delivers a signal.
	ExitOrphan

	// ExitRequest is returned when the priv side process requests shim exit.
	ExitRequest = 254
)
View Source 
const (
	// UserOffset is the offset for UID and GID ranges for each user.
	UserOffset = 100000
	// RangeSize is the size of each UID and GID range.
	RangeSize = UserOffset / 10

	// IdentityStart is the first [Config.Identity] value. This is enforced in cmd/hsu.
	IdentityStart = 0
	// IdentityEnd is the last [Config.Identity] value. This is enforced in cmd/hsu.
	IdentityEnd = AppEnd - AppStart

	// AppStart is the first app user UID and GID.
	AppStart = RangeSize * 1
	// AppEnd is the last app user UID and GID.
	AppEnd = AppStart + RangeSize - 1

	// IsolatedStart is the start of UID and GID for fully isolated sandboxed processes.
	IsolatedStart = RangeSize * 9
	// IsolatedEnd is the end of UID and GID for fully isolated sandboxed processes.
	IsolatedEnd = IsolatedStart + RangeSize - 1
)
View Source 
const FilesystemBind = "bind"

FilesystemBind is the type string of a bind mount point.

View Source 
const FilesystemDaemon = "daemon"

FilesystemDaemon is the type string of a daemon.

View Source 
const FilesystemEphemeral = "ephemeral"

FilesystemEphemeral is the type string of a mount point with ephemeral state.

View Source 
const FilesystemLink = "link"

FilesystemLink is the type string of a symbolic link.

View Source 
const FilesystemOverlay = "overlay"

FilesystemOverlay is the type string of an overlay mount point.

View Source 
const PrivateTmp = "/.hakurei"

PrivateTmp is a private writable path in a hakurei container.

View Source 
const (
	// VAllowInsecure allows use of compatibility options considered insecure
	// under any configuration, to work around ecosystem-wide flaws.
	VAllowInsecure = 1 << iota
)

Variables

View Source 
var (
	// ErrConfigNull is returned by [Config.Validate] for an invalid configuration
	// that contains a null value for any field that must not be null.
	ErrConfigNull = errors.New("unexpected null in config")

	// ErrIdentityBounds is returned by [Config.Validate] for an out of bounds
	// [Config.Identity] value.
	ErrIdentityBounds = errors.New("identity out of bounds")

	// ErrSchedPolicyBounds is returned by [Config.Validate] for an out of bounds
	// [Config.SchedPolicy] value.
	ErrSchedPolicyBounds = errors.New("scheduling policy out of bounds")

	// ErrEnviron is returned by [Config.Validate] if an environment variable
	// name contains '=' or NUL.
	ErrEnviron = errors.New("invalid environment variable name")

	// ErrInsecure is returned by [Config.Validate] if the configuration is
	// considered insecure.
	ErrInsecure = errors.New("configuration is insecure")
)
View Source 
var AbsPrivateTmp = check.MustAbs(PrivateTmp)

AbsPrivateTmp is a check.Absolute representation of PrivateTmp.

View Source 
var ErrFSNull = errors.New("unexpected null in mount point")

ErrFSNull is returned by json on encountering a null FilesystemConfig value.

View Source 
var ErrIdentifierLength = errors.New("identifier string has unexpected length")

ErrIdentifierLength is returned when encountering a hex representation of ID with unexpected length.

Functions

func NewInstanceID added in v0.3.0 

func NewInstanceID(id *ID) error

NewInstanceID creates a new unique ID.

func ToUser added in v0.3.0 

func ToUser[U int | uint32](userid, appid U) U

ToUser returns a hst.UID value from userid and appid.

Not safe against untrusted input.

Types

type AppError added in v0.2.2 

type AppError struct {
	// A user-facing description of where the error occurred.
	Step string `json:"step"`
	// The underlying error value.
	Err error `json:"err"`
	// An arbitrary error message, overriding the return value of Message if not empty.
	Msg string `json:"message,omitempty"`
}

An AppError is returned while starting an app according to hst.Config.

func (*AppError) Error added in v0.2.2 

func (e *AppError) Error() string

func (*AppError) Message added in v0.2.2 

func (e *AppError) Message() string

func (*AppError) Unwrap added in v0.2.2 

func (e *AppError) Unwrap() error

type ApplyState added in v0.2.0 

type ApplyState struct {
	// Prefix for [FSBind] in autoetc [FSBind.Special] condition.
	AutoEtcPrefix string
	// Whether to skip remounting root.
	NoRemountRoot bool

	Ops
}

ApplyState holds the address of Ops and any relevant application state.

type BadInterfaceError added in v0.3.0 

type BadInterfaceError struct {
	// Interface is the offending interface string.
	Interface string
	// Segment is passed through from the [BusConfig.CheckInterfaces] argument.
	Segment string
}

BadInterfaceError is returned when Interface fails an undocumented check in xdg-dbus-proxy, which would have cause a silent failure.

xdg-dbus-proxy fails without output when this condition is not met: 

char *dot = strrchr (filter->interface, '.');
if (dot != NULL)
  {
    *dot = 0;
    if (strcmp (dot + 1, "*") != 0)
      filter->member = g_strdup (dot + 1);
  }

trim ".*" since they are removed before searching for '.': 

if (g_str_has_suffix (name, ".*"))
  {
    name[strlen (name) - 2] = 0;
    wildcard = TRUE;
  }

func (*BadInterfaceError) Error added in v0.3.0 

func (e *BadInterfaceError) Error() string

func (*BadInterfaceError) Message added in v0.3.0 

func (e *BadInterfaceError) Message() string

type BusConfig added in v0.3.0 

type BusConfig struct {
	// See set 'see' policy for NAME (--see=NAME)
	See []string `json:"see"`
	// Talk set 'talk' policy for NAME (--talk=NAME)
	Talk []string `json:"talk"`
	// Own set 'own' policy for NAME (--own=NAME)
	Own []string `json:"own"`

	// Call set RULE for calls on NAME (--call=NAME=RULE)
	Call map[string]string `json:"call"`
	// Broadcast set RULE for broadcasts from NAME (--broadcast=NAME=RULE)
	Broadcast map[string]string `json:"broadcast"`

	// Log turn on logging (--log)
	Log bool `json:"log,omitempty"`
	// Filter enable filtering (--filter)
	Filter bool `json:"filter"`
}

BusConfig configures the xdg-dbus-proxy process.

func (*BusConfig) CheckInterfaces added in v0.3.0 

func (c *BusConfig) CheckInterfaces(segment string) error

CheckInterfaces checks for invalid interface strings based on an undocumented check in xdg-dbus-error, returning BadInterfaceError if one is encountered.

func (*BusConfig) Interfaces added in v0.3.0 

func (c *BusConfig) Interfaces(yield func(string) bool)

Interfaces iterates over all interface strings specified in BusConfig.

type Config 

type Config struct {
	// Reverse-DNS style configured arbitrary identifier string.
	//
	// This value is passed as is to Wayland security-context-v1 and used as
	// part of defaults in D-Bus session proxy. The zero value causes a default
	// value to be derived from the container instance.
	ID string `json:"id,omitempty"`

	// System services to make available in the container.
	Enablements *Enablements `json:"enablements,omitempty"`

	// Session D-Bus proxy configuration.
	//
	// Has no effect if [EDBus] but is not set in Enablements. The zero value
	// assumes built-in defaults derived from ID.
	SessionBus *BusConfig `json:"session_bus,omitempty"`
	// System D-Bus proxy configuration.
	//
	// Has no effect if [EDBus] but is not set in Enablements. The zero value
	// disables system bus proxy.
	SystemBus *BusConfig `json:"system_bus,omitempty"`

	// Direct access to Wayland socket, no attempt is made to attach
	// security-context-v1 and the bare socket is made available to the
	// container.
	//
	// This option is unsupported and will most likely enable full control over
	// the Wayland session from within the container. Do not set this to true
	// unless you are sure you know what you are doing.
	DirectWayland bool `json:"direct_wayland,omitempty"`

	// Direct access to the PipeWire socket established via SecurityContext::Create,
	// no attempt is made to start the pipewire-pulse server.
	//
	// The SecurityContext machinery is fatally flawed, it unconditionally sets
	// read and execute bits on all objects for clients with the lowest achievable
	// privilege level (by setting PW_KEY_ACCESS to "restricted" or by satisfying
	// all conditions of [the /.flatpak-info hack]). This enables them to call
	// any method targeting any object, and since Registry::Destroy checks for
	// the read and execute bit, allows the destruction of any object other than
	// PW_ID_CORE as well.
	//
	// This behaviour is implemented separately in media-session and wireplumber,
	// with the wireplumber implementation in Lua via an embedded Lua vm. In all
	// known setups, wireplumber is in use, and in that case, no option for
	// configuring this behaviour exists, without replacing the Lua script.
	// Also, since PipeWire relies on these permissions to work, reducing them
	// was never possible in the first place.
	//
	// Currently, the only other sandboxed use case is flatpak, which is not
	// aware of PipeWire and blindly exposes the bare PulseAudio socket to the
	// container (behaves like DirectPulse). This socket is backed by the
	// pipewire-pulse compatibility daemon, which obtains client pid via the
	// SO_PEERCRED option. The PipeWire daemon, pipewire-pulse daemon and the
	// session manager daemon then separately performs [the /.flatpak-info hack].
	// Under such use case, since the client has no direct access to PipeWire,
	// insecure parts of the protocol are obscured by the absence of an
	// equivalent API in PulseAudio, or pipewire-pulse simply not implementing
	// them.
	//
	// Hakurei does not rely on [the /.flatpak-info hack]. Instead, a socket is
	// sets up via SecurityContext. A pipewire-pulse server connected through it
	// achieves the same permissions as flatpak does via [the /.flatpak-info hack]
	// and is maintained for the life of the container.
	//
	// This option is unsupported and enables a denial-of-service attack as the
	// sandboxed client is able to destroy any client object and thus
	// disconnecting them from PipeWire, or destroy the SecurityContext object,
	// preventing any further container creation.
	//
	// Do not set this to true, it is insecure under any configuration.
	//
	// [the /.flatpak-info hack]: https://git.gensokyo.uk/rosa/hakurei/issues/21
	DirectPipeWire bool `json:"direct_pipewire,omitempty"`

	// Direct access to PulseAudio socket, no attempt is made to establish
	// pipewire-pulse server via a PipeWire socket with a SecurityContext
	// attached, and the bare socket is made available to the container.
	//
	// This option is unsupported and enables arbitrary code execution as the
	// PulseAudio server.
	//
	// Do not set this to true, it is insecure under any configuration.
	DirectPulse bool `json:"direct_pulse,omitempty"`

	// Extra acl updates to perform before setuid.
	ExtraPerms []ExtraPermConfig `json:"extra_perms,omitempty"`

	// Numerical application id, passed to hsu, used to derive init user
	// namespace credentials.
	Identity int `json:"identity"`
	// Init user namespace supplementary groups inherited by all container processes.
	Groups []string `json:"groups"`

	// Scheduling policy to set for the container.
	//
	// The zero value retains the current scheduling policy.
	SchedPolicy ext.SchedPolicy `json:"sched_policy,omitempty"`
	// Scheduling priority to set for the container.
	//
	// The zero value implies the minimum priority of the current SchedPolicy.
	// Has no effect if SchedPolicy is zero.
	SchedPriority ext.Int `json:"sched_priority,omitempty"`

	// High level configuration applied to the underlying [container].
	Container *ContainerConfig `json:"container"`
}

Config configures an application container.

func Template 

func Template() *Config

Template returns a fully populated instance of Config.

func (*Config) Validate added in v0.3.0 

func (config *Config) Validate(flags int) error

Validate checks Config and returns AppError if an invalid value is encountered.

type ContainerConfig 

type ContainerConfig struct {
	// Container UTS namespace hostname.
	Hostname string `json:"hostname,omitempty"`

	// Duration in nanoseconds to wait for after interrupting the initial process.
	//
	// Defaults to [WaitDelayDefault] if zero, or [WaitDelayMax] if greater than
	// [WaitDelayMax]. Values lesser than zero is equivalent to zero, bypassing
	// [WaitDelayDefault].
	WaitDelay time.Duration `json:"wait_delay,omitempty"`

	// Initial process environment variables.
	Env map[string]string `json:"env"`

	// Container mount points.
	//
	// If the first element targets /, it is inserted early and excluded from
	// path hiding. Otherwise, an anonymous instance of tmpfs is set up on /.
	Filesystem []FilesystemConfigJSON `json:"filesystem"`

	// 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"`
	// Pathname of shell in the container filesystem to use for the emulated user.
	Shell *check.Absolute `json:"shell"`
	// Directory in the container filesystem to enter and use as the home
	// directory of the emulated user.
	Home *check.Absolute `json:"home"`

	// Pathname to executable file in the container filesystem.
	Path *check.Absolute `json:"path,omitempty"`
	// Final args passed to the initial program.
	Args []string `json:"args"`

	// Flags holds boolean options of [ContainerConfig].
	Flags Flags `json:"-"`
}

ContainerConfig describes the container configuration to be applied to an underlying [container]. It is validated by Config.Validate.

func (*ContainerConfig) MarshalJSON added in v0.3.0 

func (c *ContainerConfig) MarshalJSON() ([]byte, error)

func (*ContainerConfig) UnmarshalJSON added in v0.3.0 

func (c *ContainerConfig) UnmarshalJSON(data []byte) error

type ContainerConfigF added in v0.3.0 

type ContainerConfigF ContainerConfig

ContainerConfigF is ContainerConfig stripped of its methods.

The [ContainerConfig.Flags] field does not survive a json round trip.

type Enablements added in v0.2.0 

type Enablements byte

Enablements denotes optional host service to export to the target user. 

const (
	// EWayland exposes a Wayland pathname socket via security-context-v1.
	EWayland Enablements = 1 << iota
	// EX11 adds the target user via X11 ChangeHosts and exposes the X11
	// pathname socket.
	EX11
	// EDBus enables the per-container xdg-dbus-proxy daemon.
	EDBus
	// EPipeWire exposes a pipewire pathname socket via SecurityContext.
	EPipeWire
	// EPulse copies the PulseAudio cookie to [hst.PrivateTmp] and exposes the
	// PulseAudio socket.
	EPulse

	// EM is a noop.
	EM
)

func (Enablements) MarshalJSON added in v0.2.0 

func (e Enablements) MarshalJSON() ([]byte, error)

func (Enablements) String added in v0.4.0 

func (e Enablements) String() string

String returns a string representation of the flags set on Enablements.

func (*Enablements) UnmarshalJSON added in v0.2.0 

func (e *Enablements) UnmarshalJSON(data []byte) error

func (*Enablements) Unwrap added in v0.2.0 

func (e *Enablements) Unwrap() Enablements

Unwrap returns the value pointed to by e.

type ExtraPermConfig 

type ExtraPermConfig struct {
	// Whether to create Path as a directory if it does not exist.
	Ensure bool `json:"ensure,omitempty"`
	// Pathname to act on.
	Path *check.Absolute `json:"path"`
	// Whether to set ACL_READ for the target user.
	Read bool `json:"r,omitempty"`
	// Whether to set ACL_WRITE for the target user.
	Write bool `json:"w,omitempty"`
	// Whether to set ACL_EXECUTE for the target user.
	Execute bool `json:"x,omitempty"`
}

ExtraPermConfig describes an acl update to perform before setuid.

func (*ExtraPermConfig) String 

func (e *ExtraPermConfig) String() string

String returns a checked string representation of ExtraPermConfig.

type FSBind added in v0.2.0 

type FSBind struct {
	// Pathname in the container mount namespace. Same as Source if nil.
	Target *check.Absolute `json:"dst,omitempty"`
	// Pathname in the init mount namespace. Must not be nil.
	Source *check.Absolute `json:"src"`
	// Do not remount Target read-only.
	// This has no effect if Source is mounted read-only in the init mount namespace.
	Write bool `json:"write,omitempty"`
	// Allow access to devices (special files) on Target, implies Write.
	Device bool `json:"dev,omitempty"`
	// Create Source as a directory in the init mount namespace if it does not exist.
	Ensure bool `json:"ensure,omitempty"`
	// Silently skip this mount point if Source does not exist in the init mount namespace.
	Optional bool `json:"optional,omitempty"`

	/* Enable special behaviour:
	For autoroot: Target must be [fhs.Root].
	For autoetc:  Target must be [fhs.Etc]. */
	Special bool `json:"special,omitempty"`
}

FSBind represents a host to container bind mount.

func (*FSBind) Apply added in v0.2.0 

func (b *FSBind) Apply(z *ApplyState)

func (*FSBind) Host added in v0.2.0 

func (b *FSBind) Host() []*check.Absolute

func (*FSBind) IsAutoEtc added in v0.2.0 

func (b *FSBind) IsAutoEtc() bool

IsAutoEtc returns whether this FSBind has autoetc behaviour enabled.

func (*FSBind) IsAutoRoot added in v0.2.0 

func (b *FSBind) IsAutoRoot() bool

IsAutoRoot returns whether this FSBind has autoroot behaviour enabled.

func (*FSBind) Path added in v0.2.0 

func (b *FSBind) Path() *check.Absolute

func (*FSBind) String added in v0.2.0 

func (b *FSBind) String() string

func (*FSBind) Valid added in v0.2.0 

func (b *FSBind) Valid() bool

type FSDaemon added in v0.3.2 

type FSDaemon struct {
	// Pathname indicating readiness of daemon.
	Target *check.Absolute `json:"dst"`
	// Absolute pathname to daemon executable file.
	Exec *check.Absolute `json:"path"`
	// Arguments (excl. first) passed to daemon.
	Args []string `json:"args"`
}

FSDaemon represents a daemon to be started in the container.

func (*FSDaemon) Apply added in v0.3.2 

func (d *FSDaemon) Apply(z *ApplyState)

func (*FSDaemon) Host added in v0.3.2 

func (d *FSDaemon) Host() []*check.Absolute

func (*FSDaemon) Path added in v0.3.2 

func (d *FSDaemon) Path() *check.Absolute

func (*FSDaemon) String added in v0.3.2 

func (d *FSDaemon) String() string

func (*FSDaemon) Valid added in v0.3.2 

func (d *FSDaemon) Valid() bool

type FSEphemeral added in v0.2.0 

type FSEphemeral struct {
	// Pathname in the container mount namespace.
	Target *check.Absolute `json:"dst"`
	// Do not mount filesystem read-only.
	Write bool `json:"write,omitempty"`
	// Upper limit on the size of the filesystem.
	Size int `json:"size,omitempty"`
	// Initial permission bits of the new filesystem.
	Perm os.FileMode `json:"perm,omitempty"`
}

FSEphemeral represents an ephemeral container mount point.

func (*FSEphemeral) Apply added in v0.2.0 

func (e *FSEphemeral) Apply(z *ApplyState)

func (*FSEphemeral) Host added in v0.2.0 

func (e *FSEphemeral) Host() []*check.Absolute

func (*FSEphemeral) Path added in v0.2.0 

func (e *FSEphemeral) Path() *check.Absolute

func (*FSEphemeral) String added in v0.2.0 

func (e *FSEphemeral) String() string

func (*FSEphemeral) Valid added in v0.2.0 

func (e *FSEphemeral) Valid() bool

type FSImplError added in v0.2.0 

type FSImplError struct{ Value FilesystemConfig }

FSImplError is returned for unsupported implementations of FilesystemConfig.

func (FSImplError) Error added in v0.2.0 

func (f FSImplError) Error() string
type FSLink struct {
	// Pathname in the container mount namespace.
	Target *check.Absolute `json:"dst"`
	// Arbitrary linkname value store in the symlink.
	Linkname string `json:"linkname"`

	// Whether to treat Linkname as an absolute pathname and dereference before
	// creating the link.
	Dereference bool `json:"dereference,omitempty"`
}

FSLink represents a symlink in the container filesystem.

func (*FSLink) Apply added in v0.2.0 

func (l *FSLink) Apply(z *ApplyState)

func (*FSLink) Host added in v0.2.0 

func (l *FSLink) Host() []*check.Absolute

func (*FSLink) Path added in v0.2.0 

func (l *FSLink) Path() *check.Absolute

func (*FSLink) String added in v0.2.0 

func (l *FSLink) String() string

func (*FSLink) Valid added in v0.2.0 

func (l *FSLink) Valid() bool

type FSOverlay added in v0.2.0 

type FSOverlay struct {
	// Pathname in the container mount namespace.
	Target *check.Absolute `json:"dst"`

	// Any filesystem, does not need to be on a writable filesystem, must not be nil.
	Lower []*check.Absolute `json:"lower"`
	// The upperdir is normally on a writable filesystem, leave as nil to mount
	// Lower readonly.
	Upper *check.Absolute `json:"upper,omitempty"`
	// The workdir needs to be an empty directory on the same filesystem as
	// Upper, must not be nil if Upper is populated.
	Work *check.Absolute `json:"work,omitempty"`
}

FSOverlay represents an overlay mount point.

func (*FSOverlay) Apply added in v0.2.0 

func (o *FSOverlay) Apply(z *ApplyState)

func (*FSOverlay) Host added in v0.2.0 

func (o *FSOverlay) Host() []*check.Absolute

func (*FSOverlay) Path added in v0.2.0 

func (o *FSOverlay) Path() *check.Absolute

func (*FSOverlay) String added in v0.2.0 

func (o *FSOverlay) String() string

func (*FSOverlay) Valid added in v0.2.0 

func (o *FSOverlay) Valid() bool

type FSTypeError added in v0.2.0 

type FSTypeError string

FSTypeError is returned when [ContainerConfig.Filesystem] contains an entry with invalid type.

func (FSTypeError) Error added in v0.2.0 

func (f FSTypeError) Error() string

type FilesystemConfig 

type FilesystemConfig interface {
	// Valid returns whether the configuration is valid.
	Valid() bool
	// Path returns the target path in the container.
	Path() *check.Absolute
	// Host returns a slice of all host paths used by this operation.
	Host() []*check.Absolute
	// Apply appends the [container.Op] implementing this operation.
	Apply(z *ApplyState)

	fmt.Stringer
}

FilesystemConfig is an abstract representation of a mount point.

type FilesystemConfigJSON added in v0.2.0 

type FilesystemConfigJSON struct{ FilesystemConfig }

FilesystemConfigJSON is the json adapter for FilesystemConfig.

func (*FilesystemConfigJSON) MarshalJSON added in v0.2.0 

func (f *FilesystemConfigJSON) MarshalJSON() ([]byte, error)

func (*FilesystemConfigJSON) UnmarshalJSON added in v0.2.0 

func (f *FilesystemConfigJSON) UnmarshalJSON(data []byte) error

func (*FilesystemConfigJSON) Valid added in v0.2.0 

func (f *FilesystemConfigJSON) Valid() bool

Valid returns whether the FilesystemConfigJSON is valid.

type Flags added in v0.3.0 

type Flags uintptr

Flags are options held by ContainerConfig. 

const (
	// FMultiarch unblocks system calls required for multiarch to work on
	// multiarch-enabled targets (amd64, arm64).
	FMultiarch Flags = 1 << iota

	// FSeccompCompat changes emitted seccomp filter programs to be identical to
	// that of Flatpak in enabled rulesets.
	FSeccompCompat
	// FDevel unblocks ptrace and friends.
	FDevel
	// FUserns unblocks userns creation and container setup syscalls.
	FUserns
	// FHostNet skips net namespace creation.
	FHostNet
	// FHostAbstract skips setting up abstract unix socket scope.
	FHostAbstract
	// FTty unblocks dangerous terminal I/O (faking input).
	FTty

	// FMapRealUID maps the target user uid to the 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.
	FMapRealUID

	// FDevice mount /dev/ from the init mount namespace as is in the container
	// mount namespace.
	FDevice

	// FShareRuntime shares XDG_RUNTIME_DIR between containers under the same identity.
	FShareRuntime
	// FShareTmpdir shares TMPDIR between containers under the same identity.
	FShareTmpdir

	// FAll is [ContainerConfig.Flags] with all currently defined bits set.
	FAll = fMax - 1
)

func (Flags) String added in v0.3.0 

func (flags Flags) String() string

type GID added in v0.3.0 

type GID uint32

A GID represents a kernel gid in the init namespace.

func (GID) String added in v0.3.0 

func (gid GID) String() string

String returns the group name corresponding to this gid.

Not safe against untrusted input.

type ID added in v0.3.0 

type ID [16]byte

An ID is a unique identifier held by a running hakurei container.

func (*ID) CreationTime added in v0.3.0 

func (a *ID) CreationTime() time.Time

CreationTime returns the point in time ID was created.

func (*ID) MarshalText added in v0.3.0 

func (a *ID) MarshalText() (text []byte, err error)

MarshalText encodes the hex representation of ID.

func (*ID) String added in v0.3.0 

func (a *ID) String() string

String returns the hex string representation of ID.

func (*ID) UnmarshalText added in v0.3.0 

func (a *ID) UnmarshalText(text []byte) error

UnmarshalText decodes a hex representation of ID.

type IdentifierDecodeError added in v0.3.0 

type IdentifierDecodeError struct{ Err error }

IdentifierDecodeError is returned by ID.UnmarshalText to provide relevant error descriptions.

func (IdentifierDecodeError) Error added in v0.3.0 

func (e IdentifierDecodeError) Error() string

func (IdentifierDecodeError) Unwrap added in v0.3.0 

func (e IdentifierDecodeError) Unwrap() error

type Info 

type Info struct {
	// WaylandVersion is the libwayland value of WAYLAND_VERSION.
	WaylandVersion string `json:"WAYLAND_VERSION"`

	// Version is a hardcoded version string.
	Version string `json:"version"`
	// User is the userid according to hsu.
	User int `json:"user"`

	Paths
}

Info holds basic system information collected from the implementation.

type Ops added in v0.3.0 

type Ops interface {
	// Tmpfs appends an op that mounts tmpfs on a container path.
	Tmpfs(target *check.Absolute, size int, perm os.FileMode) Ops
	// Readonly appends an op that mounts read-only tmpfs on a container path.
	Readonly(target *check.Absolute, perm os.FileMode) Ops

	// Bind appends an op that bind mounts a host path on a container path.
	Bind(source, target *check.Absolute, flags int) Ops
	// Overlay appends an op that mounts the overlay pseudo filesystem.
	Overlay(target, state, work *check.Absolute, layers ...*check.Absolute) Ops
	// OverlayReadonly appends an op that mounts the overlay pseudo filesystem readonly.
	OverlayReadonly(target *check.Absolute, layers ...*check.Absolute) Ops

	// Link appends an op that creates a symlink in the container filesystem.
	Link(target *check.Absolute, linkName string, dereference bool) Ops

	// Root appends an op that expands a directory into a toplevel bind mount
	// mirror on container root.
	Root(host *check.Absolute, flags int) Ops
	// Etc appends an op that expands host /etc into a toplevel symlink mirror
	// with /etc semantics.
	Etc(host *check.Absolute, prefix string) Ops

	// Daemon appends an op that starts a daemon in the container and blocks
	// until target appears.
	Daemon(target, path *check.Absolute, args ...string) Ops
}

The Ops interface enables FilesystemConfig to queue container ops without depending on the container package.

type Paths 

type Paths struct {
	// Temporary directory returned by [os.TempDir], usually equivalent to [fhs.AbsTmp].
	TempDir *check.Absolute `json:"temp_dir"`
	// Shared directory specific to the hsu userid, usually
	// (`/tmp/hakurei.%d`, [Info.User]).
	SharePath *check.Absolute `json:"share_path"`
	// Checked XDG_RUNTIME_DIR value, usually (`/run/user/%d`, uid).
	RuntimePath *check.Absolute `json:"runtime_path"`
	// Shared directory specific to the hsu userid located in RuntimePath,
	// usually (`/run/user/%d/hakurei`, uid).
	RunDirPath *check.Absolute `json:"run_dir_path"`
}

Paths contains environment-dependent paths used by hakurei.

type State added in v0.3.0 

type State struct {
	// Unique instance id, created by [NewInstanceID].
	ID ID `json:"instance"`
	// Monitoring process pid. Runs as the priv user.
	PID int `json:"pid"`
	// Shim process pid. Runs as the target user.
	ShimPID int `json:"shim_pid"`

	// Configuration used to start the container.
	*Config

	// Point in time the shim process was created.
	Time time.Time `json:"time"`
}

A State describes a running hakurei container.

type UID added in v0.3.0 

type UID uint32

A UID represents a kernel uid in the init namespace.

func (UID) String added in v0.3.0 

func (uid UID) String() string

String returns the username corresponding to this uid.

Not safe against untrusted input.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.