host

package
v1.30.1 Latest Latest
Warning

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

 Go to latest Published: Nov 5, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

README

host Package

The host package provides an abstraction for file and process operations on local and remote SSH hosts.

Documentation

Overview

Provides remote file and command functions

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidArgs TODO: Describe its purpose and intended use.
	ErrInvalidArgs = errors.New("invalid arguments")
	// ErrNotSupported TODO: Describe its purpose and intended use.
	ErrNotSupported = errors.New("not supported")
	// ErrNotAvailable TODO: Describe its purpose and intended use.
	ErrNotAvailable = errors.New("not available")
	// ErrExist TODO: Describe its purpose and intended use.
	ErrExist = errors.New("already exists")
	// ErrNotExist TODO: Describe its purpose and intended use.
	ErrNotExist = errors.New("does not exist")
)
View Source 
var ListSeparators = map[string]string{
	"windows": `;`,
	"linux":   ":",
	"darwin":  ":",
}

ListSeparators for separating lists of paths, e.g. in PATH environment variables, by OS

View Source 
var Localhost = NewLocal()

Localhost is a Host backed by the current machine.

View Source 
var Seperators = map[string]string{
	"windows": `\`,
	"linux":   "/",
	"darwin":  "/",
}

Separators for file paths and lists, by OS

Functions

func CopyAll 

func CopyAll(srcHost Host, srcDir string, dstHost Host, dstDir string) (err error)

CopyAll copies a directory between any combination of local or remote locations

func CopyFile 

func CopyFile(srcHost Host, srcPath string, dstHost Host, dstPath string) (err error)

CopyFile copies a file between two locations. Destination can be a directory or a file. Parent directories will be created as required. Any existing files will be overwritten.

func GetFileOwner added in v1.27.0 

func GetFileOwner(h Host, info fs.FileInfo) (uid, gid int)

GetFileOwner TODO: Document its behavior, inputs, and effects.

Types

type Host 

type Host interface {
	// informational
	String() string
	GetFs() afero.Fs
	HostPath(p string) string // return the path as a string, prefixed with "host:" if not local
	Hostname() string
	ServerVersion() string // return the SSH server version if remote, or the same as OS() if local
	OS() string            // return whatever runtime.GOOS would return for the host
	IsAvailable() (bool, error)
	IsLocalhost() bool
	LastError() error
	Uname() (string, string, error)
	Username() string

	// filepath operations
	Abs(name string) (string, error)
	Base(string) string
	// Clean()
	Dir(string) string
	// EvalSymlinks()
	Ext(string) string
	IsAbs(name string) bool
	// IsLocal()
	Join(...string) string
	// Localize()
	// Match()
	// Rel()
	Split(string) (dir, file string)
	// SplitList()
	ToSlash(string) string
	VolumeName(string) string
	// Walk()
	WalkDir(dir string, fn fs.WalkDirFunc) error

	// file operations
	Getwd() (dir string, err error)
	Chown(name string, uid, gid int) (err error)
	Chtimes(path string, atime time.Time, mtime time.Time) (err error)
	Glob(pattern string) (paths []string, err error)
	Link(oldname, newname string) (err error)
	Lchown(name string, uid, gid int) (err error)
	Lchtimes(path string, atime time.Time, mtime time.Time) (err error)
	Lstat(name string) (f fs.FileInfo, err error)
	Mkdir(name string, perm os.FileMode) (err error)
	MkdirAll(p string, perm os.FileMode) (err error)
	ReadDir(name string) (dirs []os.DirEntry, err error)
	ReadFile(name string) (b []byte, err error)
	Readlink(file string) (link string, err error)
	Remove(name string) (err error)
	RemoveAll(name string) (err error)
	Rename(oldpath, newpath string) (err error)
	Stat(name string) (f fs.FileInfo, err error)
	Symlink(oldname, newname string) (err error)
	TempDir() string
	WriteFile(name string, data []byte, perm os.FileMode) (err error)

	// these two do not conform to the afero / os interface
	Open(name string) (f io.ReadSeekCloser, err error)
	Create(p string, perms fs.FileMode) (out io.WriteCloser, err error)

	// process control
	Signal(pid int, signal syscall.Signal) (err error)
	Start(cmd *exec.Cmd, options ...ProcessOption) (pid int, err error)
	Run(cmd *exec.Cmd, options ...ProcessOption) (stdout []byte, err error)
}

Host encapsulates all the methods required by callers to manage Geneos installs on a host.

This should have been based on (and extending) something like Afero, but this was quicker for the moment. This interface also provides process handling etc.

func NewLocal 

func NewLocal() Host

NewLocal returns a Host that performs operations on the current machine.

func NewSSHRemote 

func NewSSHRemote(name string, options ...any) Host

NewSSHRemote returns a new SSHRemote with the given name and options. The name is used as the key for caching SSH and SFTP sessions and so should be unique for each remote host. Options are used to set the hostname, port, username and authentication method (password or private keys) for the remote host. If no options are given then the local username is used and the hostname is set to the name of the remote.

type Local 

type Local struct {
}

Local implements Host operations against the current machine and filesystem.

func (*Local) Abs added in v1.6.0 

func (h *Local) Abs(dir string) (abs string, err error)

Abs returns dir as an absolute local path with slash separators.

func (*Local) Base added in v1.27.1 

func (h *Local) Base(path string) string

Base returns the final path element using the local operating system's rules.

func (*Local) Chown 

func (h *Local) Chown(name string, uid, gid int) (err error)

Chown changes the owner and group of a local filesystem path.

func (*Local) Chtimes added in v1.14.2 

func (h *Local) Chtimes(path string, atime time.Time, mtime time.Time) (err error)

Chtimes changes the access and modification times of a local filesystem path.

func (*Local) Create 

func (h *Local) Create(p string, perms fs.FileMode) (out io.WriteCloser, err error)

Create opens p for writing, creating or truncating it with the supplied permissions.

func (*Local) Dir added in v1.27.1 

func (h *Local) Dir(path string) string

Dir returns the directory portion of path using local path rules.

func (*Local) Ext added in v1.27.1 

func (h *Local) Ext(path string) string

Ext returns path's file extension using local path rules.

func (*Local) GetFs 

func (h *Local) GetFs() afero.Fs

GetFs returns an afero filesystem backed by the local operating system.

func (*Local) Getwd added in v1.6.0 

func (h *Local) Getwd() (dir string, err error)

Getwd returns the current working directory.

func (*Local) Glob 

func (h *Local) Glob(pattern string) (paths []string, err error)

Glob returns local paths matching pattern, with slash-separated path elements.

func (*Local) HostPath added in v1.14.2 

func (h *Local) HostPath(p string) string

HostPath returns p unchanged because local paths need no host translation.

func (*Local) Hostname added in v1.6.0 

func (h *Local) Hostname() string

Hostname returns the current machine's hostname.

func (*Local) IsAbs added in v1.14.2 

func (h *Local) IsAbs(name string) bool

IsAbs reports whether name is an absolute path on the local operating system.

func (*Local) IsAvailable 

func (h *Local) IsAvailable() (bool, error)

IsAvailable reports that the local host is available.

func (*Local) IsLocalhost added in v1.27.1 

func (h *Local) IsLocalhost() bool

IsLocalhost reports whether h represents the current machine.

func (*Local) Join added in v1.27.1 

func (h *Local) Join(elem ...string) string

Join joins path elements using local path rules.

func (*Local) LastError 

func (h *Local) LastError() error

LastError returns nil because local host operations do not cache connection errors.

func (*Local) Lchown 

func (h *Local) Lchown(name string, uid, gid int) (err error)

Lchown changes the owner and group of a local path without following a symlink.

func (*Local) Lchtimes added in v1.14.2 

func (h *Local) Lchtimes(path string, atime time.Time, mtime time.Time) (err error)

Lchtimes TODO: Document its behavior, inputs, and effects. 

func (h *Local) Link(oldname, newname string) (err error)

Link creates a hard link from oldname to newname.

func (*Local) Lstat 

func (h *Local) Lstat(name string) (f fs.FileInfo, err error)

Lstat returns file information for name without following symbolic links.

func (*Local) Mkdir added in v1.26.0 

func (h *Local) Mkdir(p string, perm os.FileMode) (err error)

Mkdir creates one local directory with the supplied permissions.

func (*Local) MkdirAll 

func (h *Local) MkdirAll(p string, perm os.FileMode) (err error)

MkdirAll creates p and any missing parent directories with the supplied permissions.

func (*Local) OS added in v1.27.1 

func (h *Local) OS() string

OS returns the local operating-system identifier.

func (*Local) Open 

func (h *Local) Open(name string) (f io.ReadSeekCloser, err error)

Open opens name for reading and returns a seekable read-closer.

func (*Local) ReadDir 

func (h *Local) ReadDir(name string) (dirs []os.DirEntry, err error)

ReadDir reads the named directory and returns all its directory entries sorted by name.

func (*Local) ReadFile 

func (h *Local) ReadFile(name string) (b []byte, err error)

ReadFile reads and returns the complete contents of name. 

func (h *Local) Readlink(file string) (link string, err error)

Readlink returns the target of file if it is a symbolic link.

func (*Local) Remove 

func (h *Local) Remove(name string) (err error)

Remove deletes the named local file or empty directory.

func (*Local) RemoveAll 

func (h *Local) RemoveAll(name string) (err error)

RemoveAll deletes name and any children it contains.

func (*Local) Rename 

func (h *Local) Rename(oldpath, newpath string) (err error)

Rename moves a local path from oldpath to newpath.

func (*Local) Run 

func (h *Local) Run(cmd *exec.Cmd, options ...ProcessOption) (output []byte, err error)

Run starts a program, waits for completion and returns the output and/or any error. errfile is either absolute or relative to home.

func (*Local) ServerVersion 

func (h *Local) ServerVersion() string

ServerVersion returns the local operating-system identifier.

func (*Local) Signal 

func (h *Local) Signal(pid int, signal syscall.Signal) (err error)

Signal sends signal to the local process identified by pid.

func (*Local) Split added in v1.27.1 

func (h *Local) Split(path string) (dir, file string)

Split separates path into its directory and final element.

func (*Local) Start 

func (h *Local) Start(cmd *exec.Cmd, options ...ProcessOption) (pid int, err error)

Start launches cmd on the local host, detaching it unless options override process setup. Standard output and error are written to the configured error log.

func (*Local) Stat 

func (h *Local) Stat(name string) (f fs.FileInfo, err error)

Stat returns file information for name, following symbolic links.

func (*Local) String 

func (h *Local) String() string

String returns the host identifier "localhost". 

func (h *Local) Symlink(oldname, newname string) (err error)

Symlink TODO: Document its behavior, inputs, and effects.

func (*Local) TempDir added in v1.6.3 

func (h *Local) TempDir() string

TempDir returns the local operating system's temporary directory.

func (*Local) ToSlash added in v1.27.1 

func (h *Local) ToSlash(path string) string

ToSlash converts path separators to slash characters.

func (*Local) Uname added in v1.14.2 

func (h *Local) Uname() (os, arch string, err error)

Uname TODO: Document its behavior, inputs, and effects.

func (*Local) Username 

func (h *Local) Username() string

Username returns the current operating-system user's name.

func (*Local) VolumeName added in v1.27.1 

func (h *Local) VolumeName(path string) string

VolumeName returns the volume component of path, if the operating system has one.

func (*Local) WalkDir added in v1.14.2 

func (h *Local) WalkDir(dir string, fn fs.WalkDirFunc) error

WalkDir TODO: Document its behavior, inputs, and effects.

func (*Local) WriteFile 

func (h *Local) WriteFile(name string, data []byte, perm os.FileMode) (err error)

WriteFile writes data to name, creating or truncating the file with perm.

type ProcessOption added in v1.27.0 

type ProcessOption func(*processOptions)

ProcessOption TODO: Describe its purpose and intended use.

func ProcessAllowCoreDumps added in v1.27.0 

func ProcessAllowCoreDumps() ProcessOption

ProcessAllowCoreDumps TODO: Document its behavior, inputs, and effects.

func ProcessCPUAffinity added in v1.28.0 

func ProcessCPUAffinity(cpus ...int) ProcessOption

ProcessCPUAffinity TODO: Document its behavior, inputs, and effects.

func ProcessDetach added in v1.26.0 

func ProcessDetach() ProcessOption

ProcessDetach makes the process run detached from the parent

func ProcessErrfile added in v1.26.0 

func ProcessErrfile(errfile string) ProcessOption

ProcessErrfile TODO: Document its behavior, inputs, and effects.

type SSHOption added in v1.27.0 

type SSHOption func(*SSHRemote)

SSHOption TODO: Describe its purpose and intended use.

func Hostname 

func Hostname(hostname string) SSHOption

Hostname TODO: Document its behavior, inputs, and effects.

func Password 

func Password(password []byte) SSHOption

Password TODO: Document its behavior, inputs, and effects.

func Port 

func Port(port uint16) SSHOption

Port TODO: Document its behavior, inputs, and effects.

func PrivateKeyFiles added in v1.14.2 

func PrivateKeyFiles(paths ...string) SSHOption

PrivateKeyFiles add the given paths as private key files to use for SSH connections. The files must (at this time) not be passphrase protected.

func Username 

func Username(username string) SSHOption

Username TODO: Document its behavior, inputs, and effects.

type SSHRemote 

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

An SSHRemote a type that satisfies the Host interface for SSH attached remote hosts

func (*SSHRemote) Abs added in v1.6.0 

func (h *SSHRemote) Abs(dir string) (string, error)

Abs TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Base added in v1.27.1 

func (h *SSHRemote) Base(file string) string

Base TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Chown 

func (h *SSHRemote) Chown(name string, uid, gid int) error

Chown TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Chtimes added in v1.14.2 

func (h *SSHRemote) Chtimes(path string, atime time.Time, mtime time.Time) (err error)

Chtimes TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Close 

func (h *SSHRemote) Close()

Close a remote host connection

func (*SSHRemote) CloseSFTP 

func (h *SSHRemote) CloseSFTP()

CloseSFTP TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Create 

func (h *SSHRemote) Create(p string, perms fs.FileMode) (out io.WriteCloser, err error)

Create TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) DialSFTP 

func (h *SSHRemote) DialSFTP() (f *sftp.Client, err error)

DialSFTP connects to the remote host using SSH and returns an *sftp.Client is successful. The connection is cached and returned if found, without checking if it is still valid.

func (*SSHRemote) DialSSH added in v1.27.0 

func (h *SSHRemote) DialSSH() (sc *ssh.Client, err error)

DialSSH connects to a remote host using ssh and returns an *ssh.Client on success. Each connection is cached and returned if found without checking if it is still valid. To remove a session call Close()

func (*SSHRemote) Dir added in v1.27.1 

func (h *SSHRemote) Dir(file string) string

Dir TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Ext added in v1.27.1 

func (h *SSHRemote) Ext(file string) string

Ext TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) GetFs 

func (h *SSHRemote) GetFs() afero.Fs

GetFs TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Getwd added in v1.6.0 

func (h *SSHRemote) Getwd() (dir string, err error)

Getwd TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Glob 

func (h *SSHRemote) Glob(pattern string) ([]string, error)

Glob TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) HostPath added in v1.14.2 

func (h *SSHRemote) HostPath(p string) string

HostPath TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Hostname added in v1.6.0 

func (s *SSHRemote) Hostname() string

Hostname TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) IsAbs added in v1.14.2 

func (h *SSHRemote) IsAbs(name string) bool

IsAbs run from unix will use path.IsAbs unless the remote is windows in which case it checks the volume name, stripping it and testing the rest of the path

func (*SSHRemote) IsAvailable 

func (h *SSHRemote) IsAvailable() (ok bool, err error)

IsAvailable returns true is the remote host can be contacted

func (*SSHRemote) IsLocalhost added in v1.27.1 

func (h *SSHRemote) IsLocalhost() bool

IsLocalhost returns true if h is local, which for SSH is always false

func (*SSHRemote) Join added in v1.27.1 

func (h *SSHRemote) Join(elem ...string) string

Join TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) LastError 

func (h *SSHRemote) LastError() error

LastError TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Lchown 

func (h *SSHRemote) Lchown(name string, uid, gid int) error

Lchown just down a Chown() for remote files

func (*SSHRemote) Lchtimes added in v1.14.2 

func (h *SSHRemote) Lchtimes(path string, atime time.Time, mtime time.Time) (err error)

Lchtimes TODO: Document its behavior, inputs, and effects. 

func (h *SSHRemote) Link(oldname, newname string) error

Link TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Lstat 

func (h *SSHRemote) Lstat(name string) (fs.FileInfo, error)

Lstat wraps the os.Lstat and sftp.Lstat functions

func (*SSHRemote) Mkdir added in v1.26.0 

func (h *SSHRemote) Mkdir(p string, perm os.FileMode) error

Mkdir TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) MkdirAll 

func (h *SSHRemote) MkdirAll(p string, perm os.FileMode) error

MkdirAll TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) NewSession added in v1.10.2 

func (h *SSHRemote) NewSession() (sess *ssh.Session, err error)

NewSession wraps ssh.NewSession but does some retries

func (*SSHRemote) OS added in v1.27.1 

func (h *SSHRemote) OS() string

OS TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Open 

func (h *SSHRemote) Open(name string) (io.ReadSeekCloser, error)

Open TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) ReadDir 

func (h *SSHRemote) ReadDir(name string) (dirs []os.DirEntry, err error)

ReadDir reads the named directory and returns all its directory entries sorted by name.

func (*SSHRemote) ReadFile 

func (h *SSHRemote) ReadFile(name string) (b []byte, err error)

ReadFile TODO: Document its behavior, inputs, and effects. 

func (h *SSHRemote) Readlink(file string) (string, error)

Readlink TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Remove 

func (h *SSHRemote) Remove(name string) error

Remove TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) RemoveAll 

func (h *SSHRemote) RemoveAll(name string) (err error)

RemoveAll TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Rename 

func (h *SSHRemote) Rename(oldpath, newpath string) error

Rename TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Run 

func (h *SSHRemote) Run(cmd *exec.Cmd, options ...ProcessOption) (output []byte, err error)

Run starts a process on an SSH attached remote host h. It uses a shell and waits for the process status before returning. It returns the output and any error. errfile is an optional (remote) file for stderr output

func (*SSHRemote) ServerVersion 

func (h *SSHRemote) ServerVersion() string

ServerVersion TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Signal 

func (h *SSHRemote) Signal(pid int, signal syscall.Signal) (err error)

Signal sends a signal to the remote pid and returns nil on success or os.ProcessDone if the process is not found.

func (*SSHRemote) Split added in v1.27.1 

func (h *SSHRemote) Split(file string) (dir, base string)

Split TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Start 

func (h *SSHRemote) Start(cmd *exec.Cmd, options ...ProcessOption) (pid int, err error)

Start starts a process on an SSH attached remote host h. It uses a shell and backgrounds and redirects. May not work on all remotes and for all processes. errfile has stdout/stderr appended to it, use '/dev/null' if no errfile is wanted.

func (*SSHRemote) Stat 

func (h *SSHRemote) Stat(name string) (fs.FileInfo, error)

Stat wraps the os.Stat and sftp.Stat functions

func (*SSHRemote) String 

func (h *SSHRemote) String() string

String TODO: Document its behavior, inputs, and effects. 

func (h *SSHRemote) Symlink(oldname, newname string) error

Symlink TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) TempDir added in v1.6.3 

func (h *SSHRemote) TempDir() string

TempDir returns a path on the remote to a temporary directory

BUG This is currently broken - hardwired values for now

func (*SSHRemote) ToSlash added in v1.27.1 

func (h *SSHRemote) ToSlash(path string) string

ToSlash TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Uname added in v1.14.2 

func (h *SSHRemote) Uname() (os, arch string, err error)

Uname TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) Username 

func (h *SSHRemote) Username() string

Username TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) VolumeName added in v1.27.1 

func (h *SSHRemote) VolumeName(path string) string

VolumeName TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) WalkDir added in v1.14.2 

func (h *SSHRemote) WalkDir(dir string, fn fs.WalkDirFunc) error

WalkDir TODO: Document its behavior, inputs, and effects.

func (*SSHRemote) WriteFile 

func (h *SSHRemote) WriteFile(name string, data []byte, perm os.FileMode) (err error)

WriteFile TODO: Document its behavior, inputs, and effects.

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.
⌂ 换网址