CkSsh Ruby Programming
Reference Documentation
CkSsh
A client-side SSH2 implementation for executing commands and shell sessions on Unix/Windows SSH servers.
Object Creation
obj = Chilkat::CkSsh.new()
Properties
# Returns an integer value
get_ChannelOpenFailCode( )
If a request to open a channel fails, this property contains a code that identifies the reason for failure. The reason codes are defined in RFC 4254 and are reproduced here:
Symbolic name reason code
------------- -----------
SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1
SSH_OPEN_CONNECT_FAILED 2
SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3
SSH_OPEN_RESOURCE_SHORTAGE 4
# str is a CkString object (output)
get_ChannelOpenFailReason( str )
The descriptive text corresponding to the ChannelOpenFailCode property.
# str is a CkString object (output)
get_ClientIdentifier( str )
# newVal is a string (input)
put_ClientIdentifier( newVal )
The client-identifier string to be used when connecting to an SSH/SFTP server. Defaults to "SSH-2.0-PuTTY_Local:_Jun_27_2008_16:28:58". (This string is used to mimic PuTTY because some servers are known to disconnect from clients with unknown client identifiers.)
# str is a CkString object (output)
get_ClientIpAddress( str )
# newVal is a string (input)
put_ClientIpAddress( newVal )
The IP address to use for computers with multiple network interfaces or IP addresses.
For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.
The IP address is a string such as in dotted notation using numbers, not domain names, such as "165.164.55.124".
# Returns an integer value
get_ConnectTimeoutMs( )
# newVal is an integer (input)
put_ConnectTimeoutMs( newVal )
Maximum number of milliseconds to wait when connecting to an SSH server.
# str is a CkString object (output)
get_DebugLogFilePath( str )
# newVal is a string (input)
put_DebugLogFilePath( newVal )
Used for debugging in cases where a Chilkat method call hangs and never returns. This should generally never happen. The only causes for this are (1) a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired, (2) the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or (3) there is an internal problem (bug) in the Chilkat code that causes the hang.
This property allows one to specifiy a debug file path that will be created (or appended if it already exists) and information will be logged to it as the Chilkat methods are called. If a hang occurs, the log file may be viewed to get information about what happened.
# Returns an integer value
get_DisconnectCode( )
If the SSH server sent a DISCONNECT message when closing the connection, this property contains the "reason code" as specified in RFC 4253:
Symbolic name reason code
------------- -----------
SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT 1
SSH_DISCONNECT_PROTOCOL_ERROR 2
SSH_DISCONNECT_KEY_EXCHANGE_FAILED 3
SSH_DISCONNECT_RESERVED 4
SSH_DISCONNECT_MAC_ERROR 5
SSH_DISCONNECT_COMPRESSION_ERROR 6
SSH_DISCONNECT_SERVICE_NOT_AVAILABLE 7
SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED 8
SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE 9
SSH_DISCONNECT_CONNECTION_LOST 10
SSH_DISCONNECT_BY_APPLICATION 11
SSH_DISCONNECT_TOO_MANY_CONNECTIONS 12
SSH_DISCONNECT_AUTH_CANCELLED_BY_USER 13
SSH_DISCONNECT_NO_MORE_AUTH_METHODS_AVAILABLE 14
SSH_DISCONNECT_ILLEGAL_USER_NAME 15
# str is a CkString object (output)
get_DisconnectReason( str )
If the SSH/ server sent a DISCONNECT message when closing the connection, this property contains a descriptive string for the "reason code" as specified in RFC 4253.
# Returns an integer value
get_HeartbeatMs( )
# newVal is an integer (input)
put_HeartbeatMs( newVal )
This is the number of milliseconds between each AbortCheck event callback. The AbortCheck callback allows an application to abort any SSH operation prior to completion. If HeartbeatMs is 0 (the default), no AbortCheck event callbacks will fire.
# str is a CkString object (output)
get_HostKeyFingerprint( str )
Set after connecting to an SSH server. The format of the fingerprint looks like this: "ssh-rsa 1024 68:ff:d1:4e:6c:ff:d7:b0:d6:58:73:85:07:bc:2e:d5"
# str is a CkString object (output)
get_HttpProxyAuthMethod( str )
# newVal is a string (input)
put_HttpProxyAuthMethod( newVal )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy authentication method name. Valid choices are "LOGIN" or "NTLM".
# str is a CkString object (output)
get_HttpProxyHostname( str )
# newVal is a string (input)
put_HttpProxyHostname( newVal )
If an HTTP proxy is to be used, set this property to the HTTP proxy hostname or IPv4 address (in dotted decimal notation).
# str is a CkString object (output)
get_HttpProxyPassword( str )
# newVal is a string (input)
put_HttpProxyPassword( newVal )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy password.
# Returns an integer value
get_HttpProxyPort( )
# newVal is an integer (input)
put_HttpProxyPort( newVal )
If an HTTP proxy is to be used, set this property to the HTTP proxy port number. (Two commonly used HTTP proxy ports are 8080 and 3128.)
# str is a CkString object (output)
get_HttpProxyUsername( str )
# newVal is a string (input)
put_HttpProxyUsername( newVal )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy login name.
# Returns an integer value
get_IdleTimeoutMs( )
# newVal is an integer (input)
put_IdleTimeoutMs( newVal )
Causes SSH operations to fail when progress for sending or receiving data halts for more than this number of milliseconds. Setting IdleTimeoutMs = 0 (the default) allows the application to wait indefinitely.
# Returns a boolean value
get_IsConnected( )
Returns true if the component is connected to an SSH server.
Note: The IsConnected property is set to true after successfully completing the Connect method call. The IsConnected property will only be set to false by calling Disconnect, or by the failure of another method call such that the disconnection is detected.
# Returns a boolean value
get_KeepSessionLog( )
# newVal is a boolean (input)
put_KeepSessionLog( newVal )
Controls whether communications to/from the SSH server are saved to the SessionLog property. The default value is false. If this property is set to true, the contents of the SessionLog property will continuously grow as SSH activity transpires. The purpose of the KeepSessionLog / SessionLog properties is to help in debugging any future problems that may arise.
# str is a CkString object (output)
LastErrorHtml( str )
Error information in HTML format for the last method called.
# str is a CkString object (output)
LastErrorText( str )
Error information in plain-text format for the last method called.
# str is a CkString object (output)
LastErrorXml( str )
Error information in XML format for the last method called.
# Returns an integer value
get_MaxPacketSize( )
# newVal is an integer (input)
put_MaxPacketSize( newVal )
The maximum packet length to be used in the SSH transport protocol. The default value is 8192. (This should generally be left unchanged.)
# Returns an integer value
get_NumOpenChannels( )
The number of currently open channels.
# Returns a boolean value
get_PasswordChangeRequested( )
Set by the AuthenticatePw and AuthenticatePwPk methods. If the authenticate method returns a failed status, and this property is set to true, then it indicates the server requested a password change. In this case, re-call the authenticate method, but provide both the old and new passwords in the following format, where vertical bar characters encapsulate the old and new passwords:
|oldPassword|newPassword|
# Returns an integer value
get_ReadTimeoutMs( )
# newVal is an integer (input)
put_ReadTimeoutMs( newVal )
The maximum amount of time to allow for reading messages/data from the SSH server. This is different from the IdleTimeoutMs property. The IdleTimeoutMs is the maximum amount of time to wait while no incoming data is arriving. The ReadTimeoutMs is the maximum amount of time to allow for reading data even if data is continuing to arrive. The default value of 0 indicates an infinite timeout value.
# str is a CkString object (output)
get_SessionLog( str )
Contains a log of the messages sent to/from the SSH server. To enable session logging, set the KeepSessionLog property = true. Note: This property is not a filename -- it is a string property that contains the session log data.
# str is a CkString object (output)
get_SocksHostname( str )
# newVal is a string (input)
put_SocksHostname( newVal )
The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5).
# str is a CkString object (output)
get_SocksPassword( str )
# newVal is a string (input)
put_SocksPassword( newVal )
The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4.
# Returns an integer value
get_SocksPort( )
# newVal is an integer (input)
put_SocksPort( newVal )
The SOCKS4/SOCKS5 proxy port. The default value is 1080.
This property only applies if a SOCKS proxy is used (if the SocksVersion property is set to 4 or 5).
# str is a CkString object (output)
get_SocksUsername( str )
# newVal is a string (input)
put_SocksUsername( newVal )
The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5).
# Returns an integer value
get_SocksVersion( )
# newVal is an integer (input)
put_SocksVersion( newVal )
SocksVersion
May be set to one of the following integer values:
0 - No SOCKS proxy is used. This is the default.
4 - Connect via a SOCKS4 proxy.
5 - Connect via a SOCKS5 proxy.
# Returns a boolean value
get_StderrToStdout( )
# newVal is a boolean (input)
put_StderrToStdout( newVal )
If true, then stderr is redirected to stdout. In this case, channel output for both stdout and stderr is combined and retrievable via the following methods: GetReceivedData, GetReceivedDataN, GetReceivedText, GetReceivedTextS. If this property is false, then stderr is available separately via the GetReceivedStderr method.
The default value of this property is true.
# Returns a boolean value
get_TcpNoDelay( )
# newVal is a boolean (input)
put_TcpNoDelay( newVal )
Controls whether the TCP_NODELAY socket option is used for the underlying TCP/IP socket. The default value is true. This disables the Nagle algorithm and allows for better performance when small amounts of data are sent to/from the SSH server.
# Returns a boolean value
get_Utf8( )
# b is a boolean (input)
put_Utf8( b )
To be documented soon...
# Returns a boolean value
get_VerboseLogging( )
# newVal is a boolean (input)
put_VerboseLogging( newVal )
If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false.
# str is a CkString object (output)
get_Version( str )
A version string such as "2.1.0". This indicates the version of the Chilkat component.
Methods
# username is a string (input)
# Returns a boolean value
AuthenticatePk( username, privateKey )
Authenticates with the SSH server using public-key authentication. The corresponding public key must have been installed on the SSH server for the username. Authentication will succeed if the matching privateKey is provided.
Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com. Returns true for success, false for failure. Beware of too much time between connect and authentication.
# login is a string (input)
# password is a string (input)
# Returns a boolean value
AuthenticatePw( login, password )
Authenticates with the SSH server using a login and password.
An SSH session always begins by first calling Connect to connect to the SSH server, and then calling either AuthenticatePw or AuthenticatePk to login.
Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com.
Note: To learn about how to handle password change requests, see the PasswordChangeRequested property (above). Returns true for success, false for failure. Beware of too much time between connect and authentication.
# username is a string (input)
# password is a string (input)
# Returns a boolean value
AuthenticatePwPk( username, password, privateKey )
Authentication for SSH servers that require both a password and private key. (Most SSH servers are configured to require one or the other, but not both.)
Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com. Returns true for success, false for failure.
# channelNum is an integer (input)
# Returns a boolean value
ChannelIsOpen( channelNum )
Returns true if the channel indicated by channelNum is open. Otherwise returns false.
# channelNum is an integer (input)
# pollTimeoutMs is an integer (input)
# Returns an integer value
ChannelPoll( channelNum, pollTimeoutMs )
Polls for incoming data on an open channel. This method will read a channel, waiting at most pollTimeoutMs milliseconds for data to arrive. Return values are as follows:
-1 -- Error. Check the IsConnected property to see if the connection to the SSH server is still valid.
Also, call ChannelIsOpen to see if the channel remains open. The LastErrorText property will contain
more detailed information regarding the error.
-2 -- No additional data was received prior to the poll timeout.
>0 -- Additional data was received and the return value indicates how many bytes are available to be "picked up". Methods that read data on a channel do not return the received data directly. Instead, they return an integer
to indicate how many bytes are available to be "picked up". An application picks up the available data by calling
GetReceivedData or GetReceivedText.
# channelNum is an integer (input)
# Returns an integer value
ChannelRead( channelNum )
Reads incoming data on an open channel. This method will read a channel, waiting at most IdleTimeoutMs milliseconds for data to arrive. Return values are as follows:
-1 -- Error. Check the IsConnected property to see if the connection to the SSH server is still valid.
Also, call ChannelIsOpen to see if the channel remains open. The LastErrorText property will contain
more detailed information regarding the error.
-2 -- No additional data was received prior to the IdleTimeoutMs timeout.
>0 -- Additional data was received and the return value indicates how many bytes are available to be "picked up". Methods that read data on a channel do not return the received data directly. Instead, they return an integer
to indicate how many bytes are available to be "picked up". An application picks up the available data by calling
GetReceivedData or GetReceivedText.
# channelNum is an integer (input)
# pollTimeoutMs is an integer (input)
# Returns an integer value
ChannelReadAndPoll( channelNum, pollTimeoutMs )
Reads incoming data on an open channel and continues reading until no data arrives for pollTimeoutMs milliseconds. The first read will wait a max of IdleTimeoutMs milliseconds before timing out. Subsequent reads wait a max of pollTimeoutMs milliseconds before timing out.
The idea behind ChannelReadAndPoll is to capture the output of a shell command. One might imagine the typical sequence of events when executing a shell command to be like this: (1) client sends command to server, (2) server executes the command (i.e. it's computing...), potentially taking some amount of time, (3) output is streamed back to the client. It makes sense for the client to wait a longer period of time for the first data to arrive, but once it begins arriving, the timeout can be shortened. This is exactly what ChannelReadAndPoll does -- the first timeout is controlled by the IdleTimeoutMs property, while the subsequent reads (once output starts flowing) is controlled by pollTimeoutMs.
Return values are as follows:
-1 -- Error. Check the IsConnected property to see if the connection to the SSH server is still valid.
Also, call ChannelIsOpen to see if the channel remains open. The LastErrorText property will contain
more detailed information regarding the error.
-2 -- No additional data was received prior to the IdleTimeoutMs timeout.
>0 -- Additional data was received and the return value indicates how many bytes are available to be "picked up". Methods that read data on a channel do not return the received data directly. Instead, they return an integer
to indicate how many bytes are available to be "picked up". An application picks up the available data by calling
GetReceivedData or GetReceivedText.
# channelNum is an integer (input)
# pollTimeoutMs is an integer (input)
# maxNumBytes is an integer (input)
# Returns an integer value
ChannelReadAndPoll2( channelNum, pollTimeoutMs, maxNumBytes )
The same as ChannelReadAndPoll, except this method will return as soon as maxNumBytes is exceeded, which may be as large as the MaxPacketSize property setting.
# channelNum is an integer (input)
# Returns a boolean value
ChannelReceiveToClose( channelNum )
Reads incoming data on an open channel until the channel is closed by the server. If successful, the number of bytes available to be "picked up" can be determined by calling GetReceivedNumBytes. The received data may be retrieved by calling GetReceivedData or GetReceivedText. Returns true for success, false for failure.
# channelNum is an integer (input)
# matchPattern is a string (input)
# charset is a string (input)
# caseSensitive is a boolean (input)
# Returns a boolean value
ChannelReceiveUntilMatch( channelNum, matchPattern, charset, caseSensitive )
Reads incoming text data on an open channel until the received data matches the matchPattern. For example, to receive data until the string "Hello World" arrives, set matchPattern equal to "*Hello World*". charset indicates the character encoding of the text being received ("iso-8859-1" for example). caseSensitive may be set to true for case sensitive matching, or false for case insensitive matching.
Returns true if text data matching matchPattern was received and is available to be picked up by calling GetReceivedText (or GetReceivedTextS). IMPORTANT: This method may read beyond the matching text. Call GetReceivedTextS to extract only the data up-to and including the matching text. Returns true for success, false for failure.
# channelNum is an integer (input)
# matchPatterns is a CkStringArray object (output)
# charset is a string (input)
# caseSensitive is a boolean (input)
# Returns a boolean value
ChannelReceiveUntilMatchN( channelNum, matchPatterns, charset, caseSensitive )
The same as ChannelReceiveUntilMatch except that the method returns when any one of the match patterns specified in matchPatterns are received on the channel. Returns true for success, false for failure.
# channelNum is an integer (input)
# Returns a boolean value
ChannelReceivedClose( channelNum )
true if a CLOSE message has been received on the channel indicated by channelNum. When a CLOSE is received, no subsequent data should be sent in either direction -- the channel is closed in both directions.
# channelNum is an integer (input)
# Returns a boolean value
ChannelReceivedEof( channelNum )
true if an EOF message has been received on the channel indicated by channelNum. When an EOF is received, no more data will be forthcoming on the channel. However, data may still be sent in the opposite direction.
# channelNum is an integer (input)
# Returns a boolean value
ChannelReceivedExitStatus( channelNum )
true if an exit status code was received on the channel. Otherwise false.
# channelNum is an integer (input)
# Returns a boolean value
ChannelSendClose( channelNum )
Sends a CLOSE message to the server for the channel indicated by channelNum. This closes both directions of the bidirectional channel. Returns true for success, false for failure.
# channelNum is an integer (input)
# byteData is a CkByteData object (output)
# Returns a boolean value
ChannelSendData( channelNum, byteData )
Sends byte data on the channel indicated by channelNum. Returns true for success, false for failure.
# channelNum is an integer (input)
# Returns a boolean value
ChannelSendEof( channelNum )
Sends an EOF for the channel indicated by channelNum. Once an EOF is sent, no additional data may be sent on the channel. However, the channel remains open and additional data may still be received from the server. Returns true for success, false for failure.
# channelNum is an integer (input)
# textData is a string (input)
# charset is a string (input)
# Returns a boolean value
ChannelSendString( channelNum, textData, charset )
Sends character data on the channel indicated by channelNum. The text is converted to the charset indicated by charset prior to being sent. A list of supported charset values may be found on this page: Supported Charsets. Returns true for success, false for failure.
ClearTtyModes( )
To be documented soon.
# domainName is a string (input)
# port is an integer (input)
# Returns a boolean value
Connect( domainName, port )
Connects to the SSH server at domainName: port
The domainName may be a domain name or an IPv4 or IPv6 address in string format. Returns true for success, false for failure.
Disconnect( )
Disconnects from the SSH server.
# channelNum is an integer (input)
# Returns an integer value
GetChannelExitStatus( channelNum )
Returns the exit status code for a channel. This method should only be called if an exit status has been received. You may check to see if the exit status was received by calling ChannelReceivedExitStatus.
# index is an integer (input)
# Returns an integer value
GetChannelNumber( index )
Returns the channel number for the Nth open channel. Indexing begins at 0, and the number of currently open channels is indicated by the NumOpenChannels property. Returns -1 if the index is out of range.
# index is an integer (input)
# outStr is a CkString object (output)
# Returns a boolean value
GetChannelType( index, outStr )
Returns a string describing the channel type for the Nth open channel. Channel types are: "session", "x11", "forwarded-tcpip", and "direct-tcpip". Returns true for success, false for failure.
# channelNum is an integer (input)
# outBytes is a CkByteData object (output)
GetReceivedData( channelNum, outBytes )
Returns the accumulated data received on the channel indicated by channelNum and clears the channel's internal receive buffer.
# channelNum is an integer (input)
# maxNumBytes is an integer (input)
# outBytes is a CkByteData object (output)
# Returns a boolean value
GetReceivedDataN( channelNum, maxNumBytes, outBytes )
Same as GetReceivedData, but a maximum of maxNumBytes bytes is returned.
# channelNum is an integer (input)
# Returns an integer value
GetReceivedNumBytes( channelNum )
Returns the number of bytes available in the internal receive buffer for the specified channelNum. The received data may be retrieved by calling GetReceivedData or GetReceivedText.
# channelNum is an integer (input)
# outBytes is a CkByteData object (output)
GetReceivedStderr( channelNum, outBytes )
Returns the accumulated stderr bytes received on the channel indicated by ARG1 and clears the channel's internal stderr receive buffer.
Note: If the StderrToStdout property is set to true, then stderr is automatically redirected to stdout. This is the default behavior. The following methods can be called to retrieve the channel's stdout: GetReceivedData, GetReceivedDataN, GetReceivedText, and GetReceivedTextS.
# channelNum is an integer (input)
# charset is a string (input)
# outStr is a CkString object (output)
# Returns a boolean value
GetReceivedText( channelNum, charset, outStr )
Returns the accumulated text received on the channel indicated by channelNum and clears the channel's internal receive buffer. The charset indicates the charset of the character data in the internal receive buffer. A list of supported charset values may be found on this page: Supported Charsets. Returns true for success, false for failure.
# channelNum is an integer (input)
# substr is a string (input)
# charset is a string (input)
# outStr is a CkString object (output)
# Returns a boolean value
GetReceivedTextS( channelNum, substr, charset, outStr )
The same as GetReceivedText, except only the text up to and including substr is returned. The text returned is removed from the internal receive buffer. If the substr was not found in the internal receive buffer, an empty string is returned and the internal receive buffer is not modified. Returns true for success, false for failure.
# channelType is a string (input)
# Returns an integer value
OpenCustomChannel( channelType )
Opens a custom channel with a custom server that uses the SSH protocol. The channelType is application-defined.
If successful, the channel number is returned. This is the number that should be passed to any method requiring a channel number. A -1 is returned upon failure.
# targetHostname is a string (input)
# targetPort is an integer (input)
# Returns an integer value
OpenDirectTcpIpChannel( targetHostname, targetPort )
Open a direct-tcpip channel for port forwarding. Data sent on the channel via ChannelSend* methods is sent to the SSH server and then forwarded to targetHostname: targetPort. The SSH server automatically forwards data received from targetHostname: targetPort to the SSH client. Therefore, calling ChannelRead* and ChannelReceive* methods is equivalent to reading directly from targetHostname: targetPort.
If successful, the channel number is returned. This is the number that should be passed to any method requiring a channel number. A -1 is returned upon failure. SSH Tunnel (Port Forwarding via direct-tcpip channel)
# Returns an integer value
OpenSessionChannel( )
Opens a new session channel. Almost everything you will do with the Chilkat SSH component will involve opening a session channel. The normal sequence of operation is typically this: 1) Connect to the SSH server. 2) Authenticate. 3) Open a session channel. 4) do something on the channel such as opening a shell, execute a command, etc.
If successful, the channel number is returned. This is the number that should be passed to any method requiring a channel number. A -1 is returned upon failure.
# channelNum is an integer (input)
# charset is a string (input)
# outStr is a CkString object (output)
# Returns a boolean value
PeekReceivedText( channelNum, charset, outStr )
This is the same as GetReceivedText, except the internal receive buffer is not cleared. Returns true for success, false for failure.
# Returns a boolean value
ReKey( )
Initiates a re-key with the SSH server. The ReKey method does not return until the key re-exchange is complete.
RFC 4253 (the SSH Transport Layer Protocol) recommends that keys be changed after each gigabyte of transmitted data or after each hour of connection time, whichever comes sooner. Key re-exchange is a public-key operation and requires a fair amount of processing power and should not be performed too often. Either side (client or server) may initiate a key re-exchange at any time.
In most cases, a server will automatically initiate key re-exchange whenever it deems necessary, and the Chilkat SSH component handles these transparently. For example, if the Chilkat SSH component receives a re-key message from the server while in the process of receiving data on a channel, it will automatically handle the key re-exchange and the application will not even realize that an underlying key re-exchange occurred. Returns true for success, false for failure.
# filename is a string (input)
# Returns a boolean value
SaveLastError( filename )
Saves the last error information to an XML formatted file.
# Returns a boolean value
SendIgnore( )
Sends an IGNORE message to the SSH server. This is one way of verifying that the connection to the SSH server is open and valid. The SSH server does not response it an IGNORE message, it simply ignores it. IGNORE messages are not associated with a channel (in other words, you do not need to first open a channel prior to sending an IGNORE message). Returns true for success, false for failure.
# channelNum is an integer (input)
# commandLine is a string (input)
# Returns a boolean value
SendReqExec( channelNum, commandLine )
Initiates execution of a command on the channel specified by channelNum. The commandLine contains the full command line including any command-line parameters (just as you would type the command at a shell prompt).
The user's default shell (typically defined in /etc/password in UNIX systems) is started on the SSH server to execute the command.
Important: A channel only exists for a single request. You may not call SendReqExec multiple times on the same open channel. The reason is that the SSH server automatically closes the channel at the end of the exec. The solution is to call OpenSessionChannel to get a new channel, and then call SendReqExec using the new channel. It is OK to have more than one channel open simultaneously. Returns true for success, false for failure. Note about sending commands that produce no output. Note about sending interactive commands such as "more" SSH Exec (Execute Command Line) Multiple SendReqExec on Same Connection
# channelNum is an integer (input)
# termType is a string (input)
# widthInChars is an integer (input)
# heightInChars is an integer (input)
# widthInPixels is an integer (input)
# heightInPixels is an integer (input)
# Returns a boolean value
SendReqPty( channelNum, termType, widthInChars, heightInChars, widthInPixels, heightInPixels )
Requests a pseudo-terminal for a session channel. If the termType is a character oriented terminal ("vt100" for example), then widthInChars and heightInChars would be set to non-zero values, while widthInPixels and heightInPixels may be set to 0. If termType is pixel-oriented, such as "xterm", the reverse is true (i.e. set widthInPixels and heightInPixels, but set widthInChars and heightInChars equal to 0).
In most cases, you probably don't even want terminal emulation. In that case, try setting termType = "dumb". Terminal emulation causes terminal escape sequences to be included with shell command output. A "dumb" terminal should have no escape sequences.
Some SSH servers allow a shell to be started (via the SendReqShell method) without the need to first request a pseudo-terminal. The normal sequence for starting a remote shell is as follows:
1) Connect
2) Authenticate
3) OpenSessionChannel
4) Request a PTY via this method if necessary.
5) Start a shell by calling SendReqShell
Returns true for success, false for failure.
# channelNum is an integer (input)
# name is a string (input)
# value is a string (input)
# Returns a boolean value
SendReqSetEnv( channelNum, name, value )
Sets an environment variable in the remote shell. Returns true for success, false for failure.
# channelNum is an integer (input)
# Returns a boolean value
SendReqShell( channelNum )
Starts a shell on an open session channel. Some SSH servers require that a PTY (pseudo-terminal) first be requested prior to starting a shell. In that case, call SendReqPty prior to calling this method. Once a shell is started, commands may be sent by calling ChannelSendString. (Don't forget to terminate commands with a CRLF). Returns true for success, false for failure. SSH Remote Shell SSH -- Running Commands that Prompt for Additional Input, such as "su"
# channelNum is an integer (input)
# signalName is a string (input)
# Returns a boolean value
SendReqSignal( channelNum, signalName )
Delivers a signal to the remote process/service. signalName is one of the following: ABRT, ALRM, FPE, HUP, ILL, INT, KILL, PIPE, QUIT, SEGV, TERM, USR1, USR2. (Obviously, these are UNIX signals, so the remote SSH server would need to be a Unix/Linux system.) Returns true for success, false for failure.
# channelNum is an integer (input)
# subsystemName is a string (input)
# Returns a boolean value
SendReqSubsystem( channelNum, subsystemName )
Executes a pre-defined subsystem. The SFTP protocol (Secure File Transfer Protocol) is started by the Chilkat SFTP component by starting the "sftp" subsystem. Returns true for success, false for failure.
# channelNum is an integer (input)
# widthInChars is an integer (input)
# heightInRows is an integer (input)
# pixWidth is an integer (input)
# pixHeight is an integer (input)
# Returns a boolean value
SendReqWindowChange( channelNum, widthInChars, heightInRows, pixWidth, pixHeight )
To be documented soon...
# channelNum is an integer (input)
# singleConnection is a boolean (input)
# authProt is a string (input)
# authCookie is a string (input)
# screenNum is an integer (input)
# Returns a boolean value
SendReqX11Forwarding( channelNum, singleConnection, authProt, authCookie, screenNum )
To be documented soon...
# channelNum is an integer (input)
# clientCanDo is a boolean (input)
# Returns a boolean value
SendReqXonXoff( channelNum, clientCanDo )
To be documented soon...
# name is a string (input)
# value is an integer (input)
# Returns a boolean value
SetTtyMode( name, value )
To be documented soon...
# unlockCode is a string (input)
# Returns a boolean value
UnlockComponent( unlockCode )
Unlocks the component. This must be called once prior to calling any other method. A fully-functional 30-day trial is automatically started when an arbitrary string is passed to this method. For example, passing "Hello", or "abc123" will unlock the component for the 1st thirty days after the initial install. Returns true for success, false for failure. Diagnosing UnlockComponent Problems UnlockComponent LastErrorText shows exact string passed to it. Verify UnlockComponent Success w/ Permanent Unlock Code LastErrorText Standard Information How UnlockComponent Works
# Returns a string
channelOpenFailReason( )
The descriptive text corresponding to the ChannelOpenFailCode property. Returns a null on failure
# Returns a string
clientIdentifier( )
The client-identifier string to be used when connecting to an SSH/SFTP server. Defaults to "SSH-2.0-PuTTY_Local:_Jun_27_2008_16:28:58". (This string is used to mimic PuTTY because some servers are known to disconnect from clients with unknown client identifiers.) Returns a null on failure
# Returns a string
clientIpAddress( )
The IP address to use for computers with multiple network interfaces or IP addresses.
For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.
The IP address is a string such as in dotted notation using numbers, not domain names, such as "165.164.55.124". Returns a null on failure
# Returns a string
debugLogFilePath( )
Used for debugging in cases where a Chilkat method call hangs and never returns. This should generally never happen. The only causes for this are (1) a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired, (2) the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or (3) there is an internal problem (bug) in the Chilkat code that causes the hang.
This property allows one to specifiy a debug file path that will be created (or appended if it already exists) and information will be logged to it as the Chilkat methods are called. If a hang occurs, the log file may be viewed to get information about what happened. Returns a null on failure
# Returns a string
disconnectReason( )
If the SSH/ server sent a DISCONNECT message when closing the connection, this property contains a descriptive string for the "reason code" as specified in RFC 4253. Returns a null on failure
# index is an integer (input)
# Returns a string
getChannelType( index )
Returns a string describing the channel type for the Nth open channel. Channel types are: "session", "x11", "forwarded-tcpip", and "direct-tcpip". Returns a null on failure
# channelNum is an integer (input)
# charset is a string (input)
# Returns a string
getReceivedText( channelNum, charset )
Returns the accumulated text received on the channel indicated by channelNum and clears the channel's internal receive buffer. The charset indicates the charset of the character data in the internal receive buffer. A list of supported charset values may be found on this page: Supported Charsets. Returns a null on failure
# channelNum is an integer (input)
# substr is a string (input)
# charset is a string (input)
# Returns a string
getReceivedTextS( channelNum, substr, charset )
The same as GetReceivedText, except only the text up to and including substr is returned. The text returned is removed from the internal receive buffer. If the substr was not found in the internal receive buffer, an empty string is returned and the internal receive buffer is not modified. Returns a null on failure
# Returns a string
hostKeyFingerprint( )
Set after connecting to an SSH server. The format of the fingerprint looks like this: "ssh-rsa 1024 68:ff:d1:4e:6c:ff:d7:b0:d6:58:73:85:07:bc:2e:d5" Returns a null on failure
# Returns a string
httpProxyAuthMethod( )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy authentication method name. Valid choices are "LOGIN" or "NTLM". Returns a null on failure
# Returns a string
httpProxyHostname( )
If an HTTP proxy is to be used, set this property to the HTTP proxy hostname or IPv4 address (in dotted decimal notation). Returns a null on failure
# Returns a string
httpProxyPassword( )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy password. Returns a null on failure
# Returns a string
httpProxyUsername( )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy login name. Returns a null on failure
# Returns a string
lastErrorHtml( )
Error information in HTML format for the last method called.Returns a null on failure
# Returns a string
lastErrorText( )
Error information in plain-text format for the last method called.Returns a null on failure
# Returns a string
lastErrorXml( )
Error information in XML format for the last method called.Returns a null on failure
# channelNum is an integer (input)
# charset is a string (input)
# Returns a string
peekReceivedText( channelNum, charset )
This is the same as GetReceivedText, except the internal receive buffer is not cleared. Returns a null on failure
# Returns a string
sessionLog( )
Contains a log of the messages sent to/from the SSH server. To enable session logging, set the KeepSessionLog property = true. Note: This property is not a filename -- it is a string property that contains the session log data. Returns a null on failure
# Returns a string
socksHostname( )
The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5). Returns a null on failure
# Returns a string
socksPassword( )
The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4. Returns a null on failure
# Returns a string
socksUsername( )
The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5). Returns a null on failure
# Returns a string
version( )
A version string such as "2.1.0". This indicates the version of the Chilkat component. Returns a null on failure
|