sshkit

README

SSHKit

This package encapsulates my most common SSH actions needed in daily business. It simplifies creating/handling of SSH connections, simple SSH tunnels or SFTP filetransfers. Additionally it adds AgentAuth as ssh.AuthMethod. This way you can use your local SSH agent for authentication and do not have to handle passwords.

Examples

Keep in mind that these are examples. Handle your errors! Do not panic! ;)

SFTP

Transfer a file via SFTP from remote server to locahost:

package main

import (
	"github.com/mrccnt/sshkit"
	"golang.org/x/crypto/ssh"
	"fmt"
	"os"
)

func main() {

    sshClient, err := sshkit.SSHClient(
        sshkit.SSHConfig(
            "username",
            []ssh.AuthMethod{sshkit.AgentAuth()},
        ),
        "domain.tld:22",
    )
    if err != nil {
        panic(err.Error())
    }
    defer sshClient.Close()
    
    sftpClient, err := sshkit.SFTPClient(sshClient)
    if err != nil {
        panic(err.Error())
    }
    defer sftpClient.Close()
    
    bytes, err := sshkit.Pull(sftpClient, "remote/src/file.md", "local/dst/file.md")
    if err != nil {
        panic(err.Error())
    }
    fmt.Println(bytes, "bytes written on local filesystem")
    
    bytes, err = sshkit.Push(sftpClient, "local/src/file.md", "remote/dst/file.md")
    if err != nil {
        panic(err.Error())
    }
    fmt.Println(bytes, "bytes written on remote storage")

}

Tunnel

Create a tunnel to a remote host to make remote mysql server available on localhost port 13306:

package main

import (
    "github.com/mrccnt/sshkit"	
    "golang.org/x/crypto/ssh"	
)

func main(){
	// Create the complete tunnel configuration
	// You need a ssh.ClientConfig and someEndpoints
	tunnel := &sshkit.SSHTunnel{
		// Create a SSH ClientConfiguration with your requirements.
		Config: &ssh.ClientConfig{
			User: "username",
			Auth: []ssh.AuthMethod{
				sshkit.AgentAuth(),
			},
			HostKeyCallback: ssh.InsecureIgnoreHostKey(),
		},
		// The tunneled port from your remote server will be available on your localhost on port 13306
		Local: &sshkit.Endpoint{
			Host: "localhost",
			Port: 13306,
		},
		// Your remote SSH server
		Server: &sshkit.Endpoint{
			Host: "domain.tld",
			Port: 22,
		},
		// On your remote host we will use localhosts MySql server on default port 3306
		Remote: &sshkit.Endpoint{
			Host: "localhost",
			Port: 3306,
		},
	}
	// Initialize/Start the tunnel.
	// Keep in mind: This is a blocking action...
	err := tunnel.Start()
	if err != nil {
		panic(err.Error())
	}
}

Documentation

Index

• Constants
• func AgentAuth() ssh.AuthMethod
• func Exists(client *sftp.Client, path string) (bool, error)
• func GetGID(info os.FileInfo) uint32
• func GetUID(info os.FileInfo) uint32
• func HasOsAttrib(info os.FileInfo, permission uint32) bool
• func IsReadable(client *sftp.Client, path string) bool
• func LocalAgent() (net.Conn, error)
• func Pull(client *sftp.Client, remote string, local string) (int64, error)
• func Push(client *sftp.Client, local string, remote string) (int64, error)
• func SFTPClient(sshClient *ssh.Client) (*sftp.Client, error)
• func SSHClient(sshCfg *ssh.ClientConfig, addr string) (*ssh.Client, error)
• func SSHConfig(username string, auths []ssh.AuthMethod) *ssh.ClientConfig
• func StopCli(tunnel *SSHTunnel) error
• type Endpoint
  • func (endpoint *Endpoint) String() string
• type SSHTunnel
  • func (tunnel *SSHTunnel) Start() error
  • func (tunnel *SSHTunnel) StartCli() error

Constants

