CkSshTunnel Perl Programming
Reference Documentation

CkSshTunnel

A software API that makes it possible to create self-managed SSH tunnels in a background thread of an application. Each SSH tunnel object manages two background threads: a thread for accepting new connections, and a tunnel-pool thread for existing (running) SSH tunnels. This API eliminates the need for separate, standalone SSH tunnel processes (such as PUtty). Your application may use SSH tunneling on any computer where it's installed, without the need for additional SSH tunneling software/infrastructure.

Object Creation

$obj = new chilkat::CkSshTunnel();

Properties

# str is a CkString object (output)
get_AcceptThreadSessionLogPath( str )

# newVal is a string (input)
put_AcceptThreadSessionLogPath( newVal )

To be documented soon...

# str is a CkString object (output)
get_ConnectLog( str )

# newVal is a string (input)
put_ConnectLog( newVal )

Contains log text detailing the establishment of each SSH server connection. This log will continue to grow as new connections are accepted. This property may be cleared by setting it to an empty string.

# 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. The default value is 10000 (i.e. 10 seconds).

# str is a CkString object (output)
get_DestHostname( str )

# newVal is a string (input)
put_DestHostname( newVal )

The destination hostname or IP address (in dotted decimal notation) of the service (such as a database server). Data sent through the SSH tunnel is forwarded by the SSH server to this destination. Data received from the destination (by the SSH server) is forwarded back to the client through the SSH tunnel.

# Returns an integer value
get_DestPort( )

# newVal is an integer (input)
put_DestPort( newVal )

The destination port of the service (such as a database server).

# 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 a boolean value
get_IsAccepting( )

1 if a background thread is running and accepting connections.

# 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.

# str is a CkString object (output)
get_ListenBindIpAddress( str )

# newVal is a string (input)
put_ListenBindIpAddress( newVal )

