paramiko.channel

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

126 """ 127 Request a pseudo-terminal from the server. This is usually used right 128 after creating a client channel, to ask the server to provide some 129 basic terminal semantics for a shell invoked with L{invoke_shell}. 130 It isn't necessary (or desirable) to call this method if you're going 131 to exectue a single command with L{exec_command}. 132 133 @param term: the terminal type to emulate (for example, C{'vt100'}) 134 @type term: str 135 @param width: width (in characters) of the terminal screen 136 @type width: int 137 @param height: height (in characters) of the terminal screen 138 @type height: int 139 140 @raise SSHException: if the request was rejected or the channel was 141 closed 142 """ 143 if self.closed or self.eof_received or self.eof_sent or not self.active: 144 raise SSHException('Channel is not open') 145 m = Message() 146 m.add_byte(chr(MSG_CHANNEL_REQUEST)) 147 m.add_int(self.remote_chanid) 148 m.add_string('pty-req') 149 m.add_boolean(True) 150 m.add_string(term) 151 m.add_int(width) 152 m.add_int(height) 153 # pixel height, width (usually useless) 154 m.add_int(0).add_int(0) 155 m.add_string('') 156 self._event_pending() 157 self.transport._send_user_message(m) 158 self._wait_for_event()

159

160 - def invoke_shell(self):

161 """ 162 Request an interactive shell session on this channel. If the server 163 allows it, the channel will then be directly connected to the stdin, 164 stdout, and stderr of the shell. 165 166 Normally you would call L{get_pty} before this, in which case the 167 shell will operate through the pty, and the channel will be connected 168 to the stdin and stdout of the pty. 169 170 When the shell exits, the channel will be closed and can't be reused. 171 You must open a new channel if you wish to open another shell. 172 173 @raise SSHException: if the request was rejected or the channel was 174 closed 175 """ 176 if self.closed or self.eof_received or self.eof_sent or not self.active: 177 raise SSHException('Channel is not open') 178 m = Message() 179 m.add_byte(chr(MSG_CHANNEL_REQUEST)) 180 m.add_int(self.remote_chanid) 181 m.add_string('shell') 182 m.add_boolean(1) 183 self._event_pending() 184 self.transport._send_user_message(m) 185 self._wait_for_event()

186

187 - def exec_command(self, command):

188 """ 189 Execute a command on the server. If the server allows it, the channel 190 will then be directly connected to the stdin, stdout, and stderr of 191 the command being executed. 192 193 When the command finishes executing, the channel will be closed and 194 can't be reused. You must open a new channel if you wish to execute 195 another command. 196 197 @param command: a shell command to execute. 198 @type command: str 199 200 @raise SSHException: if the request was rejected or the channel was 201 closed 202 """ 203 if self.closed or self.eof_received or self.eof_sent or not self.active: 204 raise SSHException('Channel is not open') 205 m = Message() 206 m.add_byte(chr(MSG_CHANNEL_REQUEST)) 207 m.add_int(self.remote_chanid) 208 m.add_string('exec') 209 m.add_boolean(True) 210 m.add_string(command) 211 self._event_pending() 212 self.transport._send_user_message(m) 213 self._wait_for_event()

214

215 - def invoke_subsystem(self, subsystem):

216 """ 217 Request a subsystem on the server (for example, C{sftp}). If the 218 server allows it, the channel will then be directly connected to the 219 requested subsystem. 220 221 When the subsystem finishes, the channel will be closed and can't be 222 reused. 223 224 @param subsystem: name of the subsystem being requested. 225 @type subsystem: str 226 227 @raise SSHException: if the request was rejected or the channel was 228 closed 229 """ 230 if self.closed or self.eof_received or self.eof_sent or not self.active: 231 raise SSHException('Channel is not open') 232 m = Message() 233 m.add_byte(chr(MSG_CHANNEL_REQUEST)) 234 m.add_int(self.remote_chanid) 235 m.add_string('subsystem') 236 m.add_boolean(True) 237 m.add_string(subsystem) 238 self._event_pending() 239 self.transport._send_user_message(m) 240 self._wait_for_event()

241

242 - def resize_pty(self, width=80, height=24):

