config

Documentation

Index

• Variables
• func ExpandLocalHome(p string) (string, error)
• func ExpandRemoteHome(p, remoteHome string) (string, error)
• func MatchLocalCommand(entry, pathname string) bool
• func ResolveAgentBinaryPath(configPath, goos, goarch string) (string, error)
• func ResolveShimPath(configPath string) (string, error)
• func ResolveTracerPath(configPath string) (string, error)
• type Config
  • func Load(r io.Reader) (*Config, error)
  • func LoadFile(path string) (*Config, error)
  • func LoadFileRaw(path string) (*Config, error)
  • func (c *Config) Finalize() error
  • func (c *Config) Validate() error
• type Format
• type LocalCommandRule
  • func CompileLocalCommand(s string) (*LocalCommandRule, error)
  • func (r *LocalCommandRule) Match(pathname string) bool
• type Mount
  • func ParseMount(s string) (Mount, error)

Variables

var (
	// LibDir is the install location for machineproxy support binaries
	// (mproxy-shim, mproxy-tracer, and the per-OS/arch agent layout
	// under <LibDir>/agent/<goos>/<goarch>/).
	LibDir = "/usr/lib/machineproxy"

	// DefaultAgentRemotePath is the upload destination for mproxy-agent
	// on the remote host. A leading "~" is expanded against the remote
	// user's home directory at SFTP-use time.
	DefaultAgentRemotePath = "~/.cache/machineproxy/mproxy-agent"

	// DefaultPathStubDir is the local bind target for the PATH-stub
	// FUSE mount. A leading "~" is expanded against the local user's
	// home directory when the config is finalized; if home-directory
	// lookup fails, DefaultPathStubFallbackDir is used instead.
	DefaultPathStubDir = "~/.cache/machineproxy/pathstub"

	// DefaultPathStubFallbackDir is the absolute path used in place of
	// DefaultPathStubDir when the local home directory is unavailable.
	DefaultPathStubFallbackDir = "/tmp/machineproxy/pathstub"
)

Packager-overridable path defaults. These are var (not const) so a downstream packager can repoint them at build time via, e.g.:

go build -ldflags "-X github.com/jamesits/machineproxy/pkg/config.LibDir=/opt/machineproxy/lib"

var (
	Version = "0.1.0"
	Commit  = ""
	Date    = ""
)

Build-time metadata, populated via ldflags.

Functions

func ExpandLocalHome

func ExpandLocalHome(p string) (string, error)

ExpandLocalHome resolves a leading "~" or "~/" against the local user's home directory. Other paths are returned unchanged. Returns an error only if "~" is used but the home dir cannot be looked up.

func ExpandRemoteHome

func ExpandRemoteHome(p, remoteHome string) (string, error)

