flock

README

Flock: a high-level SSH library

Flock is a high-level library for executing commands on remote machines.

It's inspired by the Python Fabric package, but is written in Go.

WARNING: This library is still in development, has no test coverage, and very likely contains some potentially serious vulnerabilities. Do NOT use in production settings or in sensitive contexts.

Known Issues

• Known command injection issues. Commands line arguments are currently not being escaped properly. Do not use in production settings.
• No tests!!
• File transfer uses cat and bash. It needs to be written to use something like scp
• Code quality is pretty dodgy. It neads some refactoring and a good clean up (which is blocked by no tests).
• The use of sudo needs to be

Documentation

Overview

Flock is a high-level library for executing commands and transferring files on remote machines using SSH.

Index

• type Context
  • func (ctx *Context) AppendToFile(file string, data []byte) error
  • func (ctx *Context) Create(file string) (io.WriteCloser, error)
  • func (ctx *Context) Download(localFile, remoteFile string) error
  • func (ctx *Context) Must() *MustContext
  • func (ctx *Context) MustDo(fn func(*MustContext)) (err error)
  • func (ctx *Context) Open(file string) (io.ReadCloser, error)
  • func (ctx *Context) ReadFile(file string) ([]byte, error)
  • func (ctx *Context) RunEcho(cmd string, args ...string) error
  • func (ctx *Context) Sudo() *Context
  • func (ctx *Context) Upload(remoteFile, localFile string) error
  • func (ctx *Context) WriteFile(file string, data []byte) error
• type MustContext
  • func (mustCtx *MustContext) AppendToFile(file string, data []byte)
  • func (mustCtx *MustContext) Create(file string) io.WriteCloser
  • func (mustCtx *MustContext) Download(localFile, remoteFile string)
  • func (mustCtx *MustContext) Open(file string) io.ReadCloser
  • func (mustCtx *MustContext) Panic(err error)
  • func (mustCtx *MustContext) ReadFile(file string) []byte
  • func (mustCtx *MustContext) RunEcho(cmd string, args ...string)
  • func (mustCtx *MustContext) Sudo() *MustContext
  • func (mustCtx *MustContext) Upload(remoteFile, localFile string)
  • func (mustCtx *MustContext) WriteFile(file string, data []byte)
• type SSHAuth
  • func KeyPairAuth(path string, passphrase string) SSHAuth
  • func PasswordAuth(password string) SSHAuth
• type Session
  • func LocalSession() *Session
  • func NewSSH(addr, user string, auth SSHAuth) (*Session, error)
  • func (session *Session) Close() error

Types

type Context

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

Context represents the execution environment, such as the current directory, user, or machine. Contexts are immutable: any operation that will result in a change in the environment will return a new context.

func (*Context) AppendToFile

func (ctx *Context) AppendToFile(file string, data []byte) error

AppendToFile adds the contents to the end of a remote file. If the file does not exist, it will be created.

func (*Context) Create

func (ctx *Context) Create(file string) (io.WriteCloser, error)

Create opens a remote file for writing. The caller must close the file once done.

func (*Context) Download

func (ctx *Context) Download(localFile, remoteFile string) error

Download copies the contents of a remote file to a local file.

func (*Context) Must

func (ctx *Context) Must() *MustContext

Must returns a must context backed by this context.

func (*Context) MustDo

func (ctx *Context) MustDo(fn func(*MustContext)) (err error)

MustDo will run the function with a must context that mirrors the current context. Any panics thrown by the MustContext as a result of a failed command will be recovered here and retured as an error. Any other panics will be left to propogate up the stack.

func (*Context) Open

func (ctx *Context) Open(file string) (io.ReadCloser, error)

Open opens a remote file for reading. The caller must close the file once done.

func (*Context) ReadFile

func (ctx *Context) ReadFile(file string) ([]byte, error)

ReadFile reads the contents of a remote file and returns it as a byte slice.

func (*Context) RunEcho