243 """ 244 Resize the pseudo-terminal. This can be used to change the width and 245 height of the terminal emulation created in a previous L{get_pty} call. 246 247 @param width: new width (in characters) of the terminal screen 248 @type width: int 249 @param height: new height (in characters) of the terminal screen 250 @type height: int 251 252 @raise SSHException: if the request was rejected or the channel was 253 closed 254 """ 255 if self.closed or self.eof_received or self.eof_sent or not self.active: 256 raise SSHException('Channel is not open') 257 m = Message() 258 m.add_byte(chr(MSG_CHANNEL_REQUEST)) 259 m.add_int(self.remote_chanid) 260 m.add_string('window-change') 261 m.add_boolean(True) 262 m.add_int(width) 263 m.add_int(height) 264 m.add_int(0).add_int(0) 265 self._event_pending() 266 self.transport._send_user_message(m) 267 self._wait_for_event()

268

269 - def exit_status_ready(self):

270 """ 271 Return true if the remote process has exited and returned an exit 272 status. You may use this to poll the process status if you don't 273 want to block in L{recv_exit_status}. Note that the server may not 274 return an exit status in some cases (like bad servers). 275 276 @return: True if L{recv_exit_status} will return immediately 277 @rtype: bool 278 @since: 1.7.3 279 """ 280 return self.closed or self.status_event.isSet()

281

282 - def recv_exit_status(self):

283 """ 284 Return the exit status from the process on the server. This is 285 mostly useful for retrieving the reults of an L{exec_command}. 286 If the command hasn't finished yet, this method will wait until 287 it does, or until the channel is closed. If no exit status is 288 provided by the server, -1 is returned. 289 290 @return: the exit code of the process on the server. 291 @rtype: int 292 293 @since: 1.2 294 """ 295 self.status_event.wait() 296 assert self.status_event.isSet() 297 return self.exit_status

298

299 - def send_exit_status(self, status):

300 """ 301 Send the exit status of an executed command to the client. (This 302 really only makes sense in server mode.) Many clients expect to 303 get some sort of status code back from an executed command after 304 it completes. 305 306 @param status: the exit code of the process 307 @type status: int 308 309 @since: 1.2 310 """ 311 # in many cases, the channel will not still be open here. 312 # that's fine. 313 m = Message() 314 m.add_byte(chr(MSG_CHANNEL_REQUEST)) 315 m.add_int(self.remote_chanid) 316 m.add_string('exit-status') 317 m.add_boolean(False) 318 m.add_int(status) 319 self.transport._send_user_message(m)

320

321 - def request_x11(self, screen_number=0, auth_protocol=None, auth_cookie=None, 322 single_connection=False, handler=None):

323 """ 324 Request an x11 session on this channel. If the server allows it, 325 further x11 requests can be made from the server to the client, 326 when an x11 application is run in a shell session. 327 328 From RFC4254:: 329 330 It is RECOMMENDED that the 'x11 authentication cookie' that is 331 sent be a fake, random cookie, and that the cookie be checked and 332 replaced by the real cookie when a connection request is received. 333 334 If you omit the auth_cookie, a new secure random 128-bit value will be 335 generated, used, and returned. You will need to use this value to 336 verify incoming x11 requests and replace them with the actual local 337 x11 cookie (which requires some knoweldge of the x11 protocol). 338 339 If a handler is passed in, the handler is called from another thread 340 whenever a new x11 connection arrives. The default handler queues up 341 incoming x11 connections, which may be retrieved using 342 L{Transport.accept}. The handler's calling signature is:: 343 344 handler(channel: Channel, (address: str, port: int)) 345 346 @param screen_number: the x11 screen number (0, 10, etc) 347 @type screen_number: int 348 @param auth_protocol: the name of the X11 authentication method used; 349 if none is given, C{"MIT-MAGIC-COOKIE-1"} is used 350 @type auth_protocol: str 351 @param auth_cookie: hexadecimal string containing the x11 auth cookie; 352 if none is given, a secure random 128-bit value is generated 353 @type auth_cookie: str 354 @param single_connection: if True, only a single x11 connection will be 355 forwarded (by default, any number of x11 connections can arrive 356 over this session) 357 @type single_connection: bool 358 @param handler: an optional handler to use for incoming X11 connections 359 @type handler: function 360 @return: the auth_cookie used 361 """ 362 if self.closed or self.eof_received or self.eof_sent or not self.active: 363 raise SSHException('Channel is not open') 364 if auth_protocol is None: 365 auth_protocol = 'MIT-MAGIC-COOKIE-1' 366 if auth_cookie is None: 367 auth_cookie = binascii.hexlify(self.transport.randpool.get_bytes(16)) 368 369 m = Message() 370 m.add_byte(chr(MSG_CHANNEL_REQUEST)) 371 m.add_int(self.remote_chanid) 372 m.add_string('x11-req') 373 m.add_boolean(True) 374 m.add_boolean(single_connection) 375 m.add_string(auth_protocol) 376 m.add_string(auth_cookie) 377 m.add_int(screen_number) 378 self._event_pending() 379 self.transport._send_user_message(m) 380 self._wait_for_event() 381 self.transport._set_x11_handler(handler) 382 return auth_cookie

