host

package
v1.28.1 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 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  = errors.New("invalid arguments")
	ErrNotSupported = errors.New("not supported")
	ErrNotAvailable = errors.New("not available")
	ErrExist        = errors.New("already exists")
	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()
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)

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

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 {
}

Localhost operations

func (*Local) Abs added in v1.6.0 

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

func (*Local) Base added in v1.27.1 

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

func (*Local) Chown 

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

func (*Local) Chtimes added in v1.14.2 

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

func (*Local) Create 

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

func (*Local) Dir added in v1.27.1 

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

func (*Local) Ext added in v1.27.1 

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

func (*Local) GetFs 

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

func (*Local) Getwd added in v1.6.0 

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

func (*Local) Glob 

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

func (*Local) HostPath added in v1.14.2 

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

func (*Local) Hostname added in v1.6.0 

func (h *Local) Hostname() string

func (*Local) IsAbs added in v1.14.2 

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

IsAbs on a Windows host will always use filepath.IsAbs()

func (*Local) IsAvailable 

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

IsAvailable returns true for Local

func (*Local) IsLocalhost added in v1.27.1 

func (h *Local) IsLocalhost() bool

IsLocalhost returns true if h is local, which for Local it is

func (*Local) Join added in v1.27.1 

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

func (*Local) LastError 

func (h *Local) LastError() error

func (*Local) Lchown 

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

change the symlink ownership on local system, issue chown for remotes

func (*Local) Lchtimes added in v1.14.2 

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

func (*Local) Lstat 

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

func (*Local) Mkdir added in v1.26.0 

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

func (*Local) MkdirAll 

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

func (*Local) OS added in v1.27.1 

func (h *Local) OS() string

OS returns the operating system of the host, which for Local is whatever runtime.GOOS returns

func (*Local) Open 

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

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)
func (h *Local) Readlink(file string) (link string, err error)

func (*Local) Remove 

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

func (*Local) RemoveAll 

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

func (*Local) Rename 

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

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

func (*Local) Signal 

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

func (*Local) Split added in v1.27.1 

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

func (*Local) Start 

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

func (*Local) Stat 

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

Stat wraps the os.Stat and sftp.Stat functions

func (*Local) String 

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

func (*Local) TempDir added in v1.6.3 

func (h *Local) TempDir() string

func (*Local) ToSlash added in v1.27.1 

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

func (*Local) Uname added in v1.14.2 

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

func (*Local) Username 

func (h *Local) Username() string

func (*Local) VolumeName added in v1.27.1 

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

func (*Local) WalkDir added in v1.14.2 

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

func (*Local) WriteFile 

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

type ProcessOption added in v1.27.0 

type ProcessOption func(*processOptions)

func ProcessAllowCoreDumps added in v1.27.0 

func ProcessAllowCoreDumps() ProcessOption

func ProcessCPUAffinity added in v1.28.0 

func ProcessCPUAffinity(cpus ...int) ProcessOption

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

type SSHOption added in v1.27.0 

type SSHOption func(*SSHRemote)

func Hostname 

func Hostname(hostname string) SSHOption

func Password 

func Password(password []byte) SSHOption

func Port 

func Port(port uint16) SSHOption

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

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)

func (*SSHRemote) Base added in v1.27.1 

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

func (*SSHRemote) Chown 

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

func (*SSHRemote) Chtimes added in v1.14.2 

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

func (*SSHRemote) Close 

func (h *SSHRemote) Close()

Close a remote host connection

func (*SSHRemote) CloseSFTP 

func (h *SSHRemote) CloseSFTP()

func (*SSHRemote) Create 

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

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

func (*SSHRemote) Ext added in v1.27.1 

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

func (*SSHRemote) GetFs 

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

func (*SSHRemote) Getwd added in v1.6.0 

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

func (*SSHRemote) Glob 

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

func (*SSHRemote) HostPath added in v1.14.2 

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

func (*SSHRemote) Hostname added in v1.6.0 

func (s *SSHRemote) Hostname() string

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

func (*SSHRemote) LastError 

func (h *SSHRemote) LastError() error

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)
func (h *SSHRemote) Link(oldname, newname string) error

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

func (*SSHRemote) MkdirAll 

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

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

func (*SSHRemote) Open 

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

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)
func (h *SSHRemote) Readlink(file string) (string, error)

func (*SSHRemote) Remove 

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

func (*SSHRemote) RemoveAll 

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

func (*SSHRemote) Rename 

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

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

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)

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
func (h *SSHRemote) Symlink(oldname, newname string) error

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

func (*SSHRemote) Uname added in v1.14.2 

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

func (*SSHRemote) Username 

func (h *SSHRemote) Username() string

func (*SSHRemote) VolumeName added in v1.27.1 

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

func (*SSHRemote) WalkDir added in v1.14.2 

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

func (*SSHRemote) WriteFile 

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

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.