This document contains the API (Application Programming Interface)
+documentation for this project. Documentation for the Python
+objects defined by the project is divided into separate pages for each
+package, module, and class. The API documentation also includes two
+pages containing information about the project as a whole: a trees
+page, and an index page.
+
+
Object Documentation
+
+
Each Package Documentation page contains:
+
+
A description of the package.
+
A list of the modules and sub-packages contained by the
+ package.
+
A summary of the classes defined by the package.
+
A summary of the functions defined by the package.
+
A summary of the variables defined by the package.
+
A detailed description of each function defined by the
+ package.
+
A detailed description of each variable defined by the
+ package.
+
+
+
Each Module Documentation page contains:
+
+
A description of the module.
+
A summary of the classes defined by the module.
+
A summary of the functions defined by the module.
+
A summary of the variables defined by the module.
+
A detailed description of each function defined by the
+ module.
+
A detailed description of each variable defined by the
+ module.
+
+
+
Each Class Documentation page contains:
+
+
A class inheritance diagram.
+
A list of known subclasses.
+
A description of the class.
+
A summary of the methods defined by the class.
+
A summary of the instance variables defined by the class.
+
A summary of the class (static) variables defined by the
+ class.
+
A detailed description of each method defined by the
+ class.
+
A detailed description of each instance variable defined by the
+ class.
+
A detailed description of each class (static) variable defined
+ by the class.
+
+
+
Project Documentation
+
+
The Trees page contains the module and class hierarchies:
+
+
The module hierarchy lists every package and module, with
+ modules grouped into packages. At the top level, and within each
+ package, modules and sub-packages are listed alphabetically.
+
The class hierarchy lists every class, grouped by base
+ class. If a class has more than one base class, then it will be
+ listed under each base class. At the top level, and under each base
+ class, classes are listed alphabetically.
+
+
+
The Index page contains indices of terms and
+ identifiers:
+
+
The term index lists every term indexed by any object's
+ documentation. For each term, the index provides links to each
+ place where the term is indexed.
+
The identifier index lists the (short) name of every package,
+ module, class, method, function, variable, and parameter. For each
+ identifier, the index provides a short description, and a link to
+ its documentation.
+
+
+
The Table of Contents
+
+
The table of contents occupies the two frames on the left side of
+the window. The upper-left frame displays the project
+contents, and the lower-left frame displays the module
+contents:
+
+
+
+
+
+ Project Contents...
+
+ API Documentation Frame
+
+
+
+
+ Module Contents ...
+
+
+
+
+
+
The project contents frame contains a list of all packages
+and modules that are defined by the project. Clicking on an entry
+will display its contents in the module contents frame. Clicking on a
+special entry, labeled "Everything," will display the contents of
+the entire project.
+
+
The module contents frame contains a list of every
+submodule, class, type, exception, function, and variable defined by a
+module or package. Clicking on an entry will display its
+documentation in the API documentation frame. Clicking on the name of
+the module, at the top of the frame, will display the documentation
+for the module itself.
+
+
The "frames" and "no frames" buttons below the top
+navigation bar can be used to control whether the table of contents is
+displayed or not.
+
+
The Navigation Bar
+
+
A navigation bar is located at the top and bottom of every page.
+It indicates what type of page you are currently viewing, and allows
+you to go to related pages. The following table describes the labels
+on the navigation bar. Note that not some labels (such as
+[Parent]) are not displayed on all pages.
+
+
+
+
Label
+
Highlighted when...
+
Links to...
+
+
[Parent]
+
(never highlighted)
+
the parent of the current package
+
[Package]
+
viewing a package
+
the package containing the current object
+
+
[Module]
+
viewing a module
+
the module containing the current object
+
+
[Class]
+
viewing a class
+
the class containing the current object
+
[Trees]
+
viewing the trees page
+
the trees page
+
[Index]
+
viewing the index page
+
the index page
+
[Help]
+
viewing the help page
+
the help page
+
+
+
The "show private" and "hide private" buttons below
+the top navigation bar can be used to control whether documentation
+for private objects is displayed. Private objects are usually defined
+as objects whose (short) names begin with a single underscore, but do
+not end with an underscore. For example, "_x",
+"__pprint", and "epydoc.epytext._tokenize"
+are private objects; but "re.sub",
+"__init__", and "type_" are not. However,
+if a module defines the "__all__" variable, then its
+contents are used to decide which objects are private.
+
+
A timestamp below the bottom navigation bar indicates when each
+page was last updated.
Paramiko (a combination of the esperanto words for
+"paranoid" and "friend") is a module for python 2.3
+or greater that implements the SSH2 protocol for secure (encrypted and
+authenticated) connections to remote machines. Unlike SSL (aka TLS), the
+SSH2 protocol does not require heirarchical certificates signed by a
+powerful central authority. You may know SSH2 as the protocol that
+replaced telnet and rsh for secure access to
+remote shells, but the protocol also includes the ability to open
+arbitrary channels to remote services across an encrypted tunnel. (This
+is how sftp works, for example.)
+
To use this package, pass a socket (or socket-like object) to a Transport, and use start_server or start_client to negoatite with the remote
+host as either a server or client. As a client, you are responsible for
+authenticating using a password or private key, and checking the server's
+host key. (Key signature and verification is done by paramiko, but you
+will need to provide private keys and check that the content of a public
+key matches what you expected to see.) As a server, you are
+responsible for deciding which users, passwords, and keys to allow, and
+what kind of channels to allow.
+
Once you have finished, either side may request flow-controlled Channels
+to the other side, which are python objects that act like sockets, but
+send and receive data over the encrypted session.
+
Paramiko is written entirely in python (no C or platform-dependent
+code) and is released under the GNU Lesser General Public License
+(LGPL).
An SSH2 Message is a stream of bytes that encodes some
+combination of strings, integers, bools, and infinite-precision integers
+(known in python as longs).
An SSH Transport attaches to a stream (usually a socket), negotiates
+an encrypted session, authenticates, and then creates stream tunnels,
+called Channels, across the session.
Client interface for using private keys from an SSH agent running on
+the local machine. If an SSH agent is running, this class can be used to
+connect to it and retreive PKey objects which can be used when
+attempting to authenticate to remote SSH servers.
+Because the SSH agent protocol uses environment variables and
+unix-domain sockets, this probably doesn't work on Windows. It does work
+on most posix platforms though (Linux and MacOS X, for example).
+
+
+
+
+
+
+
Method Summary
+
+
__init__(self)
+
+Open a session with the local machine's SSH agent, if one is
+running.
get_keys(self)
+
+Return the list of keys available through the SSH agent, if any.
+
+
+
+
+
+
+
Method Details
+
+
+
+
+
__init__(self)
+ (Constructor)
+
+ Open a session with the local machine's SSH agent, if one is
+ running. If no agent is running, initialization will succeed, but get_keys will return an empty tuple.
+
+
Raises:
+
SSHException -
+ if an SSH agent is found, but speaks an incompatible
+ protocol
+
+
+
+
+
+
+
close(self)
+
+ Close the SSH agent connection.
+
+
+
+
+
+
+
get_keys(self)
+
+ Return the list of keys available through the SSH agent, if any. If
+ no SSH agent was running (or it couldn't be contacted), an empty list
+ will be returned.
+
+
Returns:
+
+ a list of keys available on the SSH agent
+
+ (type=tuple of AgentKey)
+
+
+
+
+Private key held in a local SSH agent. This type of key can be used
+for authenticating to a remote server (signing). Most other key
+operations work as expected.
+
+
+
+
+
+
+
Method Summary
+
+
__init__(self,
+ agent,
+ blob)
+
+
str
+
+
__str__(self)
+
+Return a string of an SSH Message made up of the public part(s) of
+this key.
+
str
+
+
get_name(self)
+
+Return the name of this private key implementation.
+ Return a string of an SSH Message made up of the public part(s) of
+ this key. This string is suitable for passing to __init__ to re-create the key object
+ later.
+
+
Returns:
+
+ string representation of an SSH key message.
+
+ (type=str)
+
+
+
+
+Exception raised when an authentication type (like password) is used,
+but the server isn't allowing that type. (It may only allow public-key,
+for example.)
+
+
+
+ Returns an iterator that can be used to iterate over the lines in
+ this file. This iterator happens to return the file itself, since a
+ file is its own iterator.
+
+
Returns:
+
+ an interator.
+
+ (type=iterator)
+
+
+
Raises:
+
ValueError -
+ if the file is closed.
+
+
+
+
+
+
+
close(self)
+
+ Close the file. Future read and write operations will fail.
+
+
+
+
+
+
+
flush(self)
+
+ Write out any data in the write buffer. This may do nothing if write
+ buffering is not turned on.
+
+
+
+
+
+
+
next(self)
+
+ Returns the next line from the input, or raises
+ StopIteration when EOF is hit. Unlike python file objects,
+ it's okay to mix calls to next and readline.
+
+
Returns:
+
+ a line read from the file.
+
+ (type=str)
+
+
+
Raises:
+
StopIteration -
+ when the end of the file is reached.
+
+
+
+
+
+
+
read(self,
+ size=None)
+
+ Read at most size bytes from the file (less if we hit
+ the end of the file first). If the size argument is
+ negative or omitted, read all the remaining data in the file.
+
+
Parameters:
+
size -
+ maximum number of bytes to read.
+
+ (type=int)
+
+
+
Returns:
+
+ data read from the file, or an empty string if EOF was
+ encountered immediately.
+
+ (type=str)
+
+
+
+
+
+
+
+
readline(self,
+ size=None)
+
+ Read one entire line from the file. A trailing newline character is
+ kept in the string (but may be absent when a file ends with an
+ incomplete line). If the size argument is present and non-negative, it
+ is a maximum byte count (including the trailing newline) and an
+ incomplete line may be returned. An empty string is returned only when
+ EOF is encountered immediately.
+
+
Parameters:
+
size -
+ maximum length of returned string.
+
+ (type=int)
+
+
+
Returns:
+
+ next line of the file, or an empty string if the end of the
+ file has been reached.
+
+ (type=str)
+
+
+
Note: Unlike stdio's fgets(), the returned string contains null
+characters ('\0') if they occurred in the input.
+
+
+
+
+
+
+
+
readlines(self,
+ sizehint=None)
+
+ Read all remaining lines using readline and return them as a list. If
+ the optional sizehint argument is present, instead of
+ reading up to EOF, whole lines totalling approximately sizehint bytes
+ (possibly after rounding up to an internal buffer size) are read.
+
+
Parameters:
+
sizehint -
+ desired maximum number of bytes to read.
+
+ (type=int)
+
+
+
Returns:
+
+ list of lines read from the file.
+
+ (type=list)
+
+
+
+
+
+
+
+
seek(self,
+ offset,
+ whence=0)
+
+ Set the file's current position, like stdio's fseek.
+ Not all file objects support seeking.
+
+
Parameters:
+
offset -
+ position to move to within the file, relative to
+ whence.
+
+ (type=int)
+
whence -
+ type of movement: 0 = absolute; 1 = relative to the current
+ position; 2 = relative to the end of the file.
+
+ (type=int)
+
+
+
Raises:
+
IOError -
+ if the file doesn't support random access.
+
+
Note: If a file is opened in append mode ('a' or
+'a+'), any seek operations will be undone at the next write
+(as the file position will move back to the end of the file).
+
+
+
+
+
+
+
+
tell(self)
+
+ Return the file's current position. This may not be accurate or
+ useful if the underlying file doesn't support random access, or was
+ opened in append mode.
+
+
Returns:
+
+ file position (in bytes).
+
+ (type=int)
+
+
+
+
+
+
+
+
write(self,
+ data)
+
+ Write data to the file. If write buffering is on
+ (bufsize was specified and non-zero), some or all of the
+ data may not actually be written yet. (Use flush or close to force buffered data to be
+ written out.)
+
+
Parameters:
+
data -
+ data to write.
+
+ (type=str)
+
+
+
+
+
+
+
+
writelines(self,
+ sequence)
+
+ Write a sequence of strings to the file. The sequence can be any
+ iterable object producing strings, typically a list of strings. (The
+ name is intended to match readlines; writelines does
+ not add line separators.)
+
+
Parameters:
+
sequence -
+ an iterable sequence of strings.
+
+ (type=sequence)
+
+
+
+
+
+
+
+
xreadlines(self)
+
+ Identical to iter(f). This is a deprecated file
+ interface that predates python iterator support.
+
A secure tunnel across an SSH Transport. A Channel is meant to behave
+like a socket, and has an API that should be indistinguishable from the
+python socket API.
+Because SSH2 has a windowing kind of flow control, if you stop reading
+data from a Channel and its buffer fills up, the server will be unable to
+send you any more data until you read some of it. (This won't affect
+other channels on the same transport -- all channels on a single
+transport are flow-controlled independently.) Similarly, if the server
+isn't reading data you send, calls to send may block, unless you set a timeout.
+This is exactly like a normal network socket, so it shouldn't be too
+surprising.
+
+
+
+
+
send_exit_status(self,
+ status)
+
+Send the exit status of an executed command to the client.
+
int
+
+
send_stderr(self,
+ s)
+
+Send data to the channel on the "stderr" stream.
+
+
sendall(self,
+ s)
+
+Send data to the channel, without allowing partial results.
+
+
sendall_stderr(self,
+ s)
+
+Send data to the channel's "stderr" stream, without allowing
+partial results.
+
bool
+
+
set_combine_stderr(self,
+ combine)
+
+Set whether stderr should be combined into stdout on this channel.
+
+
set_name(self,
+ name)
+
+Set a name for this channel.
+
+
setblocking(self,
+ blocking)
+
+Set blocking or non-blocking mode of the channel: if
+blocking is 0, the channel is set to non-blocking mode;
+otherwise it's set to blocking mode.
+
+
settimeout(self,
+ timeout)
+
+Set a timeout on blocking read/write operations.
+
+
shutdown(self,
+ how)
+
+Shut down one or both halves of the connection.
+
+
shutdown_read(self)
+
+Shutdown the receiving side of this socket, closing the stream in the
+incoming direction.
+
+
shutdown_write(self)
+
+Shutdown the sending side of this socket, closing the stream in the
+outgoing direction.
+
+
Inherited from object
+
+
__delattr__(...)
+
+x.__delattr__('name') <==> del x.name
+ Create a new channel. The channel is not associated with any
+ particular session or Transport until the Transport attaches
+ it. Normally you would only call this method from the constructor of a
+ subclass of Channel.
+
+
Parameters:
+
chanid -
+ the ID of this channel, as passed by an existing Transport.
+
+ (type=int)
+
+ Close the channel. All future read/write operations on the channel
+ will fail. The remote end will receive no more data (after queued data
+ is flushed). Channels are automatically closed when their Transport is closed or when they are
+ garbage collected.
+
+
+
+
+
+
+
exec_command(self,
+ command)
+
+
Execute a command on the server. If the server allows it, the
+ channel will then be directly connected to the stdin, stdout, and
+ stderr of the command being executed.
+ When the command finishes executing, the channel will be closed and
+ can't be reused. You must open a new channel if you wish to execute
+ another command.
+
+
Parameters:
+
command -
+ a shell command to execute.
+
+ (type=str)
+
+
+
Returns:
+
+ True if the operation succeeded;
+ False if not.
+
+ (type=bool)
+
+
+
+
+
+
+
+
fileno(self)
+
+
Returns an OS-level file descriptor which can be used for polling,
+ but but not for reading or writing). This is primaily to allow
+ python's select module to work.
+ The first time fileno is called on a channel, a pipe is
+ created to simulate real OS-level file descriptor (FD) behavior.
+ Because of this, two OS-level FDs are created, which will use up FDs
+ faster than normal. You won't notice this effect unless you open
+ hundreds or thousands of channels simultaneously, but it's still
+ notable.
+
+
Returns:
+
+ an OS-level file descriptor
+
+ (type=int)
+
+
+
Warning: This method causes channel reads to be slightly less efficient.
+
+
+
+
+
+
+
+
get_id(self)
+
+ Return the ID # for this channel. The channel ID is unique across a
+ Transport and usually a small number.
+ It's also the number passed to ServerInterface.check_channel_request
+ when determining whether to accept a channel request in server
+ mode.
+
+
Returns:
+
+ the ID of this channel.
+
+ (type=int)
+
+
+
Since: ivysaur
+
+
+
+
+
+
+
+
get_name(self)
+
+ Get the name of this channel that was previously set by set_name.
+
+ Request a pseudo-terminal from the server. This is usually used
+ right after creating a client channel, to ask the server to provide
+ some basic terminal semantics for a shell invoked with invoke_shell. It isn't necessary (or
+ desirable) to call this method if you're going to exectue a single
+ command with exec_command.
+
+
Parameters:
+
term -
+ the terminal type to emulate (for example,
+ 'vt100').
+
+ (type=str)
+
width -
+ width (in characters) of the terminal screen
+
+ (type=int)
+
height -
+ height (in characters) of the terminal screen
+
+ (type=int)
+
+
+
Returns:
+
+ True if the operation succeeded;
+ False if not.
+
+ (type=bool)
+
+
+
+
+
+
+
+
get_transport(self)
+
+ Return the Transport associated with this
+ channel.
+
+
Returns:
+
+ the Transport that was used to create
+ this channel.
+
+ (type=Transport)
+
+
+
+
+
+
+
+
gettimeout(self)
+
+ Returns the timeout in seconds (as a float) associated with socket
+ operations, or None if no timeout is set. This reflects
+ the last call to setblocking or settimeout.
+
+
Returns:
+
+ timeout in seconds, or None.
+
+ (type=float)
+
+
+
+
+
+
+
+
invoke_shell(self)
+
+
Request an interactive shell session on this channel. If the server
+ allows it, the channel will then be directly connected to the stdin,
+ stdout, and stderr of the shell.
+
Normally you would call get_pty before this, in which case the
+ shell will operate through the pty, and the channel will be connected
+ to the stdin and stdout of the pty.
+ When the shell exits, the channel will be closed and can't be
+ reused. You must open a new channel if you wish to open another
+ shell.
+
+
Returns:
+
+ True if the operation succeeded;
+ False if not.
+
+ (type=bool)
+
+
+
+
+
+
+
+
invoke_subsystem(self,
+ subsystem)
+
+
Request a subsystem on the server (for example, sftp).
+ If the server allows it, the channel will then be directly connected to
+ the requested subsystem.
+ When the subsystem finishes, the channel will be closed and can't be
+ reused.
+
+
Parameters:
+
subsystem -
+ name of the subsystem being requested.
+
+ (type=str)
+
+
+
Returns:
+
+ True if the operation succeeded;
+ False if not.
+
+ (type=bool)
+
+
+
+
+
+
+
+
makefile(self,
+ *params)
+
+ Return a file-like object associated with this channel. The optional
+ mode and bufsize arguments are interpreted
+ the same way as by the built-in file() function in
+ python.
+
+
Returns:
+
+ object which can be used for python file I/O.
+
+ (type=ChannelFile)
+
+
+
+
+
+
+
+
makefile_stderr(self,
+ *params)
+
+
Return a file-like object associated with this channel's stderr
+ stream. Only channels using exec_command or invoke_shell without a pty will ever have
+ data on the stderr stream.
+ The optional mode and bufsize arguments
+ are interpreted the same way as by the built-in file()
+ function in python. For a client, it only makes sense to open this file
+ for reading. For a server, it only makes sense to open this file for
+ writing.
+
+
Returns:
+
+ object which can be used for python file I/O.
+
+ (type=ChannelFile)
+
+
+
Since: 1.1
+
+
+
+
+
+
+
+
recv(self,
+ nbytes)
+
+ Receive data from the channel. The return value is a string
+ representing the data received. The maximum amount of data to be
+ received at once is specified by nbytes. If a string of
+ length zero is returned, the channel stream has closed.
+
+
Parameters:
+
nbytes -
+ maximum number of bytes to read.
+
+ (type=int)
+
+
+
Returns:
+
+ data.
+
+ (type=str)
+
+
+
Raises:
+
socket.timeout -
+ if no data is ready before the timeout set by settimeout.
+
+
+
+
+
+
+
recv_exit_status(self)
+
+ Return the exit status from the process on the server. This is
+ mostly useful for retrieving the reults of an exec_command. If the command hasn't
+ finished yet, this method will wait until it does, or until the channel
+ is closed. If no exit status is provided by the server, -1 is
+ returned.
+
+
Returns:
+
+ the exit code of the process on the server.
+
+ (type=int)
+
+
+
Since: 1.2
+
+
+
+
+
+
+
+
recv_ready(self)
+
+ Returns true if data is buffered and ready to be read from this
+ channel. A False result does not mean that the channel has
+ closed; it means you may need to wait before more data arrives.
+
+
Returns:
+
+ True if a recv call on this channel would
+ immediately return at least one byte; False
+ otherwise.
+
+ (type=boolean)
+
+
+
+
+
+
+
+
recv_stderr(self,
+ nbytes)
+
+ Receive data from the channel's stderr stream. Only channels using
+ exec_command or invoke_shell without a pty will ever have
+ data on the stderr stream. The return value is a string representing
+ the data received. The maximum amount of data to be received at once is
+ specified by nbytes. If a string of length zero is
+ returned, the channel stream has closed.
+
+
Parameters:
+
nbytes -
+ maximum number of bytes to read.
+
+ (type=int)
+
+
+
Returns:
+
+ data.
+
+ (type=str)
+
+
+
Raises:
+
socket.timeout -
+ if no data is ready before the timeout set by settimeout.
+
+
Since: 1.1
+
+
+
+
+
+
+
+
recv_stderr_ready(self)
+
+ Returns true if data is buffered and ready to be read from this
+ channel's stderr stream. Only channels using exec_command or invoke_shell without a pty will ever have
+ data on the stderr stream.
+
+
Returns:
+
+ True if a recv_stderr call on this channel
+ would immediately return at least one byte; False
+ otherwise.
+
+ (type=boolean)
+
+
+
Since: 1.1
+
+
+
+
+
+
+
+
resize_pty(self,
+ width=80,
+ height=24)
+
+ Resize the pseudo-terminal. This can be used to change the width and
+ height of the terminal emulation created in a previous get_pty call.
+
+
Parameters:
+
width -
+ new width (in characters) of the terminal screen
+
+ (type=int)
+
height -
+ new height (in characters) of the terminal screen
+
+ (type=int)
+
+
+
Returns:
+
+ True if the operation succeeded;
+ False if not.
+
+ (type=bool)
+
+
+
+
+
+
+
+
send(self,
+ s)
+
+ Send data to the channel. Returns the number of bytes sent, or 0 if
+ the channel stream is closed. Applications are responsible for checking
+ that all data has been sent: if only some of the data was transmitted,
+ the application needs to attempt delivery of the remaining data.
+
+
Parameters:
+
s -
+ data to send.
+
+ (type=str)
+
+
+
Returns:
+
+ number of bytes actually sent.
+
+ (type=int)
+
+
+
Raises:
+
socket.timeout -
+ if no data could be sent before the timeout set by settimeout.
+
+
+
+
+
+
+
send_exit_status(self,
+ status)
+
+ Send the exit status of an executed command to the client. (This
+ really only makes sense in server mode.) Many clients expect to get
+ some sort of status code back from an executed command after it
+ completes.
+
+
Parameters:
+
status -
+ the exit code of the process
+
+ (type=int)
+
+
+
Since: 1.2
+
+
+
+
+
+
+
+
send_stderr(self,
+ s)
+
+ Send data to the channel on the "stderr" stream. This is
+ normally only used by servers to send output from shell commands --
+ clients won't use this. Returns the number of bytes sent, or 0 if the
+ channel stream is closed. Applications are responsible for checking
+ that all data has been sent: if only some of the data was transmitted,
+ the application needs to attempt delivery of the remaining data.
+
+
Parameters:
+
s -
+ data to send.
+
+ (type=str)
+
+
+
Returns:
+
+ number of bytes actually sent.
+
+ (type=int)
+
+
+
Raises:
+
socket.timeout -
+ if no data could be sent before the timeout set by settimeout.
+
+
Since: 1.1
+
+
+
+
+
+
+
+
sendall(self,
+ s)
+
+ Send data to the channel, without allowing partial results. Unlike
+ send, this method continues to send data
+ from the given string until either all data has been sent or an error
+ occurs. Nothing is returned.
+
+
Parameters:
+
s -
+ data to send.
+
+ (type=str)
+
+
+
Raises:
+
socket.timeout -
+ if sending stalled for longer than the timeout set by settimeout.
+
socket.error -
+ if an error occured before the entire string was sent.
+
+
Note: If the channel is closed while only part of the data hase been sent,
+there is no way to determine how much data (if any) was sent. This is
+irritating, but identically follows python's API.
+
+
+
+
+
+
+
+
sendall_stderr(self,
+ s)
+
+ Send data to the channel's "stderr" stream, without
+ allowing partial results. Unlike send_stderr, this method continues to
+ send data from the given string until all data has been sent or an
+ error occurs. Nothing is returned.
+
+
Parameters:
+
s -
+ data to send to the client as "stderr" output.
+
+ (type=str)
+
+
+
Raises:
+
socket.timeout -
+ if sending stalled for longer than the timeout set by settimeout.
+
socket.error -
+ if an error occured before the entire string was sent.
+
+
Since: 1.1
+
+
+
+
+
+
+
+
set_combine_stderr(self,
+ combine)
+
+
Set whether stderr should be combined into stdout on this channel.
+ The default is False, but in some cases it may be
+ convenient to have both streams combined.
+
If this is False, and exec_command is called (or
+ invoke_shell with no pty), output to stderr will not show
+ up through the recv and recv_ready calls. You will have to use recv_stderr and recv_stderr_ready to get stderr
+ output.
combine -
+ True if stderr output should be combined into
+ stdout on this channel.
+
+ (type=bool)
+
+
+
Returns:
+
+ previous setting.
+
+ (type=bool)
+
+
+
Since: 1.1
+
+
+
+
+
+
+
+
set_name(self,
+ name)
+
+ Set a name for this channel. Currently it's only used to set the
+ name of the log level used for debugging. The name can be fetched with
+ the get_name method.
+
+
Parameters:
+
name -
+ new channel name.
+
+ (type=str)
+
+
+
+
+
+
+
+
setblocking(self,
+ blocking)
+
+
Set blocking or non-blocking mode of the channel: if
+ blocking is 0, the channel is set to non-blocking mode;
+ otherwise it's set to blocking mode. Initially all channels are in
+ blocking mode.
+
In non-blocking mode, if a recv call doesn't find any data, or if a
+ send call can't immediately dispose of
+ the data, an error exception is raised. In blocking mode, the calls
+ block until they can proceed.
+ chan.setblocking(0) is equivalent to
+ chan.settimeout(0); chan.setblocking(1) is
+ equivalent to chan.settimeout(None).
+
+
Parameters:
+
blocking -
+ 0 to set non-blocking mode; non-0 to set blocking mode.
+
+ (type=int)
+
+
+
+
+
+
+
+
settimeout(self,
+ timeout)
+
+
Set a timeout on blocking read/write operations. The
+ timeout argument can be a nonnegative float expressing
+ seconds, or None. If a float is given, subsequent channel
+ read/write operations will raise a timeout exception if the timeout
+ period value has elapsed before the operation has completed. Setting a
+ timeout of None disables timeouts on socket
+ operations.
+ chan.settimeout(0.0) is equivalent to
+ chan.setblocking(0); chan.settimeout(None) is
+ equivalent to chan.setblocking(1).
+
+
Parameters:
+
timeout -
+ seconds to wait for a pending read/write operation before
+ raising socket.timeout, or None for no
+ timeout.
+
+ (type=float)
+
+
+
+
+
+
+
+
shutdown(self,
+ how)
+
+ Shut down one or both halves of the connection. If how
+ is 0, further receives are disallowed. If how is 1,
+ further sends are disallowed. If how is 2, further sends
+ and receives are disallowed. This closes the stream in one or both
+ directions.
+
+
Parameters:
+
how -
+ 0 (stop receiving), 1 (stop sending), or 2 (stop receiving and
+ sending).
+
+ (type=int)
+
+
+
+
+
+
+
+
shutdown_read(self)
+
+ Shutdown the receiving side of this socket, closing the stream in
+ the incoming direction. After this call, future reads on this channel
+ will fail instantly. This is a convenience method, equivalent to
+ shutdown(0), for people who don't make it a habit to
+ memorize unix constants from the 1970s.
+
+
Since: 1.2
+
+
+
+
+
+
+
+
shutdown_write(self)
+
+ Shutdown the sending side of this socket, closing the stream in the
+ outgoing direction. After this call, future writes on this channel will
+ fail instantly. This is a convenience method, equivalent to
+ shutdown(1), for people who don't make it a habit to
+ memorize unix constants from the 1970s.
+
generate(bits,
+ progress_func)
+
+Generate a new private DSS key. (Static method)
+
+
int
+
+
get_bits(self)
+
+Return the number of significant bits in this key.
+
str
+
+
get_name(self)
+
+Return the name of this private key implementation.
+
+
sign_ssh_data(self,
+ rpool,
+ data)
+
+
boolean
+
+
verify_ssh_sig(self,
+ data,
+ msg)
+
+Given a blob of data, and an SSH message representing a signature of
+that data, verify that it was signed with this key.
+
+
write_private_key_file(self,
+ filename,
+ password)
+
+Write private key contents into a file.
+
+
Inherited from object
+
+
__delattr__(...)
+
+x.__delattr__('name') <==> del x.name
+ Create a new instance of this public key type. If msg
+ is given, the key's public part(s) will be filled in from the message.
+ If data is given, the key's public part(s) will be filled
+ in from the string.
+
+
Parameters:
+
msg -
+ an optional SSH Message containing a public key of
+ this type.
+
+ (type=Message)
+
data -
+ an optional string containing a public key of this type
+
+ (type=str)
+
+
+
Raises:
+
SSHException -
+ if a key cannot be created from the data or
+ msg given, or no key was passed in.
+
+ Return a string of an SSH Message made up of the public part(s) of
+ this key. This string is suitable for passing to __init__ to re-create the key object
+ later.
+
+
Returns:
+
+ string representation of an SSH key message.
+
+ (type=str)
+
An SSH2 Message is a stream of bytes that encodes some
+combination of strings, integers, bools, and infinite-precision integers
+(known in python as longs). This class builds or breaks down such
+a byte stream.
+Normally you don't need to deal with anything this low-level, but it's
+exposed for people implementing custom extensions, or features that
+paramiko doesn't support yet.
+
+
+
+
+
+
+
Method Summary
+
+
__init__(self,
+ content)
+
+Create a new SSH2 Message.
+
string
+
+
__repr__(self)
+
+Returns a string representation of this object, for debugging.
+
string
+
+
__str__(self)
+
+Return the byte stream content of this Message, as a string.
+
+
add(self,
+ *seq)
+
+Add a sequence of items to the stream.
+
+
add_boolean(self,
+ b)
+
+Add a boolean value to the stream.
+
+
add_byte(self,
+ b)
+
+Write a single byte to the stream, without any formatting.
+
+
add_bytes(self,
+ b)
+
+Write bytes to the stream, without any formatting.
+
+
add_int(self,
+ n)
+
+Add an integer to the stream.
+
+
add_int64(self,
+ n)
+
+Add a 64-bit int to the stream.
+
+
add_list(self,
+ l)
+
+Add a list of strings to the stream.
+
+
add_mpint(self,
+ z)
+
+Add a long int to the stream, encoded as an infinite-precision
+integer.
+
+
add_string(self,
+ s)
+
+Add a string to the stream.
+
bool
+
+
get_boolean(self)
+
+Fetch a boolean from the stream.
+
string
+
+
get_byte(self)
+
+Return the next byte of the Message, without decomposing it.
+
string
+
+
get_bytes(self,
+ n)
+
+Return the next n bytes of the Message, without
+decomposing into an int, string, etc.
+ Add a sequence of items to the stream. The values are encoded based
+ on their type: str, int, bool, list, or long.
+
+
Parameters:
+
seq -
+ the sequence of items
+
+ (type=sequence)
+
+
+
Bug: longs are encoded non-deterministically. Don't use this method.
+
+
+
+
+
+
+
+
add_boolean(self,
+ b)
+
+ Add a boolean value to the stream.
+
+
Parameters:
+
b -
+ boolean value to add
+
+ (type=bool)
+
+
+
+
+
+
+
+
add_byte(self,
+ b)
+
+ Write a single byte to the stream, without any formatting.
+
+
Parameters:
+
b -
+ byte to add
+
+ (type=str)
+
+
+
+
+
+
+
+
add_bytes(self,
+ b)
+
+ Write bytes to the stream, without any formatting.
+
+
Parameters:
+
b -
+ bytes to add
+
+ (type=str)
+
+
+
+
+
+
+
+
add_int(self,
+ n)
+
+ Add an integer to the stream.
+
+
Parameters:
+
n -
+ integer to add
+
+ (type=int)
+
+
+
+
+
+
+
+
add_int64(self,
+ n)
+
+ Add a 64-bit int to the stream.
+
+
Parameters:
+
n -
+ long int to add
+
+ (type=long)
+
+
+
+
+
+
+
+
add_list(self,
+ l)
+
+ Add a list of strings to the stream. They are encoded identically to
+ a single string of values separated by commas. (Yes, really, that's how
+ SSH2 does it.)
+
+
Parameters:
+
l -
+ list of strings to add
+
+ (type=list(str))
+
+
+
+
+
+
+
+
add_mpint(self,
+ z)
+
+ Add a long int to the stream, encoded as an infinite-precision
+ integer. This method only works on positive numbers.
+
+
Parameters:
+
z -
+ long int to add
+
+ (type=long)
+
+
+
+
+
+
+
+
add_string(self,
+ s)
+
+ Add a string to the stream.
+
+
Parameters:
+
s -
+ string to add
+
+ (type=str)
+
+
+
+
+
+
+
+
get_boolean(self)
+
+ Fetch a boolean from the stream.
+
+
Returns:
+
+ True or False (from the
+ Message).
+
+ (type=bool)
+
+
+
+
+
+
+
+
get_byte(self)
+
+ Return the next byte of the Message, without decomposing it. This is
+ equivalent to get_bytes(1).
+
+
Returns:
+
+ the next byte of the Message, or ' ' if there
+ aren't any bytes remaining.
+
+ (type=string)
+
+
+
+
+
+
+
+
get_bytes(self,
+ n)
+
+ Return the next n bytes of the Message, without
+ decomposing into an int, string, etc. Just the raw bytes are
+ returned.
+
+
Returns:
+
+ a string of the next n bytes of the Message, or a
+ string of n zero bytes, if there aren't
+ n bytes remaining.
+
+ (type=string)
+
+
+
+
+
+
+
+
get_int(self)
+
+ Fetch an int from the stream.
+
+
Returns:
+
+ a 32-bit unsigned integer.
+
+ (type=int)
+
+
+
+
+
+
+
+
get_int64(self)
+
+ Fetch a 64-bit int from the stream.
+
+
Returns:
+
+ a 64-bit unsigned integer.
+
+ (type=long)
+
+
+
+
+
+
+
+
get_list(self)
+
+ Fetch a list of strings from the stream. These are trivially encoded
+ as comma-separated values in a string.
+
+
Returns:
+
+ a list of strings.
+
+ (type=list of strings)
+
+
+
+
+
+
+
+
get_mpint(self)
+
+ Fetch a long int (mpint) from the stream.
+
+
Returns:
+
+ an arbitrary-length integer.
+
+ (type=long)
+
+
+
+
+
+
+
+
get_remainder(self)
+
+ Return the bytes of this Message that haven't already been parsed
+ and returned.
+
+
Returns:
+
+ a string of the bytes not parsed yet.
+
+ (type=string)
+
+
+
+
+
+
+
+
get_so_far(self)
+
+ Returns the bytes of this Message that have been parsed and
+ returned. The string passed into a Message's constructor can be
+ regenerated by concatenating get_so_far and get_remainder.
+
+
Returns:
+
+ a string of the bytes parsed so far.
+
+ (type=string)
+
+
+
+
+
+
+
+
get_string(self)
+
+ Fetch a string from the stream. This could be a byte string and may
+ contain unprintable characters. (It's not unheard of for a string to
+ contain another byte-stream Message.)
+
+
Returns:
+
+ a string.
+
+ (type=string)
+
+
+
+
+
+
+
+
rewind(self)
+
+ Rewind the message to the beginning as if no items had been parsed
+ out of it yet.
+
generate(bits,
+ progress_func)
+
+Generate a new private RSA key. (Static method)
+
+
int
+
+
get_bits(self)
+
+Return the number of significant bits in this key.
+
str
+
+
get_name(self)
+
+Return the name of this private key implementation.
+
+
sign_ssh_data(self,
+ rpool,
+ data)
+
+
boolean
+
+
verify_ssh_sig(self,
+ data,
+ msg)
+
+Given a blob of data, and an SSH message representing a signature of
+that data, verify that it was signed with this key.
+
+
write_private_key_file(self,
+ filename,
+ password)
+
+Write private key contents into a file.
+
+
Inherited from object
+
+
__delattr__(...)
+
+x.__delattr__('name') <==> del x.name
+ Create a new instance of this public key type. If msg
+ is given, the key's public part(s) will be filled in from the message.
+ If data is given, the key's public part(s) will be filled
+ in from the string.
+
+
Parameters:
+
msg -
+ an optional SSH Message containing a public key of
+ this type.
+
+ (type=Message)
+
data -
+ an optional string containing a public key of this type
+
+ (type=str)
+
+
+
Raises:
+
SSHException -
+ if a key cannot be created from the data or
+ msg given, or no key was passed in.
+
+ Return a string of an SSH Message made up of the public part(s) of
+ this key. This string is suitable for passing to __init__ to re-create the key object
+ later.
+
+
Returns:
+
+ string representation of an SSH key message.
+
+ (type=str)
+
+
+
+
+Representation of the attributes of a file (or proxied file) for SFTP
+in client or server mode. It attemps to mirror the object returned by
+os.stat as closely as possible, so it may have the following
+fields, with the same meanings as those returned by an
+os.stat object:
+
+
+ st_size
+
+
+ st_uid
+
+
+ st_gid
+
+
+ st_mode
+
+
+ st_atime
+
+
+ st_mtime
+
+
+Because SFTP allows flags to have other arbitrary named attributes,
+these are stored in a dict named attr. Occasionally, the
+filename is also stored, in filename.
+
+
+
+
+
+
+
Method Summary
+
+
__init__(self)
+
+Create a new (empty) SFTPAttributes object.
+
+
__repr__(self)
+
+
+
__str__(self)
+
+create a unix-style long description of the file (like ls -l)
+ Change the "current directory" of this SFTP session. Since
+ SFTP doesn't really have the concept of a current working directory,
+ this is emulated by paramiko. Once you use this method to set a working
+ directory, all operations on this SFTPClient object will be relative to
+ that path.
+
+
Parameters:
+
path -
+ new current working directory
+
+ (type=str)
+
+
+
Raises:
+
IOError -
+ if the requested path doesn't exist on the server
+
+
Since: 1.4
+
+
+
+
+
+
+
+
chmod(self,
+ path,
+ mode)
+
+ Change the mode (permissions) of a file. The permissions are
+ unix-style and identical to those used by python's
+ os.chmod function.
+
+
Parameters:
+
path -
+ path of the file to change the permissions of.
+
+ (type=string)
+
mode -
+ new permissions.
+
+ (type=int)
+
+
+
+
+
+
+
+
chown(self,
+ path,
+ uid,
+ gid)
+
+ Change the owner (uid) and group (gid) of
+ a file. As with python's os.chown function, you must pass
+ both arguments, so if you only want to change one, use stat first to retrieve the current owner
+ and group.
+
+
Parameters:
+
path -
+ path of the file to change the owner and group of.
+
+ (type=string)
+
uid -
+ new owner's uid
+
+ (type=int)
+
gid -
+ new group id
+
+ (type=int)
+
+
+
+
+
+
+
+
close(self)
+
+ Close the SFTP session and its underlying channel.
+
Open a file on the remote server. The arguments are the same as for
+ python's built-in file (aka open). A
+ file-like object is returned, which closely mimics the behavior of a
+ normal python file object.
+
The mode indicates how the file is to be opened: 'r'
+ for reading, 'w' for writing (truncating an existing
+ file), 'a' for appending, 'r+' for
+ reading/writing, 'w+' for reading/writing (truncating an
+ existing file), 'a+' for reading/appending. The python
+ 'b' flag is ignored, since SSH treats all files as binary.
+ The 'U' flag is supported in a compatible way.
+
Since 1.5.2, an 'x' flag indicates that the operation
+ should only succeed if the file was created and did not previously
+ exist. This has no direct mapping to python's file flags, but is
+ commonly known as the O_EXCL flag in posix.
+ The file will be buffered in standard python style by default, but
+ can be altered with the bufsize parameter. 0
+ turns off buffering, 1 uses line buffering, and any number
+ greater than 1 (>1) uses that specific buffer size.
+
+
Parameters:
+
filename -
+ name of the file to open.
+
+ (type=string)
+
mode -
+ mode (python-style) to open in.
+
+ (type=string)
+
+ a file object representing the open file.
+
+ (type=SFTPFile)
+
+
+
Raises:
+
IOError -
+ if the file could not be opened.
+
+
+
+
+
+
+
get(self,
+ remotepath,
+ localpath)
+
+ Copy a remote file (remotepath) from the SFTP server to
+ the local host as localpath. Any exception raised by
+ operations will be passed through. This method is primarily provided as
+ a convenience.
+
+
Parameters:
+
remotepath -
+ the remote file to copy
+
+ (type=str)
+
localpath -
+ the destination path on the local host
+
+ (type=str)
+
+
+
Since: 1.4
+
+
+
+
+
+
+
+
getcwd(self)
+
+ Return the "current working directory" for this SFTP
+ session, as emulated by paramiko. If no directory has been set with chdir, this method will return
+ None.
+
+
Returns:
+
+ the current working directory on the server, or
+ None
+
+ (type=str)
+
+
+
Since: 1.4
+
+
+
+
+
+
+
+
listdir(self,
+ path='.')
+
+ Return a list containing the names of the entries in the given
+ path. The list is in arbitrary order. It does not include
+ the special entries '.' and '..' even if they
+ are present in the folder. This method is meant to mirror
+ os.listdir as closely as possible. For a list of full SFTPAttributes objects, see listdir_attr.
+
+
Parameters:
+
path -
+ path to list (defaults to '.')
+
+ (type=str)
+
+
+
Returns:
+
+ list of filenames
+
+ (type=list of str)
+
+
+
+
+
+
+
+
listdir_attr(self,
+ path='.')
+
+ Return a list containing SFTPAttributes objects corresponding to
+ files in the given path. The list is in arbitrary order.
+ It does not include the special entries '.' and
+ '..' even if they are present in the folder.
+
+
Parameters:
+
path -
+ path to list (defaults to '.')
+
+ (type=str)
+
+
+
Returns:
+
+ list of attributes
+
+ (type=list of SFTPAttributes)
+
+
+
Since: 1.2
+
+
+
+
+
+
+
+
lstat(self,
+ path)
+
+ Retrieve information about a file on the remote system, without
+ following symbolic links (shortcuts). This otherwise behaves exactly
+ the same as stat.
+
+
Parameters:
+
path -
+ the filename to stat.
+
+ (type=string)
+
+
+
Returns:
+
+ an object containing attributes about the given file.
+
+ (type=SFTPAttributes)
+
+
+
+
+
+
+
+
mkdir(self,
+ path,
+ mode=511)
+
+ Create a folder (directory) named path with numeric
+ mode mode. The default mode is 0777 (octal). On some
+ systems, mode is ignored. Where it is used, the current umask value is
+ first masked out.
+
+
Parameters:
+
path -
+ name of the folder to create.
+
+ (type=string)
+
mode -
+ permissions (posix-style) for the newly-created folder.
+
+ (type=int)
+
+
+
+
+
+
+
+
normalize(self,
+ path)
+
+ Return the normalized path (on the server) of a given path. This can
+ be used to quickly resolve symbolic links or determine what the server
+ is considering to be the "current folder" (by passing
+ '.' as path).
+
+
Parameters:
+
path -
+ path to be normalized.
+
+ (type=str)
+
+
+
Returns:
+
+ normalized form of the given path.
+
+ (type=str)
+
+
+
Raises:
+
IOError -
+ if the path can't be resolved on the server
+
Open a file on the remote server. The arguments are the same as for
+ python's built-in file (aka open). A
+ file-like object is returned, which closely mimics the behavior of a
+ normal python file object.
+
The mode indicates how the file is to be opened: 'r'
+ for reading, 'w' for writing (truncating an existing
+ file), 'a' for appending, 'r+' for
+ reading/writing, 'w+' for reading/writing (truncating an
+ existing file), 'a+' for reading/appending. The python
+ 'b' flag is ignored, since SSH treats all files as binary.
+ The 'U' flag is supported in a compatible way.
+
Since 1.5.2, an 'x' flag indicates that the operation
+ should only succeed if the file was created and did not previously
+ exist. This has no direct mapping to python's file flags, but is
+ commonly known as the O_EXCL flag in posix.
+ The file will be buffered in standard python style by default, but
+ can be altered with the bufsize parameter. 0
+ turns off buffering, 1 uses line buffering, and any number
+ greater than 1 (>1) uses that specific buffer size.
+
+
Parameters:
+
filename -
+ name of the file to open.
+
+ (type=string)
+
mode -
+ mode (python-style) to open in.
+
+ (type=string)
+
+ a file object representing the open file.
+
+ (type=SFTPFile)
+
+
+
Raises:
+
IOError -
+ if the file could not be opened.
+
+
+
+
+
+
+
put(self,
+ localpath,
+ remotepath)
+
+
Copy a local file (localpath) to the SFTP server as
+ remotepath. Any exception raised by operations will be
+ passed through. This method is primarily provided as a convenience.
+ The SFTP operations use pipelining for speed.
+
+
Parameters:
+
localpath -
+ the local file to copy
+
+ (type=str)
+
remotepath -
+ the destination path on the SFTP server
+
+ (type=str)
+
+
+
Since: 1.4
+
+
+
+
+
+
+
+
readlink(self,
+ path)
+
+ Return the target of a symbolic link (shortcut). You can use symlink to create these. The result may
+ be either an absolute or relative pathname.
+
+
Parameters:
+
path -
+ path of the symbolic link file.
+
+ (type=str)
+
+
+
Returns:
+
+ target path.
+
+ (type=str)
+
+
+
+
+
+
+
+
remove(self,
+ path)
+
+ Remove the file at the given path.
+
+
Parameters:
+
path -
+ path (absolute or relative) of the file to remove.
+
+ (type=string)
+
+
+
Raises:
+
IOError -
+ if the path refers to a folder (directory). Use rmdir to remove a folder.
+
+
+
+
+
+
+
rename(self,
+ oldpath,
+ newpath)
+
+ Rename a file or folder from oldpath to
+ newpath.
+
+
Parameters:
+
oldpath -
+ existing name of the file or folder.
+
+ (type=string)
+
newpath -
+ new name for the file or folder.
+
+ (type=string)
+
+
+
Raises:
+
IOError -
+ if newpath is a folder, or something else goes
+ wrong.
+
+
+
+
+
+
+
rmdir(self,
+ path)
+
+ Remove the folder named path.
+
+
Parameters:
+
path -
+ name of the folder to remove.
+
+ (type=string)
+
+
+
+
+
+
+
+
stat(self,
+ path)
+
+
Retrieve information about a file on the remote system. The return
+ value is an object whose attributes correspond to the attributes of
+ python's stat structure as returned by
+ os.stat, except that it contains fewer fields. An SFTP
+ server may return as much or as little info as it wants, so the results
+ may vary from server to server.
+
Unlike a python stat object, the result may not be
+ accessed as a tuple. This is mostly due to the author's slack
+ factor.
+ The fields supported are: st_mode,
+ st_size, st_uid, st_gid,
+ st_atime, and st_mtime.
+
+
Parameters:
+
path -
+ the filename to stat.
+
+ (type=string)
+
+
+
Returns:
+
+ an object containing attributes about the given file.
+
+ (type=SFTPAttributes)
+
+
+
+
+
+
+
+
symlink(self,
+ source,
+ dest)
+
+ Create a symbolic link (shortcut) of the source path at
+ destination.
+
+
Parameters:
+
source -
+ path of the original file.
+
+ (type=string)
+
dest -
+ path of the newly created symlink.
+
+ (type=string)
+
+
+
+
+
+
+
+
unlink(self,
+ path)
+
+ Remove the file at the given path.
+
+
Parameters:
+
path -
+ path (absolute or relative) of the file to remove.
+
+ (type=string)
+
+
+
Raises:
+
IOError -
+ if the path refers to a folder (directory). Use rmdir to remove a folder.
+
+
+
+
+
+
+
utime(self,
+ path,
+ times)
+
+ Set the access and modified times of the file specified by
+ path. If times is None, then the
+ file's access and modified times are set to the current time.
+ Otherwise, times must be a 2-tuple of numbers, of the form
+ (atime, mtime), which is used to set the access and
+ modified times, respectively. This bizarre API is mimicked from python
+ for the sake of consistency -- I apologize.
+
+
Parameters:
+
path -
+ path of the file to modify.
+
+ (type=string)
+
times -
+ None or a tuple of (access time, modified time)
+ in standard internet epoch time (seconds since 01 January 1970
+ GMT).
+
+ (type=tuple of int)
+
+
+
+
+
+
+
+
+
+
+
Class Method Details
+
+
+
+
+
from_transport(selfclass,
+ t)
+
+ Create an SFTP client channel from an open Transport.
+
+
Parameters:
+
t -
+ an open Transport which is already
+ authenticated.
+
+ (type=Transport)
+
+
+
Returns:
+
+ a new SFTPClient object, referring to an
+ sftp session (channel) across the transport.
+
+ (type=SFTPClient)
+
Ask the server for a hash of a section of this file. This can be
+ used to verify a successful upload or download, or for various
+ rsync-like operations.
+
The file is hashed from offset, for length
+ bytes. If length is 0, the remainder of the file is
+ hashed. Thus, if both offset and length are
+ zero, the entire file is hashed.
+
Normally, block_size will be 0 (the default), and this
+ method will return a byte string representing the requested hash (for
+ example, a string of length 16 for MD5, or 20 for SHA-1). If a non-zero
+ block_size is given, each chunk of the file (from
+ offset to offset + length) of
+ block_size bytes is computed as a separate hash. The hash
+ results are all concatenated and returned as a single string.
+ For example, check('sha1', 0, 1024, 512) will return a
+ string of length 40. The first 20 bytes will be the SHA-1 of the first
+ 512 bytes of the file, and the last 20 bytes will be the SHA-1 of the
+ next 512 bytes.
+
+
Parameters:
+
hash_algorithm -
+ the name of the hash algorithm to use (normally
+ "sha1" or
+ "md5")
+
+ (type=str)
+
offset -
+ offset into the file to begin hashing (0 means to start from
+ the beginning)
+
+ (type=int or long)
+
length -
+ number of bytes to hash (0 means continue to the end of the
+ file)
+
+ (type=int or long)
+
block_size -
+ number of bytes to hash per result (must not be less than 256;
+ 0 means to compute only one hash of the entire segment)
+
+ (type=int)
+
+
+
Returns:
+
+ string of bytes representing the hash of each block,
+ concatenated together
+
+ (type=str)
+
+
+
Raises:
+
IOError -
+ if the server doesn't support the "check-file"
+ extension, or possibly doesn't support the hash algorithm
+ requested
+
+
Note: Many (most?) servers don't support this extension yet.
+
+
+
Since: 1.4
+
+
+
+
+
+
+
+
close(self,
+ _async=False)
+
+ Close the file. Future read and write operations will fail.
+
+ Pre-fetch the remaining contents of this file in anticipation of
+ future read calls. If reading the entire file,
+ pre-fetching can dramatically improve the download speed by avoiding
+ roundtrip latency. The file's contents are incrementally buffered in a
+ background thread.
+
+
Since: 1.5.1
+
+
+
+
+
+
+
+
seek(self,
+ offset,
+ whence=0)
+
+ Set the file's current position, like stdio's fseek.
+ Not all file objects support seeking.
+
+
Parameters:
+
offset -
+ position to move to within the file, relative to
+ whence.
+
+ (type=int)
+
whence -
+ type of movement: 0 = absolute; 1 = relative to the current
+ position; 2 = relative to the end of the file.
+
+ (type=int)
+
+
+
Raises:
+
IOError -
+ if the file doesn't support random access.
+
Note: If a file is opened in append mode ('a' or
+'a+'), any seek operations will be undone at the next write
+(as the file position will move back to the end of the file).
+
+
+
+
+
+
+
+
set_pipelined(self,
+ pipelined=True)
+
+
Turn on/off the pipelining of write operations to this file. When
+ pipelining is on, paramiko won't wait for the server response after
+ each write operation. Instead, they're collected as they come in. At
+ the first non-write operation (including close), all remaining server responses
+ are collected. This means that if there was an error with one of your
+ later writes, an exception might be thrown from within close instead of write.
+ By default, files are not pipelined.
+
+
Parameters:
+
pipelined -
+ True if pipelining should be turned on for this
+ file; False otherwise
+
+ (type=bool)
+
+
+
Since: 1.5
+
+
+
+
+
+
+
+
setblocking(self,
+ blocking)
+
+ Set blocking or non-blocking mode on the underiying socket or ssh Channel.
+
+
Parameters:
+
blocking -
+ 0 to set non-blocking mode; non-0 to set blocking mode.
+
+ (type=int)
+
Abstract object representing a handle to an open file (or folder) in
+an SFTP server implementation. Each handle has a string representation
+used by the client to refer to the underlying file.
+Server implementations can (and should) subclass SFTPHandle to
+implement features of a file handle, like stat or chattr.
+
+
+
+
+
+
+
Method Summary
+
+
__init__(self)
+
+
int
+
+
chattr(self,
+ attr)
+
+Change the attributes of this file.
+
+
close(self)
+
+When a client closes a file, this method is called on the handle.
+
str
+
+
read(self,
+ offset,
+ length)
+
+Read up to length bytes from this file, starting at
+position offset.
+ Change the attributes of this file. The attr object
+ will contain only those fields provided by the client in its request,
+ so you should check for the presence of fields before using them.
+
+
Parameters:
+
attr -
+ the attributes to change on this file.
+
+ (type=SFTPAttributes)
+
When a client closes a file, this method is called on the handle.
+ Normally you would use this method to close the underlying OS level
+ file object(s).
+ The default implementation checks for attributes on
+ self named readfile and/or
+ writefile, and if either or both are present, their
+ close() methods are called. This means that if you are
+ using the default implementations of read and write, this method's default
+ implementation should be fine also.
+
+
+
+
+
+
+
read(self,
+ offset,
+ length)
+
+
Read up to length bytes from this file, starting at
+ position offset. The offset may be a python long, since
+ SFTP allows it to be 64 bits.
+
If the end of the file has been reached, this method may return an
+ empty string to signify EOF, or it may also return SFTP_EOF.
+ The default implementation checks for an attribute on
+ self named readfile, and if present, performs
+ the read operation on the python file-like object found there. (This is
+ meant as a time saver for the common case where you are wrapping a
+ python file object.)
+
+
Parameters:
+
offset -
+ position in the file to start reading from.
+
+ (type=int or long)
+
length -
+ number of bytes to attempt to read.
+
+ (type=int)
+
+
+
Returns:
+
+ data read from the file, or an SFTP error code.
+
+ (type=str)
+
+
+
+
+
+
+
+
stat(self)
+
+ Return an SFTPAttributes object referring to this
+ open file, or an error code. This is equivalent to SFTPServerInterface.stat, except it's
+ called on an open file instead of a path.
+
Write data into this file at position
+ offset. Extending the file past its original end is
+ expected. Unlike python's normal write() methods, this
+ method cannot do a partial write: it must write all of
+ data or else return an error.
+ The default implementation checks for an attribute on
+ self named writefile, and if present,
+ performs the write operation on the python file-like object found
+ there. The attribute is named differently from readfile to
+ make it easy to implement read-only (or write-only) files, but if both
+ attributes are present, they should refer to the same file.
+
+
Parameters:
+
offset -
+ position in the file to start reading from.
+
+ (type=int or long)
+
data -
+ data to write into the file.
+
+ (type=str)
+
+
+
+
+Server-side SFTP subsystem support. Since this is a SubsystemHandler, it can be (and is meant
+to be) set as the handler for "sftp" requests. Use
+Transport.set_subsystem_handler to activate
+this class.
+
+
+
+
+
+
+
Method Summary
+
+
__init__(self,
+ channel,
+ name,
+ server,
+ sftp_si,
+ *largs,
+ **kwargs)
+
+The constructor for SFTPServer is meant to be called from within the
+Transport as a subsystem handler.
+
int
+
+
convert_errno(e)
+
+Convert an errno value (as from an OSError or
+IOError) into a standard SFTP result code. (Static method)
+
+
+
finish_subsystem(self)
+
+Perform any cleanup at the end of a subsystem.
+
+
set_file_attr(filename,
+ attr)
+
+Change a file's attributes on the local filesystem. (Static method)
+
+
+
start_subsystem(self,
+ name,
+ transport,
+ channel)
+
+Process an ssh subsystem in server mode.
+ The constructor for SFTPServer is meant to be called from within the
+ Transport as a subsystem handler.
+ server and any additional parameters or keyword parameters
+ are passed from the original call to Transport.set_subsystem_handler.
+
+
Parameters:
+
channel -
+ channel passed from the Transport.
+
+ (type=Channel)
+
name -
+ name of the requested subsystem.
+
+ (type=str)
+
server -
+ the server object associated with this channel and
+ subsystem
+
+ (type=ServerInterface)
+
sftp_si -
+ a subclass of SFTPServerInterface to use for
+ handling individual requests.
+
+ (type=class)
+
Process an ssh subsystem in server mode. This method is called on a
+ new object (and in a new thread) for each subsystem request. It is
+ assumed that all subsystem logic will take place here, and when the
+ subsystem is finished, this method will return. After this method
+ returns, the channel is closed.
+ The combination of transport and channel
+ are unique; this handler corresponds to exactly one Channel on one Transport.
+
+
Parameters:
+
name -
+ name of the requested subsystem.
+
+ (type=str)
+
Note: It is the responsibility of this method to exit if the underlying Transport is closed. This can be done by
+checking Transport.is_active or noticing an EOF on
+the Channel. If this method loops forever
+without checking for this case, your python interpreter may refuse to
+exit because this thread will still be running.
+
+
+
+
+
+
+
+
+
+
+
Static Method Details
+
+
+
+
+
convert_errno(e)
+
+ Convert an errno value (as from an OSError or
+ IOError) into a standard SFTP result code. This is a
+ convenience function for trapping exceptions in server code and
+ returning an appropriate result.
+
+
Parameters:
+
e -
+ an errno code, as from OSError.errno.
+
+ (type=int)
+
Change a file's attributes on the local filesystem. The contents of
+ attr are used to change the permissions, owner, group
+ ownership, and/or modification & access time of the file, depending
+ on which attributes are present in attr.
+ This is meant to be a handy helper function for translating SFTP
+ file requests into local file operations.
+
+
Parameters:
+
filename -
+ name of the file to alter (should usually be an absolute
+ path).
+
+ (type=str)
+
attr -
+ attributes to change.
+
+ (type=SFTPAttributes)
+
Simple object containing the security preferences of an ssh transport.
+These are tuples of acceptable ciphers, digests, key types, and key
+exchange algorithms, listed in order of preference.
+Changing the contents and/or order of these fields affects the
+underlying Transport (but only if you change them
+before starting the session). If you try to add an algorithm that
+paramiko doesn't recognize, ValueError will be raised. If
+you try to assign something besides a tuple to one of the fields,
+TypeError will be raised.
+
+
+
Since: ivysaur
+
+
+
+
+
+
+
Method Summary
+
+
__init__(self,
+ transport)
+
+
str
+
+
__repr__(self)
+
+Returns a string representation of this object, for debugging.
+
+
Inherited from object
+
+
__delattr__(...)
+
+x.__delattr__('name') <==> del x.name
Handler for a subsytem in server mode. If you create a subclass of
+this class and pass it to Transport.set_subsystem_handler, an object
+of this class will be created for each request for this subsystem. Each
+new object will be executed within its own new thread by calling start_subsystem. When that method
+completes, the channel is closed.
+For example, if you made a subclass MP3Handler and
+registered it as the handler for subsystem "mp3",
+then whenever a client has successfully authenticated and requests
+subsytem "mp3", an object of class
+MP3Handler will be created, and start_subsystem will be called on it from a
+new thread.
+
+
+
Since: ivysaur
+
+
+
+
+
+
+
Method Summary
+
+
__init__(self,
+ channel,
+ name,
+ server)
+
+Create a new handler for a channel.
+
+
finish_subsystem(self)
+
+Perform any cleanup at the end of a subsystem.
+ Create a new handler for a channel. This is used by ServerInterface to start up a new handler
+ when a channel requests this subsystem. You don't need to override this
+ method, but if you do, be sure to pass the channel and
+ name parameters through to the original
+ __init__ method here.
+
+
Parameters:
+
channel -
+ the channel associated with this subsystem request.
+
+ (type=Channel)
+
name -
+ name of the requested subsystem.
+
+ (type=str)
+
server -
+ the server object for the session that started this
+ subsystem
+
+ (type=ServerInterface)
+
Process an ssh subsystem in server mode. This method is called on a
+ new object (and in a new thread) for each subsystem request. It is
+ assumed that all subsystem logic will take place here, and when the
+ subsystem is finished, this method will return. After this method
+ returns, the channel is closed.
+ The combination of transport and channel
+ are unique; this handler corresponds to exactly one Channel on one Transport.
+
+
Parameters:
+
name -
+ name of the requested subsystem.
+
+ (type=str)
+
channel -
+ the channel associated with this subsystem request.
+
+ (type=Channel)
+
+
+
Note: It is the responsibility of this method to exit if the underlying Transport is closed. This can be done by
+checking Transport.is_active or noticing an EOF on
+the Channel. If this method loops forever
+without checking for this case, your python interpreter may refuse to
+exit because this thread will still be running.
+
+
+
+
+An SSH Transport attaches to a stream (usually a socket), negotiates
+an encrypted session, authenticates, and then creates stream tunnels,
+called Channels, across the session. Multiple
+channels can be multiplexed across a single session (and often are, in
+the case of port forwardings).
+
+
+
+
+
+
+
Method Summary
+
+
__init__(self,
+ sock)
+
+Create a new SSH session over an existing socket, or socket-like
+object.
+
+
__del__(self)
+
+
str
+
+
__repr__(self)
+
+Returns a string representation of this object, for debugging.
accept(self,
+ timeout)
+
+Return the next channel opened by the client over this transport, in
+server mode.
+
+
add_server_key(self,
+ key)
+
+Add a host key to the list of keys used for server mode.
+
list
+
+
auth_interactive(self,
+ username,
+ handler,
+ submethods)
+
+Authenticate to the server interactively.
+
list
+
+
auth_none(self,
+ username)
+
+Try to authenticate to the server using no authentication at all.
+
list
+
+
auth_password(self,
+ username,
+ password,
+ event,
+ fallback)
+
+Authenticate to the server using a password.
+
list
+
+
auth_publickey(self,
+ username,
+ key,
+ event)
+
+Authenticate to the server using a private key.
+
+
close(self)
+
+Close this session, and any open channels that are tied to it.
+
+
connect(self,
+ hostkey,
+ username,
+ password,
+ pkey)
+
+Negotiate an SSH2 session, and optionally verify the server's host key
+and authenticate using a password or private key.
+
Exception
+
+
get_exception(self)
+
+Return any exception that happened during the last server request.
+
bool
+
+
get_hexdump(self)
+
+Return True if the transport is currently logging hex
+dumps of protocol traffic.
+
str
+
+
get_log_channel(self)
+
+Return the channel name used for this transport's logging.
get_security_options(self)
+
+Return a SecurityOptions object which can be used to
+tweak the encryption algorithms this transport will permit, and the order
+of preference for them.
global_request(self,
+ kind,
+ data,
+ wait)
+
+Make a global request to the remote host.
+
bool
+
+
is_active(self)
+
+Return true if this session is active (open).
+
bool
+
+
is_authenticated(self)
+
+Return true if this session is active and authenticated.
+
bool
+
+
load_server_moduli(filename)
+
+(optional) Load a file of prime moduli for use in doing
+group-exchange key negotiation in server mode. (Static method)
+
Create a new SSH session over an existing socket, or socket-like
+ object. This only creates the Transport object; it doesn't begin the
+ SSH session yet. Use connect or start_client to begin a client session,
+ or start_server to begin a server
+ session.
+ If the object is not actually a socket, it must have the following
+ methods:
+
+
+ send(str): Writes from 1 to len(str)
+ bytes, and returns an int representing the number of bytes written.
+ Returns 0 or raises EOFError if the stream has been
+ closed.
+
+
+ recv(int): Reads from 1 to int bytes
+ and returns them as a string. Returns 0 or raises
+ EOFError if the stream has been closed.
+
+
+ close(): Closes the socket.
+
+
+ settimeout(n): Sets a (float) timeout on I/O
+ operations.
+
+
+ For ease of use, you may also pass in an address (as a tuple) or a
+ host string as the sock argument. (A host string is a
+ hostname with an optional port (separated by
+ ":") which will be converted into a tuple of
+ (hostname, port).) A socket will be connected to this
+ address and used for communication. Exceptions from the
+ socket call may be thrown in this case.
+
+
Parameters:
+
sock -
+ a socket or socket-like object to create the session over.
+
+ (type=socket)
+
+ Return the next channel opened by the client over this transport, in
+ server mode. If no channel is opened before the given timeout,
+ None is returned.
+
+
Parameters:
+
timeout -
+ seconds to wait for a channel, or None to wait
+ forever
+
+ (type=int)
+
+
+
Returns:
+
+ a new Channel opened by the client
+
+ (type=Channel)
+
+
+
+
+
+
+
+
add_server_key(self,
+ key)
+
+ Add a host key to the list of keys used for server mode. When
+ behaving as a server, the host key is used to sign certain packets
+ during the SSH2 negotiation, so that the client can trust that we are
+ who we say we are. Because this is used for signing, the key must
+ contain private key info, not just the public half. Only one key of
+ each type (RSA or DSS) is kept.
+
+
Parameters:
+
key -
+ the host key to add, usually an RSAKey or DSSKey.
+
+ (type=PKey)
+
Authenticate to the server interactively. A handler is used to
+ answer arbitrary questions from the server. On many servers, this is
+ just a dumb wrapper around PAM.
+
This method will block until the authentication succeeds or fails,
+ peroidically calling the handler asynchronously to get answers to
+ authentication questions. The handler may be called more than once if
+ the server continues to ask questions.
+
The handler is expected to be a callable that will handle calls of
+ the form: handler(title, instructions, prompt_list). The
+ title is meant to be a dialog-window title, and the
+ instructions are user instructions (both are strings).
+ prompt_list will be a list of prompts, each prompt being a
+ tuple of (str, bool). The string is the prompt and the
+ boolean indicates whether the user text should be echoed.
+
A sample call would thus be: handler('title', 'instructions',
+ [('Password:', False)]).
+
The handler should return a list or tuple of answers to the server's
+ questions.
+ If the server requires multi-step authentication (which is very
+ rare), this method will return a list of auth types permissible for the
+ next step. Otherwise, in the normal case, an empty list is
+ returned.
+
+
Parameters:
+
username -
+ the username to authenticate as
+
+ (type=string)
+
handler -
+ a handler for responding to server questions
+
+ (type=callable)
+
submethods -
+ a string list of desired submethods (optional)
+
+ (type=str)
+
+
+
Returns:
+
+ list of auth types permissible for the next stage of
+ authentication (normally empty).
+
+ (type=list)
+
+
+
Raises:
+
BadAuthenticationType -
+ if public-key authentication isn't allowed by the server for
+ this user
+
SSHException -
+ if the authentication failed
+
+
Since: 1.5
+
+
+
+
+
+
+
+
auth_none(self,
+ username)
+
+ Try to authenticate to the server using no authentication at all.
+ This will almost always fail. It may be useful for determining the list
+ of authentication types supported by the server, by catching the BadAuthenticationType exception
+ raised.
+
+
Parameters:
+
username -
+ the username to authenticate as
+
+ (type=string)
+
+
+
Returns:
+
+ list of auth types permissible for the next stage of
+ authentication (normally empty)
+
+ (type=list)
+
+
+
Raises:
+
BadAuthenticationType -
+ if "none" authentication isn't allowed by the server
+ for this user
+
SSHException -
+ if the authentication failed due to a network error
+
Authenticate to the server using a password. The username and
+ password are sent over an encrypted link.
+
If an event is passed in, this method will return
+ immediately, and the event will be triggered once authentication
+ succeeds or fails. On success, is_authenticated will return
+ True. On failure, you may use get_exception to get more detailed error
+ information.
+
Since 1.1, if no event is passed, this method will block until the
+ authentication succeeds or fails. On failure, an exception is raised.
+ Otherwise, the method simply returns.
+
Since 1.5, if no event is passed and fallback is
+ True (the default), if the server doesn't support plain
+ password authentication but does support so-called
+ "keyboard-interactive" mode, an attempt will be made to
+ authenticate using this interactive mode. If it fails, the normal
+ exception will be thrown as if the attempt had never been made. This is
+ useful for some recent Gentoo and Debian distributions, which turn off
+ plain password authentication in a misguided belief that interactive
+ authentication is "more secure". (It's not.)
+ If the server requires multi-step authentication (which is very
+ rare), this method will return a list of auth types permissible for the
+ next step. Otherwise, in the normal case, an empty list is
+ returned.
+
+
Parameters:
+
username -
+ the username to authenticate as
+
+ (type=string)
+
password -
+ the password to authenticate with
+
+ (type=string)
+
event -
+ an event to trigger when the authentication attempt is
+ complete (whether it was successful or not)
+
+ (type=threading.Event)
+
fallback -
+ True if an attempt at an automated
+ "interactive" password auth should be made if the
+ server doesn't support normal password auth
+
+ (type=bool)
+
+
+
Returns:
+
+ list of auth types permissible for the next stage of
+ authentication (normally empty)
+
+ (type=list)
+
+
+
Raises:
+
BadAuthenticationType -
+ if password authentication isn't allowed by the server for
+ this user (and no event was passed in)
+
SSHException -
+ if the authentication failed (and no event was passed in)
+
Authenticate to the server using a private key. The key is used to
+ sign data from the server, so it must include the private part.
+
If an event is passed in, this method will return
+ immediately, and the event will be triggered once authentication
+ succeeds or fails. On success, is_authenticated will return
+ True. On failure, you may use get_exception to get more detailed error
+ information.
+
Since 1.1, if no event is passed, this method will block until the
+ authentication succeeds or fails. On failure, an exception is raised.
+ Otherwise, the method simply returns.
+ If the server requires multi-step authentication (which is very
+ rare), this method will return a list of auth types permissible for the
+ next step. Otherwise, in the normal case, an empty list is
+ returned.
+
+
Parameters:
+
username -
+ the username to authenticate as
+
+ (type=string)
+
key -
+ the private key to authenticate with
+
+ (type=PKey)
+
event -
+ an event to trigger when the authentication attempt is
+ complete (whether it was successful or not)
+
+ (type=threading.Event)
+
+
+
Returns:
+
+ list of auth types permissible for the next stage of
+ authentication (normally empty).
+
+ (type=list)
+
+
+
Raises:
+
BadAuthenticationType -
+ if public-key authentication isn't allowed by the server for
+ this user (and no event was passed in).
+
SSHException -
+ if the authentication failed (and no event was passed in).
+
+
+
+
+
+
+
close(self)
+
+ Close this session, and any open channels that are tied to it.
+
+ You can use this method immediately after creating a Transport to
+ negotiate encryption with a server. If it fails, an exception will be
+ thrown. On success, the method will return cleanly, and an encrypted
+ session exists. You may immediately call open_channel or open_session to get a Channel object, which is used for data
+ transfer.
+
+
Parameters:
+
hostkey -
+ the host key expected from the server, or None if
+ you don't want to do host key verification.
+
+ (type=PKey)
+
username -
+ the username to authenticate as.
+
+ (type=str)
+
password -
+ a password to use for authentication, if you want to use
+ password authentication; otherwise None.
+
+ (type=str)
+
pkey -
+ a private key to use for authentication, if you want to use
+ private key authentication; otherwise None.
+
+ (type=PKey)
+
+
+
Raises:
+
SSHException -
+ if the SSH2 negotiation fails, the host key supplied by the
+ server is incorrect, or authentication fails.
+
+
Note: If you fail to supply a password or private key, this method may
+succeed, but a subsequent open_channel or open_session call may fail because you
+haven't authenticated yet.
+
+
+
Since: doduo
+
+
+
+
+
+
+
+
get_exception(self)
+
+ Return any exception that happened during the last server request.
+ This can be used to fetch more specific error information after using
+ calls like start_client. The exception (if any) is
+ cleared after this call.
+
+
Returns:
+
+ an exception, or None if there is no stored
+ exception.
+
+ (type=Exception)
+
+
+
Since: 1.1
+
+
+
+
+
+
+
+
get_hexdump(self)
+
+ Return True if the transport is currently logging hex
+ dumps of protocol traffic.
+
+
Returns:
+
+ True if hex dumps are being logged
+
+ (type=bool)
+
+
+
Since: 1.4
+
+
+
+
+
+
+
+
get_log_channel(self)
+
+ Return the channel name used for this transport's logging.
+
+
Returns:
+
+ channel name.
+
+ (type=str)
+
+
+
Since: 1.2
+
+
+
+
+
+
+
+
get_remote_server_key(self)
+
+ Return the host key of the server (in client mode).
+
+
Returns:
+
+ public key of the remote server.
+
+ (type=PKey)
+
+
+
Raises:
+
SSHException -
+ if no session is currently active.
+
+
Note: Previously this call returned a tuple of (key type, key string). You
+can get the same effect by calling PKey.get_name for the key type, and
+str(key) for the key string.
+
+
+
+
+
+
+
+
get_security_options(self)
+
+ Return a SecurityOptions object which can be used
+ to tweak the encryption algorithms this transport will permit, and the
+ order of preference for them.
+
+
Returns:
+
+ an object that can be used to change the preferred algorithms
+ for encryption, digest (hash), public key, and key exchange.
+
+ (type=SecurityOptions)
+
+
+
Since: ivysaur
+
+
+
+
+
+
+
+
get_server_key(self)
+
+ Return the active host key, in server mode. After negotiating with
+ the client, this method will return the negotiated host key. If only
+ one type of host key was set with add_server_key, that's the only key that
+ will ever be returned. But in cases where you have set more than one
+ type of host key (for example, an RSA key and a DSS key), the key type
+ will be negotiated by the client, and this method will return the key
+ of the type agreed on. If the host key has not been negotiated yet,
+ None is returned. In client mode, the behavior is
+ undefined.
+
+
Returns:
+
+ host key of the type negotiated by the client, or
+ None.
+
+ (type=PKey)
+
+
+
+
+
+
+
+
get_username(self)
+
+ Return the username this connection is authenticated for. If the
+ session is not authenticated (or authentication failed), this method
+ returns None.
+
+
Returns:
+
+ username that was authenticated, or None.
+
+ (type=string)
+
+ Make a global request to the remote host. These are normally
+ extensions to the SSH2 protocol.
+
+
Parameters:
+
kind -
+ name of the request.
+
+ (type=str)
+
data -
+ an optional tuple containing additional data to attach to the
+ request.
+
+ (type=tuple)
+
wait -
+ True if this method should not return until a
+ response is received; False otherwise.
+
+ (type=bool)
+
+
+
Returns:
+
+ a Message containing possible
+ additional data if the request was successful (or an empty Message if wait was
+ False); None if the request was
+ denied.
+
+ (type=Message)
+
+
+
Since: fearow
+
+
+
+
+
+
+
+
is_active(self)
+
+ Return true if this session is active (open).
+
+
Returns:
+
+ True if the session is still active (open); False if the
+ session is closed.
+
+ (type=bool)
+
+
+
+
+
+
+
+
is_authenticated(self)
+
+ Return true if this session is active and authenticated.
+
+
Returns:
+
+ True if the session is still open and has been authenticated
+ successfully; False if authentication failed and/or the session
+ is closed.
+
+ (type=bool)
+
+ Request a new channel to the server. Channels are socket-like objects used for
+ the actual transfer of data across the session. You may only request a
+ channel after negotiating encryption (using connect or start_client) and authenticating.
+
+
Parameters:
+
kind -
+ the kind of channel requested (usually
+ "session",
+ "forwarded-tcpip" or
+ "direct-tcpip").
+
+ (type=str)
+
dest_addr -
+ the destination address of this port forwarding, if
+ kind is "forwarded-tcpip" or
+ "direct-tcpip" (ignored for other channel
+ types).
+
+ (type=(str, int))
+
src_addr -
+ the source address of this port forwarding, if
+ kind is "forwarded-tcpip" or
+ "direct-tcpip".
+
+ (type=(str, int))
+
+
+
Returns:
+
+ a new Channel on success, or
+ None if the request is rejected or the session ends
+ prematurely.
+
+ (type=Channel)
+
+
+
+
+
+
+
+
open_session(self)
+
+ Request a new channel to the server, of type
+ "session". This is just an alias for
+ open_channel('session').
+
+
Returns:
+
+ a new Channel on success, or
+ None if the request is rejected or the session ends
+ prematurely.
+
+ (type=Channel)
+
+
+
+
+
+
+
+
open_sftp_client(self)
+
+ Create an SFTP client channel from an open transport. On success, an
+ SFTP session will be opened with the remote host, and a new SFTPClient
+ object will be returned.
+
+
Returns:
+
+ a new SFTPClient object, referring to an
+ sftp session (channel) across this transport
+
+ (type=SFTPClient)
+
+
+
+
+
+
+
+
renegotiate_keys(self)
+
+ Force this session to switch to new keys. Normally this is done
+ automatically after the session hits a certain number of packets or
+ bytes sent or received, but this method gives you the option of forcing
+ new keys whenever you want. Negotiating new keys causes a pause in
+ traffic both ways as the two sides swap keys and do computations. This
+ method returns when the session has switched to new keys, or the
+ session has died mid-negotiation.
+
+
Returns:
+
+ True if the renegotiation was successful, and the link is
+ using new keys; False if the session dropped during
+ renegotiation.
+
+ (type=bool)
+
+
+
+
+
+
+
+
send_ignore(self,
+ bytes=None)
+
+ Send a junk packet across the encrypted link. This is sometimes used
+ to add "noise" to a connection to confuse would-be attackers.
+ It can also be used as a keep-alive for long lived connections
+ traversing firewalls.
+
+
Parameters:
+
bytes -
+ the number of random bytes to send in the payload of the
+ ignored packet -- defaults to a random number from 10 to 41.
+
+ (type=int)
+
+
+
Since: fearow
+
+
+
+
+
+
+
+
set_hexdump(self,
+ hexdump)
+
+ Turn on/off logging a hex dump of protocol traffic at DEBUG level in
+ the logs. Normally you would want this off (which is the default), but
+ if you are debugging something, it may be useful.
+
+
Parameters:
+
hexdump -
+ True to log protocol traffix (in hex) to the log;
+ False otherwise.
+
+ (type=bool)
+
+
+
+
+
+
+
+
set_keepalive(self,
+ interval)
+
+ Turn on/off keepalive packets (default is off). If this is set,
+ after interval seconds without sending any data over the
+ connection, a "keepalive" packet will be sent (and ignored by
+ the remote host). This can be useful to keep connections alive over a
+ NAT, for example.
+
+
Parameters:
+
interval -
+ seconds to wait before sending a keepalive packet (or 0 to
+ disable keepalives).
+
+ (type=int)
+
+
+
Since: fearow
+
+
+
+
+
+
+
+
set_log_channel(self,
+ name)
+
+ Set the channel for this transport's logging. The default is
+ "paramiko.transport" but it can be set to
+ anything you want. (See the logging module for more info.)
+ SSH Channels will log to a sub-channel of the one specified.
+
+
Parameters:
+
name -
+ new channel name for logging.
+
+ (type=str)
+
Set the handler class for a subsystem in server mode. If a request
+ for this subsystem is made on an open ssh channel later, this handler
+ will be constructed and called -- see SubsystemHandler for more detailed
+ documentation.
+ Any extra parameters (including keyword arguments) are saved and
+ passed to the SubsystemHandler constructor later.
+
+
Parameters:
+
name -
+ name of the subsystem.
+
+ (type=str)
+
handler -
+ subclass of SubsystemHandler that handles this
+ subsystem.
+
+ (type=class)
+
+
+
+
+
+
+
+
start_client(self,
+ event=None)
+
+
Negotiate a new SSH2 session as a client. This is the first step
+ after creating a new Transport. A separate thread is created
+ for protocol negotiation.
+
If an event is passed in, this method returns immediately. When
+ negotiation is done (successful or not), the given Event
+ will be triggered. On failure, is_active will return
+ False.
+
(Since 1.4) If event is None, this method
+ will not return until negotation is done. On success, the method
+ returns normally. Otherwise an SSHException is raised.
+ After a successful negotiation, you will usually want to
+ authenticate, calling auth_password or auth_publickey.
+
+
Parameters:
+
event -
+ an event to trigger when negotiation is complete
+ (optional)
+
+ (type=threading.Event)
+
+
+
Raises:
+
SSHException -
+ if negotiation fails (and no event was passed
+ in)
+
+
Notes:
+
+
connect is a simpler method for connecting
+as a client.
+
+
After calling this method (or start_server or connect), you should no longer directly
+read from or write to the original socket object.
+
+
+
+
+
+
+
+
+
+
start_server(self,
+ event=None,
+ server=None)
+
+
Negotiate a new SSH2 session as a server. This is the first step
+ after creating a new Transport and setting up your server host
+ key(s). A separate thread is created for protocol negotiation.
+
If an event is passed in, this method returns immediately. When
+ negotiation is done (successful or not), the given Event
+ will be triggered. On failure, is_active will return
+ False.
+
(Since 1.4) If event is None, this method
+ will not return until negotation is done. On success, the method
+ returns normally. Otherwise an SSHException is raised.
+ After a successful authentication, the client should request to open
+ a channel. Override check_channel_request in the given
+ server object to allow channels to be opened.
+
+
Parameters:
+
event -
+ an event to trigger when negotiation is complete.
+
+ (type=threading.Event)
+
SSHException -
+ if negotiation fails (and no event was passed
+ in)
+
+
Note: After calling this method (or start_client or connect), you should no longer directly
+read from or write to the original socket object.
+
+
+
+
+
+
+
+
use_compression(self,
+ compress=True)
+
+ Turn on/off compression. This will only have an affect before
+ starting the transport (ie before calling connect, etc). By default, compression is
+ off since it negatively affects interactive sessions and is not fully
+ tested.
+
+
Parameters:
+
compress -
+ True to ask the remote client/server to compress
+ traffic; False to refuse compression
+
+ (type=bool)
+
+
+
Since: 1.5.2
+
+
+
+
+
+
+
+
+
+
+
Static Method Details
+
+
+
+
+
load_server_moduli(filename=None)
+
+
(optional) Load a file of prime moduli for use in doing
+ group-exchange key negotiation in server mode. It's a rather obscure
+ option and can be safely ignored.
+ In server mode, the remote client may request
+ "group-exchange" key negotiation, which asks the server to
+ send a random prime number that fits certain criteria. These primes are
+ pretty difficult to compute, so they can't be generated on demand. But
+ many systems contain a file of suitable primes (usually named something
+ like /etc/ssh/moduli). If you call
+ load_server_moduli and it returns True, then
+ this file of primes has been loaded and we will support
+ "group-exchange" in server mode. Otherwise server mode will
+ just claim that it doesn't support that method of key negotiation.
+
+
Parameters:
+
filename -
+ optional path to the moduli file, if you happen to know that
+ it's not in a standard location.
+
+ (type=str)
+
+
+
Returns:
+
+ True if a moduli file was successfully loaded; False
+ otherwise.
+
+ (type=bool)
+
+
+
Note: This has no effect when used in client mode.
+
+ Create a new interactive query to send to the client. The name and
+ instructions are optional, but are generally displayed to the end user.
+ A list of prompts may be included, or they may be added via the add_prompt method.
+
+
Parameters:
+
name -
+ name of this query
+
+ (type=str)
+
instructions -
+ user instructions (usually short) about this query
+
+ (type=str)
+
deflate_long(n,
+ add_sign_padding)
+
+turns a long-int into a normalized byte string (adapted from
+Crypto.Util.number)
+
+
format_binary(data,
+ prefix)
+
+
+
format_binary_line(data)
+
+
+
format_binary_weird(data)
+
+
string
+
+
generate_key_bytes(hashclass,
+ salt,
+ key,
+ nbytes)
+
+Given a password, passphrase, or other human-source key, scramble it
+through a secure hash into some keyworthy bytes.
load_host_keys(filename)
+
+Read a file of known SSH host keys, in the format used by openssh, and
+return a compound dict of hostname -> keytype ->PKey.
+
+
log_to_file(filename,
+ level)
+
+send paramiko logs to a logfile, if they're not already going
+somewhere
+
+
lookup_ssh_host_config(hostname,
+ config)
+
+Return a dict of config options for a given hostname.
+
+
mod_inverse(x,
+ m)
+
+
object
+
+
parse_ssh_config(file_obj)
+
+Parse a config file of the format used by OpenSSH, and return an
+object that can be used to make queries to lookup_ssh_host_config.
+
+
safe_string(s)
+
+
+
tb_strings()
+
+
+
unhexify(s)
+
+turn a hex sequence back into a string
+
+
+
+
+
+
+
Function Details
+
+
+
+
+
deflate_long(n,
+ add_sign_padding=True)
+
+ turns a long-int into a normalized byte string (adapted from
+ Crypto.Util.number)
+
+ Given a password, passphrase, or other human-source key, scramble it
+ through a secure hash into some keyworthy bytes. This specific
+ algorithm is used for encrypting/decrypting private key files.
+
+
Parameters:
+
hashclass -
+ class from Crypto.Hash that can be used as a
+ secure hashing function (like MD5 or
+ SHA).
+
+ (type=Crypto.Hash)
+
salt -
+ data to salt the hash with.
+
+ (type=string)
+
nbytes -
+ number of bytes to generate.
+
+ (type=int)
+
+
+
Returns:
+
+ key data
+
+ (type=string)
+
+
+
+
+
+
+
+
hexify(s)
+
+ turn a string into a hex sequence
+
+
+
+
+
+
+
inflate_long(s,
+ always_positive=False)
+
+ turns a normalized byte string into a long-int (adapted from
+ Crypto.Util.number)
+
+
+
+
+
+
+
load_host_keys(filename)
+
+
Read a file of known SSH host keys, in the format used by openssh,
+ and return a compound dict of hostname -> keytype ->
+ PKey. The hostname may be an IP address
+ or DNS name. The keytype will be either
+ "ssh-rsa" or
+ "ssh-dss".
+ This type of file unfortunately doesn't exist on Windows, but on
+ posix, it will usually be stored in
+ os.path.expanduser("~/.ssh/known_hosts").
+
+
Parameters:
+
filename -
+ name of the file to read host keys from
+
+ (type=str)
+
+
+
Returns:
+
+ dict of host keys, indexed by hostname and then keytype
+
+ (type=dict(hostname, dict(keytype, PKey)))
+
+
+
+
+
+
+
+
log_to_file(filename,
+ level=10)
+
+ send paramiko logs to a logfile, if they're not already going
+ somewhere
+
+
+
+
+
+
+
lookup_ssh_host_config(hostname,
+ config)
+
+
Return a dict of config options for a given hostname. The
+ config object must come from parse_ssh_config.
+
The host-matching rules of OpenSSH's ssh_config man
+ page are used, which means that all configuration options from matching
+ host specifications are merged, with more specific hostmasks taking
+ precedence. In other words, if "Port" is set
+ under "Host *" and also "Host
+ *.example.com", and the lookup is for
+ "ssh.example.com", then the port entry for
+ "Host *.example.com" will win out.
+ The keys in the returned dict are all normalized to lowercase (look
+ for "port", not "Port".
+ No other processing is done to the keys or values.
+
+
Parameters:
+
hostname -
+ the hostname to lookup
+
+ (type=str)
+
config -
+ the config object to search
+
+ (type=object)
+
+
+
+
+
+
+
+
parse_ssh_config(file_obj)
+
+
Parse a config file of the format used by OpenSSH, and return an
+ object that can be used to make queries to lookup_ssh_host_config. The format is
+ described in OpenSSH's ssh_config man page. This method is
+ provided primarily as a convenience to posix users (since the OpenSSH
+ format is a de-facto standard on posix) but should work fine on Windows
+ too.
+ The return value is currently a list of dictionaries, each
+ containing host-specific configuration, but this is considered an
+ implementation detail and may be subject to change in later
+ versions.
+
+
Parameters:
+
file_obj -
+ a file-like object to read the config file from
+
+ (type=file)
+
paramiko: Paramiko (a combination of the esperanto words for
+"paranoid" and "friend") is a module for python 2.3
+or greater that implements the SSH2 protocol for secure (encrypted and
+authenticated) connections to remote machines.
+
paramiko.Message:
+An SSH2 Message is a stream of bytes that encodes some
+combination of strings, integers, bools, and infinite-precision integers
+(known in python as longs).
+