383

384 - def get_transport(self):

385 """ 386 Return the L{Transport} associated with this channel. 387 388 @return: the L{Transport} that was used to create this channel. 389 @rtype: L{Transport} 390 """ 391 return self.transport

392

393 - def set_name(self, name):

394 """ 395 Set a name for this channel. Currently it's only used to set the name 396 of the channel in logfile entries. The name can be fetched with the 397 L{get_name} method. 398 399 @param name: new channel name 400 @type name: str 401 """ 402 self._name = name

403

404 - def get_name(self):

405 """ 406 Get the name of this channel that was previously set by L{set_name}. 407 408 @return: the name of this channel. 409 @rtype: str 410 """ 411 return self._name

412

413 - def get_id(self):

414 """ 415 Return the ID # for this channel. The channel ID is unique across 416 a L{Transport} and usually a small number. It's also the number 417 passed to L{ServerInterface.check_channel_request} when determining 418 whether to accept a channel request in server mode. 419 420 @return: the ID of this channel. 421 @rtype: int 422 """ 423 return self.chanid

424

425 - def set_combine_stderr(self, combine):

426 """ 427 Set whether stderr should be combined into stdout on this channel. 428 The default is C{False}, but in some cases it may be convenient to 429 have both streams combined. 430 431 If this is C{False}, and L{exec_command} is called (or C{invoke_shell} 432 with no pty), output to stderr will not show up through the L{recv} 433 and L{recv_ready} calls. You will have to use L{recv_stderr} and 434 L{recv_stderr_ready} to get stderr output. 435 436 If this is C{True}, data will never show up via L{recv_stderr} or 437 L{recv_stderr_ready}. 438 439 @param combine: C{True} if stderr output should be combined into 440 stdout on this channel. 441 @type combine: bool 442 @return: previous setting. 443 @rtype: bool 444 445 @since: 1.1 446 """ 447 data = '' 448 self.lock.acquire() 449 try: 450 old = self.combine_stderr 451 self.combine_stderr = combine 452 if combine and not old: 453 # copy old stderr buffer into primary buffer 454 data = self.in_stderr_buffer.empty() 455 finally: 456 self.lock.release() 457 if len(data) > 0: 458 self._feed(data) 459 return old

460 461 462 ### socket API 463 464

465 - def settimeout(self, timeout):

466 """ 467 Set a timeout on blocking read/write operations. The C{timeout} 468 argument can be a nonnegative float expressing seconds, or C{None}. If 469 a float is given, subsequent channel read/write operations will raise 470 a timeout exception if the timeout period value has elapsed before the 471 operation has completed. Setting a timeout of C{None} disables 472 timeouts on socket operations. 473 474 C{chan.settimeout(0.0)} is equivalent to C{chan.setblocking(0)}; 475 C{chan.settimeout(None)} is equivalent to C{chan.setblocking(1)}. 476 477 @param timeout: seconds to wait for a pending read/write operation 478 before raising C{socket.timeout}, or C{None} for no timeout. 479 @type timeout: float 480 """ 481 self.timeout = timeout

482

483 - def gettimeout(self):

484 """ 485 Returns the timeout in seconds (as a float) associated with socket 486 operations, or C{None} if no timeout is set. This reflects the last 487 call to L{setblocking} or L{settimeout}. 488 489 @return: timeout in seconds, or C{None}. 490 @rtype: float 491 """ 492 return self.timeout

493

494 - def setblocking(self, blocking):

495 """ 496 Set blocking or non-blocking mode of the channel: if C{blocking} is 0, 497 the channel is set to non-blocking mode; otherwise it's set to blocking 498 mode. Initially all channels are in blocking mode. 499 500 In non-blocking mode, if a L{recv} call doesn't find any data, or if a 501 L{send} call can't immediately dispose of the data, an error exception 502 is raised. In blocking mode, the calls block until they can proceed. An 503 EOF condition is considered "immediate data" for L{recv}, so if the 504 channel is closed in the read direction, it will never block. 505 506 C{chan.setblocking(0)} is equivalent to C{chan.settimeout(0)}; 507 C{chan.setblocking(1)} is equivalent to C{chan.settimeout(None)}. 508 509 @param blocking: 0 to set non-blocking mode; non-0 to set blocking 510 mode. 511 @type blocking: int 512 """ 513 if blocking: 514 self.settimeout(None) 515 else: 516 self.settimeout(0.0)