In most cases, this property does not need to be set. It is provided for cases where it is required to bind the listen socket to a specific IP address (usually 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.

# Returns an integer value
get_ListenPort( )

If a port number equal to 0 is passed to BeginAccepting, then this property will contain the actual allocated port number used. Otherwise it is equal to the port number passed to BeginAccepting, or 0 if BeginAccepting was never 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 32768.

# str is a CkString object (output)
get_OutboundBindIpAddress( str )

# newVal is a string (input)
put_OutboundBindIpAddress( newVal )

In most cases, this property does not need to be set. It is provided for cases where it is required to bind the socket that is to connect to the SSH server (in the background thread) to a specific IP address (usually 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.

# Returns an integer value
get_OutboundBindPort( )

# newVal is an integer (input)
put_OutboundBindPort( newVal )

Unless there is a specific requirement for binding to a specific port, leave this unset (at the default value of 0). (99.9% of all users should never need to set this property.)

# 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.

# str is a CkString object (output)
get_SshHostname( str )

# newVal is a string (input)
put_SshHostname( newVal )

The SSH server's hostname or IP address (in dotted-decimal notation).

# str is a CkString object (output)
get_SshLogin( str )

# newVal is a string (input)
put_SshLogin( newVal )

The SSH server login. Authentication is typically required to establish the SSH tunnel in the background thread.

# str is a CkString object (output)
get_SshPassword( str )

# newVal is a string (input)
put_SshPassword( newVal )

The SSH server password.

# Returns an integer value
get_SshPort( )

# newVal is an integer (input)
put_SshPort( newVal )

The SSH server's port. The default is 22, and this typically won't change.

# 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 0. Setting this property equal to 1 disables the Nagle algorithm and allows for better performance when small amounts of data are sent.

# str is a CkString object (output)
get_TunnelThreadSessionLogPath( str )

# newVal is a string (input)
put_TunnelThreadSessionLogPath( newVal )

To be documented soon...

# Returns a boolean value
get_Utf8( )

# b is a boolean (input)
put_Utf8( b )

To be documented soon...

Methods

# listenPort is an integer (input)
# Returns a boolean value
BeginAccepting( listenPort )

Starts a background thread for listening on listenPort. A new SSH tunnel is created and managed for each accepted connection. SSH tunnels are managed in a 2nd background thread: the SSH tunnel pool thread.

BeginAccepting starts a background thread that creates a socket, binds to the port, and begins listening. If the bind fails (meaning something else may have already bound to the same port), then the background thread exits. You may check to see if BeginAccepting succeeds by waiting a short time (perhaps 50 millisec) and then examine the IsAccepting property. If it is 0, then BeginAccepting failed.

Returns 1 for success, 0 for failure.

SSH Tunnel for Database Connection (such as ADO, ODBC, etc.)

# outStr is a CkString object (output)
# Returns a boolean value
GetTunnelsXml( outStr )

Returns information about the current set of running SSH tunnels. This is a snapshot of the tunnels at a single point in time. The XML has this format:

<tunnels>
	<t>
		<uniqueId>...</uniqueId>
		<clientIp>...</clientIp>
		<clientPort>...</clientPort>
		<serverIp>...</serverIp>
		<serverPort>...</serverPort>
		<tunnelType>...</tunnelType>
		<login>...</login>
		<password>...</password>
	</t>
	<t>
	...
	</t>
	...
</tunnels>

Returns 1 for success, 0 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
SetSshAuthenticationKey( key )

Sets the key to be used for public-key SSH authentication. NOTE: The private key is required for authentication. The public-part of the key is installed on the server, and the client must present the private key.

Returns 1 for success, 0 for failure.

# Returns a boolean value
StopAccepting( )

Stops the listen background thread. It is possible to continue accepting connections by re-calling BeginAccepting.

Returns 1 for success, 0 for failure.

# maxWaitMs is an integer (input)
# Returns a boolean value
StopAllTunnels( maxWaitMs )

Stops all currently running tunnels in the SSH tunnel pool background thread.

Returns 1 for success, 0 for failure.

# 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 1 for success, 0 for failure.

# Returns a string
acceptThreadSessionLogPath( )

To be documented soon...

# Returns a string
connectLog( )

Contains log text detailing the establishment of each SSH server connection. This log will continue to grow as new connections are accepted. This property may be cleared by setting it to an empty string.

Returns a null on failure

# Returns a string
destHostname( )

The destination hostname or IP address (in dotted decimal notation) of the service (such as a database server). Data sent through the SSH tunnel is forwarded by the SSH server to this destination. Data received from the destination (by the SSH server) is forwarded back to the client through the SSH tunnel.

Returns a null on failure

# Returns a string
getTunnelsXml( )

Returns information about the current set of running SSH tunnels. This is a snapshot of the tunnels at a single point in time. The XML has this format:

<tunnels>
	<t>
		<uniqueId>...</uniqueId>
		<clientIp>...</clientIp>
		<clientPort>...</clientPort>
		<serverIp>...</serverIp>
		<serverPort>...</serverPort>
		<tunnelType>...</tunnelType>
		<login>...</login>
		<password>...</password>
	</t>
	<t>
	...
	</t>
	...
</tunnels>

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

# Returns a string
listenBindIpAddress( )

In most cases, this property does not need to be set. It is provided for cases where it is required to bind the listen socket to a specific IP address (usually 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.

Returns a null on failure

# Returns a string
outboundBindIpAddress( )

In most cases, this property does not need to be set. It is provided for cases where it is required to bind the socket that is to connect to the SSH server (in the background thread) to a specific IP address (usually 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.

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
sshHostname( )

The SSH server's hostname or IP address (in dotted-decimal notation).

Returns a null on failure

# Returns a string
sshLogin( )

The SSH server login. Authentication is typically required to establish the SSH tunnel in the background thread.

Returns a null on failure

# Returns a string
sshPassword( )

The SSH server password.

Returns a null on failure

# Returns a string
tunnelThreadSessionLogPath( )

To be documented soon...