1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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
40 MIN_PACKET_SIZE = 1024
41
42
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
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
99 try:
100 self.close()
101 except:
102 pass
103
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
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
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
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
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
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
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
320
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
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
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
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
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
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
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
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
496
497
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
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
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
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
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
573
574
575
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
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
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
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
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
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
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
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
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
733
734 self.transport._send_user_message(m)
735 return size
736
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
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
771
772 self.transport._send_user_message(m)
773 return size
774
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
796 raise socket.error('Socket is closed')
797 sent = self.send(s)
798 s = s[sent:]
799 return None
800
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
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
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
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
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
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
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
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
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
934
935
939
941 self.in_window_size = window_size
942 self.in_max_packet_size = max_packet_size
943
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
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
956 self._log(DEBUG, 'Sesch channel %d request ok' % self.chanid)
957 self.event_ready = True
958 self.event.set()
959 return
960
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
972 if type(m) is str:
973
974 s = m
975 else:
976 s = m.get_string()
977 self.in_buffer.feed(s)
978
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
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
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
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
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
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
1105
1106
1107 - def _log(self, level, msg, *args):
1108 self.logger.log(level, "[chan " + self._name + "] " + msg, *args)
1109
1111 self.event.clear()
1112 self.event_ready = False
1113
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
1125
1126 self.closed = True
1127 self.in_buffer.close()
1128 self.in_stderr_buffer.close()
1129 self.out_buffer_cv.notifyAll()
1130
1131 self.event.set()
1132 self.status_event.set()
1133 if self._pipe is not None:
1134 self._pipe.set_forever()
1135
1137
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
1148
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
1157
1158 return m1, m2
1159
1161
1162 if self.closed:
1163 return
1164 self.lock.acquire()
1165 try:
1166 self._set_closed()
1167 self.transport._unlink_channel(self.chanid)
1168 finally:
1169 self.lock.release()
1170
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
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
1198 if self.closed or self.eof_sent:
1199 return 0
1200 if self.out_window_size == 0:
1201
1202 if self.timeout == 0.0:
1203 raise socket.timeout()
1204
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
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
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):
1243
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
1254
1258
1259
1261 - def __init__(self, channel, mode = 'r', bufsize = -1):
1263
1266
1270
1271
1272
1273