paramiko模块简介

paramiko是基于SSHv2协议开发的，可用于连接远程SSH服务器，通过SSH连接执行远程命令或者文件传输。paramiko支持Python（2.7，3.4+版本）。paramiko利用Python C扩展来现简单的加密，它本身是一个围绕SSH网络概念的纯Python接口。

paramiko分为以下几个部分

SSH协议核心类

• Channel
• Client
• Message
• Packetizer
• Transport

秘钥认证类
SSH agents
Host keys / known_hosts files
Key handling
Parent key class

• DSA (DSS)
• RSA
• ECDSA
• Ed25519

GSS-API authentication
GSS-API key exchange

其它功能类

• Configuration
• Keywords currently supported
• Expansion tokens
• config module API documentation
• ProxyCommand support
• Server implementation
• SFTP

杂类

• Buffered pipes
• Buffered files
• Cross-platform pipe implementations
• Exceptions

下面对各类进行简单介绍

 

 

SSH协议核心类

channel类

class paramiko.channel.Channel(chanid)

channel类的描述：

channel是一个SSH传输的安全隧道。一个通道类似于一个socket，由于SSH2有一种窗口式的流控制，如果停止从channel中读取数据，并且其缓冲区已满，服务器将无法向channel发送更多的数据，直到从channel中读取其中一些数据。（注意：这不会影响同一传输上的其他channel，单个传输上的所有channel都是独立的流控制。）同样，如果服务器不读取channel发送的数据，则除非设置超时，否则发送调用会一直处于阻塞。

channel类中的常用方法：

__init__(chanid)：构造函数，channel是由Transport创建的，所以我们不用管。

close()：

功能：关闭channel，断开SSH连接。

参数：无。

返回值：无。

exec_command(self, command)：

功能：执行远程命令，注意命令执行完成后channel将关闭，不能被复用。

参数：

command(str)：要执行的命令。

返回值：元组(stdin, stdout, stderr)。

exit_status_ready()：

功能：当服务端主动断开连接时，接收服务端的退出状态码。如果因为程序假死，或者服务器宕机等特殊原因造成exit_status_ready()无法接收到退出状态码，该方法将无法通过获取状态码的形式来判断服务器的状态。

参数：无

返回值：如果接收到服务器退出状态码返回True，否则返回False。

fileno()：

功能：在使用Python的select模块时会用到fileon()返回的文件描述符FD。如果有很多channel都使用此方法将导致channel读取的效率变慢。

参数：无

返回值：返回一个操作系统级文件描述符（int）FD，该描述符不用于读取或写入。

get_id()：

功能：返回channel的ID，通常是一个很小的数字。

参数：无

返回值：channel的ID。

get_name()：

功能：获取channel的名字，可以使用set_name设置channel的名字。

参数：无

返回值：channel的名字。

get_pty(term="vt100",width=80,height=24,width_pixels=0,height_pixels=0)：

功能：向服务器请求获取一个伪终端，通常在创建channel后，立即调用get_pty()请求一个伪终端，在使用invoke_shell想要创建一个交互式shell环境时需要提前调用get_pty()，如果调用的是exec_command执行命令，不需要使用get_pty()。

参数：

term(str)：要模拟的终端类型，如：'vt100'。
width(int)：终端宽度，以字符为单位。
height(int)：终端高度，以字符为单位。
width_pixels(int)：终端宽度，以像素为单位。
height_pixels(int)：终端高度，以像素为单位。

返回值：无

resize_pty(self, width=80, height=24, width_pixels=0, height_pixels=0)：

功能：执行get_pty()后，可以通过resize_pty()重新设置伪终端窗口大小。

参数：同get_pty()。

返回值：无

invoke_shell(self)：

功能：前面使用get_pty()获取一个伪终端后，需要使用invoke_shell()激活这个伪终端，激活成功后在伪终端中就可以向操作本机一样操作远程主机即所谓的交互式shell。当退出伪终端后，channel将被关闭，无法被复用。

参数：无

返回值：无

recv(nbytes)：

功能：从channel中接收nbytes的数据，并以字节的形式返回。

参数：

nbytes(int)：接收的最大字节数。

返回值：以字节的形式返回接收到的数据。

recv_exit_status()：

功能：接收服务器进程返回退出状态码。对于检索执行命令的结果非常有用。如果命令尚未完成，则此方法将等待完成，或者直到通道关闭。如果服务器没有提供退出状态，则返回-1。

参数：无

返回值：如果接收到状态码返回状态码，否则返回-1。

