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