517

518 - def getpeername(self):

519 """ 520 Return the address of the remote side of this Channel, if possible. 521 This is just a wrapper around C{'getpeername'} on the Transport, used 522 to provide enough of a socket-like interface to allow asyncore to work. 523 (asyncore likes to call C{'getpeername'}.) 524 525 @return: the address if the remote host, if known 526 @rtype: tuple(str, int) 527 """ 528 return self.transport.getpeername()

529

530 - def close(self):

531 """ 532 Close the channel. All future read/write operations on the channel 533 will fail. The remote end will receive no more data (after queued data 534 is flushed). Channels are automatically closed when their L{Transport} 535 is closed or when they are garbage collected. 536 """ 537 self.lock.acquire() 538 try: 539 # only close the pipe when the user explicitly closes the channel. 540 # otherwise they will get unpleasant surprises. (and do it before 541 # checking self.closed, since the remote host may have already 542 # closed the connection.) 543 if self._pipe is not None: 544 self._pipe.close() 545 self._pipe = None 546 547 if not self.active or self.closed: 548 return 549 msgs = self._close_internal() 550 finally: 551 self.lock.release() 552 for m in msgs: 553 if m is not None: 554 self.transport._send_user_message(m)

555

556 - def recv_ready(self):

557 """ 558 Returns true if data is buffered and ready to be read from this 559 channel. A C{False} result does not mean that the channel has closed; 560 it means you may need to wait before more data arrives. 561 562 @return: C{True} if a L{recv} call on this channel would immediately 563 return at least one byte; C{False} otherwise. 564 @rtype: boolean 565 """ 566 return self.in_buffer.read_ready()

567

568 - def recv(self, nbytes):

569 """ 570 Receive data from the channel. The return value is a string 571 representing the data received. The maximum amount of data to be 572 received at once is specified by C{nbytes}. If a string of length zero 573 is returned, the channel stream has closed. 574 575 @param nbytes: maximum number of bytes to read. 576 @type nbytes: int 577 @return: data. 578 @rtype: str 579 580 @raise socket.timeout: if no data is ready before the timeout set by 581 L{settimeout}. 582 """ 583 try: 584 out = self.in_buffer.read(nbytes, self.timeout) 585 except PipeTimeout, e: 586 raise socket.timeout() 587 588 ack = self._check_add_window(len(out)) 589 # no need to hold the channel lock when sending this 590 if ack > 0: 591 m = Message() 592 m.add_byte(chr(MSG_CHANNEL_WINDOW_ADJUST)) 593 m.add_int(self.remote_chanid) 594 m.add_int(ack) 595 self.transport._send_user_message(m) 596 597 return out

598

599 - def recv_stderr_ready(self):

600 """ 601 Returns true if data is buffered and ready to be read from this 602 channel's stderr stream. Only channels using L{exec_command} or 603 L{invoke_shell} without a pty will ever have data on the stderr 604 stream. 605 606 @return: C{True} if a L{recv_stderr} call on this channel would 607 immediately return at least one byte; C{False} otherwise. 608 @rtype: boolean 609 610 @since: 1.1 611 """ 612 return self.in_stderr_buffer.read_ready()

613

614 - def recv_stderr(self, nbytes):

615 """ 616 Receive data from the channel's stderr stream. Only channels using 617 L{exec_command} or L{invoke_shell} without a pty will ever have data 618 on the stderr stream. The return value is a string representing the 619 data received. The maximum amount of data to be received at once is 620 specified by C{nbytes}. If a string of length zero is returned, the 621 channel stream has closed. 622 623 @param nbytes: maximum number of bytes to read. 624 @type nbytes: int 625 @return: data. 626 @rtype: str 627 628 @raise socket.timeout: if no data is ready before the timeout set by 629 L{settimeout}. 630 631 @since: 1.1 632 """ 633 try: 634 out = self.in_stderr_buffer.read(nbytes, self.timeout) 635 except PipeTimeout, e: 636 raise socket.timeout() 637 638 ack = self._check_add_window(len(out)) 639 # no need to hold the channel lock when sending this 640 if ack > 0: 641 m = Message() 642 m.add_byte(chr(MSG_CHANNEL_WINDOW_ADJUST)) 643 m.add_int(self.remote_chanid) 644 m.add_int(ack) 645 self.transport._send_user_message(m) 646 647 return out

