Package: parallel-ssh
Asynchronous parallel SSH client library.Run SSH commands over many - hundreds/hundreds of thousands - number of servers asynchronously and with minimal system load on the client host.Native code based clients with extremely high performance, making use of C libraries.Installationpipinstallparallel-sshAn update topipmay be needed to be able to install binary wheels.pipinstall-Upippipinstallparallel-sshUsage ExampleSee documentation onread the docsfor more complete examples.Rununameon two hosts in parallel.frompssh.clientsimportParallelSSHClienthosts=['localhost','localhost']client=ParallelSSHClient(hosts)output=client.run_command('uname')forhost_outputinoutput:forlineinhost_output.stdout:print(line)exit_code=host_output.exit_codeOutput:LinuxLinuxSingle Host ClientSingle host client with similar API can be used if parallel functionality is not needed.frompssh.clientsimportSSHClienthost='localhost'cmd='uname'client=SSHClient(host)host_out=client.run_command(cmd)forlineinhost_out.stdout:print(line)exit_code=host_out.exit_codeContentsInstallationUsage ExampleSingle Host ClientQuestions And DiscussionNative clientsNative Code Client FeaturesWhy This LibraryWaiting for Completion and Exit CodesBuilt in Host Output LoggerSCPSFTPQuestions And DiscussionGithub discussionscan be used to discuss, ask questions and share ideas regarding the use of parallel-ssh.Native clientsThe default client inparallel-sshis a native client based onssh2-python-libssh2C library - which offers much greater performance and reduced overhead compared to other Python SSH libraries.Seethis postfor a performance comparison of different Python SSH libraries.Alternative clients based onssh-python(libssh) are also available underpssh.clients.ssh. Seeclient documentationfor a feature comparison of the available clients in the library.parallel-sshmakes use of clients and an event loop solely based on C libraries providing native code levels of performance and stability with an easy to use Python API.Native Code Client FeaturesHighest performance and least overhead of any Python SSH libraryThread safe - makes use of native threads for CPU bound calls like authenticationNatively asynchronous utilising C libraries implementing the SSH protocolSignificantly reduced overhead in CPU and memory usageWhy This LibraryBecause other options are either immature, unstable, lacking in performance or all of the aforementioned.Certain other self-proclaimedleadingPython SSH libraries leave a lot to be desired from a performance and stability point of view, as well as suffering from a lack of maintenance with hundreds of open issues, unresolved pull requests and inherent design flaws.The SSH librariesparallel-sshuses are, on the other hand, long standing mature C libraries inlibssh2andlibsshthat have been in production use for decades and are part of some of the most widely distributed software available today -Gititself,OpenSSH,Curland many others.These low level libraries are far better placed to provide the maturity, stability and performance needed from an SSH client for production use.parallel-sshprovides easy to use SSH clients that hide the complexity, while offering stability and native code levels of performance and as well as the ability to scale to hundreds or more concurrent hosts.Seealternativesfor a more complete comparison of alternative SSH libraries, as well asperformance comparisonsmentioned previously.Waiting for Completion and Exit CodesThe client’sjoinfunction can be used to wait for all commands in output to finish.Afterjoinreturns, commands have finished and all output can be read without blocking.Onceeitherstandard output is iterated onto completion, orclient.join()is called, exit codes become available in host output.Iteration endsonly when remote command has completed, though it may be interrupted and resumed at any point - seejoin and output timeoutsdocumentation.HostOutput.exit_codeis a dynamic property and will returnNonewhen exit code is not ready, meaning command has not finished, or unavailable due to error.Once all output has been gathered exit codes become available even without callingjoinas per previous examples.output=client.run_command('uname')client.join()forhost_outinoutput:forlineinhost_out.stdout:print(line)print(host_out.exit_code)Output:Linux0Linux0Similarly, exit codes are available afterclient.join()without reading output.output=client.run_command('uname')client.join()forhost_outputinoutput:print(host_out.exit_code)Output:00Built in Host Output LoggerThere is also a built in host logger that can be enabled to log output from remote hosts for both stdout and stderr. The helper functionpssh.utils.enable_host_loggerwill enable host logging to stdout.To log output without having to iterate over output generators, theconsume_outputflagmustbe enabled - for example:frompssh.utilsimportenable_host_loggerenable_host_logger()client.run_command('uname')client.join(consume_output=True)Output:[localhost]LinuxSCPSCP is supported - native client only - and provides the best performance for file copying.Unlike with the SFTP functionality, remote files that already exist arenotoverwritten and an exception is raised instead.Note that enabling recursion with SCP requires server SFTP support for creating remote directories.To copy a local file to remote hosts in parallel with SCP:frompssh.clientsimportParallelSSHClientfromgeventimportjoinallhosts=['myhost1','myhost2']client=ParallelSSHClient(hosts)cmds=client.scp_send('../test','test_dir/test')joinall(cmds,raise_error=True)SeeSFTP and SCP documentationfor more examples.SFTPSFTP is supported in the native client.To copy a local file to remote hosts in parallel:frompssh.clientsimportParallelSSHClientfrompssh.utilsimportenable_logger,loggerfromgeventimportjoinallenable_logger(logger)hosts=['myhost1','myhost2']client=ParallelSSHClient(hosts)cmds=client.copy_file('../test','test_dir/test')joinall(cmds,raise_error=True)Output:Copiedlocalfile../testtoremotedestinationmyhost1:test_dir/testCopiedlocalfile../testtoremotedestinationmyhost2:test_dir/testThere is similar capability to copy remote files to local ones with configurable file names via thecopy_remote_filefunction.In addition, per-host configurable file name functionality is provided for both SFTP and SCP  - seedocumentation.Directory recursion is supported in both cases via therecurseparameter - defaults to off.SeeSFTP and SCP documentationfor more examples.