recv_ready()：

功能：如果channel中有可读数据返回True，否则返回False。但返回False并不意味着通道已关闭，或者没有可读取的数据，有可能需要等待更多的数据到达后在进行读取。

参数：无

返回值：如果channel中有可读数据返回True，否则返回False。

recv_stderr(nbytes)：

功能：从channel中的stderr流接收nbytes字节的数据。此方法只在不调用get_pty的情况下使用exec_command或invoke_shell时channel中stderr流上才拥有数据。

参数：

nbytes(int)：接收最大的字节数。

返回值： 从channel中的stderr流接收到的数据（字节）。

recv_stderr_ready()：

功能：判断channel中是否有可读的stderr流。此方法只在不调用get_pty的情况下使用exec_command或invoke_shell时channel中stderr流上才拥有数据。

参数：无

返回值： 如果channel中有stderr流返回True，否则返回False。

request_forward_agent( handler)：

功能：在channel上请求转发SSH代理。 仅对来自OpenSSH的ssh-agent有效！

参数：

handler：handler是用于传入SSH Agen连接的必需可调用处理程序 。

返回值：没太懂，貌似只要执行了就返回True。

get_transport()：

功能：获取与channel关联的Transport对象。

参数：无

返回值：Transport对象

getpeername()：

功能：获取远程服务器的地址。

参数：无

返回值：远程服务器的地址

gettimeout()：

功能：调用“ setblocking”或“ settimeout”设置超时键后，可以使用此方法获取超时时间单位秒，如果没有设置超时时间返回None。

参数：无

返回值：如果设置超时时间返回超时时间单位秒，否则返回None。

def request_x11(screen_number=0,

auth_protocol=None,

auth_cookie=None,

single_connection=False,

handler=None)：

功能：在channel上请求x11会话。 如果服务器允许，则在Shell会话中运行x11应用程序时，可以从服务器向客户端发出进一步的x11请求。

参数：

screen_number(int)：屏幕号取值范围0-10。
auth_protocol(str)：X11身份验证使用的协议，如果未指定默认使用“MIT-MAGIC-COOKIE-1”。
auth_cookie(str)：x11身份验证cookie的十六进制字符串；如果没有给定，生成一个安全的随机128位值。
single_connection(bool)：如果为True，则仅转发一个x11连接，为False可以转发任意数量的x11连接。
handler=None：handler是X11连接的可选可调用处理程序。

返回值：身份验证的cookie。

send( s)：

功能：发送数据给服务端，s是要发送的数据，但由于发送缓冲大小的原因数据可能无法被一次性发完，需要开发人员检测数据是否被全部发送，如果数据没有发送完，需要再次发送后续数据，直到数据全部发送。

参数：
s(str)：是要发送的数据。

返回值：发送的字节数。

send_exit_status(status)：

功能：向客户端发送退出状态码，仅当作为服务端时才有效。

参数：

status(int)：退出状态码。

返回值：无

send_ready()：

功能：如果channel不需要阻塞可以立即向发送缓冲区中写入数据返回True，否则返回False。注意，如果channel已关闭，任何尝试向channel发送缓冲区写入数据都会被立即返回，因为无法写入所以被立即返回，这种情况send_ready也会返回True。

参数：无

返回值：如果channel不需要阻塞可以立即向发送缓冲区中写入数据返回True，否则返回False。

send_stderr(s)：

功能：向客户端发送stderr流，仅当作为服务端时才有效。需要开发人员检测数据是否被全部发送，如果数据没有发送完，需要再次发送后续数据，直到数据全部发送。

参数：

s(str)：要发送的数据。

返回值：发送的字节数。

sendall(s)：

功能：将数据全部发送出去，与send的区别是，sendall会自动将所有数据全部发送，不需要人为干预。

参数：

s(str)：要发送数据。

返回值：无

sendall_stderr(s)：

功能：向客户端发送stderr流，仅当作为服务端时才有效，与send_stderr区别是sendall_stderr会自动将所有数据全部发送，不需要人为干预。

返回值：无

set_combine_stderr(combine)：

功能：是否将channel中stderr流和stdout流进行合并，默认combine=False，如果为false表示不合并，在调用exec_command后只能通过recv_stderr来获取channel中的stderr流，而不能使用recv。如果为True，表示将stderr流和stdout流进行合并，则无法通过recv_stderr来获取stderr流，因为stderr已经合并到stdout流中，可以使用recv来获取。

参数：

combine(bool)：True|False。