ExpandRemoteHome resolves a leading "~" or "~/" against remoteHome (typically the SFTP server's default working directory). Other paths are returned unchanged. SFTP servers do not expand "~" themselves and session.Start single-quotes its argument, so this rewrite must happen client-side before any remote use.

func MatchLocalCommand

func MatchLocalCommand(entry, pathname string) bool

MatchLocalCommand is a convenience that compiles entry and matches in one step. Returns false for malformed entries.

func ResolveAgentBinaryPath

func ResolveAgentBinaryPath(configPath, goos, goarch string) (string, error)

ResolveAgentBinaryPath finds the mproxy-agent binary. It checks the MPROXY_AGENT_BIN env var first, then the config value, adjacent binary, and well-known install paths. The goos and goarch parameters select the correct platform-specific binary for the remote host.

func ResolveShimPath

func ResolveShimPath(configPath string) (string, error)

ResolveShimPath finds the mproxy-shim binary using the config value, then falling back to adjacent binary and well-known install paths.

func ResolveTracerPath

func ResolveTracerPath(configPath string) (string, error)

ResolveTracerPath finds the mproxy-tracer binary using the config value, then falling back to adjacent binary and well-known install paths.

Types

type Config

type Config struct {
	LogLevel string `yaml:"log_level" toml:"log_level" json:"log_level"` // trace, debug, info, warn, error
	LogFile  string `yaml:"log_file"  toml:"log_file"  json:"log_file"`  // empty = stderr

	Remote struct {
		// Type selects the backend implementation: "ssh" (default) or
		// "docker". The CLI --backend flag overrides this when set.
		Type string `yaml:"type" toml:"type" json:"type"`
		// SSH is resolved via the user's ssh_config (see ssh_config(5)).
		// Host accepts either a literal hostname/IP or a Host alias defined
		// in ~/.ssh/config; User and Port, when set, override the resolved
		// values from ssh_config.
		SSH struct {
			Host string `yaml:"host" toml:"host" json:"host"`
			User string `yaml:"user" toml:"user" json:"user"`
			Port int    `yaml:"port" toml:"port" json:"port"`
		} `yaml:"ssh" toml:"ssh" json:"ssh"`
		// Docker selects a running container by name or ID. Host (when
		// set) overrides the DOCKER_HOST env var for this invocation.
		Docker struct {
			Container string `yaml:"container" toml:"container" json:"container"`
			Host      string `yaml:"host" toml:"host" json:"host"`
		} `yaml:"docker" toml:"docker" json:"docker"`
		// Compose selects a running container by Docker Compose project and
		// service name. Project "." resolves from the working directory.
		// Sequence (1-based) picks a specific replica of a scaled service;
		// 0 means auto (errors if more than one container matches).
		// Host, when set, overrides the DOCKER_HOST env var.
		Compose struct {
			Project  string `yaml:"project"  toml:"project"  json:"project"`
			Service  string `yaml:"service"  toml:"service"  json:"service"`
			Sequence int    `yaml:"sequence" toml:"sequence" json:"sequence"`
			Host     string `yaml:"host"     toml:"host"     json:"host"`
		} `yaml:"compose" toml:"compose" json:"compose"`
		// OS selects the remote-side agent binary's GOOS. When empty,
		// the runtime first asks the backend to detect it and only
		// falls back to the local runtime.GOOS if detection fails.
		OS string `yaml:"os" toml:"os" json:"os"`
		// Arch selects the remote-side agent binary's GOARCH. Empty
		// triggers the same detection/fallback chain as OS.
		Arch string `yaml:"arch" toml:"arch" json:"arch"`
	} `yaml:"remote" toml:"remote" json:"remote"`

	Container struct {
		LocalCommands []string `yaml:"local_commands" toml:"local_commands" json:"local_commands"`
		Mounts        []string `yaml:"mounts" toml:"mounts" json:"mounts"`                // docker-compose style: [local:]remote
		WorkingDir    string   `yaml:"working_dir" toml:"working_dir" json:"working_dir"` // override container working directory; defaults to first mount's local path
		EnvRemove     []string `yaml:"env_remove" toml:"env_remove" json:"env_remove"`    // glob/regex patterns for env vars to strip from the container process
		// PathProxy controls the FUSE-backed PATH-stub directory that
		// surfaces remote-side executables inside the container.
		//   "prepend"  — stubs win over locally-installed binaries (default)
		//   "append"   — local binaries win; stubs only fill gaps
		//   "disabled" — skip enumeration entirely
		PathProxy string `yaml:"path_proxy" toml:"path_proxy" json:"path_proxy"`
		// PathStubDir is the in-container directory where the stub FUSE
		// is bind-mounted. Defaults to $HOME/.cache/machineproxy/pathstub
		// so bwrap (which lacks privilege to mkdir parents under /var)
		// can create the bind target. A leading "~" is expanded against
		// the local user's home; the resulting path must be absolute.
		PathStubDir string `yaml:"path_stub_dir" toml:"path_stub_dir" json:"path_stub_dir"`
		// ForceResolveInitialCommandLocally controls whether the
		// resolved entrypoint command, its shebang interpreter, and
		// any env-target are auto-appended to LocalCommands. The
		// initial exec is always resolved against the local PATH
		// (the path-stub directory is skipped) because the path-stub
		// serves remote ELF binaries that cannot be loaded by the
		// local kernel; whitelisting the resolved chain prevents the
		// tracer from later routing those same paths to the remote
		// when they are re-execed (for instance by the kernel's
		// binfmt_script interpreter). Defaults to true; set false to
		// opt out.
		ForceResolveInitialCommandLocally *bool `` /* 134-byte string literal not displayed */
	} `yaml:"container" toml:"container" json:"container"`

	Agent struct {
		EnvKeep   []string `yaml:"env_keep" toml:"env_keep" json:"env_keep"`       // glob/regex patterns for inherited env vars to forward to remote
		EnvRemove []string `yaml:"env_remove" toml:"env_remove" json:"env_remove"` // glob/regex patterns for env vars to always strip from remote
	} `yaml:"agent" toml:"agent" json:"agent"`

	Components struct {
		ShimPath        string `yaml:"shim_path" toml:"shim_path" json:"shim_path"`
		TracerPath      string `yaml:"tracer_path" toml:"tracer_path" json:"tracer_path"`
		AgentLocalPath  string `yaml:"agent_local_path" toml:"agent_local_path" json:"agent_local_path"`
		AgentRemotePath string `yaml:"agent_remote_path" toml:"agent_remote_path" json:"agent_remote_path"`
	} `yaml:"components" toml:"components" json:"components"`

	Recording struct {
		Path string `yaml:"path" toml:"path" json:"path"` // empty disables recording
	} `yaml:"recording" toml:"recording" json:"recording"`
}

Config describes machineproxy runtime behavior.

func Load

func Load(r io.Reader) (*Config, error)

Load reads from r, auto-detecting YAML vs TOML by sniffing the bytes, and applies defaults plus validation. Use LoadFile when you have a path so the extension hint applies first.

func LoadFile

func LoadFile(path string) (*Config, error)

LoadFile reads and decodes the config at path, applies defaults, and validates. Format is detected by file extension first (.yaml/.yml/.json → YAML, .toml → TOML); if the extension is unrecognized, the contents are sniffed (see detectFormat).

func LoadFileRaw

func LoadFileRaw(path string) (*Config, error)

LoadFileRaw reads and decodes the config at path without applying defaults or validating. Callers that need to mutate the result before use (for instance, applying CLI overrides) should call Finalize after their mutations. Format detection matches LoadFile.

func (*Config) Finalize

func (c *Config) Finalize() error

Finalize applies defaults and validates the config. Call this after decoding (via LoadFileRaw) and any post-decode mutations such as CLI overrides. LoadFile and Load call Finalize automatically.

func (*Config) Validate

func (c *Config) Validate() error

type Format

type Format int

Format identifies the on-disk format of a config file.

const (
	FormatYAML Format = iota
	FormatTOML
)

type LocalCommandRule

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

LocalCommandRule is a compiled local_commands entry that can match against executable pathnames. Supported forms:

• "/absolute/path" — exact full path match
• "/regex/" — regex matched against the full pathname
• "basename" — matched against the last segment of the path

func CompileLocalCommand

func CompileLocalCommand(s string) (*LocalCommandRule, error)

CompileLocalCommand parses and validates a local_commands entry, returning a rule that can match pathnames.

func (*LocalCommandRule) Match

func (r *LocalCommandRule) Match(pathname string) bool

Match reports whether pathname matches this rule.

type Mount

type Mount struct {
	// RemotePath is the path on the remote machine (FUSE source).
	RemotePath string
	// ContainerPath is the path inside the container (bind target).
	// Equals RemotePath when no explicit local path is given.
	ContainerPath string
}

Mount represents a parsed container mount entry in docker-compose style. Format: [local_path:]remote_path

func ParseMount

func ParseMount(s string) (Mount, error)

ParseMount parses a docker-compose style mount string.

Either side may start with "~" or "~/"; the local side is expanded against the local user's home immediately so the resulting ContainerPath is always absolute. The remote side is returned in its raw form (still possibly "~/..."), to be expanded against the remote user's home at SFTP-use time — see ExpandRemoteHome.