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):
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 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