github.com/glycerine/xcryptossh@v7.0.4+incompatible/README.md (about) 1 # xcryptossh 2 3 This is an evolution of golang.org/x/crypto/ssh to fix memory leaks, provide for graceful shutdown, and implement idle timeouts. It is not API backwards compatible, as it provides `context.Context` based cancellation. 4 5 New feature: idle timeouts 6 -------------------------- 7 8 9 a) We would like to recognize when there has been no communication for some time 10 on an ssh.Channel. So that reads and writes can timeout. 11 12 b) We would like to timeout reads and writes so that they don't hang forever, 13 blocking and leaking a goroutine. 14 15 c) We would like to be able to send large files and only have these timeout when 16 there is no activity, rather than continuous acitivity of long duration. 17 A simple deadline estimate does not allow us to readily anticipate the 18 work and time needed to send a big file. 19 20 d) We found that the net.Conn approach of providing deadlines does not 21 serve case (c) above, and prohibits the implimentation of idle 22 times while simultaneously using facilities such as io.Copy() on 23 the stream, since the io.Copy will do multiple Reads/Writes. Each 24 Read/Write may need a deadline adjustment, but io.Copy cannot do 25 that for us. Therefore a more general means of establishing an 26 idle timeout is required. 27 28 To answer these needs, a new API method on the ssh.Channel interface has been implemented, 29 the `SetIdleTimeout` method. See the `channel.go` file. https://github.com/glycerine/xcryptossh/blob/master/channel.go#L91 30 31 ~~~ 32 package ssh 33 34 // A Channel is an ordered, reliable, flow-controlled, duplex stream 35 // that is multiplexed over an SSH connection. 36 type Channel interface { 37 38 ... 39 // SetIdleTimeout starts an idle timer on 40 // that will cause them to timeout after dur. 41 // A successful Read will bump the idle 42 // timeout into the future. Successful writes 43 // don't bump the timer because Write() to 44 // a Channel will "succeed" in the sense of 45 // returning a nil error long before they 46 // reach the remote end (or not). Writes 47 // are buffered internally. Hence write success 48 // has no impact on idle timeout. 49 // 50 // Providing dur of 0 will disable the idle timeout. 51 // Zero is the default until SetIdleTimeout() is called. 52 // 53 // SetIdleTimeout() will always reset and 54 // clear any raised timeout left over from prior use. 55 // Any new timer (if dur > 0) begins from the return of 56 // the SetIdleTimeout() invocation. 57 // 58 // Idle timeouts are easier to use than deadlines, 59 // as they don't need to be refreshed after 60 // every read and write. Hence routines like io.Copy() 61 // that makes many calls to Read() and Write() 62 // can be leveraged, while still having a timeout in 63 // the case of no activity. 64 // 65 // Moreover idle timeouts are more 66 // efficient because we don't guess at a 67 // deadline and then interrupt a perfectly 68 // good ongoing copy that happens to be 69 // taking a few seconds longer than our 70 // guesstimate. We avoid the pain of trying 71 // to restart long interrupted transfers that 72 // were making fine progress. 73 // 74 SetIdleTimeout(dur time.Duration) error 75 } 76 ~~~ 77 78 See the tests in `timeout_test.go` for example use. 79 80 ## install 81 82 ~~~ 83 $ go get -t -u -v github.com/glycerine/xcryptossh/... 84 ~~~ 85 86 ## author 87 88 Jason E. Aten, Ph.D. 89 90 ## license 91 92 Licensed under the same BSD style license as the x/crypto/ssh code. 93 See the LICENSE file. 94 95 ## current status 96 97 All functionality is working, but I still consider it experimental until 98 I've gotten more feedback and experience with it. Please try it out and 99 give feedback. 100 101 As of 2017 Aug 29: 102 103 Excellent. Tested on OSX and Linux. 104 105 All tests pass under -race. The tests no longer leak goroutines. 106 107 ## net.Conn limitations 108 109 ssh.Channel now impliments net.Conn, but there is a caveat 110 that you should be aware of. Write() calls will return a nil 111 error before data reaches the remote end. 112 113