libgo/go/exp/ssh/doc.go

   1 // Copyright 2011 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 /*
   6 Package ssh implements an SSH client and server.
   7
   8 SSH is a transport security protocol, an authentication protocol and a
   9 family of application protocols. The most typical application level
  10 protocol is a remote shell and this is specifically implemented.  However,
  11 the multiplexed nature of SSH is exposed to users that wish to support
  12 others.
  13
  14 An SSH server is represented by a ServerConfig, which holds certificate
  15 details and handles authentication of ServerConns.
  16
  17         config := new(ServerConfig)
  18         config.PubKeyCallback = pubKeyAuth
  19         config.PasswordCallback = passwordAuth
  20
  21         pemBytes, err := ioutil.ReadFile("id_rsa")
  22         if err != nil {
  23                 panic("Failed to load private key")
  24         }
  25         err = config.SetRSAPrivateKey(pemBytes)
  26         if err != nil {
  27                 panic("Failed to parse private key")
  28         }
  29
  30 Once a ServerConfig has been configured, connections can be accepted.
  31
  32         listener := Listen("tcp", "0.0.0.0:2022", config)
  33         sConn, err := listener.Accept()
  34         if err != nil {
  35                 panic("failed to accept incoming connection")
  36         }
  37         err = sConn.Handshake(conn)
  38         if err != nil {
  39                 panic("failed to handshake")
  40         }
  41
  42 An SSH connection multiplexes several channels, which must be accepted themselves:
  43
  44         for {
  45                 channel, err := sConn.Accept()
  46                 if err != nil {
  47                         panic("error from Accept")
  48                 }
  49
  50                 ...
  51         }
  52
  53 Accept reads from the connection, demultiplexes packets to their corresponding
  54 channels and returns when a new channel request is seen. Some goroutine must
  55 always be calling Accept; otherwise no messages will be forwarded to the
  56 channels.
  57
  58 Channels have a type, depending on the application level protocol intended. In
  59 the case of a shell, the type is "session" and ServerShell may be used to
  60 present a simple terminal interface.
  61
  62         if channel.ChannelType() != "session" {
  63                 c.Reject(UnknownChannelType, "unknown channel type")
  64                 return
  65         }
  66         channel.Accept()
  67
  68         shell := NewServerShell(channel, "> ")
  69         go func() {
  70                 defer channel.Close()
  71                 for {
  72                         line, err := shell.ReadLine()
  73                         if err != nil {
  74                                 break
  75                         }
  76                         println(line)
  77                 }
  78                 return
  79         }()
  80
  81 An SSH client is represented with a ClientConn. Currently only the "password"
  82 authentication method is supported.
  83
  84         config := &ClientConfig{
  85                 User: "username",
  86                 Password: "123456",
  87         }
  88         client, err := Dial("yourserver.com:22", config)
  89
  90 Each ClientConn can support multiple interactive sessions, represented by a Session.
  91
  92         session, err := client.NewSession()
  93
  94 Once a Session is created, you can execute a single command on the remote side
  95 using the Exec method.
  96
  97         if err := session.Exec("/usr/bin/whoami"); err != nil {
  98                 panic("Failed to exec: " + err.String())
  99         }
 100         reader := bufio.NewReader(session.Stdin)
 101         line, _, _ := reader.ReadLine()
 102         fmt.Println(line)
 103         session.Close()
 104 */
 105 package ssh