648

649 - def send_ready(self):

650 """ 651 Returns true if data can be written to this channel without blocking. 652 This means the channel is either closed (so any write attempt would 653 return immediately) or there is at least one byte of space in the 654 outbound buffer. If there is at least one byte of space in the 655 outbound buffer, a L{send} call will succeed immediately and return 656 the number of bytes actually written. 657 658 @return: C{True} if a L{send} call on this channel would immediately 659 succeed or fail 660 @rtype: boolean 661 """ 662 self.lock.acquire() 663 try: 664 if self.closed or self.eof_sent: 665 return True 666 return self.out_window_size > 0 667 finally: 668 self.lock.release()

669

670 - def send(self, s):

671 """ 672 Send data to the channel. Returns the number of bytes sent, or 0 if 673 the channel stream is closed. Applications are responsible for 674 checking that all data has been sent: if only some of the data was 675 transmitted, the application needs to attempt delivery of the remaining 676 data. 677 678 @param s: data to send 679 @type s: str 680 @return: number of bytes actually sent 681 @rtype: int 682 683 @raise socket.timeout: if no data could be sent before the timeout set 684 by L{settimeout}. 685 """ 686 size = len(s) 687 self.lock.acquire() 688 try: 689 size = self._wait_for_send_window(size) 690 if size == 0: 691 # eof or similar 692 return 0 693 m = Message() 694 m.add_byte(chr(MSG_CHANNEL_DATA)) 695 m.add_int(self.remote_chanid) 696 m.add_string(s[:size]) 697 finally: 698 self.lock.release() 699 # Note: We release self.lock before calling _send_user_message. 700 # Otherwise, we can deadlock during re-keying. 701 self.transport._send_user_message(m) 702 return size

703

704 - def send_stderr(self, s):

705 """ 706 Send data to the channel on the "stderr" stream. This is normally 707 only used by servers to send output from shell commands -- clients 708 won't use this. Returns the number of bytes sent, or 0 if the channel 709 stream is closed. Applications are responsible for checking that all 710 data has been sent: if only some of the data was transmitted, the 711 application needs to attempt delivery of the remaining data. 712 713 @param s: data to send. 714 @type s: str 715 @return: number of bytes actually sent. 716 @rtype: int 717 718 @raise socket.timeout: if no data could be sent before the timeout set 719 by L{settimeout}. 720 721 @since: 1.1 722 """ 723 size = len(s) 724 self.lock.acquire() 725 try: 726 size = self._wait_for_send_window(size) 727 if size == 0: 728 # eof or similar 729 return 0 730 m = Message() 731 m.add_byte(chr(MSG_CHANNEL_EXTENDED_DATA)) 732 m.add_int(self.remote_chanid) 733 m.add_int(1) 734 m.add_string(s[:size]) 735 finally: 736 self.lock.release() 737 # Note: We release self.lock before calling _send_user_message. 738 # Otherwise, we can deadlock during re-keying. 739 self.transport._send_user_message(m) 740 return size

741

742 - def sendall(self, s):

743 """ 744 Send data to the channel, without allowing partial results. Unlike 745 L{send}, this method continues to send data from the given string until 746 either all data has been sent or an error occurs. Nothing is returned. 747 748 @param s: data to send. 749 @type s: str 750 751 @raise socket.timeout: if sending stalled for longer than the timeout 752 set by L{settimeout}. 753 @raise socket.error: if an error occured before the entire string was 754 sent. 755 756 @note: If the channel is closed while only part of the data hase been 757 sent, there is no way to determine how much data (if any) was sent. 758 This is irritating, but identically follows python's API. 759 """ 760 while s: 761 if self.closed: 762 # this doesn't seem useful, but it is the documented behavior of Socket 763 raise socket.error('Socket is closed') 764 sent = self.send(s) 765 s = s[sent:] 766 return None

767

768 - def sendall_stderr(self, s):

769 """ 770 Send data to the channel's "stderr" stream, without allowing partial 771 results. Unlike L{send_stderr}, this method continues to send data 772 from the given string until all data has been sent or an error occurs. 773 Nothing is returned. 774 775 @param s: data to send to the client as "stderr" output. 776 @type s: str 777 778 @raise socket.timeout: if sending stalled for longer than the timeout 779 set by L{settimeout}. 780 @raise socket.error: if an error occured before the entire string was 781 sent. 782 783 @since: 1.1 784 """ 785 while s: 786 if self.closed: 787 raise socket.error('Socket is closed') 788 sent = self.send_stderr(s) 789 s = s[sent:] 790 return None

