SSHClient Class
Properties Methods Events Configuration Settings Errors
The SSHClient class implements a fully functional, open-ended SSH client.
Syntax
class ipworksssh.SSHClient
Remarks
The SSHClient class can be used to perform any number of tasks secured by the Secure Shell (SSH) protocol. First set ssh_host, ssh_user and either ssh_password or the ssh_cert* properties , then call ssh_logon to establish a secure connection.
To open channels, use open_channel. To open a channel to tunnel data to a remote machine, call open_tcp_ip_channel. The channels property contains a list of all of the channels open for the current instance of the class.
Once a "session" channel has been opened, you can call start_service to initialize a service on that channel. If you are using a "shell" service, you can call open_terminal to establish a pseudo-terminal for formatting the data output from the shell.
Data received from the server will be fired through on_ssh_channel_data events. Any requests received can be processed through the on_ssh_channel_request event.
Property List
The following is the full list of the properties of the class with short descriptions. Click on the links for further details.
| ssh_channel_count | The number of records in the arrays. |
| bytes_sent | The number of bytes actually sent after a sending channel data. |
| channel_id | An id generated by the class to identify the current SSH channel. |
| data_to_send | A string of data to be sent to the remote host. |
| ready_to_send | This property is True when data can be sent over the SSH Channel. |
| record_length | The length of received data records. |
| service | This property holds the channel type that was requested when opening the channel. |
| connected | Triggers a connection or disconnection. |
| firewall_auto_detect | This property tells the class whether or not to automatically detect and use firewall system settings, if available. |
| firewall_type | This property determines the type of firewall to connect through. |
| firewall_host | This property contains the name or IP address of firewall (optional). |
| firewall_password | This property contains a password if authentication is to be used when connecting through the firewall. |
| firewall_port | This property contains the TCP port for the firewall Host . |
| firewall_user | This property contains a user name if authentication is to be used connecting through a firewall. |
| local_host | The name of the local host or user-assigned IP interface through which connections are initiated or accepted. |
| local_port | The TCP port in the local host where the class binds. |
| ssh_accept_server_host_key_encoded | The certificate (PEM/base64 encoded). |
| ssh_auth_mode | The authentication method to be used the class when calling SSHLogon . |
| ssh_cert_encoded | The certificate (PEM/base64 encoded). |
| ssh_cert_store | The name of the certificate store for the client certificate. |
| ssh_cert_store_password | If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store. |
| ssh_cert_store_type | The type of certificate store for this certificate. |
| ssh_cert_subject | The subject of the certificate used for client authentication. |
| ssh_compression_algorithms | A comma-separated list containing all allowable compression algorithms. |
| ssh_encryption_algorithms | A comma-separated list containing all allowable encryption algorithms. |
| ssh_host | The address of the SSH host. |
| ssh_key_exchange_algorithms | A comma-separated list containing all allowable key exchange algorithms. |
| ssh_mac_algorithms | A comma-separated list containing all allowable message authentication algorithms. |
| ssh_password | The password for SSH password-based authentication. |
| ssh_port | The port on the SSH server where the SSH service is running; by default, 22. |
| ssh_public_key_algorithms | A comma-separated list containing all allowable public key authentication algorithms. |
| ssh_user | The username for SSH authentication. |
| timeout | A timeout for the class. |
Method List
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
| close_channel | Closes a existing SSHChannel . |
| config | Sets or retrieves a configuration setting. |
| decode_packet | Decodes a hex-encoded SSH packet. |
| do_events | Processes events from the internal message queue. |
| encode_packet | Hex encodes an SSH packet. |
| exchange_keys | Causes the class to exchange a new set of session keys with the SSHHost . |
| get_ssh_param | Used to read a field from an SSH packet's payload. |
| get_ssh_param_bytes | Used to read a field from an SSH packet's payload. |
| open_channel | Opens a new SSHChannel . |
| open_tcp_ip_channel | Opens a special TCP/IP tunneling SSHChannel . |
| open_terminal | Creates a pseudo-terminal to be used to help display data for a channel. |
| reset | Reset the class. |
| send_channel_data | Used to send regular data over an SSH channel. |
| send_ssh_packet | Used to send an encoded SSH packet to the server. |
| set_ssh_param | Used to write a field to the end of a payload. |
| ssh_logoff | Logoff from the SSH server. |
| ssh_logon | Logon to the SSHHost using the current SSHUser and SSHPassword . |
| start_service | Requests the given service on a target channel. |
Event List
The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.
| on_connected | Fired immediately after a connection completes (or fails). |
| on_connection_status | Fired to indicate changes in connection state. |
| on_disconnected | Fired when a connection is closed. |
| on_error | Information about errors during data delivery. |
| on_log | Fires once for each log message. |
| on_ssh_channel_closed | Fired when a channel is closed. |
| on_ssh_channel_data | Fired when the SSHHost sends channel data to the client. |
| on_ssh_channel_eof | Fired when the remote peer signals the end of the data stream for the channel. |
| on_ssh_channel_opened | Fired when a channel is successfully opened. |
| on_ssh_channel_open_request | Fired when a host attempts to open a new channel. |
| on_ssh_channel_ready_to_send | Fired when the class is ready to send data. |
| on_ssh_channel_request | Fired when the SSHHost sends a channel request to the client. |
| on_ssh_channel_requested | Fired if the SSHChannelRequest was successful, any further processing for the channel request should be done here. |
| on_ssh_custom_auth | Fired when the class is doing custom authentication. |
| on_ssh_keyboard_interactive | Fired when the class receives a request for user input from the server. |
| on_ssh_server_authentication | Fired after the server presents its public key to the client. |
| on_ssh_status | Shows the progress of the secure connection. |
Configuration Settings
The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.
| ClientSSHVersionString | The SSH version string used by the class. |
| EnablePageantAuth | Whether to use a key stored in Pageant to perform client authentication. |
| KerberosDelegation | If true, asks for credentials with delegation enabled during authentication. |
| KerberosRealm | The fully qualified domain name of the Kerberos Realm to use for GSSAPI authentication. |
| KerberosSPN | The Kerberos Service Principal Name of the SSH host. |
| KeyRenegotiationThreshold | Sets the threshold for the SSH Key Renegotiation. |
| LogLevel | Specifies the level of detail that is logged. |
| MaxPacketSize | The maximum packet size of the channel, in bytes. |
| MaxWindowSize | The maximum window size allowed for the channel, in bytes. |
| PasswordPrompt | The text of the password prompt used in keyboard-interactive authentication. |
| PreferredDHGroupBits | The size (in bits) of the preferred modulus (p) to request from the server. |
| RecordLength | The length of received data records. |
| ServerSSHVersionString | The remote host's SSH version string. |
| SignedSSHCert | The CA signed client public key used when authenticating. |
| SSHAcceptAnyServerHostKey | If set the class will accept any key presented by the server. |
| SSHAcceptServerCAKey | The CA public key that signed the server's host key. |
| SSHAcceptServerHostKeyFingerPrint | The fingerprint of the server key to accept. |
| SSHFingerprintHashAlgorithm | The algorithm used to calculate the fingerprint. |
| SSHFingerprintMD5 | The server hostkey's MD5 fingerprint. |
| SSHFingerprintSHA1 | The server hostkey's SHA1 fingerprint. |
| SSHFingerprintSHA256 | The server hostkey's SHA256 fingerprint. |
| SSHKeepAliveCountMax | The maximum number of keep alive packets to send without a response. |
| SSHKeepAliveInterval | The interval between keep alive packets. |
| SSHKeyExchangeAlgorithms | Specifies the supported key exchange algorithms. |
| SSHKeyRenegotiate | Causes the class to renegotiate the SSH keys. |
| SSHMacAlgorithms | Specifies the supported Mac algorithms. |
| SSHPubKeyAuthSigAlgorithms | Specifies the enabled signature algorithms that may be used when attempting public key authentication. |
| SSHPublicKeyAlgorithms | Specifies the supported public key algorithms. |
| SSHVersionPattern | The pattern used to match the remote host's version string. |
| TryAllAvailableAuthMethods | If set to true, the class will try all available authentication methods. |
| WaitForChannelClose | Whether to wait for channels to be closed before disconnected. |
| WaitForServerDisconnect | Whether to wait for the server to close the connection. |
| ConnectionTimeout | Sets a separate timeout value for establishing a connection. |
| FirewallAutoDetect | Tells the class whether or not to automatically detect and use firewall system settings, if available. |
| FirewallHost | Name or IP address of firewall (optional). |
| FirewallPassword | Password to be used if authentication is to be used when connecting through the firewall. |
| FirewallPort | The TCP port for the FirewallHost;. |
| FirewallType | Determines the type of firewall to connect through. |
| FirewallUser | A user name if authentication is to be used connecting through a firewall. |
| KeepAliveInterval | The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received. |
| KeepAliveTime | The inactivity time in milliseconds before a TCP keep-alive packet is sent. |
| Linger | When set to True, connections are terminated gracefully. |
| LingerTime | Time in seconds to have the connection linger. |
| LocalHost | The name of the local host through which connections are initiated or accepted. |
| LocalPort | The port in the local host where the class binds. |
| MaxLineLength | The maximum amount of data to accumulate when no EOL is found. |
| MaxTransferRate | The transfer rate limit in bytes per second. |
| ProxyExceptionsList | A semicolon separated list of hosts and IPs to bypass when using a proxy. |
| TCPKeepAlive | Determines whether or not the keep alive socket option is enabled. |
| TcpNoDelay | Whether or not to delay when sending packets. |
| UseIPv6 | Whether to use IPv6. |
| AbsoluteTimeout | Determines whether timeouts are inactivity timeouts or absolute timeouts. |
| FirewallData | Used to send extra data to the firewall. |
| InBufferSize | The size in bytes of the incoming queue of the socket. |
| OutBufferSize | The size in bytes of the outgoing queue of the socket. |
| BuildInfo | Information about the product's build. |
| CodePage | The system code page used for Unicode to Multibyte translations. |
| LicenseInfo | Information about the current license. |
| ProcessIdleEvents | Whether the class uses its internal event loop to process events when the main thread is idle. |
| SelectWaitMillis | The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process. |
| UseInternalSecurityAPI | Tells the class whether or not to use the system security libraries or an internal implementation. |