Skip to content
This repository has been archived by the owner on Oct 2, 2022. It is now read-only.
/ sshserver Public archive

The SSH server and decoding library used by ContainerSSH

License

Notifications You must be signed in to change notification settings

ContainerSSH/sshserver

Folders and files

NameName
Last commit message
Last commit date

Latest commit

author
Janos Pasztor
Dec 11, 2020
0116211 · Dec 11, 2020

History

46 Commits
Nov 24, 2020
Nov 7, 2020
Dec 11, 2020
Nov 7, 2020
Dec 5, 2020
Dec 10, 2020
Dec 10, 2020
Dec 11, 2020
Dec 11, 2020
Dec 11, 2020
Nov 22, 2020
Dec 10, 2020
Dec 11, 2020
Nov 24, 2020
Nov 24, 2020
Nov 23, 2020
Dec 11, 2020

Repository files navigation

ContainerSSH - Launch Containers on Demand

ContainerSSH SSH Server Library

Go Report Card LGTM Alerts

This library provides an overlay for the built-in go SSH server library that makes it easier to handle.

Note: This is a developer documentation.
The user documentation for ContainerSSH is located at containerssh.github.io.

Using this library

This library provides a friendlier way to handle SSH requests than with the built-in SSH library. the primary method of using this library is via the Lifecycle objects from the service library:

// Create the server. See the description below for parameters.
server, err := sshserver.New(
    cfg,
    handler,
    logger,
)
if err != nil {
    // Handle configuration errors
    log.Fatalf("%v", err)
}
lifecycle := service.NewLifecycle(server)

defer func() {
    // The Run method will run the server and return when the server is shut down.
    // We are running this in a goroutine so the shutdown below can proceed after a minute.
    if err := lifecycle.Run(); err != nil {
        // Handle errors while running the server
    }
}()

time.Sleep(60 * time.Second)

// Shut down the server. Pass a context to indicate how long the server should wait
// for existing connections to finish. This function will return when the server
// has stopped. 
lifecycle.Stop(
    context.WithTimeout(
        context.Background(),
        30 * time.Second,
    ),
)

The cfg variable will be a Config structure as described in config.go.

The handler variable must be an implementation of the Handler interface described in handler.go.

The logger variable needs to be an instance of the Logger interface from github.com/containerssh/log.

Implementing a handler

The handler interface consists of multiple parts:

  • The Handler is the main handler for the application providing several hooks for events. On new connections the OnNetworkConnection method is called, which must return a NetworkConnectionHandler
  • The NetworkConnectionHandler is a handler for network connections before the SSH handshake is complete. It is called to perform authentication and return an SSHConnectionHandler when the authentication is successful.
  • The SSHConnectionHandler is responsible for handling an individual SSH connection. Most importantly, it is responsible for providing a SessionChannelHandler when a new session channel is requested by the client.
  • The SessionChannelHandler is responsible for an individual session channel (single program execution). It provides several hooks for setting up and running the program. Once the program execution is complete the channel is closed. You must, however, keep handling requests (e.g. window size change) during program execution.

A sample implementation can be found in the test code at the bottom of the file.

About the connectionID

The connectionID parameter in the OnNetworkConnection() is a hexadecimal string uniquely identifying a connection. This ID can be used to track connection-related information across multiple subsystems (e.g. logs, audit logs, authentication and configuration requests, etc.)