From c3f37d4334b00a4a6d9262e998bcb747292e3712 Mon Sep 17 00:00:00 2001 From: Jeff Lindsay Date: Wed, 30 Nov 2016 16:06:57 -0600 Subject: [PATCH] more docs, license, readme. Signed-off-by: Jeff Lindsay --- LICENSE | 27 +++++++++++++++++++++++++++ README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc.go | 16 ++++++++++++---- session.go | 2 +- 4 files changed, 91 insertions(+), 5 deletions(-) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4a03f02 --- /dev/null +++ b/LICENSE @@ -0,0 +1,27 @@ +Copyright (c) 2016 Glider Labs. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following disclaimer +in the documentation and/or other materials provided with the +distribution. + * Neither the name of Glider Labs nor the names of its +contributors may be used to endorse or promote products derived from +this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..7d59982 --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +# gliderlabs/ssh + +[![Slack](https://slack.gliderlabs.com/badge.svg)](http://slack.gliderlabs.com) [![GoDoc](https://godoc.org/github.com/gliderlabs/ssh?status.svg)](https://godoc.org/github.com/gliderlabs/ssh) + +This Go package wraps the [crypto/ssh +package](https://godoc.org/golang.org/x/crypto/ssh) with a higher-level API for +building SSH servers. The goal of the API was to make it as simple as using +[net/http](https://golang.org/pkg/net/http/), so the API is very similar: + +``` +package main + +import ( + "io" + "github.com/gliderlabs/ssh" +) + +func main() { + ssh.Handle(func(s ssh.Session) { + io.WriteString(s, "Hello world\n") + }) + + log.Fatal(ssh.ListenAndServe(":2222", nil)) +} + +``` + +This package was built after working on nearly a dozen projects using SSH and +collaborating with [@shazow](https://twitter.com/shazow) (known for [ssh-chat](https://github.com/shazow/ssh-chat)). + +## Usage + +[See GoDoc reference.](https://godoc.org/github.com/gliderlabs/ssh) + +## Testing + +We could use some help figuring out the best way to test this library. Since +there is very little functionality it's adding, it doesn't seem appropriate to +duplicate the crypto/ssh tests, however, maybe that's actually the best idea. Perform +the same tests using this API. + +## Contributing + +Pull requests are welcome! However, since this project is very much about API +design, please submit API changes as issues to discuss before submitting PRs. + +Also, you can [join our Slack](http://slack.gliderlabs.com) to discuss as well. + +## License + +BSD diff --git a/doc.go b/doc.go index 8f364a5..0361fb9 100644 --- a/doc.go +++ b/doc.go @@ -12,7 +12,7 @@ ListenAndServe starts an SSH server with a given address, handler, and options. handler is usually nil, which means to use DefaultHandler. Handle sets DefaultHandler: ssh.Handle(func(s ssh.Session) { - io.WriteString(s, "Hello world\n") + io.WriteString(s, "Hello world\n") }) log.Fatal(ssh.ListenAndServe(":2222", nil)) @@ -27,13 +27,21 @@ Although all options have functional option helpers, another way to control the server's behavior is by creating a custom Server: s := &ssh.Server{ - Addr: ":2222", - Handler: sessionHandler, - PublicKeyHandler: authHandler, + Addr: ":2222", + Handler: sessionHandler, + PublicKeyHandler: authHandler, } s.AddHostKey(hostKeySigner) log.Fatal(s.ListenAndServe()) +This package automatically handles basic SSH requests like setting environment +variables, requesting PTY, and changing window size. These requests are +processed, responded to, and any relevant state is updated. This state is then +exposed to you via the Session interface. + +The one big feature missing from the Session abstraction is signals. This was +started, but not completed. Pull Requests welcome! + */ package ssh diff --git a/session.go b/session.go index 46bd561..79c313e 100644 --- a/session.go +++ b/session.go @@ -43,7 +43,7 @@ type Session interface { PublicKey() PublicKey // Pty returns PTY information, a channel of window size changes, and a boolean - // of whether or not a PTY was created for this session. + // of whether or not a PTY was accepted for this session. Pty() (Pty, <-chan Window, bool) // TODO: Signals(c chan<- Signal)