ssh

Description

SSH plugin.

Configuration

ssh:
  # [Optional]
  # Default key file (default: any "id_rsa", "id_dsa",
  # "id_ecdsa", or "id_ed25519" key discoverable in ``~/.ssh/``.
  # key_file:   # type=Optional[str]

  # [Optional]
  # Key file passphrase (default: None).
  # passphrase:   # type=Optional[str]

Dependencies

pip

pip install paramiko

Alpine

apk add py3-paramiko

Debian

apt install python3-paramiko

Fedora

yum install python-paramiko

Arch Linux

pacman -S python-paramiko

Actions

• ssh.chdir

• ssh.chmod

• ssh.chown

• ssh.connect

• ssh.disconnect

• ssh.exec

• ssh.get

• ssh.getcwd

• ssh.keygen

• ssh.ln

• ssh.ls

• ssh.mkdir

• ssh.mv

• ssh.put

• ssh.rm

• ssh.rmdir

• ssh.start_forward_tunnel

• ssh.start_reverse_tunnel

• ssh.stop_forward_tunnel

• ssh.stop_reverse_tunnel

Module reference

class platypush.plugins.ssh.SshPlugin(key_file: str | None = None, passphrase: str | None = None, **kwargs)

Bases: Plugin

SSH plugin.

__init__(key_file: str | None = None, passphrase: str | None = None, **kwargs)

Parameters:

• key_file – Default key file (default: any “id_rsa”, “id_dsa”, “id_ecdsa”, or “id_ed25519” key discoverable in ~/.ssh/.

• passphrase – Key file passphrase (default: None).

chdir(path: str, keep_alive: bool = False, **kwargs) → None

Change directory to the specified path.

Parameters:

• path – Destination path.

• keep_alive – Keep the connection active after running the command (default: False).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

chmod(path: str, mode: int, keep_alive: bool = False, **kwargs) → None

Change the access rights of a path.

Parameters:

• path – Path to be modified.

• mode – Access permissions (in octal mode).

• keep_alive – Keep the connection active after running the command (default: False).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

chown(path: str, uid: int, gid: int, keep_alive: bool = False, **kwargs) → None

Change the owner of a path.

Parameters:

• path – Path to be modified.

• uid – New user ID.

• gid – New group ID.

• keep_alive – Keep the connection active after running the command (default: False).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

connect(host: str, port: int = 22, user: str | None = None, password: str | None = None, key_file: str | None = None, passphrase: str | None = None, compress: bool = False, timeout: int | None = None, auth_timeout: int | None = None) → None

Open an SSH connection.

Parameters:

• host – Host name or IP. Can also be in the format [user]@<host>:[port].

• port – Remote port (default: 22).

• user – Username (default: None, same user name as the one running platypush).

• password – Password (default: None).

• key_file – Key file to use for authentication (default: None).

• passphrase – Passphrase for the key file (default: None).

• compress – Compress data on the connection (default: False).

• timeout – Data transfer timeout in seconds (default: None).

• auth_timeout – Authentication timeout in seconds (default: None).

disconnect(host: str, port: int = 22, user: str | None = None) → None

Close a connection to a host.

Parameters:

• host – Host name or IP. Can also be in the format [user]@<host>:[port].

• port – Remote port (default: 22).

• user – Username (default: None, same user name as the one running platypush).

exec(cmd: str, keep_alive: bool = False, timeout: int | None = None, stdin: str | None = None, env: Dict[str, str] | None = None, **kwargs) → Response

Run a command on a host.

Parameters:

• cmd – Command to run

• keep_alive – Keep the connection active after running the command (default: False).

• timeout – Communication timeout in seconds (default: None).

• stdin – Optional string to pass on the stdin of the command.

• env – Dictionary of environment variables to be used for the connection (default: None).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

Returns:

The output of the executed command.

get(remote_path: str, local_path: str, recursive: bool = False, keep_alive: bool = False, **kwargs) → None

Download a file or folder from an SSH server.

Parameters:

• remote_path – Remote path (file or directory).

• local_path – Local path (file or directory).

• recursive – Set to True if you want to recursively download folders (default: False).

• keep_alive – Keep the connection active after running the command (default: False).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

getcwd(keep_alive: bool = False, **kwargs) → str

Get the current working directory.

Parameters:

• keep_alive – Keep the connection active after running the command (default: False).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

keygen(filename: str, type: str = 'rsa', bits: int = 4096, comment: str | None = None, passphrase: str | None = None) → dict

Generate an SSH keypair.

Parameters:

• filename – Output file name for the private key (the public key will be stored in <filename>.pub).

• type – Encryption algorithm, either “rsa” or “dsa” (default: “rsa”).

• bits – Key length in bits (default: 4096).

• comment – Key comment (default: None).

• passphrase – Key passphrase (default: None).

Returns:

{
  "fingerprint": "SHA256:...",
  "key_file": "private_key_file",
  "pub_key_file": "public_key_file"
}

ln(src: str, dest: str, keep_alive: bool = False, **kwargs) → None

Create a symbolic link.

Parameters:

• src – Source path.

• dest – Destination path.

• keep_alive – Keep the connection active after running the command (default: False).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

ls(path: str = '.', attrs: bool = False, keep_alive: bool = False, **kwargs) → List[str] | Dict[str, Any]

Return the list of files in a path on a remote server.

Parameters:

• path – Remote path (default: current directory).

• keep_alive – Keep the connection active after running the command (default: False).

• attrs – Set to True if you want to get the full information of each file (default: False).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

Returns:

A list of filenames if attrs=False, otherwise a dictionary filename -> {attributes if attrs=True.

mkdir(path: str, mode: int = 511, keep_alive: bool = False, **kwargs) → None

Create a directory.

Parameters:

• path – Path to be created.

• mode – Access permissions (default: 0777).

• keep_alive – Keep the connection active after running the command (default: False).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

mv(path: str, new_path: str, keep_alive: bool = False, **kwargs) → None

Move/rename a file.

Parameters:

• path – Remote path to move/rename.

• new_path – Destination path.

• keep_alive – Keep the connection active after running the command (default: False).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

put(remote_path: str, local_path: str, recursive: bool = False, keep_alive: bool = False, **kwargs) → None

Upload a file or folder to an SSH server.

Parameters:

• remote_path – Remote path (file or directory).

• local_path – Local path (file or directory).

• recursive – Set to True if you want to recursively upload folders (default: False).

• keep_alive – Keep the connection active after running the command (default: False).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

rm(path: str, keep_alive: bool = False, **kwargs) → None

Remove a file from the server.

Parameters:

• path – Remote path to remove.

• keep_alive – Keep the connection active after running the command (default: False).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

rmdir(path: str, keep_alive: bool = False, **kwargs) → None

Remove a directory.

Parameters:

• path – Path to be removed.

• keep_alive – Keep the connection active after running the command (default: False).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

start_forward_tunnel(local_port: int, remote_host: str, remote_port: int, bind_addr: str = '', **kwargs)

Start an SSH forward tunnel, tunnelling <local_port> to <remote_host>:<remote_port>.

Parameters:

• local_port – Local port.

• remote_host – Remote host.

• remote_port – Remote port.

• bind_addr – If set, the local_port will be bound to this address/subnet (default: ‘’, or 0.0.0.0: any).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

start_reverse_tunnel(server_port: int, remote_host: str, remote_port: int, bind_addr: str = '', **kwargs)

Start an SSH reversed tunnel. <server_port> on the SSH server is forwarded across an SSH session back to the local machine, and out to a <remote_host>:<remote_port> reachable from this network.

Parameters:

• server_port – Server port.

• remote_host – Remote host.

• remote_port – Remote port.

• bind_addr – If set, the server_port will be bound to this address/subnet (default: ‘’, or 0.0.0.0: any).

• kwargs – Arguments for platypush.plugins.ssh.SshPlugin.connect().

stop_forward_tunnel(local_port: int, remote_host: str, remote_port: int)

Stop an active SSH forward tunnel.

Parameters:

• local_port – Local port.

• remote_host – Remote host.

• remote_port – Remote port.

stop_reverse_tunnel(server_port: int, remote_host: str, remote_port: int)

Stop an active SSH reversed tunnel.

Parameters:

• server_port – Server port.

• remote_host – Remote host.

• remote_port – Remote port.