791

792 - def makefile(self, *params):

793 """ 794 Return a file-like object associated with this channel. The optional 795 C{mode} and C{bufsize} arguments are interpreted the same way as by 796 the built-in C{file()} function in python. 797 798 @return: object which can be used for python file I/O. 799 @rtype: L{ChannelFile} 800 """ 801 return ChannelFile(*([self] + list(params)))

802

803 - def makefile_stderr(self, *params):

804 """ 805 Return a file-like object associated with this channel's stderr 806 stream. Only channels using L{exec_command} or L{invoke_shell} 807 without a pty will ever have data on the stderr stream. 808 809 The optional C{mode} and C{bufsize} arguments are interpreted the 810 same way as by the built-in C{file()} function in python. For a 811 client, it only makes sense to open this file for reading. For a 812 server, it only makes sense to open this file for writing. 813 814 @return: object which can be used for python file I/O. 815 @rtype: L{ChannelFile} 816 817 @since: 1.1 818 """ 819 return ChannelStderrFile(*([self] + list(params)))

820

821 - def fileno(self):

822 """ 823 Returns an OS-level file descriptor which can be used for polling, but 824 but I{not} for reading or writing. This is primaily to allow python's 825 C{select} module to work. 826 827 The first time C{fileno} is called on a channel, a pipe is created to 828 simulate real OS-level file descriptor (FD) behavior. Because of this, 829 two OS-level FDs are created, which will use up FDs faster than normal. 830 (You won't notice this effect unless you have hundreds of channels 831 open at the same time.) 832 833 @return: an OS-level file descriptor 834 @rtype: int 835 836 @warning: This method causes channel reads to be slightly less 837 efficient. 838 """ 839 self.lock.acquire() 840 try: 841 if self._pipe is not None: 842 return self._pipe.fileno() 843 # create the pipe and feed in any existing data 844 self._pipe = pipe.make_pipe() 845 p1, p2 = pipe.make_or_pipe(self._pipe) 846 self.in_buffer.set_event(p1) 847 self.in_stderr_buffer.set_event(p2) 848 return self._pipe.fileno() 849 finally: 850 self.lock.release()

851

852 - def shutdown(self, how):

853 """ 854 Shut down one or both halves of the connection. If C{how} is 0, 855 further receives are disallowed. If C{how} is 1, further sends 856 are disallowed. If C{how} is 2, further sends and receives are 857 disallowed. This closes the stream in one or both directions. 858 859 @param how: 0 (stop receiving), 1 (stop sending), or 2 (stop 860 receiving and sending). 861 @type how: int 862 """ 863 if (how == 0) or (how == 2): 864 # feign "read" shutdown 865 self.eof_received = 1 866 if (how == 1) or (how == 2): 867 self.lock.acquire() 868 try: 869 m = self._send_eof() 870 finally: 871 self.lock.release() 872 if m is not None: 873 self.transport._send_user_message(m)

874

875 - def shutdown_read(self):

876 """ 877 Shutdown the receiving side of this socket, closing the stream in 878 the incoming direction. After this call, future reads on this 879 channel will fail instantly. This is a convenience method, equivalent 880 to C{shutdown(0)}, for people who don't make it a habit to 881 memorize unix constants from the 1970s. 882 883 @since: 1.2 884 """ 885 self.shutdown(0)

886

887 - def shutdown_write(self):

888 """ 889 Shutdown the sending side of this socket, closing the stream in 890 the outgoing direction. After this call, future writes on this 891 channel will fail instantly. This is a convenience method, equivalent 892 to C{shutdown(1)}, for people who don't make it a habit to 893 memorize unix constants from the 1970s. 894 895 @since: 1.2 896 """ 897 self.shutdown(1)

898 899 900 ### calls from Transport 901 902

903 - def _set_transport(self, transport):

904 self.transport = transport 905 self.logger = util.get_logger(self.transport.get_log_channel())

906

907 - def _set_window(self, window_size, max_packet_size):

908 self.in_window_size = window_size 909 self.in_max_packet_size = max_packet_size 910 # threshold of bytes we receive before we bother to send a window update 911 self.in_window_threshold = window_size // 10 912 self.in_window_sofar = 0 913 self._log(DEBUG, 'Max packet in: %d bytes' % max_packet_size)

914

915 - def _set_remote_channel(self, chanid, window_size, max_packet_size):

