paramiko.channel

Package paramiko :: Module channel |
[frames] | no frames]

# Source Code for Module paramiko.channel

       1  # Copyright (C) 2003-2007  Robey Pointer <robeypointer@gmail.com>
       2  #
       3  # This file is part of paramiko.
       4  #
       5  # Paramiko is free software; you can redistribute it and/or modify it under the
       6  # terms of the GNU Lesser General Public License as published by the Free
       7  # Software Foundation; either version 2.1 of the License, or (at your option)
       8  # any later version.
       9  #
      10  # Paramiko is distributed in the hope that it will be useful, but WITHOUT ANY
      11  # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
      12  # A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
      13  # details.
      14  #
      15  # You should have received a copy of the GNU Lesser General Public License
      16  # along with Paramiko; if not, write to the Free Software Foundation, Inc.,
      17  # 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.
      18
      19  """
      20  Abstraction for an SSH2 channel.
      21  """
      22
      23  import binascii
      24  import sys
      25  import time
      26  import threading
      27  import socket
      28  import os
      29
      30  from paramiko.common import *
      31  from paramiko import util
      32  from paramiko.message import Message
      33  from paramiko.ssh_exception import SSHException
      34  from paramiko.file import BufferedFile
      35  from paramiko.buffered_pipe import BufferedPipe, PipeTimeout
      36  from paramiko import pipe
      37
      38
      39  # lower bound on the max packet size we'll accept from the remote host
      40  MIN_PACKET_SIZE = 1024
      41
      42
      43 -class Channel (object):
      44      """
      45      A secure tunnel across an SSH L{Transport}.  A Channel is meant to behave
      46      like a socket, and has an API that should be indistinguishable from the
      47      python socket API.
      48
      49      Because SSH2 has a windowing kind of flow control, if you stop reading data
      50      from a Channel and its buffer fills up, the server will be unable to send
      51      you any more data until you read some of it.  (This won't affect other
      52      channels on the same transport -- all channels on a single transport are
      53      flow-controlled independently.)  Similarly, if the server isn't reading
      54      data you send, calls to L{send} may block, unless you set a timeout.  This
      55      is exactly like a normal network socket, so it shouldn't be too surprising.
      56      """
      57
      58 -    def __init__(self, chanid):
      59          """
      60          Create a new channel.  The channel is not associated with any
      61          particular session or L{Transport} until the Transport attaches it.
      62          Normally you would only call this method from the constructor of a
      63          subclass of L{Channel}.
      64
      65          @param chanid: the ID of this channel, as passed by an existing
      66              L{Transport}.
      67          @type chanid: int
      68          """
      69          self.chanid = chanid
      70          self.remote_chanid = 0
      71          self.transport = None
      72          self.active = False
      73          self.eof_received = 0
      74          self.eof_sent = 0
      75          self.in_buffer = BufferedPipe()
      76          self.in_stderr_buffer = BufferedPipe()
      77          self.timeout = None
      78          self.closed = False
      79          self.ultra_debug = False
      80          self.lock = threading.Lock()
      81          self.out_buffer_cv = threading.Condition(self.lock)
      82          self.in_window_size = 0
      83          self.out_window_size = 0
      84          self.in_max_packet_size = 0
      85          self.out_max_packet_size = 0
      86          self.in_window_threshold = 0
      87          self.in_window_sofar = 0
      88          self.status_event = threading.Event()
      89          self._name = str(chanid)
      90          self.logger = util.get_logger('paramiko.transport')
      91          self._pipe = None
      92          self.event = threading.Event()
      93          self.event_ready = False
      94          self.combine_stderr = False
      95          self.exit_status = -1
      96          self.origin_addr = None
      97
      98 -    def __del__(self):
      99          try:
     100              self.close()
     101          except:
     102              pass
     103
     104 -    def __repr__(self):
     105          """
     106          Return a string representation of this object, for debugging.
     107
     108          @rtype: str
     109          """
     110          out = '<paramiko.Channel %d' % self.chanid
     111          if self.closed:
     112              out += ' (closed)'
     113          elif self.active:
     114              if self.eof_received:
     115                  out += ' (EOF received)'
     116              if self.eof_sent:
     117                  out += ' (EOF sent)'
     118              out += ' (open) window=%d' % (self.out_window_size)
     119              if len(self.in_buffer) > 0:
     120                  out += ' in-buffer=%d' % (len(self.in_buffer),)
     121          out += ' -> ' + repr(self.transport)
     122          out += '>'
     123          return out
     124
     125 -    def get_pty(self, term='vt100', width=80, height=24, width_pixels=0,
     126                  height_pixels=0):
     127          """
     128          Request a pseudo-terminal from the server.  This is usually used right
     129          after creating a client channel, to ask the server to provide some
     130          basic terminal semantics for a shell invoked with L{invoke_shell}.
     131          It isn't necessary (or desirable) to call this method if you're going
     132          to exectue a single command with L{exec_command}.
     133
     134          @param term: the terminal type to emulate (for example, C{'vt100'})
     135          @type term: str
     136          @param width: width (in characters) of the terminal screen
     137          @type width: int
     138          @param height: height (in characters) of the terminal screen
     139          @type height: int
     140          @param width_pixels: width (in pixels) of the terminal screen
     141          @type width_pixels: int
     142          @param height_pixels: height (in pixels) of the terminal screen
     143          @type height_pixels: int
     144
     145          @raise SSHException: if the request was rejected or the channel was
     146              closed
     147          """
     148          if self.closed or self.eof_received or self.eof_sent or not self.active:
     149              raise SSHException('Channel is not open')
     150          m = Message()
     151          m.add_byte(chr(MSG_CHANNEL_REQUEST))
     152          m.add_int(self.remote_chanid)
     153          m.add_string('pty-req')
     154          m.add_boolean(True)
     155          m.add_string(term)
     156          m.add_int(width)
     157          m.add_int(height)
     158          m.add_int(width_pixels)
     159          m.add_int(height_pixels)
     160          m.add_string('')
     161          self._event_pending()
     162          self.transport._send_user_message(m)
     163          self._wait_for_event()
     164
     165 -    def invoke_shell(self):
     166          """
     167          Request an interactive shell session on this channel.  If the server
     168          allows it, the channel will then be directly connected to the stdin,
     169          stdout, and stderr of the shell.
     170
     171          Normally you would call L{get_pty} before this, in which case the
     172          shell will operate through the pty, and the channel will be connected
     173          to the stdin and stdout of the pty.
     174
     175          When the shell exits, the channel will be closed and can't be reused.
     176          You must open a new channel if you wish to open another shell.
     177
     178          @raise SSHException: if the request was rejected or the channel was
     179              closed
     180          """
     181          if self.closed or self.eof_received or self.eof_sent or not self.active:
     182              raise SSHException('Channel is not open')
     183          m = Message()
     184          m.add_byte(chr(MSG_CHANNEL_REQUEST))
     185          m.add_int(self.remote_chanid)
     186          m.add_string('shell')
     187          m.add_boolean(1)
     188          self._event_pending()
     189          self.transport._send_user_message(m)
     190          self._wait_for_event()
     191
     192 -    def exec_command(self, command):
     193          """
     194          Execute a command on the server.  If the server allows it, the channel
     195          will then be directly connected to the stdin, stdout, and stderr of
     196          the command being executed.
     197
     198          When the command finishes executing, the channel will be closed and
     199          can't be reused.  You must open a new channel if you wish to execute
     200          another command.
     201
     202          @param command: a shell command to execute.
     203          @type command: str
     204
     205          @raise SSHException: if the request was rejected or the channel was
     206              closed
     207          """
     208          if self.closed or self.eof_received or self.eof_sent or not self.active:
     209              raise SSHException('Channel is not open')
     210          m = Message()
     211          m.add_byte(chr(MSG_CHANNEL_REQUEST))
     212          m.add_int(self.remote_chanid)
     213          m.add_string('exec')
     214          m.add_boolean(True)
     215          m.add_string(command)
     216          self._event_pending()
     217          self.transport._send_user_message(m)
     218          self._wait_for_event()
     219
     220 -    def invoke_subsystem(self, subsystem):
     221          """
     222          Request a subsystem on the server (for example, C{sftp}).  If the
     223          server allows it, the channel will then be directly connected to the
     224          requested subsystem.
     225
     226          When the subsystem finishes, the channel will be closed and can't be
     227          reused.
     228
     229          @param subsystem: name of the subsystem being requested.
     230          @type subsystem: str
     231
     232          @raise SSHException: if the request was rejected or the channel was
     233              closed
     234          """
     235          if self.closed or self.eof_received or self.eof_sent or not self.active:
     236              raise SSHException('Channel is not open')
     237          m = Message()
     238          m.add_byte(chr(MSG_CHANNEL_REQUEST))
     239          m.add_int(self.remote_chanid)
     240          m.add_string('subsystem')
     241          m.add_boolean(True)
     242          m.add_string(subsystem)
     243          self._event_pending()
     244          self.transport._send_user_message(m)
     245          self._wait_for_event()
     246
     247 -    def resize_pty(self, width=80, height=24, width_pixels=0, height_pixels=0):
     248          """
     249          Resize the pseudo-terminal.  This can be used to change the width and
     250          height of the terminal emulation created in a previous L{get_pty} call.
     251
     252          @param width: new width (in characters) of the terminal screen
     253          @type width: int
     254          @param height: new height (in characters) of the terminal screen
     255          @type height: int
     256          @param width_pixels: new width (in pixels) of the terminal screen
     257          @type width_pixels: int
     258          @param height_pixels: new height (in pixels) of the terminal screen
     259          @type height_pixels: int
     260
     261          @raise SSHException: if the request was rejected or the channel was
     262              closed
     263          """
     264          if self.closed or self.eof_received or self.eof_sent or not self.active:
     265              raise SSHException('Channel is not open')
     266          m = Message()
     267          m.add_byte(chr(MSG_CHANNEL_REQUEST))
     268          m.add_int(self.remote_chanid)
     269          m.add_string('window-change')
     270          m.add_boolean(False)
     271          m.add_int(width)
     272          m.add_int(height)
     273          m.add_int(width_pixels)
     274          m.add_int(height_pixels)
     275          self.transport._send_user_message(m)
     276
     277 -    def exit_status_ready(self):
     278          """
     279          Return true if the remote process has exited and returned an exit
     280          status. You may use this to poll the process status if you don't
     281          want to block in L{recv_exit_status}. Note that the server may not
     282          return an exit status in some cases (like bad servers).
     283
     284          @return: True if L{recv_exit_status} will return immediately
     285          @rtype: bool
     286          @since: 1.7.3
     287          """
     288          return self.closed or self.status_event.isSet()
     289
     290 -    def recv_exit_status(self):
     291          """
     292          Return the exit status from the process on the server.  This is
     293          mostly useful for retrieving the reults of an L{exec_command}.
     294          If the command hasn't finished yet, this method will wait until
     295          it does, or until the channel is closed.  If no exit status is
     296          provided by the server, -1 is returned.
     297
     298          @return: the exit code of the process on the server.
     299          @rtype: int
     300
     301          @since: 1.2
     302          """
     303          self.status_event.wait()
     304          assert self.status_event.isSet()
     305          return self.exit_status
     306
     307 -    def send_exit_status(self, status):
     308          """
     309          Send the exit status of an executed command to the client.  (This
     310          really only makes sense in server mode.)  Many clients expect to
     311          get some sort of status code back from an executed command after
     312          it completes.
     313
     314          @param status: the exit code of the process
     315          @type status: int
     316
     317          @since: 1.2
     318          """
     319          # in many cases, the channel will not still be open here.
     320          # that's fine.
     321          m = Message()
     322          m.add_byte(chr(MSG_CHANNEL_REQUEST))
     323          m.add_int(self.remote_chanid)
     324          m.add_string('exit-status')
     325          m.add_boolean(False)
     326          m.add_int(status)
     327          self.transport._send_user_message(m)
     328
     329 -    def request_x11(self, screen_number=0, auth_protocol=None, auth_cookie=None,
     330                      single_connection=False, handler=None):
     331          """
     332          Request an x11 session on this channel.  If the server allows it,
     333          further x11 requests can be made from the server to the client,
     334          when an x11 application is run in a shell session.
     335
     336          From RFC4254::
     337
     338              It is RECOMMENDED that the 'x11 authentication cookie' that is
     339              sent be a fake, random cookie, and that the cookie be checked and
     340              replaced by the real cookie when a connection request is received.
     341
     342          If you omit the auth_cookie, a new secure random 128-bit value will be
     343          generated, used, and returned.  You will need to use this value to
     344          verify incoming x11 requests and replace them with the actual local
     345          x11 cookie (which requires some knoweldge of the x11 protocol).
     346
     347          If a handler is passed in, the handler is called from another thread
     348          whenever a new x11 connection arrives.  The default handler queues up
     349          incoming x11 connections, which may be retrieved using
     350          L{Transport.accept}.  The handler's calling signature is::
     351
     352              handler(channel: Channel, (address: str, port: int))
     353
     354          @param screen_number: the x11 screen number (0, 10, etc)
     355          @type screen_number: int
     356          @param auth_protocol: the name of the X11 authentication method used;
     357              if none is given, C{"MIT-MAGIC-COOKIE-1"} is used
     358          @type auth_protocol: str
     359          @param auth_cookie: hexadecimal string containing the x11 auth cookie;
     360              if none is given, a secure random 128-bit value is generated
     361          @type auth_cookie: str
     362          @param single_connection: if True, only a single x11 connection will be
     363              forwarded (by default, any number of x11 connections can arrive
     364              over this session)
     365          @type single_connection: bool
     366          @param handler: an optional handler to use for incoming X11 connections
     367          @type handler: function
     368          @return: the auth_cookie used
     369          """
     370          if self.closed or self.eof_received or self.eof_sent or not self.active:
     371              raise SSHException('Channel is not open')
     372          if auth_protocol is None:
     373              auth_protocol = 'MIT-MAGIC-COOKIE-1'
     374          if auth_cookie is None:
     375              auth_cookie = binascii.hexlify(self.transport.rng.read(16))
     376
     377          m = Message()
     378          m.add_byte(chr(MSG_CHANNEL_REQUEST))
     379          m.add_int(self.remote_chanid)
     380          m.add_string('x11-req')
     381          m.add_boolean(True)
     382          m.add_boolean(single_connection)
     383          m.add_string(auth_protocol)
     384          m.add_string(auth_cookie)
     385          m.add_int(screen_number)
     386          self._event_pending()
     387          self.transport._send_user_message(m)
     388          self._wait_for_event()
     389          self.transport._set_x11_handler(handler)
     390          return auth_cookie
     391
     392 -    def request_forward_agent(self, handler):
     393          """
     394          Request for a forward SSH Agent on this channel.
     395          This is only valid for an ssh-agent from openssh !!!
     396
     397          @param handler: a required handler to use for incoming SSH Agent connections
     398          @type handler: function
     399
     400          @return: if we are ok or not (at that time we always return ok)
     401          @rtype: boolean
     402
     403          @raise: SSHException in case of channel problem.
     404          """
     405          if self.closed or self.eof_received or self.eof_sent or not self.active:
     406              raise SSHException('Channel is not open')
     407
     408          m = Message()
     409          m.add_byte(chr(MSG_CHANNEL_REQUEST))
     410          m.add_int(self.remote_chanid)
     411          m.add_string('auth-agent-req@openssh.com')
     412          m.add_boolean(False)
     413          self.transport._send_user_message(m)
     414          self.transport._set_forward_agent_handler(handler)
     415          return True
     416
     417 -    def get_transport(self):
     418          """
     419          Return the L{Transport} associated with this channel.
     420
     421          @return: the L{Transport} that was used to create this channel.
     422          @rtype: L{Transport}
     423          """
     424          return self.transport
     425
     426 -    def set_name(self, name):
     427          """
     428          Set a name for this channel.  Currently it's only used to set the name
     429          of the channel in logfile entries.  The name can be fetched with the
     430          L{get_name} method.
     431
     432          @param name: new channel name
     433          @type name: str
     434          """
     435          self._name = name
     436
     437 -    def get_name(self):
     438          """
     439          Get the name of this channel that was previously set by L{set_name}.
     440
     441          @return: the name of this channel.
     442          @rtype: str
     443          """
     444          return self._name
     445
     446 -    def get_id(self):
     447          """
     448          Return the ID # for this channel.  The channel ID is unique across
     449          a L{Transport} and usually a small number.  It's also the number
     450          passed to L{ServerInterface.check_channel_request} when determining
     451          whether to accept a channel request in server mode.
     452
     453          @return: the ID of this channel.
     454          @rtype: int
     455          """
     456          return self.chanid
     457
     458 -    def set_combine_stderr(self, combine):
     459          """
     460          Set whether stderr should be combined into stdout on this channel.
     461          The default is C{False}, but in some cases it may be convenient to
     462          have both streams combined.
     463
     464          If this is C{False}, and L{exec_command} is called (or C{invoke_shell}
     465          with no pty), output to stderr will not show up through the L{recv}
     466          and L{recv_ready} calls.  You will have to use L{recv_stderr} and
     467          L{recv_stderr_ready} to get stderr output.
     468
     469          If this is C{True}, data will never show up via L{recv_stderr} or
     470          L{recv_stderr_ready}.
     471
     472          @param combine: C{True} if stderr output should be combined into
     473              stdout on this channel.
     474          @type combine: bool
     475          @return: previous setting.
     476          @rtype: bool
     477
     478          @since: 1.1
     479          """
     480          data = ''
     481          self.lock.acquire()
     482          try:
     483              old = self.combine_stderr
     484              self.combine_stderr = combine
     485              if combine and not old:
     486                  # copy old stderr buffer into primary buffer
     487                  data = self.in_stderr_buffer.empty()
     488          finally:
     489              self.lock.release()
     490          if len(data) > 0:
     491              self._feed(data)
     492          return old
     493
     494
     495      ###  socket API
     496
     497
     498 -    def settimeout(self, timeout):
     499          """
     500          Set a timeout on blocking read/write operations.  The C{timeout}
     501          argument can be a nonnegative float expressing seconds, or C{None}.  If
     502          a float is given, subsequent channel read/write operations will raise
     503          a timeout exception if the timeout period value has elapsed before the
     504          operation has completed.  Setting a timeout of C{None} disables
     505          timeouts on socket operations.
     506
     507          C{chan.settimeout(0.0)} is equivalent to C{chan.setblocking(0)};
     508          C{chan.settimeout(None)} is equivalent to C{chan.setblocking(1)}.
     509
     510          @param timeout: seconds to wait for a pending read/write operation
     511              before raising C{socket.timeout}, or C{None} for no timeout.
     512          @type timeout: float
     513          """
     514          self.timeout = timeout
     515
     516 -    def gettimeout(self):
     517          """
     518          Returns the timeout in seconds (as a float) associated with socket
     519          operations, or C{None} if no timeout is set.  This reflects the last
     520          call to L{setblocking} or L{settimeout}.
     521
     522          @return: timeout in seconds, or C{None}.
     523          @rtype: float
     524          """
     525          return self.timeout
     526
     527 -    def setblocking(self, blocking):
     528          """
     529          Set blocking or non-blocking mode of the channel: if C{blocking} is 0,
     530          the channel is set to non-blocking mode; otherwise it's set to blocking
     531          mode. Initially all channels are in blocking mode.
     532
     533          In non-blocking mode, if a L{recv} call doesn't find any data, or if a
     534          L{send} call can't immediately dispose of the data, an error exception
     535          is raised. In blocking mode, the calls block until they can proceed. An
     536          EOF condition is considered "immediate data" for L{recv}, so if the
     537          channel is closed in the read direction, it will never block.
     538
     539          C{chan.setblocking(0)} is equivalent to C{chan.settimeout(0)};
     540          C{chan.setblocking(1)} is equivalent to C{chan.settimeout(None)}.
     541
     542          @param blocking: 0 to set non-blocking mode; non-0 to set blocking
     543              mode.
     544          @type blocking: int
     545          """
     546          if blocking:
     547              self.settimeout(None)
     548          else:
     549              self.settimeout(0.0)
     550
     551 -    def getpeername(self):
     552          """
     553          Return the address of the remote side of this Channel, if possible.
     554          This is just a wrapper around C{'getpeername'} on the Transport, used
     555          to provide enough of a socket-like interface to allow asyncore to work.
     556          (asyncore likes to call C{'getpeername'}.)
     557
     558          @return: the address if the remote host, if known
     559          @rtype: tuple(str, int)
     560          """
     561          return self.transport.getpeername()
     562
     563 -    def close(self):
     564          """
     565          Close the channel.  All future read/write operations on the channel
     566          will fail.  The remote end will receive no more data (after queued data
     567          is flushed).  Channels are automatically closed when their L{Transport}
     568          is closed or when they are garbage collected.
     569          """
     570          self.lock.acquire()
     571          try:
     572              # only close the pipe when the user explicitly closes the channel.
     573              # otherwise they will get unpleasant surprises.  (and do it before
     574              # checking self.closed, since the remote host may have already
     575              # closed the connection.)
     576              if self._pipe is not None:
     577                  self._pipe.close()
     578                  self._pipe = None
     579
     580              if not self.active or self.closed:
     581                  return
     582              msgs = self._close_internal()
     583          finally:
     584              self.lock.release()
     585          for m in msgs:
     586              if m is not None:
     587                  self.transport._send_user_message(m)
     588
     589 -    def recv_ready(self):
     590          """
     591          Returns true if data is buffered and ready to be read from this
     592          channel.  A C{False} result does not mean that the channel has closed;
     593          it means you may need to wait before more data arrives.
     594
     595          @return: C{True} if a L{recv} call on this channel would immediately
     596              return at least one byte; C{False} otherwise.
     597          @rtype: boolean
     598          """
     599          return self.in_buffer.read_ready()
     600
     601 -    def recv(self, nbytes):
     602          """
     603          Receive data from the channel.  The return value is a string
     604          representing the data received.  The maximum amount of data to be
     605          received at once is specified by C{nbytes}.  If a string of length zero
     606          is returned, the channel stream has closed.
     607
     608          @param nbytes: maximum number of bytes to read.
     609          @type nbytes: int
     610          @return: data.
     611          @rtype: str
     612
     613          @raise socket.timeout: if no data is ready before the timeout set by
     614              L{settimeout}.
     615          """
     616          try:
     617              out = self.in_buffer.read(nbytes, self.timeout)
     618          except PipeTimeout, e:
     619              raise socket.timeout()
     620
     621          ack = self._check_add_window(len(out))
     622          # no need to hold the channel lock when sending this
     623          if ack > 0:
     624              m = Message()
     625              m.add_byte(chr(MSG_CHANNEL_WINDOW_ADJUST))
     626              m.add_int(self.remote_chanid)
     627              m.add_int(ack)
     628              self.transport._send_user_message(m)
     629
     630          return out
     631
     632 -    def recv_stderr_ready(self):
     633          """
     634          Returns true if data is buffered and ready to be read from this
     635          channel's stderr stream.  Only channels using L{exec_command} or
     636          L{invoke_shell} without a pty will ever have data on the stderr
     637          stream.
     638
     639          @return: C{True} if a L{recv_stderr} call on this channel would
     640              immediately return at least one byte; C{False} otherwise.
     641          @rtype: boolean
     642
     643          @since: 1.1
     644          """
     645          return self.in_stderr_buffer.read_ready()
     646
     647 -    def recv_stderr(self, nbytes):
     648          """
     649          Receive data from the channel's stderr stream.  Only channels using
     650          L{exec_command} or L{invoke_shell} without a pty will ever have data
     651          on the stderr stream.  The return value is a string representing the
     652          data received.  The maximum amount of data to be received at once is
     653          specified by C{nbytes}.  If a string of length zero is returned, the
     654          channel stream has closed.
     655
     656          @param nbytes: maximum number of bytes to read.
     657          @type nbytes: int
     658          @return: data.
     659          @rtype: str
     660
     661          @raise socket.timeout: if no data is ready before the timeout set by
     662              L{settimeout}.
     663
     664          @since: 1.1
     665          """
     666          try:
     667              out = self.in_stderr_buffer.read(nbytes, self.timeout)
     668          except PipeTimeout, e:
     669              raise socket.timeout()
     670
     671          ack = self._check_add_window(len(out))
     672          # no need to hold the channel lock when sending this
     673          if ack > 0:
     674              m = Message()
     675              m.add_byte(chr(MSG_CHANNEL_WINDOW_ADJUST))
     676              m.add_int(self.remote_chanid)
     677              m.add_int(ack)
     678              self.transport._send_user_message(m)
     679
     680          return out
     681
     682 -    def send_ready(self):
     683          """
     684          Returns true if data can be written to this channel without blocking.
     685          This means the channel is either closed (so any write attempt would
     686          return immediately) or there is at least one byte of space in the
     687          outbound buffer. If there is at least one byte of space in the
     688          outbound buffer, a L{send} call will succeed immediately and return
     689          the number of bytes actually written.
     690
     691          @return: C{True} if a L{send} call on this channel would immediately
     692              succeed or fail
     693          @rtype: boolean
     694          """
     695          self.lock.acquire()
     696          try:
     697              if self.closed or self.eof_sent:
     698                  return True
     699              return self.out_window_size > 0
     700          finally:
     701              self.lock.release()
     702
     703 -    def send(self, s):
     704          """
     705          Send data to the channel.  Returns the number of bytes sent, or 0 if
     706          the channel stream is closed.  Applications are responsible for
     707          checking that all data has been sent: if only some of the data was
     708          transmitted, the application needs to attempt delivery of the remaining
     709          data.
     710
     711          @param s: data to send
     712          @type s: str
     713          @return: number of bytes actually sent
     714          @rtype: int
     715
     716          @raise socket.timeout: if no data could be sent before the timeout set
     717              by L{settimeout}.
     718          """
     719          size = len(s)
     720          self.lock.acquire()
     721          try:
     722              size = self._wait_for_send_window(size)
     723              if size == 0:
     724                  # eof or similar
     725                  return 0
     726              m = Message()
     727              m.add_byte(chr(MSG_CHANNEL_DATA))
     728              m.add_int(self.remote_chanid)
     729              m.add_string(s[:size])
     730          finally:
     731              self.lock.release()
     732          # Note: We release self.lock before calling _send_user_message.
     733          # Otherwise, we can deadlock during re-keying.
     734          self.transport._send_user_message(m)
     735          return size
     736
     737 -    def send_stderr(self, s):
     738          """
     739          Send data to the channel on the "stderr" stream.  This is normally
     740          only used by servers to send output from shell commands -- clients
     741          won't use this.  Returns the number of bytes sent, or 0 if the channel
     742          stream is closed.  Applications are responsible for checking that all
     743          data has been sent: if only some of the data was transmitted, the
     744          application needs to attempt delivery of the remaining data.
     745
     746          @param s: data to send.
     747          @type s: str
     748          @return: number of bytes actually sent.
     749          @rtype: int
     750
     751          @raise socket.timeout: if no data could be sent before the timeout set
     752              by L{settimeout}.
     753
     754          @since: 1.1
     755          """
     756          size = len(s)
     757          self.lock.acquire()
     758          try:
     759              size = self._wait_for_send_window(size)
     760              if size == 0:
     761                  # eof or similar
     762                  return 0
     763              m = Message()
     764              m.add_byte(chr(MSG_CHANNEL_EXTENDED_DATA))
     765              m.add_int(self.remote_chanid)
     766              m.add_int(1)
     767              m.add_string(s[:size])
     768          finally:
     769              self.lock.release()
     770          # Note: We release self.lock before calling _send_user_message.
     771          # Otherwise, we can deadlock during re-keying.
     772          self.transport._send_user_message(m)
     773          return size
     774
     775 -    def sendall(self, s):
     776          """
     777          Send data to the channel, without allowing partial results.  Unlike
     778          L{send}, this method continues to send data from the given string until
     779          either all data has been sent or an error occurs.  Nothing is returned.
     780
     781          @param s: data to send.
     782          @type s: str
     783
     784          @raise socket.timeout: if sending stalled for longer than the timeout
     785              set by L{settimeout}.
     786          @raise socket.error: if an error occured before the entire string was
     787              sent.
     788
     789          @note: If the channel is closed while only part of the data hase been
     790              sent, there is no way to determine how much data (if any) was sent.
     791              This is irritating, but identically follows python's API.
     792          """
     793          while s:
     794              if self.closed:
     795                  # this doesn't seem useful, but it is the documented behavior of Socket
     796                  raise socket.error('Socket is closed')
     797              sent = self.send(s)
     798              s = s[sent:]
     799          return None
     800
     801 -    def sendall_stderr(self, s):
     802          """
     803          Send data to the channel's "stderr" stream, without allowing partial
     804          results.  Unlike L{send_stderr}, this method continues to send data
     805          from the given string until all data has been sent or an error occurs.
     806          Nothing is returned.
     807
     808          @param s: data to send to the client as "stderr" output.
     809          @type s: str
     810
     811          @raise socket.timeout: if sending stalled for longer than the timeout
     812              set by L{settimeout}.
     813          @raise socket.error: if an error occured before the entire string was
     814              sent.
     815
     816          @since: 1.1
     817          """
     818          while s:
     819              if self.closed:
     820                  raise socket.error('Socket is closed')
     821              sent = self.send_stderr(s)
     822              s = s[sent:]
     823          return None
     824
     825 -    def makefile(self, *params):
     826          """
     827          Return a file-like object associated with this channel.  The optional
     828          C{mode} and C{bufsize} arguments are interpreted the same way as by
     829          the built-in C{file()} function in python.
     830
     831          @return: object which can be used for python file I/O.
     832          @rtype: L{ChannelFile}
     833          """
     834          return ChannelFile(*([self] + list(params)))
     835
     836 -    def makefile_stderr(self, *params):
     837          """
     838          Return a file-like object associated with this channel's stderr
     839          stream.   Only channels using L{exec_command} or L{invoke_shell}
     840          without a pty will ever have data on the stderr stream.
     841
     842          The optional C{mode} and C{bufsize} arguments are interpreted the
     843          same way as by the built-in C{file()} function in python.  For a
     844          client, it only makes sense to open this file for reading.  For a
     845          server, it only makes sense to open this file for writing.
     846
     847          @return: object which can be used for python file I/O.
     848          @rtype: L{ChannelFile}
     849
     850          @since: 1.1
     851          """
     852          return ChannelStderrFile(*([self] + list(params)))
     853
     854 -    def fileno(self):
     855          """
     856          Returns an OS-level file descriptor which can be used for polling, but
     857          but I{not} for reading or writing.  This is primaily to allow python's
     858          C{select} module to work.
     859
     860          The first time C{fileno} is called on a channel, a pipe is created to
     861          simulate real OS-level file descriptor (FD) behavior.  Because of this,
     862          two OS-level FDs are created, which will use up FDs faster than normal.
     863          (You won't notice this effect unless you have hundreds of channels
     864          open at the same time.)
     865
     866          @return: an OS-level file descriptor
     867          @rtype: int
     868
     869          @warning: This method causes channel reads to be slightly less
     870              efficient.
     871          """
     872          self.lock.acquire()
     873          try:
     874              if self._pipe is not None:
     875                  return self._pipe.fileno()
     876              # create the pipe and feed in any existing data
     877              self._pipe = pipe.make_pipe()
     878              p1, p2 = pipe.make_or_pipe(self._pipe)
     879              self.in_buffer.set_event(p1)
     880              self.in_stderr_buffer.set_event(p2)
     881              return self._pipe.fileno()
     882          finally:
     883              self.lock.release()
     884
     885 -    def shutdown(self, how):
     886          """
     887          Shut down one or both halves of the connection.  If C{how} is 0,
     888          further receives are disallowed.  If C{how} is 1, further sends
     889          are disallowed.  If C{how} is 2, further sends and receives are
     890          disallowed.  This closes the stream in one or both directions.
     891
     892          @param how: 0 (stop receiving), 1 (stop sending), or 2 (stop
     893              receiving and sending).
     894          @type how: int
     895          """
     896          if (how == 0) or (how == 2):
     897              # feign "read" shutdown
     898              self.eof_received = 1
     899          if (how == 1) or (how == 2):
     900              self.lock.acquire()
     901              try:
     902                  m = self._send_eof()
     903              finally:
     904                  self.lock.release()
     905              if m is not None:
     906                  self.transport._send_user_message(m)
     907
     908 -    def shutdown_read(self):
     909          """
     910          Shutdown the receiving side of this socket, closing the stream in
     911          the incoming direction.  After this call, future reads on this
     912          channel will fail instantly.  This is a convenience method, equivalent
     913          to C{shutdown(0)}, for people who don't make it a habit to
     914          memorize unix constants from the 1970s.
     915
     916          @since: 1.2
     917          """
     918          self.shutdown(0)
     919
     920 -    def shutdown_write(self):
     921          """
     922          Shutdown the sending side of this socket, closing the stream in
     923          the outgoing direction.  After this call, future writes on this
     924          channel will fail instantly.  This is a convenience method, equivalent
     925          to C{shutdown(1)}, for people who don't make it a habit to
     926          memorize unix constants from the 1970s.
     927
     928          @since: 1.2
     929          """
     930          self.shutdown(1)
     931
     932
     933      ###  calls from Transport
     934
     935
     936 -    def _set_transport(self, transport):
     937          self.transport = transport
     938          self.logger = util.get_logger(self.transport.get_log_channel())
     939
     940 -    def _set_window(self, window_size, max_packet_size):
     941          self.in_window_size = window_size
     942          self.in_max_packet_size = max_packet_size
     943          # threshold of bytes we receive before we bother to send a window update
     944          self.in_window_threshold = window_size // 10
     945          self.in_window_sofar = 0
     946          self._log(DEBUG, 'Max packet in: %d bytes' % max_packet_size)
     947
     948 -    def _set_remote_channel(self, chanid, window_size, max_packet_size):
     949          self.remote_chanid = chanid
     950          self.out_window_size = window_size
     951          self.out_max_packet_size = max(max_packet_size, MIN_PACKET_SIZE)
     952          self.active = 1
     953          self._log(DEBUG, 'Max packet out: %d bytes' % max_packet_size)
     954
     955 -    def _request_success(self, m):
     956          self._log(DEBUG, 'Sesch channel %d request ok' % self.chanid)
     957          self.event_ready = True
     958          self.event.set()
     959          return
     960
     961 -    def _request_failed(self, m):
     962          self.lock.acquire()
     963          try:
     964              msgs = self._close_internal()
     965          finally:
     966              self.lock.release()
     967          for m in msgs:
     968              if m is not None:
     969                  self.transport._send_user_message(m)
     970
     971 -    def _feed(self, m):
     972          if type(m) is str:
     973              # passed from _feed_extended
     974              s = m
     975          else:
     976              s = m.get_string()
     977          self.in_buffer.feed(s)
     978
     979 -    def _feed_extended(self, m):
     980          code = m.get_int()
     981          s = m.get_string()
     982          if code != 1:
     983              self._log(ERROR, 'unknown extended_data type %d; discarding' % code)
     984              return
     985          if self.combine_stderr:
     986              self._feed(s)
     987          else:
     988              self.in_stderr_buffer.feed(s)
     989
     990 -    def _window_adjust(self, m):
     991          nbytes = m.get_int()
     992          self.lock.acquire()
     993          try:
     994              if self.ultra_debug:
     995                  self._log(DEBUG, 'window up %d' % nbytes)
     996              self.out_window_size += nbytes
     997              self.out_buffer_cv.notifyAll()
     998          finally:
     999              self.lock.release()
    1000
    1001 -    def _handle_request(self, m):
    1002          key = m.get_string()
    1003          want_reply = m.get_boolean()
    1004          server = self.transport.server_object
    1005          ok = False
    1006          if key == 'exit-status':
    1007              self.exit_status = m.get_int()
    1008              self.status_event.set()
    1009              ok = True
    1010          elif key == 'xon-xoff':
    1011              # ignore
    1012              ok = True
    1013          elif key == 'pty-req':
    1014              term = m.get_string()
    1015              width = m.get_int()
    1016              height = m.get_int()
    1017              pixelwidth = m.get_int()
    1018              pixelheight = m.get_int()
    1019              modes = m.get_string()
    1020              if server is None:
    1021                  ok = False
    1022              else:
    1023                  ok = server.check_channel_pty_request(self, term, width, height, pixelwidth,
    1024                                                        pixelheight, modes)
    1025          elif key == 'shell':
    1026              if server is None:
    1027                  ok = False
    1028              else:
    1029                  ok = server.check_channel_shell_request(self)
    1030          elif key == 'env':
    1031              name = m.get_string()
    1032              value = m.get_string()
    1033              if server is None:
    1034                  ok = False
    1035              else:
    1036                  ok = server.check_channel_env_request(self, name, value)
    1037          elif key == 'exec':
    1038              cmd = m.get_string()
    1039              if server is None:
    1040                  ok = False
    1041              else:
    1042                  ok = server.check_channel_exec_request(self, cmd)
    1043          elif key == 'subsystem':
    1044              name = m.get_string()
    1045              if server is None:
    1046                  ok = False
    1047              else:
    1048                  ok = server.check_channel_subsystem_request(self, name)
    1049          elif key == 'window-change':
    1050              width = m.get_int()
    1051              height = m.get_int()
    1052              pixelwidth = m.get_int()
    1053              pixelheight = m.get_int()
    1054              if server is None:
    1055                  ok = False
    1056              else:
    1057                  ok = server.check_channel_window_change_request(self, width, height, pixelwidth,
    1058                                                                  pixelheight)
    1059          elif key == 'x11-req':
    1060              single_connection = m.get_boolean()
    1061              auth_proto = m.get_string()
    1062              auth_cookie = m.get_string()
    1063              screen_number = m.get_int()
    1064              if server is None:
    1065                  ok = False
    1066              else:
    1067                  ok = server.check_channel_x11_request(self, single_connection,
    1068                                                        auth_proto, auth_cookie, screen_number)
    1069          elif key == 'auth-agent-req@openssh.com':
    1070              if server is None:
    1071                  ok = False
    1072              else:
    1073                  ok = server.check_channel_forward_agent_request(self)
    1074          else:
    1075              self._log(DEBUG, 'Unhandled channel request "%s"' % key)
    1076              ok = False
    1077          if want_reply:
    1078              m = Message()
    1079              if ok:
    1080                  m.add_byte(chr(MSG_CHANNEL_SUCCESS))
    1081              else:
    1082                  m.add_byte(chr(MSG_CHANNEL_FAILURE))
    1083              m.add_int(self.remote_chanid)
    1084              self.transport._send_user_message(m)
    1085
    1086 -    def _handle_eof(self, m):
    1087          self.lock.acquire()
    1088          try:
    1089              if not self.eof_received:
    1090                  self.eof_received = True
    1091                  self.in_buffer.close()
    1092                  self.in_stderr_buffer.close()
    1093                  if self._pipe is not None:
    1094                      self._pipe.set_forever()
    1095          finally:
    1096              self.lock.release()
    1097          self._log(DEBUG, 'EOF received (%s)', self._name)
    1098
    1099 -    def _handle_close(self, m):
    1100          self.lock.acquire()
    1101          try:
    1102              msgs = self._close_internal()
    1103              self.transport._unlink_channel(self.chanid)
    1104          finally:
    1105              self.lock.release()
    1106          for m in msgs:
    1107              if m is not None:
    1108                  self.transport._send_user_message(m)
    1109
    1110
    1111      ###  internals...
    1112
    1113
    1114 -    def _log(self, level, msg, *args):
    1115          self.logger.log(level, "[chan " + self._name + "] " + msg, *args)
    1116
    1117 -    def _event_pending(self):
    1118          self.event.clear()
    1119          self.event_ready = False
    1120
    1121 -    def _wait_for_event(self):
    1122          self.event.wait()
    1123          assert self.event.isSet()
    1124          if self.event_ready:
    1125              return
    1126          e = self.transport.get_exception()
    1127          if e is None:
    1128              e = SSHException('Channel closed.')
    1129          raise e
    1130
    1131 -    def _set_closed(self):
    1132          # you are holding the lock.
    1133          self.closed = True
    1134          self.in_buffer.close()
    1135          self.in_stderr_buffer.close()
    1136          self.out_buffer_cv.notifyAll()
    1137          # Notify any waiters that we are closed
    1138          self.event.set()
    1139          self.status_event.set()
    1140          if self._pipe is not None:
    1141              self._pipe.set_forever()
    1142
    1143 -    def _send_eof(self):
    1144          # you are holding the lock.
    1145          if self.eof_sent:
    1146              return None
    1147          m = Message()
    1148          m.add_byte(chr(MSG_CHANNEL_EOF))
    1149          m.add_int(self.remote_chanid)
    1150          self.eof_sent = True
    1151          self._log(DEBUG, 'EOF sent (%s)', self._name)
    1152          return m
    1153
    1154 -    def _close_internal(self):
    1155          # you are holding the lock.
    1156          if not self.active or self.closed:
    1157              return None, None
    1158          m1 = self._send_eof()
    1159          m2 = Message()
    1160          m2.add_byte(chr(MSG_CHANNEL_CLOSE))
    1161          m2.add_int(self.remote_chanid)
    1162          self._set_closed()
    1163          # can't unlink from the Transport yet -- the remote side may still
    1164          # try to send meta-data (exit-status, etc)
    1165          return m1, m2
    1166
    1167 -    def _unlink(self):
    1168          # server connection could die before we become active: still signal the close!
    1169          if self.closed:
    1170              return
    1171          self.lock.acquire()
    1172          try:
    1173              self._set_closed()
    1174              self.transport._unlink_channel(self.chanid)
    1175          finally:
    1176              self.lock.release()
    1177
    1178 -    def _check_add_window(self, n):
    1179          self.lock.acquire()
    1180          try:
    1181              if self.closed or self.eof_received or not self.active:
    1182                  return 0
    1183              if self.ultra_debug:
    1184                  self._log(DEBUG, 'addwindow %d' % n)
    1185              self.in_window_sofar += n
    1186              if self.in_window_sofar <= self.in_window_threshold:
    1187                  return 0
    1188              if self.ultra_debug:
    1189                  self._log(DEBUG, 'addwindow send %d' % self.in_window_sofar)
    1190              out = self.in_window_sofar
    1191              self.in_window_sofar = 0
    1192              return out
    1193          finally:
    1194              self.lock.release()
    1195
    1196 -    def _wait_for_send_window(self, size):
    1197          """
    1198          (You are already holding the lock.)
    1199          Wait for the send window to open up, and allocate up to C{size} bytes
    1200          for transmission.  If no space opens up before the timeout, a timeout
    1201          exception is raised.  Returns the number of bytes available to send
    1202          (may be less than requested).
    1203          """
    1204          # you are already holding the lock
    1205          if self.closed or self.eof_sent:
    1206              return 0
    1207          if self.out_window_size == 0:
    1208              # should we block?
    1209              if self.timeout == 0.0:
    1210                  raise socket.timeout()
    1211              # loop here in case we get woken up but a different thread has filled the buffer
    1212              timeout = self.timeout
    1213              while self.out_window_size == 0:
    1214                  if self.closed or self.eof_sent:
    1215                      return 0
    1216                  then = time.time()
    1217                  self.out_buffer_cv.wait(timeout)
    1218                  if timeout != None:
    1219                      timeout -= time.time() - then
    1220                      if timeout <= 0.0:
    1221                          raise socket.timeout()
    1222          # we have some window to squeeze into
    1223          if self.closed or self.eof_sent:
    1224              return 0
    1225          if self.out_window_size < size:
    1226              size = self.out_window_size
    1227          if self.out_max_packet_size - 64 < size:
    1228              size = self.out_max_packet_size - 64
    1229          self.out_window_size -= size
    1230          if self.ultra_debug:
    1231              self._log(DEBUG, 'window down to %d' % self.out_window_size)
    1232          return size
    1233
    1234
    1235 -class ChannelFile (BufferedFile):
    1236      """
    1237      A file-like wrapper around L{Channel}.  A ChannelFile is created by calling
    1238      L{Channel.makefile}.
    1239
    1240      @bug: To correctly emulate the file object created from a socket's
    1241          C{makefile} method, a L{Channel} and its C{ChannelFile} should be able
    1242          to be closed or garbage-collected independently.  Currently, closing
    1243          the C{ChannelFile} does nothing but flush the buffer.
    1244      """
    1245
    1246 -    def __init__(self, channel, mode = 'r', bufsize = -1):
    1247          self.channel = channel
    1248          BufferedFile.__init__(self)
    1249          self._set_mode(mode, bufsize)
    1250
    1251 -    def __repr__(self):
    1252          """
    1253          Returns a string representation of this object, for debugging.
    1254
    1255          @rtype: str
    1256          """
    1257          return '<paramiko.ChannelFile from ' + repr(self.channel) + '>'
    1258
    1259 -    def _read(self, size):
    1260          return self.channel.recv(size)
    1261
    1262 -    def _write(self, data):
    1263          self.channel.sendall(data)
    1264          return len(data)
    1265
    1266
    1267 -class ChannelStderrFile (ChannelFile):
    1268 -    def __init__(self, channel, mode = 'r', bufsize = -1):
    1269          ChannelFile.__init__(self, channel, mode, bufsize)
    1270
    1271 -    def _read(self, size):
    1272          return self.channel.recv_stderr(size)
    1273
    1274 -    def _write(self, data):
    1275          self.channel.sendall_stderr(data)
    1276          return len(data)
    1277
    1278
    1279  # vim: set shiftwidth=4 expandtab :
    1280