const (
	OsRead       = 04
	OsWrite      = 02
	OsEx         = 01
	OsUserShift  = 6
	OsGroupShift = 3
	OsOthShift   = 0

	OsUserR   = OsRead << OsUserShift
	OsUserW   = OsWrite << OsUserShift
	OsUserX   = OsEx << OsUserShift
	OsUserRw  = OsUserR | OsUserW
	OsUserRwx = OsUserRw | OsUserX

	OsGroupR   = OsRead << OsGroupShift
	OsGroupW   = OsWrite << OsGroupShift
	OsGroupX   = OsEx << OsGroupShift
	OsGroupRw  = OsGroupR | OsGroupW
	OsGroupRwx = OsGroupRw | OsGroupX

	OsOthR   = OsRead << OsOthShift
	OsOthW   = OsWrite << OsOthShift
	OsOthX   = OsEx << OsOthShift
	OsOthRw  = OsOthR | OsOthW
	OsOthRwx = OsOthRw | OsOthX

	OsAllR   = OsUserR | OsGroupR | OsOthR
	OsAllW   = OsUserW | OsGroupW | OsOthW
	OsAllX   = OsUserX | OsGroupX | OsOthX
	OsAllRw  = OsAllR | OsAllW
	OsAllRwx = OsAllRw | OsGroupX
)

File permission attributes (linux)

Functions

func AgentAuth

func AgentAuth() ssh.AuthMethod

AgentAuth returns a ssh.AuthMethod to use your local authentication agent

func Exists

func Exists(client *sftp.Client, path string) (bool, error)

Exists checks via glob() if a given file exists on the remote server

func GetGID

func GetGID(info os.FileInfo) uint32

GetGID returns the GID of given os.FileInfo

func GetUID

func GetUID(info os.FileInfo) uint32

GetUID returns the UID of given os.FileInfo

func HasOsAttrib

func HasOsAttrib(info os.FileInfo, permission uint32) bool

HasOsAttrib checks if given os.FileInfo matches given permissions:

Use OS_ constants to define the permissions flag:

if sshkit.HasOsAttrib(info, sshkit.OsUserR) {
		// This file is readable for user
}

if !sshkit.HasOsAttrib(info, sshkit.OsGroupW) {
		// This file is NOT writable for group members
}

func IsReadable

func IsReadable(client *sftp.Client, path string) bool

IsReadable checks if a given file on the remote server is readable

func LocalAgent

func LocalAgent() (net.Conn, error)

LocalAgent returns a connection to the local authentication agent via auth sock env variable

func Pull

func Pull(client *sftp.Client, remote string, local string) (int64, error)

Pull downloads a file from remote server to local fs

func Push

func Push(client *sftp.Client, local string, remote string) (int64, error)

Push uploads a file from local fs to remote server

func SFTPClient

func SFTPClient(sshClient *ssh.Client) (*sftp.Client, error)

SFTPClient returns a client to handle any SFTP actions

func SSHClient

func SSHClient(sshCfg *ssh.ClientConfig, addr string) (*ssh.Client, error)

SSHClient returns a SSH Client for given config and address

func SSHConfig

func SSHConfig(username string, auths []ssh.AuthMethod) *ssh.ClientConfig

SSHConfig returns a ssh.ClientConfig for given parameters

func StopCli

func StopCli(tunnel *SSHTunnel) error

StopCli closes tunnel to/from remote host via shell exec using ssh commands

Types

type Endpoint

type Endpoint struct {
	Host string
	Port int
}

Endpoint defines a host and port

func (*Endpoint) String

func (endpoint *Endpoint) String() string

String returns the preferred ssh package address format

type SSHTunnel

type SSHTunnel struct {
	Local  *Endpoint
	Server *Endpoint
	Remote *Endpoint
	Config *ssh.ClientConfig
	// contains filtered or unexported fields
}

SSHTunnel is the config needed to create a tunnel

func (*SSHTunnel) Start

func (tunnel *SSHTunnel) Start() error

Start initializes the tunnel and starts a forwarding (blocking)

func (*SSHTunnel) StartCli

func (tunnel *SSHTunnel) StartCli() error

StartCli creates tunnel to/from remote host via shell exec using ssh commands