916 self.remote_chanid = chanid 917 self.out_window_size = window_size 918 self.out_max_packet_size = max(max_packet_size, MIN_PACKET_SIZE) 919 self.active = 1 920 self._log(DEBUG, 'Max packet out: %d bytes' % max_packet_size)

921

922 - def _request_success(self, m):

923 self._log(DEBUG, 'Sesch channel %d request ok' % self.chanid) 924 self.event_ready = True 925 self.event.set() 926 return

927

928 - def _request_failed(self, m):

929 self.lock.acquire() 930 try: 931 msgs = self._close_internal() 932 finally: 933 self.lock.release() 934 for m in msgs: 935 if m is not None: 936 self.transport._send_user_message(m)

937

938 - def _feed(self, m):

939 if type(m) is str: 940 # passed from _feed_extended 941 s = m 942 else: 943 s = m.get_string() 944 self.in_buffer.feed(s)

945

946 - def _feed_extended(self, m):

947 code = m.get_int() 948 s = m.get_string() 949 if code != 1: 950 self._log(ERROR, 'unknown extended_data type %d; discarding' % code) 951 return 952 if self.combine_stderr: 953 self._feed(s) 954 else: 955 self.in_stderr_buffer.feed(s)

956

957 - def _window_adjust(self, m):

958 nbytes = m.get_int() 959 self.lock.acquire() 960 try: 961 if self.ultra_debug: 962 self._log(DEBUG, 'window up %d' % nbytes) 963 self.out_window_size += nbytes 964 self.out_buffer_cv.notifyAll() 965 finally: 966 self.lock.release()

967

968 - def _handle_request(self, m):

969 key = m.get_string() 970 want_reply = m.get_boolean() 971 server = self.transport.server_object 972 ok = False 973 if key == 'exit-status': 974 self.exit_status = m.get_int() 975 self.status_event.set() 976 ok = True 977 elif key == 'xon-xoff': 978 # ignore 979 ok = True 980 elif key == 'pty-req': 981 term = m.get_string() 982 width = m.get_int() 983 height = m.get_int() 984 pixelwidth = m.get_int() 985 pixelheight = m.get_int() 986 modes = m.get_string() 987 if server is None: 988 ok = False 989 else: 990 ok = server.check_channel_pty_request(self, term, width, height, pixelwidth, 991 pixelheight, modes) 992 elif key == 'shell': 993 if server is None: 994 ok = False 995 else: 996 ok = server.check_channel_shell_request(self) 997 elif key == 'exec': 998 cmd = m.get_string() 999 if server is None: 1000 ok = False 1001 else: 1002 ok = server.check_channel_exec_request(self, cmd) 1003 elif key == 'subsystem': 1004 name = m.get_string() 1005 if server is None: 1006 ok = False 1007 else: 1008 ok = server.check_channel_subsystem_request(self, name) 1009 elif key == 'window-change': 1010 width = m.get_int() 1011 height = m.get_int() 1012 pixelwidth = m.get_int() 1013 pixelheight = m.get_int() 1014 if server is None: 1015 ok = False 1016 else: 1017 ok = server.check_channel_window_change_request(self, width, height, pixelwidth, 1018 pixelheight) 1019 elif key == 'x11-req': 1020 single_connection = m.get_boolean() 1021 auth_proto = m.get_string() 1022 auth_cookie = m.get_string() 1023 screen_number = m.get_int() 1024 if server is None: 1025 ok = False 1026 else: 1027 ok = server.check_channel_x11_request(self, single_connection, 1028 auth_proto, auth_cookie, screen_number) 1029 else: 1030 self._log(DEBUG, 'Unhandled channel request "%s"' % key) 1031 ok = False 1032 if want_reply: 1033 m = Message() 1034 if ok: 1035 m.add_byte(chr(MSG_CHANNEL_SUCCESS)) 1036 else: 1037 m.add_byte(chr(MSG_CHANNEL_FAILURE)) 1038 m.add_int(self.remote_chanid) 1039 self.transport._send_user_message(m)

1040

1041 - def _handle_eof(self, m):

1042 self.lock.acquire() 1043 try: 1044 if not self.eof_received: 1045 self.eof_received = True 1046 self.in_buffer.close() 1047 self.in_stderr_buffer.close() 1048 if self._pipe is not None: 1049 self._pipe.set_forever() 1050 finally: 1051 self.lock.release() 1052 self._log(DEBUG, 'EOF received (%s)', self._name)

1053

1054 - def _handle_close(self, m):

