host

package
v0.84.2 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package host provides a way to interact with an e2e remote host and capture its state.

Index

Constants

View Source 
const (
	// Loaded is the load state of a systemd unit.
	Loaded LoadState = "loaded"
	// NotLoaded is the load state of a systemd unit.
	NotLoaded LoadState = "not-found"
	// Masked is the load state of a systemd unit.
	Masked LoadState = "masked"
	// Error is the load state of a systemd unit.
	Error LoadState = "error"

	// Running is the sub state of a systemd unit.
	Running SubState = "running"
	// Dead is the sub state of a systemd unit.
	Dead SubState = "dead"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type FakeAgent 

type FakeAgent struct {
	// contains filtered or unexported fields
}

FakeAgent represents a fake Agent.

func (FakeAgent) SetExit0 

func (f FakeAgent) SetExit0(agent string) FakeAgent

SetExit0 sets the fake Agent to exit with code 0.

func (FakeAgent) SetExit1 

func (f FakeAgent) SetExit1(agent string) FakeAgent

SetExit1 sets the fake Agent to exit with code 1.

func (FakeAgent) SetStopWithSigkill 

func (f FakeAgent) SetStopWithSigkill(agent string) FakeAgent

SetStopWithSigkill sets the fake Agent to stop with SIGKILL.

func (FakeAgent) SetStopWithSigterm 

func (f FakeAgent) SetStopWithSigterm(agent string) FakeAgent

SetStopWithSigterm sets the fake Agent to stop with SIGTERM.

func (FakeAgent) SetStopWithSigtermExit0 added in v0.56.0 

func (f FakeAgent) SetStopWithSigtermExit0(agent string) FakeAgent

SetStopWithSigtermExit0 sets the fake Agent to stop with SIGTERM and exit with code 0.

type FileInfo 

type FileInfo struct {
	Name      string
	Size      int64
	Perms     fs.FileMode
	ModTime   time.Time
	IsDir     bool
	IsSymlink bool
	Link      string
	User      string
	Group     string
}

FileInfo struct mimics os.FileInfo

type Host 

type Host struct {
	// contains filtered or unexported fields
}

Host is a remote host environment.

func New 

func New(t func() *testing.T, remote *components.RemoteHost, os e2eos.Descriptor, arch e2eos.Architecture, opts ...Option) *Host

New creates a new Host.

func (*Host) AgentRuntimeConfig 

func (h *Host) AgentRuntimeConfig() (string, error)

AgentRuntimeConfig returns the runtime agent config on the host.

func (*Host) AgentStableVersion added in v0.57.0 

func (h *Host) AgentStableVersion() string

AgentStableVersion returns the stable version of the agent on the host.

func (*Host) AssertPackageInstalledByInstaller 

func (h *Host) AssertPackageInstalledByInstaller(pkgs ...string)

AssertPackageInstalledByInstaller checks if a package is installed by the installer on the host.

func (*Host) AssertPackageInstalledByPackageManager 

func (h *Host) AssertPackageInstalledByPackageManager(pkgs ...string)

AssertPackageInstalledByPackageManager checks if a package is installed by the package manager on the host.

func (*Host) AssertPackageNotInstalledByInstaller added in v0.67.0 

func (h *Host) AssertPackageNotInstalledByInstaller(pkgs ...string)

AssertPackageNotInstalledByInstaller checks if a package is not installed by the installer on the host.

func (*Host) AssertPackageNotInstalledByPackageManager 

func (h *Host) AssertPackageNotInstalledByPackageManager(pkgs ...string)

AssertPackageNotInstalledByPackageManager checks if a package is not installed by the package manager on the host.

func (*Host) AssertPackagePrefix added in v0.57.0 

func (h *Host) AssertPackagePrefix(pkg string, semver string)

AssertPackagePrefix checks if a package is installed with a version with the prefix

func (*Host) AssertPackageVersion 

func (h *Host) AssertPackageVersion(pkg string, version string)

AssertPackageVersion checks if a package is installed with the correct version

func (*Host) AssertProcmgrTelemetry added in v0.84.0 

func (h *Host) AssertProcmgrTelemetry(t *testing.T, serviceID, processName string)

AssertProcmgrTelemetry verifies the agent's COAT gauges report serviceID/processName as managed by dd-procmgrd. Call this after the process is confirmed running so procmgr is reachable.

func (*Host) AssertSystemdEvents 

func (h *Host) AssertSystemdEvents(since JournaldTimestamp, events SystemdEventSequence)

AssertSystemdEvents asserts that the systemd events have been logged since the given timestamp

func (*Host) AssertUnitProperty 

func (h *Host) AssertUnitProperty(unit, property, value string)

AssertUnitProperty asserts that the given systemd unit has the given property

func (*Host) BootstrapperVersion added in v0.60.0 

func (h *Host) BootstrapperVersion() string

BootstrapperVersion returns the version of the bootstrapper on the host.

func (*Host) CallExamplePythonApp 

func (h *Host) CallExamplePythonApp(traceID string)

CallExamplePythonApp calls the example Python app

func (*Host) CallExamplePythonAppInDocker 

func (h *Host) CallExamplePythonAppInDocker(traceID string)

CallExamplePythonAppInDocker calls the example Python app in Docker

func (*Host) ConfigureAptMirrors added in v0.82.3 

func (h *Host) ConfigureAptMirrors()

ConfigureAptMirrors hardens apt against package-mirror outages on apt-based hosts. It bounds apt's per-request timeout and retries so an unreachable (or merely slow) mirror fails within seconds instead of hanging until the CI job's 2h timeout, and on Ubuntu rewrites the apt sources to a "mirror+file" list so apt fails over to global mirrors when the regional EC2 mirror is down or degraded. us-east-1 is kept as the first entry (our infra's region), with archive.ubuntu.com / ports.ubuntu.com and a third-party mirror (mirror.leaseweb.net, which mirrors both amd64 and ports) as fallbacks, since ports.ubuntu.com alone is shared across every non-x86 architecture (arm64, armhf, ppc64el, s390x, riscv64) and is far less provisioned than the amd64-only archive.ubuntu.com global CDN. The timeout/retry values mirror Dockerfiles/agent/Dockerfile so CI image builds and e2e installs degrade identically. The source rewrite is skipped on releases whose apt lacks the "mirror+file" method driver (apt < 1.6, e.g. Ubuntu 16.04). See incidents 58780 and 59571.

func (*Host) ConfigureYumMirrors added in v0.82.3 

func (h *Host) ConfigureYumMirrors()

ConfigureYumMirrors is the yum counterpart to ConfigureAptMirrors. CentOS 7 is EOL and its stock /centos/7/ path on vault.centos.org now returns HTTP 403, breaking any "yum install". It repoints base/updates/extras at the versioned vault archive (7.9.2009), with the CERN and kernel.org vault mirrors as ordered fallbacks (failovermethod=priority) plus skip_if_unavailable and a bounded timeout to fail fast. vault's http path matches the agent's production kernel-header downloader (pkg/util/kernel/headers/download/rpm/centos.go). See incident 58780.

func (*Host) DeletePath 

func (h *Host) DeletePath(path string)

DeletePath deletes a path on the host.

func (*Host) FileExists 

func (h *Host) FileExists(path string) (bool, error)

FileExists checks if a file exists on the host.

func (*Host) GetDockerRuntimePath 

func (h *Host) GetDockerRuntimePath(runtime string) string

GetDockerRuntimePath returns the runtime path of a docker runtime

func (*Host) GetPkgManager 

func (h *Host) GetPkgManager() string

GetPkgManager returns the package manager of the host.

func (*Host) GroupExists added in v0.66.1 

func (h *Host) GroupExists(groupname string) bool

GroupExists checks if a group exists on the host.

func (*Host) InstallDocker 

func (h *Host) InstallDocker()

TODO[@agent-devx]: Probably move this to the proper docker component defined in components/docker/component.go InstallDocker installs Docker on the host if it is not already installed.

func (*Host) InstallerVersion 

func (h *Host) InstallerVersion() string

InstallerVersion returns the version of the installer on the host.

func (*Host) LastJournaldTimestamp 

func (h *Host) LastJournaldTimestamp() JournaldTimestamp

LastJournaldTimestamp returns the monotonic timestamp of the last journald log entry

func (*Host) ProcmgrEnabled added in v0.84.0 

func (h *Host) ProcmgrEnabled() bool

Procmgr enabled returns true if the procmgr is enabled on the host, ie if the folder processes.d exists

func (*Host) ReadFile 

func (h *Host) ReadFile(path string) ([]byte, error)

ReadFile reads a file from the host.

func (*Host) RemoveBrokenDockerConfig 

func (h *Host) RemoveBrokenDockerConfig()

RemoveBrokenDockerConfig removes the broken configuration from the Docker daemon

func (*Host) RemoveProxy added in v0.61.0 

func (h *Host) RemoveProxy()

RemoveProxy removes the Squid Proxy & iptables/nftables rules

func (*Host) Run 

func (h *Host) Run(command string, env ...string) string

Run executes a command on the host.

func (*Host) SetBrokenDockerConfig 

func (h *Host) SetBrokenDockerConfig()

SetBrokenDockerConfig injects a broken JSON in the Docker daemon configuration

func (*Host) SetBrokenDockerConfigAdditionalFields 

func (h *Host) SetBrokenDockerConfigAdditionalFields()

SetBrokenDockerConfigAdditionalFields injects additional fields in the Docker daemon configuration these fields are not supported

func (*Host) SetUmask added in v0.57.0 

func (h *Host) SetUmask(mask string) (oldmask string)

SetUmask set the default umask for commands

func (*Host) SetupFakeAgentExp 

func (h *Host) SetupFakeAgentExp() FakeAgent

SetupFakeAgentExp sets up a fake Agent experiment with configurable options.

func (*Host) SetupProxy added in v0.61.0 

func (h *Host) SetupProxy()

SetupProxy sets up a Squid Proxy with Docker & adds iptables/nftables rules to redirect block all traffic except for the proxy

func (*Host) StartExamplePythonApp 

func (h *Host) StartExamplePythonApp()

StartExamplePythonApp starts an example Python app

func (*Host) StartExamplePythonAppInDocker 

func (h *Host) StartExamplePythonAppInDocker()

StartExamplePythonAppInDocker starts the example Python app in Docker

func (*Host) State 

func (h *Host) State() State

State returns the state of the host.

func (*Host) StopExamplePythonApp 

func (h *Host) StopExamplePythonApp()

StopExamplePythonApp stops the example Python app

func (*Host) StopExamplePythonAppInDocker 

func (h *Host) StopExamplePythonAppInDocker()

StopExamplePythonAppInDocker stops the example Python app in Docker

func (*Host) UserExists added in v0.66.1 

func (h *Host) UserExists(username string) bool

UserExists checks if a user exists on the host.

func (*Host) WaitForFileExists added in v0.56.0 

func (h *Host) WaitForFileExists(useSudo bool, filePaths ...string)

WaitForFileExists waits for a file to exist on the host

func (*Host) WaitForProcessesRunning added in v0.84.0 

func (h *Host) WaitForProcessesRunning(t *testing.T, names ...string)

WaitForProcessesRunning waits for procmgr-supervised processes to report a Running state. Unlike State.AssertProcessesRunning (a static snapshot check with no retry), this polls dd-procmgrd directly: becoming Running takes a few extra hops after the hosting systemd unit itself is active (daemon init, processes.d read, condition_path_exists check, process spawn), so a plain WaitForUnitActive on the procmgr unit is not enough to avoid a race with State().

func (*Host) WaitForTraceAgentSocketReady added in v0.57.0 

func (h *Host) WaitForTraceAgentSocketReady()

WaitForTraceAgentSocketReady waits for the trace agent to be ready to receive traces This is because of a race condition where the trace agent is not ready to receive traces and we send them meaning that the traces are lost

func (*Host) WaitForUnitActivating added in v0.56.0 

func (h *Host) WaitForUnitActivating(t *testing.T, units ...string)

WaitForUnitActivating waits for a systemd unit to be activating

func (*Host) WaitForUnitActive 

func (h *Host) WaitForUnitActive(t *testing.T, units ...string)

WaitForUnitActive waits for a systemd unit to be active

func (*Host) WaitForUnitExited added in v0.74.0 

func (h *Host) WaitForUnitExited(t *testing.T, exitCode int, units ...string)

WaitForUnitExited waits for a systemd unit to exit with a specific exit code

func (*Host) WriteFile added in v0.56.0 

func (h *Host) WriteFile(path string, content []byte) error

WriteFile writes a file to the host.

type JournaldTimestamp 

type JournaldTimestamp int64

JournaldTimestamp represents a monotonic timestamp of a journald log entry

type LoadState 

type LoadState string

LoadState is the load state of a systemd unit.

type Option 

type Option func(func() *testing.T, *Host)

Option is an option to configure a Host.

type ProcessesUnitInfo added in v0.84.0 

type ProcessesUnitInfo struct {
	Name         string
	UUID         string
	State        string
	PID          int
	Command      string
	Args         []string
	RestartCount int
	LastExitCode *int
	LastSignal   *int
	AutoStart    bool
}

ProcessesUnitInfo is the info of a process managed by procmgr.

type State 

type State struct {
	Users     []user.User
	Groups    []user.Group
	FS        map[string]FileInfo
	Units     map[string]SystemdUnitInfo
	Processes map[string]ProcessesUnitInfo
	// contains filtered or unexported fields
}

State is the state of a remote host.

func (*State) AssertDirExists 

func (s *State) AssertDirExists(path string, perms fs.FileMode, user string, group string)

AssertDirExists asserts that a directory exists on the host with the given perms, user, and group.

func (*State) AssertFileExists 

func (s *State) AssertFileExists(path string, perms fs.FileMode, user string, group string)

AssertFileExists asserts that a file exists on the host with the given perms, user, and group.

func (*State) AssertFileExistsAnyUser added in v0.58.0 

func (s *State) AssertFileExistsAnyUser(path string, perms fs.FileMode)

AssertFileExistsAnyUser asserts that a file exists on the host with the given perms.

func (*State) AssertGroupExists 

func (s *State) AssertGroupExists(groupName string)

AssertGroupExists asserts that a group exists on the host.

func (*State) AssertPathDoesNotExist 

func (s *State) AssertPathDoesNotExist(path string)

AssertPathDoesNotExist asserts that a path does not exist on the host.

func (*State) AssertProcessesDead added in v0.84.0 

func (s *State) AssertProcessesDead(names ...string)

AssertProcessesDead asserts that processes are not running under procmgr (stopped, exited, crashed or failed).

func (*State) AssertProcessesEnabled added in v0.84.0 

func (s *State) AssertProcessesEnabled(names ...string)

AssertProcessesEnabled asserts that processes are configured to auto-start under procmgr.

func (*State) AssertProcessesLoaded added in v0.84.0 

func (s *State) AssertProcessesLoaded(names ...string)

AssertProcessesLoaded asserts that processes are loaded (registered) by procmgr.

func (*State) AssertProcessesNotEnabled added in v0.84.0 

func (s *State) AssertProcessesNotEnabled(names ...string)

AssertProcessesNotEnabled asserts that processes are loaded but not configured to auto-start.

func (*State) AssertProcessesNotLoaded added in v0.84.0 

func (s *State) AssertProcessesNotLoaded(names ...string)

AssertProcessesNotLoaded asserts that processes are not loaded (registered) by procmgr.

func (*State) AssertProcessesRunning added in v0.84.0 

func (s *State) AssertProcessesRunning(names ...string)

AssertProcessesRunning asserts that processes are running under procmgr.

func (*State) AssertSymlinkExists 

func (s *State) AssertSymlinkExists(path string, target string, user string, group string)

AssertSymlinkExists asserts that a symlink exists on the host with the given target, user, and group.

func (*State) AssertUnitsActive added in v0.80.0 

func (s *State) AssertUnitsActive(names ...string)

AssertUnitsActive asserts that a systemd unit is active (covers oneshot+RemainAfterExit services whose substate is "exited").

func (*State) AssertUnitsDead 

func (s *State) AssertUnitsDead(names ...string)

AssertUnitsDead asserts that a systemd unit is not running.

func (*State) AssertUnitsEnabled 

func (s *State) AssertUnitsEnabled(names ...string)

AssertUnitsEnabled asserts that a systemd unit is not loaded.

func (*State) AssertUnitsLoaded 

func (s *State) AssertUnitsLoaded(names ...string)

AssertUnitsLoaded asserts that units are enabled on the host.

func (*State) AssertUnitsNotEnabled 

func (s *State) AssertUnitsNotEnabled(names ...string)

AssertUnitsNotEnabled asserts that a systemd unit is not enabled

func (*State) AssertUnitsNotLoaded 

func (s *State) AssertUnitsNotLoaded(names ...string)

AssertUnitsNotLoaded asserts that a systemd unit is not loaded.

func (*State) AssertUnitsRunning 

func (s *State) AssertUnitsRunning(names ...string)

AssertUnitsRunning asserts that a systemd unit is running.

func (*State) AssertUserExists 

func (s *State) AssertUserExists(userName string)

AssertUserExists asserts that a user exists on the host.

func (*State) AssertUserHasGroup 

func (s *State) AssertUserHasGroup(userName, groupName string)

AssertUserHasGroup asserts that a user has a group on the host.

func (*State) ListDirectory added in v0.57.0 

func (s *State) ListDirectory(path string) []FileInfo

ListDirectory returns a list of entries in the directory and fails the test if it doesn't exist

func (*State) Stat added in v0.56.0 

func (s *State) Stat(path string) (FileInfo, bool)

Stat returns the FileInfo of a path on the host.

type SubState 

type SubState string

SubState is the sub state of a systemd unit.

type SystemdEvent 

type SystemdEvent struct {
	Unit    string
	Pattern string
}

SystemdEvent represents a systemd event

type SystemdEventSequence 

type SystemdEventSequence struct {
	Events [][]SystemdEvent
}

SystemdEventSequence represents a sequence of systemd events

func SystemdEvents 

func SystemdEvents() SystemdEventSequence

SystemdEvents returns a new SystemdEventSequence

func (SystemdEventSequence) Failed 

func (s SystemdEventSequence) Failed(unit string) SystemdEventSequence

Failed adds a "Failed" event to the sequence

func (SystemdEventSequence) Sigkill 

func (s SystemdEventSequence) Sigkill(unit string) SystemdEventSequence

Sigkill adds a "Sigkill" event to the sequence

func (SystemdEventSequence) SigtermTimed 

func (s SystemdEventSequence) SigtermTimed(unit string) SystemdEventSequence

SigtermTimed adds a "SigtermTimed" event to the sequence

func (SystemdEventSequence) Skipped 

func (s SystemdEventSequence) Skipped(unit string) SystemdEventSequence

Skipped adds a "Skipped" event to the sequence

func (SystemdEventSequence) SkippedIf added in v0.58.0 

func (s SystemdEventSequence) SkippedIf(unit string, condition bool) SystemdEventSequence

SkippedIf adds a "Skipped" event to the sequence if the condition is true

func (SystemdEventSequence) Started 

func (s SystemdEventSequence) Started(unit string) SystemdEventSequence

Started adds a "Started" event to the sequence

func (SystemdEventSequence) Starting 

func (s SystemdEventSequence) Starting(unit string) SystemdEventSequence

Starting adds a "Starting" event to the sequence

func (SystemdEventSequence) Stopped 

func (s SystemdEventSequence) Stopped(unit string) SystemdEventSequence

Stopped adds a "Stopped" event to the sequence

func (SystemdEventSequence) Stopping 

func (s SystemdEventSequence) Stopping(unit string) SystemdEventSequence

Stopping adds a "Stopping" event to the sequence

func (SystemdEventSequence) Timed 

func (s SystemdEventSequence) Timed(unit string) SystemdEventSequence

Timed adds a "Timed" event to the sequence

func (SystemdEventSequence) Unordered 

func (s SystemdEventSequence) Unordered(events SystemdEventSequence) SystemdEventSequence

Unordered adds an unordered sequence of events to the sequence

type SystemdUnitInfo 

type SystemdUnitInfo struct {
	Name      string
	Active    string
	Enabled   string
	SubState  SubState
	LoadState LoadState
}

SystemdUnitInfo is the info of a systemd unit.

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.