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 == 'exec': 1031 cmd = m.get_string() 1032 if server is None: 1033 ok = False 1034 else: 1035 ok = server.check_channel_exec_request(self, cmd) 1036 elif key == 'subsystem': 1037 name = m.get_string() 1038 if server is None: 1039 ok = False 1040 else: 1041 ok = server.check_channel_subsystem_request(self, name) 1042 elif key == 'window-change': 1043 width = m.get_int() 1044 height = m.get_int() 1045 pixelwidth = m.get_int() 1046 pixelheight = m.get_int() 1047 if server is None: 1048 ok = False 1049 else: 1050 ok = server.check_channel_window_change_request(self, width, height, pixelwidth, 1051 pixelheight) 1052 elif key == 'x11-req': 1053 single_connection = m.get_boolean() 1054 auth_proto = m.get_string() 1055 auth_cookie = m.get_string() 1056 screen_number = m.get_int() 1057 if server is None: 1058 ok = False 1059 else: 1060 ok = server.check_channel_x11_request(self, single_connection, 1061 auth_proto, auth_cookie, screen_number) 1062 elif key == 'auth-agent-req@openssh.com': 1063 if server is None: 1064 ok = False 1065 else: 1066 ok = server.check_channel_forward_agent_request(self) 1067 else: 1068 self._log(DEBUG, 'Unhandled channel request "%s"' % key) 1069 ok = False 1070 if want_reply: 1071 m = Message() 1072 if ok: 1073 m.add_byte(chr(MSG_CHANNEL_SUCCESS)) 1074 else: 1075 m.add_byte(chr(MSG_CHANNEL_FAILURE)) 1076 m.add_int(self.remote_chanid) 1077 self.transport._send_user_message(m)
1078
1079 - def _handle_eof(self, m):
1080 self.lock.acquire() 1081 try: 1082 if not self.eof_received: 1083 self.eof_received = True 1084 self.in_buffer.close() 1085 self.in_stderr_buffer.close() 1086 if self._pipe is not None: 1087 self._pipe.set_forever() 1088 finally: 1089 self.lock.release() 1090 self._log(DEBUG, 'EOF received (%s)', self._name)
1091
1092 - def _handle_close(self, m):
1093 self.lock.acquire() 1094 try: 1095 msgs = self._close_internal() 1096 self.transport._unlink_channel(self.chanid) 1097 finally: 1098 self.lock.release() 1099 for m in msgs: 1100 if m is not None: 1101 self.transport._send_user_message(m)
1102 1103 1104 ### internals... 1105 1106
1107 - def _log(self, level, msg, *args):
1108 self.logger.log(level, "[chan " + self._name + "] " + msg, *args)
1109
1110 - def _event_pending(self):
1111 self.event.clear() 1112 self.event_ready = False
1113
1114 - def _wait_for_event(self):
1115 self.event.wait() 1116 assert self.event.isSet() 1117 if self.event_ready: 1118 return 1119 e = self.transport.get_exception() 1120 if e is None: 1121 e = SSHException('Channel closed.') 1122 raise e
1123
1124 - def _set_closed(self):
1125 # you are holding the lock. 1126 self.closed = True 1127 self.in_buffer.close() 1128 self.in_stderr_buffer.close() 1129 self.out_buffer_cv.notifyAll() 1130 # Notify any waiters that we are closed 1131 self.event.set() 1132 self.status_event.set() 1133 if self._pipe is not None: 1134 self._pipe.set_forever()
1135
1136 - def _send_eof(self):
1137 # you are holding the lock. 1138 if self.eof_sent: 1139 return None 1140 m = Message() 1141 m.add_byte(chr(MSG_CHANNEL_EOF)) 1142 m.add_int(self.remote_chanid) 1143 self.eof_sent = True 1144 self._log(DEBUG, 'EOF sent (%s)', self._name) 1145 return m
1146
1147 - def _close_internal(self):
1148 # you are holding the lock. 1149 if not self.active or self.closed: 1150 return None, None 1151 m1 = self._send_eof() 1152 m2 = Message() 1153 m2.add_byte(chr(MSG_CHANNEL_CLOSE)) 1154 m2.add_int(self.remote_chanid) 1155 self._set_closed() 1156 # can't unlink from the Transport yet -- the remote side may still 1157 # try to send meta-data (exit-status, etc) 1158 return m1, m2
1159 1170
1171 - def _check_add_window(self, n):
1172 self.lock.acquire() 1173 try: 1174 if self.closed or self.eof_received or not self.active: 1175 return 0 1176 if self.ultra_debug: 1177 self._log(DEBUG, 'addwindow %d' % n) 1178 self.in_window_sofar += n 1179 if self.in_window_sofar <= self.in_window_threshold: 1180 return 0 1181 if self.ultra_debug: 1182 self._log(DEBUG, 'addwindow send %d' % self.in_window_sofar) 1183 out = self.in_window_sofar 1184 self.in_window_sofar = 0 1185 return out 1186 finally: 1187 self.lock.release()
1188
1189 - def _wait_for_send_window(self, size):
1190 """ 1191 (You are already holding the lock.) 1192 Wait for the send window to open up, and allocate up to C{size} bytes 1193 for transmission. If no space opens up before the timeout, a timeout 1194 exception is raised. Returns the number of bytes available to send 1195 (may be less than requested). 1196 """ 1197 # you are already holding the lock 1198 if self.closed or self.eof_sent: 1199 return 0 1200 if self.out_window_size == 0: 1201 # should we block? 1202 if self.timeout == 0.0: 1203 raise socket.timeout() 1204 # loop here in case we get woken up but a different thread has filled the buffer 1205 timeout = self.timeout 1206 while self.out_window_size == 0: 1207 if self.closed or self.eof_sent: 1208 return 0 1209 then = time.time() 1210 self.out_buffer_cv.wait(timeout) 1211 if timeout != None: 1212 timeout -= time.time() - then 1213 if timeout <= 0.0: 1214 raise socket.timeout() 1215 # we have some window to squeeze into 1216 if self.closed or self.eof_sent: 1217 return 0 1218 if self.out_window_size < size: 1219 size = self.out_window_size 1220 if self.out_max_packet_size - 64 < size: 1221 size = self.out_max_packet_size - 64 1222 self.out_window_size -= size 1223 if self.ultra_debug: 1224 self._log(DEBUG, 'window down to %d' % self.out_window_size) 1225 return size
1226 1227
1228 -class ChannelFile (BufferedFile):
1229 """ 1230 A file-like wrapper around L{Channel}. A ChannelFile is created by calling 1231 L{Channel.makefile}. 1232 1233 @bug: To correctly emulate the file object created from a socket's 1234 C{makefile} method, a L{Channel} and its C{ChannelFile} should be able 1235 to be closed or garbage-collected independently. Currently, closing 1236 the C{ChannelFile} does nothing but flush the buffer. 1237 """ 1238
1239 - def __init__(self, channel, mode = 'r', bufsize = -1):
1240 self.channel = channel 1241 BufferedFile.__init__(self) 1242 self._set_mode(mode, bufsize)
1243
1244 - def __repr__(self):
1245 """ 1246 Returns a string representation of this object, for debugging. 1247 1248 @rtype: str 1249 """ 1250 return '<paramiko.ChannelFile from ' + repr(self.channel) + '>'
1251
1252 - def _read(self, size):
1253 return self.channel.recv(size)
1254
1255 - def _write(self, data):
1256 self.channel.sendall(data) 1257 return len(data)
1258 1259
1260 -class ChannelStderrFile (ChannelFile):
1261 - def __init__(self, channel, mode = 'r', bufsize = -1):
1262 ChannelFile.__init__(self, channel, mode, bufsize)
1263
1264 - def _read(self, size):
1265 return self.channel.recv_stderr(size)
1266
1267 - def _write(self, data):
1268 self.channel.sendall_stderr(data) 1269 return len(data)
1270 1271 1272 # vim: set shiftwidth=4 expandtab : 1273