sshutil

README

sshutil

A Go helper library for working with github.com/pkg/sftp and golang.org/x/crypto/ssh.

Documentation

Overview

Package sshutil provides additional SSH functionality.

Index

• Constants
• func AddHostKeyToKnownHosts(knownHostsFilePath string, hostname string, key ssh.PublicKey) error
• func AllowAndAddHostKeyCallBack(hostname string, remote net.Addr, currentKey ssh.PublicKey) error
• func GetKnownHostsFile() (exists bool, filePath string, err error)
• func ImitateSSHClientHostKeyCallBack(promptFunc func(SSHHostKeyPromptInfo) bool) ssh.HostKeyCallback
• func IsSSHHostKnown(hostPublicKey ssh.PublicKey, hostname string, fileContents []byte) (bool, error)
• func OnlyAllowKnownHostsKeyCallBack(hostname string, remote net.Addr, currentKey ssh.PublicKey) error
• func UploadFileUsingScp(localFilePath string, destinationFilePath string, sshClient *ssh.Client, ...) error
• func UploadFileUsingSftp(localFilePath string, destinationFilePath string, sshClient *ssh.Client, ...) error
• type CommandOptions
• type CommandResult
  • func ExecuteCommand(command string, sshClient *ssh.Client, options CommandOptions) CommandResult
  • func (o CommandResult) FirstString(delimiter string) string
  • func (o CommandResult) IsError() bool
  • func (o CommandResult) IsOutputEmpty() bool
  • func (o CommandResult) LastString(delimiter string) string
• type SSHHostKeyPromptInfo
• type TransferProgress
• type UploadOptions

Constants

const (
	DefaultKnownHostsFileMode = 0644

	ErrorDeterminingKnownHostsPath = "failed to determine known hosts file path"
	ErrorNoKnownHostsFilePresent   = "the known hosts file does not exist"
	ErrorUnknownHostKey            = "the specified host is not present in the known hosts file"
)

const (
	ErrorUploadTimeoutReached = "upload timeout was exceeded"
	ErrorUploadCanceled       = "the upload was canceled"
)

const (
	ErrorCommandDidNotProduceOutput = "the executed command did not produce any output"
)

Functions

func AddHostKeyToKnownHosts

func AddHostKeyToKnownHosts(knownHostsFilePath string, hostname string, key ssh.PublicKey) error

AddHostKeyToKnownHosts adds a host key to the known hosts file.

func AllowAndAddHostKeyCallBack

func AllowAndAddHostKeyCallBack(hostname string, remote net.Addr, currentKey ssh.PublicKey) error

AllowAndAddHostKeyCallBack permits any host and adds its key to the known hosts file.

func GetKnownHostsFile

func GetKnownHostsFile() (exists bool, filePath string, err error)

GetKnownHostsFile gets the path to the SSH known hosts file. The file path is not returned if the path could not be constructed. An error is returned when the file's path cannot be determined or if the file's mask is not equal to DefaultKnownHostsFileMode.

func ImitateSSHClientHostKeyCallBack

func ImitateSSHClientHostKeyCallBack(promptFunc func(SSHHostKeyPromptInfo) bool) ssh.HostKeyCallback

ImitateSSHClientHostKeyCallBack returns a ssh.HostKeyCallback that imitates the standard SSH command line client's behavior of prompting the user to verify an unknown public key, as well as rejecting mismatched public keys. This callback will call the provided promptFunc, which provides data about the host. The function should return 'true' if the user accepts the SSH host key. The function should return 'false' if the user does not accept the key.

func IsSSHHostKnown

func IsSSHHostKnown(hostPublicKey ssh.PublicKey, hostname string, fileContents []byte) (bool, error)

IsSSHHostKnown determines if an SSH server is known by the client according to the known hosts file.

func OnlyAllowKnownHostsKeyCallBack

func OnlyAllowKnownHostsKeyCallBack(hostname string, remote net.Addr, currentKey ssh.PublicKey) error

OnlyKnownHostKeyCallBack only permits known hosts when connecting to a SSH server. ErrorUnknownHostKey is returned if the host key does not exist in the known hosts file.

func UploadFileUsingScp

func UploadFileUsingScp(localFilePath string, destinationFilePath string, sshClient *ssh.Client, options UploadOptions) error

UploadFileUsingScp uploads a file using SCP (Secure Copy Protocol). The resulting file name is determined by the value of the destination file path. I.e., specifying a destination of '/root/my-cool-file.txt' results in the file being named 'my-cool-file.txt' located in '/root'. Be aware that the '~' character is not supported. If a timeout occurs, then ErrorUploadTimeoutReached is returned.

func UploadFileUsingSftp

func UploadFileUsingSftp(localFilePath string, destinationFilePath string, sshClient *ssh.Client, options UploadOptions) error

UploadFileUsingSftp uploads a file using SFTP (SSH File Transfer Protocol). The resulting file name is determined by the value of the destination file path. I.e., specifying a destination of '/root/my-cool-file.txt' results in the file being named 'my-cool-file.txt' located in '/root'. Be aware that the '~' character is not supported. If a timeout occurs, then ErrorUploadTimeoutReached is returned.

Types

type CommandOptions

type CommandOptions struct {
	RequireOutput bool
	StripNewLine  bool
}

type CommandResult

type CommandResult struct {
	Output string
	Error  string
}

func ExecuteCommand

func ExecuteCommand(command string, sshClient *ssh.Client, options CommandOptions) CommandResult

ExecuteCommand executes a command on a remote machine using SSH.

func (CommandResult) FirstString

func (o CommandResult) FirstString(delimiter string) string

func (CommandResult) IsError

func (o CommandResult) IsError() bool

func (CommandResult) IsOutputEmpty

func (o CommandResult) IsOutputEmpty() bool

func (CommandResult) LastString

func (o CommandResult) LastString(delimiter string) string

type SSHHostKeyPromptInfo

type SSHHostKeyPromptInfo struct {
	UserFacingPrompt    string
	FoundKnownHostsFile bool
	RemoteHostname      string
	RemotePublicKey     ssh.PublicKey
}

type TransferProgress

type TransferProgress struct {
	LocalFileSize  int64
	RemoteFileSize int64
	Percent        int
}

type UploadOptions

type UploadOptions struct {
	Cancel   chan bool
	Progress chan TransferProgress
	Timeout  time.Duration
}