sshmux

README

sshmux

SSH multiplexing library, allowing you to write "jump host" style proxies.

Supports both transparent -oProxyJump=sshmux-server style jumps, as well as interactive session forwarding (with some limitations).

But i just want to run it...

Look at sshmuxd instead, then: https://github.com/kennylevinsen/sshmuxd. For fleet management, look at https://github.com/kennylevinsen/sshfleet.

Documentation

Index

• func KeyboardChallenge(comm io.ReadWriter, user, instruction string, questions []string, echos []bool) ([]string, error)
• func StringCallback(comm io.ReadWriter, prompt string, hide bool) (string, error)
• type Remote
  • func DefaultInteractive(comm io.ReadWriter, session *Session) (*Remote, error)
• type Server
  • func New(signer ssh.Signer, auth func(ssh.ConnMetadata, ssh.PublicKey) (*User, error), ...) *Server
  • func (s *Server) ChannelForward(session *Session, newChannel ssh.NewChannel)
  • func (s *Server) HandleConn(c net.Conn)
  • func (s *Server) Serve(l net.Listener) error
  • func (s *Server) SessionForward(session *Session, newChannel ssh.NewChannel)
• type Session
• type User

Functions

func KeyboardChallenge

func KeyboardChallenge(comm io.ReadWriter, user, instruction string, questions []string, echos []bool) ([]string, error)

KeyboardChallenge prompts the user for keyboards challenges.

func StringCallback

func StringCallback(comm io.ReadWriter, prompt string, hide bool) (string, error)

StringCallback prompts the user for a password.

Types

type Remote

type Remote struct {
	// The various names that can be used to select this remote
	Names []string

	// The description used for interactive prompting
	Description string

	// The address of this remote
	Address string

	// The username to connect with
	Username string
}

Remote describes the selectable remote server.

func DefaultInteractive

func DefaultInteractive(comm io.ReadWriter, session *Session) (*Remote, error)

DefaultInteractive is the default server selection prompt for users during session forward.

type Server

type Server struct {
	// Authenticator checks if a connection is permitted, and returns a user if
	// recognized.. Returning nil error indicates that the login was allowed,
	// regardless of whether the user was recognized or not. To disallow a
	// connection, return an error.
	Authenticator func(ssh.ConnMetadata, ssh.PublicKey) (*User, error)

	// Setup takes a Session, the most important task being filling out the
	// permitted remote hosts. Returning an error here will send the error to
	// the user and terminate the connection. This is not as clean as denying
	// the user in Authenticator, but can be used in case the denial was too
	// dynamic.
	Setup func(*Session) error

	// Interactive is called to ask the user to select a host on the list of
	// potential remote hosts. This is only called in the case where more than
	// one option is available. If an error is returned, it is presented to the
	// user and the connection is terminated. The io.ReadWriter is to be used
	// for user interaction.
	Interactive func(io.ReadWriter, *Session) (*Remote, error)

	// Selected is called when a remote host has been decided upon. The main
	// purpose of this callback is logging, but returning an error will
	// terminate the connection, allowing it to be used as a last-minute
	// bailout.
	Selected func(*Session, string) error

	// Dialer specifies a dial-up function used to establish the underlying
	// network connection to the ssh servers. Defaults to net.Dial.
	Dialer func(network, address string) (net.Conn, error)

	// UsernamePrompt is used to prompt the user for a username. If nil, the
	// username used to connect to sshmux will be used.
	UsernamePrompt func(io.ReadWriter, *Session) (string, error)

	// ConnectionTimeout specifies the timeout to use when forwarding a
	// connection. If zero, a sensible default will be used.
	ConnectionTimeout time.Duration
	// contains filtered or unexported fields
}

Server is the sshmux server instance.

func New

func New(signer ssh.Signer, auth func(ssh.ConnMetadata, ssh.PublicKey) (*User, error), setup func(*Session) error) *Server

New returns a Server initialized with the provided signer and callbacks.

func (*Server) ChannelForward

func (s *Server) ChannelForward(session *Session, newChannel ssh.NewChannel)

ChannelForward establishes a secure channel forward (ssh -W) to the server requested by the user, assuming it is a permitted host.

func (*Server) HandleConn

func (s *Server) HandleConn(c net.Conn)

HandleConn takes a net.Conn and runs it through sshmux.

func (*Server) Serve

func (s *Server) Serve(l net.Listener) error

Serve is an Accept loop that sends the accepted connections through HandleConn.

func (*Server) SessionForward

func (s *Server) SessionForward(session *Session, newChannel ssh.NewChannel)

SessionForward performs a regular forward, providing the user with an interactive remote host selection if necessary. This forwarding type requires agent forwarding in order to work.

type Session

type Session struct {
	// Conn is the ssh.ServerConn associated with the connection.
	Conn *ssh.ServerConn

	// User is the current user, or nil if unknown.
	User *User

	// Remotes is the allowed set of remote hosts.
	Remotes []*Remote

	// PublicKey is the public key used in this session.
	PublicKey ssh.PublicKey
}

Session describes the current user session.

type User

type User struct {
	// The public key of the user.
	PublicKey ssh.PublicKey

	// The name the user will be referred to as. *NOT* the username used when
	// starting the session.
	Name string
}

User describes an authenticable user.