func (ctx *Context) RunEcho(cmd string, args ...string) error

RunEcho runs the commands with no input and all output echoed to stdout. An error is returned if the command fails to execute successfully.

func (*Context) Sudo

func (ctx *Context) Sudo() *Context

Sudo returns a new context which will run commands and transfer files as the sudo user.

func (*Context) Upload

func (ctx *Context) Upload(remoteFile, localFile string) error

Upload copies the contents of a local file to the remote machine.

func (*Context) WriteFile

func (ctx *Context) WriteFile(file string, data []byte) error

WriteFile writes the contents of a remote file. If the file exists, it will be overwritten.

type MustContext

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

MustContext represents the execution environment, such as the current directory, user or machine. It's a lot like context except that any failures will cause the MustContext to panic instead of return an error.

func (*MustContext) AppendToFile

func (mustCtx *MustContext) AppendToFile(file string, data []byte)

AppendToFile adds the contents to the end of a remote file. The context will panic if there was a problem opening, writing to, or closing the file.

func (*MustContext) Create

func (mustCtx *MustContext) Create(file string) io.WriteCloser

Create opens a remote file for writing. The context will panic if there is a problem creating the remote file. An errors writing or closing to the file will not result in a panic. The caller must close the file once done.

func (*MustContext) Download

func (mustCtx *MustContext) Download(localFile, remoteFile string)

Download copies the contents of a remote file to a local file. The context will panic if there was a problem within the process.

func (*MustContext) Open

func (mustCtx *MustContext) Open(file string) io.ReadCloser

Open opens a remote file for reading. The context will panic if there is a problem opening the file. Any errors reading or closing the file will not result in a panic. The caller must close the file once done.

func (*MustContext) Panic

func (mustCtx *MustContext) Panic(err error)

Panic will cause the current MustContext to panic and fail. When running in Context.MustDo(), the passed in error will be returned.

func (*MustContext) ReadFile

func (mustCtx *MustContext) ReadFile(file string) []byte

ReadFile reads the contents of a remote file. The context will panic if there was a problem opening, reading or closing the file.

func (*MustContext) RunEcho

func (mustCtx *MustContext) RunEcho(cmd string, args ...string)

RunEcho runs the commands with no input and all output echoed to stdout. The context will panic if the command fails to execute successfully.

func (*MustContext) Sudo

func (mustCtx *MustContext) Sudo() *MustContext

Sudo returns a new context which will run commands and transfer files as the sudo user.

func (*MustContext) Upload

func (mustCtx *MustContext) Upload(remoteFile, localFile string)

Upload copies the contents of a local file to the remote machine. The context will panic if there was a problem within the process.

func (*MustContext) WriteFile

func (mustCtx *MustContext) WriteFile(file string, data []byte)

WriteFile writes the contents of a remote file. The context will panic if there was a problem opening, writing to, or closing the file.

type SSHAuth

type SSHAuth interface {
	// contains filtered or unexported methods
}

SSHAuth is the means of authenticating a session.

func KeyPairAuth

func KeyPairAuth(path string, passphrase string) SSHAuth

KeyPairAuth authenticates the session using a public-private key-pair, with the private key located at path with passphrase.

func PasswordAuth

func PasswordAuth(password string) SSHAuth

PasswordAuth authenticates the session using a simple password.

type Session

type Session struct {
	*Context
}

Session represents an SSH session to a particular machine. A session must be closed once it is no longer required.

func LocalSession

func LocalSession() *Session

LocalSession returns a session that is configured to run on the local machine. The commands and file transfer operations are run directly on the machine itself: they do not require a running SSH service.

func NewSSH

func NewSSH(addr, user string, auth SSHAuth) (*Session, error)

NewSSH creates a new SSH session to the remote machine addr as user authenticated using auth. An error is returned if there is a problem establishing the SSH session.

func (*Session) Close

func (session *Session) Close() error

Close closes the session.