返回值：设定的combine的值。

set_environment_variable(name, value)：

功能：设置环境变量的值。注意：如果服务端在配置文件中设置AcceptEnv拒绝客户端设置环境变量，该方法将不会提示设置失败。

参数：

name(str)：环境变量。

value(str)：环境变量的值。

返回值：无

set_name(name)：

功能：给channel设置一个名字。

参数：

name(str)：channel的名字。

返回值：无

setblocking(blocking)：

功能：设置channel的阻塞模式，如果blocking为0表示非阻塞模式，否则为阻塞模式。在非阻塞模式下如果recv无法立即接收到数据，或者send无法立即发送数据将会引发错误异常。在阻塞模式下send或recv会一直等待执行完成，EOF条件被视为recv的“立即数据”，因此，如果channel在读取方向上关闭，则它将永远不会阻塞。

参数：

blocking(int)：如果是0表示阻塞非阻塞模式，非0是阻塞模式blocking表示的是阻塞时间单位是秒，如果blocking是1表示一直阻塞，直到执行完成。

返回值：无

settimeout(timeout)：

功能：设置超时时间。与setblocking功能类似。不同之处在于timeout可以是None，而setblocking中的blocking参数只能是int类型，而blocking=1就相当于timeout=None。所以两者功能上基本类似。

参数：

timeout(float)：超时时间单位秒，如果timeout为None阻塞模式，一直等到recv接收完成，或send发送完成。

返回值：无

shutdown(how)：

功能：关闭连接的发送端或者接收端，也可以全部关闭。

参数：

how(int)：如果how=0，关闭接收端，如果how=1，关闭发送端，如果how=2，关闭发送端和接收端。

返回值：无

shutdown_read()

功能：关闭连接的接收端，相当于shutdown(0)。

参数：无

返回值：无

shutdown_write()：

功能：关闭连接的发送端，相当于shutdown(1)。

参数：无

返回值：无

update_environment(environment)：

功能：更新远程服务器的环境变量，注意：如果服务端在配置文件中设置AcceptEnv拒绝客户端设置环境变量，该方法将不会提示设置失败。

参数：

environment(dict)：是一个{'环境变量名'：'环境变量的值',...}。

返回值：无

 

SSHClient类

class paramiko.client.SSHClient：

描述：

SSHClient是与SSH服务器回话的高级封装，其内部实现了身份验证，执行命令等大多数基础功能。

close()：

功能：关闭SSHClient对象及其底层的Transport。使用完SSHClient对象后，最好调用close()关闭对象释放资源，尽量不依靠python的垃圾回收机制来关闭SSHClient对象。

参数：无

返回值：无

connect(hostname, port=22, username=None, password=None, pkey=None,

key_filename=None, timeout=None, allow_agent=True, look_for_keys=True,

compress=False, sock=None, gss_auth=False, gss_kex=False, gss_deleg_creds=True,

gss_host=None, banner_timeout=None, auth_timeout=None, gss_trust_dns=True,

passphrase=None, disabled_algorithms=None)

功能：连接SSH服务器。

参数：

hostname(str)：SSH服务器主机地址。

port(int)：SSH服务器的端口号。

username(str)：登录SSH服务器的用户名。

password(str)：登录SSH服务器用户名的密码。

pkey(PKey)：用于身份验证的私钥。

key_filename(str)：用于尝试身份验证的私钥或证书的文件路径。

time(float)：建立TCP连接的超时时间单位是秒。

allow_agent(bool)：如果为False，将禁止连接SSH agent，如果为True通过SSH agent获取私钥。

look_for_keys(bool)：如果为False将禁止在~/.ssh中搜索可用的私钥。

compress(bool)：如果为True将启用压缩。

sock(socket)：socket对象。

gss_auth(bool)：如果为True可以使用GSS-API进行认证。

gss_kex(bool)：执行GSS-API密钥交换和用户身份验证。

gss_deleg_creds(bool)：是否委托GSS-API客户端凭据。

gss_host(str)：kerberos数据库中的目标名称。默认是hostname的值。

gss_trus_dns(bool)：是否信任DNS安全规范化所连接主机的名称（默认为True）。

banner_timeout(float)：SSH连接成功后banner信息出现的超时时间单位为秒。

auth_timeout(float)：身份认证的超时时间，单位为秒。

disabled_algroitms(dict)：直接传递给Transport的可选dict及其同名的关键字参数。

注意：