1055 self.lock.acquire() 1056 try: 1057 msgs = self._close_internal() 1058 self.transport._unlink_channel(self.chanid) 1059 finally: 1060 self.lock.release() 1061 for m in msgs: 1062 if m is not None: 1063 self.transport._send_user_message(m)

1064 1065 1066 ### internals... 1067 1068

1069 - def _log(self, level, msg, *args):

1070 self.logger.log(level, "[chan " + self._name + "] " + msg, *args)

1071

1072 - def _event_pending(self):

1073 self.event.clear() 1074 self.event_ready = False

1075

1076 - def _wait_for_event(self):

1077 self.event.wait() 1078 assert self.event.isSet() 1079 if self.event_ready: 1080 return 1081 e = self.transport.get_exception() 1082 if e is None: 1083 e = SSHException('Channel closed.') 1084 raise e

1085

1086 - def _set_closed(self):

1087 # you are holding the lock. 1088 self.closed = True 1089 self.in_buffer.close() 1090 self.in_stderr_buffer.close() 1091 self.out_buffer_cv.notifyAll() 1092 # Notify any waiters that we are closed 1093 self.event.set() 1094 self.status_event.set() 1095 if self._pipe is not None: 1096 self._pipe.set_forever()

1097

1098 - def _send_eof(self):

1099 # you are holding the lock. 1100 if self.eof_sent: 1101 return None 1102 m = Message() 1103 m.add_byte(chr(MSG_CHANNEL_EOF)) 1104 m.add_int(self.remote_chanid) 1105 self.eof_sent = True 1106 self._log(DEBUG, 'EOF sent (%s)', self._name) 1107 return m

1108

1109 - def _close_internal(self):

1110 # you are holding the lock. 1111 if not self.active or self.closed: 1112 return None, None 1113 m1 = self._send_eof() 1114 m2 = Message() 1115 m2.add_byte(chr(MSG_CHANNEL_CLOSE)) 1116 m2.add_int(self.remote_chanid) 1117 self._set_closed() 1118 # can't unlink from the Transport yet -- the remote side may still 1119 # try to send meta-data (exit-status, etc) 1120 return m1, m2

1121

1122 - def _unlink(self):

1123 # server connection could die before we become active: still signal the close! 1124 if self.closed: 1125 return 1126 self.lock.acquire() 1127 try: 1128 self._set_closed() 1129 self.transport._unlink_channel(self.chanid) 1130 finally: 1131 self.lock.release()

1132

1133 - def _check_add_window(self, n):

1134 self.lock.acquire() 1135 try: 1136 if self.closed or self.eof_received or not self.active: 1137 return 0 1138 if self.ultra_debug: 1139 self._log(DEBUG, 'addwindow %d' % n) 1140 self.in_window_sofar += n 1141 if self.in_window_sofar <= self.in_window_threshold: 1142 return 0 1143 if self.ultra_debug: 1144 self._log(DEBUG, 'addwindow send %d' % self.in_window_sofar) 1145 out = self.in_window_sofar 1146 self.in_window_sofar = 0 1147 return out 1148 finally: 1149 self.lock.release()

1150

1151 - def _wait_for_send_window(self, size):

1152 """ 1153 (You are already holding the lock.) 1154 Wait for the send window to open up, and allocate up to C{size} bytes 1155 for transmission. If no space opens up before the timeout, a timeout 1156 exception is raised. Returns the number of bytes available to send 1157 (may be less than requested). 1158 """ 1159 # you are already holding the lock 1160 if self.closed or self.eof_sent: 1161 return 0 1162 if self.out_window_size == 0: 1163 # should we block? 1164 if self.timeout == 0.0: 1165 raise socket.timeout() 1166 # loop here in case we get woken up but a different thread has filled the buffer 1167 timeout = self.timeout 1168 while self.out_window_size == 0: 1169 if self.closed or self.eof_sent: 1170 return 0 1171 then = time.time() 1172 self.out_buffer_cv.wait(timeout) 1173 if timeout != None: 1174 timeout -= time.time() - then 1175 if timeout <= 0.0: 1176 raise socket.timeout() 1177 # we have some window to squeeze into 1178 if self.closed or self.eof_sent: 1179 return 0 1180 if self.out_window_size < size: 1181 size = self.out_window_size 1182 if self.out_max_packet_size - 64 < size: 1183 size = self.out_max_packet_size - 64 1184 self.out_window_size -= size 1185 if self.ultra_debug: 1186 self._log(DEBUG, 'window down to %d' % self.out_window_size) 1187 return size

Source Code for Module paramiko.channel