Changed in version 1.15: Added the banner_timeout, gss_auth, gss_kex, gss_deleg_creds and gss_host arguments.
Changed in version 2.3: Added the gss_trust_dns argument.
Changed in version 2.4: Added the passphrase argument.
Changed in version 2.6: Added the disabled_algorithms argument.

身份认证的优先级顺序（由高到底）：

• pkey和key_filename优先级相同。
• 通过SSH agent获取私钥（allow_agent=True）。
• 本地~/.ssh中发现的“id_rsa”、“id_dsa”或“id_ecdsa”密钥。
• 通过用户名密码的方式进行验证。

exec_command(
command,
bufsize=-1,
timeout=None,
get_pty=False,
environment=None,
)：

功能：执行远程命令

参数：

command(str)：要执行的命令，多条命令用分号隔开。

bufsize(int)：0 表示不缓冲，如果为 1 表示进行行缓冲，大于 1 为缓冲区大小。

timeout(float)：命令执行的超时时间，单位秒。

get_pty(bool)：如果为True相当于Channel.get_pty，向服务器请求一个伪终端。

environment(dict)：在执行命令时附加环境变量。

返回值：返回一个元组 (stdin, stdout, and stderr)

get_host_keys()：

功能：获取本机秘钥。

参数：无

返回值：本地秘钥HostKey对象。

get_transport()：

功能：获取一个关于当前SSH连接的Transport对象，该对象可用于创建channel。

参数：无

返回值：Transport对象。

invoke_shell(
term="vt100",
width=80,
height=24,
width_pixels=0,
height_pixels=0,
environment=None,
)：

功能：创建一个新的channel，向SSH服务器请求一个伪终端，建立交互式shell环境。

参数：

term(str)：终端类型。

width(int)：终端宽度（即以字符为计算单位）。

height(int)：终端高度（即以字符为计算单位）。

witth_pixels(int)：终端宽度（即以像素为计算单位）。

height_pixels(int)：终端高度（即以像素为计算单位）。

environment(dict)：环境变量。

返回值：返回一个建立好交互环境的channel对象。

load_host_keys(filename)：

功能：从本地文件中读取秘钥后，通过调用load_system_host_keys对其秘钥进行检查。检查完成后调用save_host_keys()将秘钥保存回源文件当中，秘钥保存在秘钥保存在self._entries中。当连接一台未知的主机时，缺省策略AutoAddPolicy会将load_host_keys读取到的秘钥添加到自己的秘钥集合中用于验证未知的服务器。

参数：

filename(str)：秘钥文件路径。

返回值：无

load_system_host_keys(filename=None)：

功能：从本地加载秘钥，如果filename=None，将从本地如~/.ssh下获取相关秘钥文件（不适用于Windows系统），该方法以只读的方式读取秘钥，秘钥读取后不会进行回写，秘钥保存在self._entries中。

参数：

filename(str)：秘钥文件路径。

返回值：无

open_sftp()：

功能：在SSH服务器打开一个SFTP回话。

参数：无

返回值：SFTPClient对象。

save_host_keys(filename)：

功能：将主机秘钥存回源文件，仅当使用load_host_keys()方法时，该方法才有效。

参数：

filename(str)：秘钥文件路径。

返回值：无

set_log_channel(name)：

功能：设置channel在日志中的名字，默认是paramiko.transport。

参数：

name(str)：channel在日志中的名字，可以是任意名字。

返回值：无

set_missing_host_key_policy(policy)：

功能：设置一个秘钥策略，当连接一台没有没有该主机秘钥的主机时，使用的秘钥策略。

参数：

policy(MissingHostKeyPolicy)：秘钥策略。MissingHostKeyPolicy有三种秘钥策略：RejectPolicy，AutoAddPolicy，WarningPolicy。

class paramiko.client.RejectPolicy：

功能：秘钥策略，拒绝连接未知秘钥的主机，已知的主机秘钥是指由load_system_host_keys 和load_host_keys从文件中读取到的秘钥，该秘钥保存在在self._entries中。如果self._entries中没有主机对应的秘钥条目则视为未知的主机。

class paramiko.client.WarningPolicy：

功能：秘钥策略，允许连接未知秘钥的主机，通过用户提供的秘钥对主机进行连接，但会发出警告。如下：

class paramiko.client.AutoAddPolicy：

功能：秘钥策略，允许连接未知秘钥的主机，并自动将主机和对应的秘钥添加到本地的HostKeys中。

返回值：无

 

参考文档：http://docs.paramiko.org/en/stable/

======================================================================================

 

                                未完待续

 

======================================================================================