SshTunnel

Set this property to true from another thread to request that the currently running foreground operation be aborted. For example, it can interrupt a synchronous Connect that is waiting for an SSH server response.

This property does not stop the background listener or terminate established background tunnel clients.

Contains the in-memory activity log for the background listener thread started by BeginAccepting.

The log is populated only when KeepAcceptLog is true.

Specifies the local file path where activity from the background listener thread is written.

This file-based log is separate from the in-memory AcceptLog.

Specifies the SSH client-identification string sent when connecting to the SSH server.

Starting in Chilkat v9.5.0.99, the default is SSH-2.0-Chilkat_ followed by the Chilkat version number, such as SSH-2.0-Chilkat_9.5.0.99.

Specifies the local directory where a separate log file is created for each tunnel client.

When this property is not empty, files are named using the pattern tunnel_client_log_{random_id}.txt.

Specifies the maximum number of milliseconds allowed for establishing the SSH connection.

• The default value is 30000 milliseconds (30 seconds).
• A value of 0 disables the connection timeout and allows an unlimited wait.

The timeout applies to more than the initial TCP connection. It also covers connection setup performed through an HTTP or SOCKS proxy and waiting for the SSH server identification string after the TCP connection has been established.

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

• A timeout property set to 0, indicating an infinite timeout.
• A hang occurring within an event callback in the application code.
• An internal bug in the Chilkat code causing the hang.

Specifies the destination hostname or IP address for fixed-destination port forwarding. This is typically the host running the database server or other TCP service that local clients need to reach.

The destination is interpreted from the SSH server's network environment. For example, localhost and 127.0.0.1 refer to the SSH server itself, not the computer running the application. Hostname resolution is therefore performed as part of the forwarding request on the SSH-server side.

Traffic accepted by the local listener is carried through SSH, forwarded by the SSH server to this destination, and returned through the same tunnel.

Specifies the TCP port of the destination service used for fixed-destination forwarding, such as the port of a database server.

It is used together with DestHostname and is ignored when DynamicPortForwarding is true.

Controls whether the listener performs fixed-destination or dynamic port forwarding.

• When false (the default), every accepted connection is forwarded to DestHostname and DestPort.
• When true, the listener acts as a SOCKS proxy and each inbound client supplies its own destination.

The SOCKS version is detected independently from each inbound client handshake; there is no separate inbound SOCKS-version property. SOCKS4 and SOCKS5 CONNECT requests are supported. SOCKS5 BIND and UDP association are not supported.

Leave InboundSocksUsername empty to allow SOCKS5 clients to use the no-authentication method. Set the inbound username and password to require SOCKS5 username/password authentication. For SOCKS4, only the user ID can be checked because SOCKS4 has no password field.

Enables automatic resolution of credentials from secure storage provided by the operating system.

When set to true, supported password properties and methods may receive a secret specification string beginning with !! instead of a literal password. Chilkat resolves the secret from:

• Windows Credential Manager on Windows.
• Apple Keychain on macOS.

The specification format is: !![appName|]service[|domain]|username

This applies to HttpProxyPassword, SocksPassword, AuthenticatePw, and AuthenticatePwPk.

The default value is false.

Contains the SSH server host-key fingerprint after Connect or ConnectThroughSsh establishes the SSH connection. The value is available before user authentication.

Example: ssh-ed25519 256 e0:33:b1:81:a5:c6:9a:d2:2e:c9:d3:15:60:ea:cf:4c

Compare this value with a trusted expected fingerprint to verify the identity of the SSH server. For ConnectThroughSsh, the fingerprint is for the final SSH server, not the first-hop server.

Specifies the authentication method to use when the outbound connection to the SSH server passes through an HTTP proxy that requires authentication.

Valid values are Basic and NTLM.

If SocksVersion is set to 4 or 5, the SOCKS proxy takes precedence and these HTTP proxy settings are ignored. The proxies are not chained.

Specifies the optional Windows domain used for NTLM authentication with the HTTP proxy.

This applies only to the outbound proxy connection used to reach the SSH server, and only when HttpProxyAuthMethod is NTLM.

If SocksVersion is set to 4 or 5, the SOCKS proxy takes precedence and these HTTP proxy settings are ignored. The proxies are not chained.

Specifies the hostname or IPv4 address of the HTTP proxy through which the outbound connection to the SSH server is made.

Leave this property empty when no HTTP proxy is required.

If SocksVersion is set to 4 or 5, the SOCKS proxy takes precedence and these HTTP proxy settings are ignored. The proxies are not chained.

Specifies the password used to authenticate with the HTTP proxy for the outbound connection to the SSH server.

If SocksVersion is set to 4 or 5, the SOCKS proxy takes precedence and these HTTP proxy settings are ignored. The proxies are not chained.

Specifies the TCP port of the HTTP proxy used for the outbound connection to the SSH server.

Common HTTP proxy ports include 8080 and 3128.

If SocksVersion is set to 4 or 5, the SOCKS proxy takes precedence and these HTTP proxy settings are ignored. The proxies are not chained.

Specifies the username used to authenticate with the HTTP proxy for the outbound connection to the SSH server.

If SocksVersion is set to 4 or 5, the SOCKS proxy takes precedence and these HTTP proxy settings are ignored. The proxies are not chained.

Specifies a stall timeout, in milliseconds, for tunnel data-transfer operations. The default value is 30000 milliseconds (30 seconds). A value of 0 disables the timeout.

Specifies the password required from inbound SOCKS5 clients when DynamicPortForwarding is true.

This property is used together with InboundSocksUsername. It does not apply to SOCKS4 because the SOCKS4 protocol has no password field.

Specifies the username required from inbound SOCKS clients when DynamicPortForwarding is true.

• For SOCKS5, setting this property enables username/password authentication.
• For SOCKS4, the value is compared with the client-supplied user ID.
• Leave it empty to require no inbound SOCKS username.

true when the local listener thread is running and accepting inbound TCP connections; otherwise false.

This property describes only the local listener. It can remain true after the SSH connection is lost or after CloseTunnel is called. In those states a client may connect to the local port even though its traffic cannot be forwarded.

Use IsSshConnected separately when the application also needs to know whether the SSH transport is available.

Controls whether activity from the background listener thread is retained in memory.

The default value is false. When enabled, retrieve the log from AcceptLog.

Controls whether SSH tunnel-thread activity is retained in memory.

The default value is false. When enabled, retrieve the log from TunnelLog.

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

Specifies the local IPv4 address to which the tunnel's listening socket is bound.

If the value is malformed or is not assigned to a local interface, BeginAccepting returns false and the bind failure is available in LastErrorText and the accept log.

Contains the local TCP port used by the listener started by BeginAccepting.

• If BeginAccepting succeeds with a nonzero requested port, this property contains that port.
• If BeginAccepting succeeds with 0, the operating system chooses an available port and this property contains the allocated port when the method returns.
• After a bind failure for an explicitly requested port, this property may still contain the requested port even though IsAccepting is false.
• The value is initially 0.

Specifies the local IP address to which the outbound socket is bound before connecting to the SSH server.

Most applications should leave this property empty. Set it only on a multihomed computer when the SSH connection must originate from a specific local network interface or IP address.

Specifies the local TCP port to bind before making the outbound connection to the SSH server.

The default value is 0, which allows the operating system to choose an available ephemeral port. Nearly all applications should leave this property unchanged.

Controls which IP version is preferred when a hostname resolves to both IPv4 and IPv6 addresses.

• false (the default) prefers IPv4.
• true prefers IPv6.

Specifies the hostname or IPv4 address of the outbound SOCKS4 or SOCKS5 proxy used to reach the SSH server.

This property is used only when SocksVersion is 4 or 5.

Specifies the password for authenticating with an outbound SOCKS5 proxy used to reach the SSH server.

SOCKS4 does not support password authentication, so this property does not apply when SocksVersion is 4.

Specifies the TCP port of the outbound SOCKS4 or SOCKS5 proxy used to reach the SSH server.

The default value is 1080. This property is used only when SocksVersion is 4 or 5.

Specifies the username for the outbound SOCKS4 or SOCKS5 proxy used to reach the SSH server.

This property is used only when SocksVersion is 4 or 5.

Selects whether the outbound connection to the SSH server is made through a SOCKS proxy.

When this property is 4 or 5, the SOCKS proxy settings take precedence over the HTTP proxy settings. The SOCKS and HTTP proxies are not chained.

Sets the receive-buffer size for the underlying TCP socket.

The default value is 4194304 bytes. Normally this property should remain unchanged. If receive performance is unusually slow, testing a larger value that is a multiple of 4096 may help.

Sets the send-buffer size for the underlying TCP socket.

The default value is 262144 bytes. Normally this property should remain unchanged. If send performance is unusually slow, testing values such as 524288 or 1048576 may help. A multiple of 4096 is recommended.

Controls the TCP_NODELAY socket option for the underlying TCP connection.

The default value is false. Setting it to true disables the Nagle algorithm, which can reduce latency when many small amounts of data are sent.

Contains the in-memory activity log for the SSH tunnel and client-manager threads. The log is populated only when KeepTunnelLog is true.

Specifies the local file path where SSH tunnel-thread activity is written.

This file-based log is separate from the in-memory TunnelLog.

Provides optional behavior for uncommon requirements. The default value is an empty string, which is appropriate for most applications.

To enable more than one option, provide a comma-separated list of keywords.

If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

Version of the component/library, such as "10.1.0"

Authenticates with the SSH server using public-key authentication.

The public key corresponding to privateKey must already be installed for username on the SSH server.

Call Connect or ConnectThroughSsh before calling this method.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Authenticates with the SSH server using login and password.

Establish the SSH connection first by calling Connect or ConnectThroughSsh. After authentication succeeds, call BeginAccepting to begin accepting tunnel clients.

• A rejected username or password does not close the SSH connection; the application may correct the credentials and call this method again.
• Calling this method again after authentication has already succeeded returns false with an “Already authenticated” error.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Authenticates with an SSH server that requires both a password and a private key.

The public key corresponding to privateKey must already be installed for username on the SSH server. Most SSH servers require either password authentication or public-key authentication rather than both.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Performs the same password authentication as AuthenticatePw, but receives the login and password in SecureString objects.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Performs the same combined password-and-private-key authentication as AuthenticatePwPk, but receives the username and password in SecureString objects.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Creates and starts the local listener on listenPort.

The SSH connection must already have been established. Although the listener can be started before user authentication, clients accepted in that state cannot be forwarded. The recommended sequence is to connect, authenticate, and then call this method.

• The requested port must not already be in use on the selected local interface.
• Pass 0 to let the operating system choose an available port, then read ListenPort.
• Calling this method while the listener is already running returns false.

The method waits for the initial bind-and-listen result. It returns false for errors such as an occupied port, a malformed bind address, or an address that is not assigned to the local computer. Details are available immediately in LastErrorText and, when enabled, the accept log.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Disconnects active tunnel clients and stops the tunnel-manager thread.

When waitForThreads is true, the method waits for the client and tunnel-manager threads to exit. It returns false if a worker thread does not stop; capture LastErrorText immediately for details.

Calling this method more than once is allowed. However, it does not reset the object for a new call to Connect. Use a new SshTunnel object when connecting to a different SSH server.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Establishes the SSH connection that will carry tunneled traffic. This method performs the TCP or proxy connection, the SSH protocol handshake, and host-key negotiation, but it does not authenticate the SSH user.

After connecting, verify HostKeyFingerprint, then authenticate by calling one of the Authenticate* methods. Finally, call BeginAccepting to start the local listener.

The host-key fingerprint is available immediately after this method succeeds, before user authentication. Calling Connect again while an SSH tunnel already exists returns false.

Chilkat sends an SSH ignore message every 20 seconds to help keep an unused SSH connection alive. To disable this behavior, add NoKeepAliveIgnoreMsg to UncommonOptions before connecting.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Connects to a second SSH server through the existing connected and authenticated Ssh object supplied in ssh.

application -> first SSH server -> second SSH server

hostname and port identify the second SSH server. After this method succeeds, call an authentication method on this SshTunnel object to authenticate with the second server.

The supplied Ssh object is borrowed, not copied. It must remain alive, connected, and authenticated for as long as this tunnel is used. If the first-hop object is disconnected, existing forwarded clients stop working and new local connections cannot be forwarded. The local listener may nevertheless remain active until explicitly stopped.

HostKeyFingerprint reports the fingerprint of the second SSH server. After the connection is established, fixed forwarding destinations such as 127.0.0.1 are interpreted from the second server's network environment.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Continues a keyboard-interactive authentication exchange started by StartKeyboardAuth.

If the server requested one response, pass that value directly in response. If it requested multiple responses, pass XML in the following form:

<response>
  <response1>response to first prompt</response1>
  <response2>response to second prompt</response2>
  ...
  <responseN>response to Nth prompt</responseN>
</response>

When authentication completes, the returned XML indicates success or failure:

<success>success message</success>

<error>error message</error>

If another challenge is required, the method returns another infoRequest XML document containing the next set of prompts.

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

Disconnects all active tunnel clients while leaving the local listener and SSH connection available.

When waitForThreads is true, the method waits for the current client threads to exit before returning. The listener continues accepting new clients, and newly accepted clients can be forwarded normally.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Returns an XML snapshot describing the tunnel manager, SSH channels, and current tunnel clients. The returned data is intended for diagnostics and monitoring.

A typical result has the following structure:

<CurrentState>
  <tunnelManager rcvByteCount="433" sndByteCount="34"
      threadRunning="1" dynamicPortForwarding="0"
      staticDestHost="localhost" staticDestPort="18080">
    <openChannels count="1">
      <channel num="101" channelType="direct-tcpip"
          clientWinSize="2096927" serverWinSize="2097127" />
    </openChannels>
    <closedChannels count="0" />
  </tunnelManager>
  <clients count="1">
    <client destIp="localhost" destPort="18080"
        sshChannelNum="101" threadRunning="1"
        rcvByteCount="25" sndByteCount="225" />
  </clients>
</CurrentState>

The exact child elements can vary with state. For example, channel collections may be empty, and some transport details may be omitted before the tunnel is started or after it stops.

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

Returns true when the SSH transport used by this tunnel is connected; otherwise returns false.

This is independent of the local listener state. The listener may still be accepting local TCP connections when this method returns false, but those connections cannot be forwarded until a usable SSH transport exists.

For a tunnel created with ConnectThroughSsh, this method becomes false when the borrowed first-hop Ssh connection is disconnected.

Restricts the SSH connection to the algorithms specified in json.

This allows an application to define the exact algorithm set that may be used during SSH negotiation.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Begins keyboard-interactive authentication for login.

When the server requests one or more responses, the returned XML contains the request name, instructions, and prompts:

<infoRequest numPrompts="N">
  <name>name text</name>
  <instruction>instruction text</instruction>
  <prompt1 echo="1_or_0">prompt text</prompt1>
  ...
  <promptN echo="1_or_0">prompt text</promptN>
</infoRequest>

The echo attribute indicates whether the response should be displayed while entered.

If authentication immediately succeeds or fails without requiring a response, the returned XML has one of these forms:

<success>success message</success>

<error>error message</error>

Pass the requested response or responses to ContinueKeyboardAuth.

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

Stops the local listener so that no new client connections are accepted. Existing forwarded clients remain connected and continue exchanging data.

• When waitForThread is true, the method waits for the listener thread to exit before returning.
• When it is false, shutdown is asynchronous and IsAccepting may remain true briefly after the method returns.

Call BeginAccepting again to resume accepting connections. The listener can be restarted on the same port after the previous listener has stopped.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

Enables a method call to be aborted by triggering the AbortCheck event at intervals defined by the HeartbeatMs property. If HeartbeatMs is set to its default value of 0, no events will occur. For instance, set HeartbeatMs to 200 to trigger 5 AbortCheck events per second.

Example

const Abort = struct {
    stop: std.atomic.Value(bool) = .init(false),
    pub fn abortCheck(self: *Abort) bool {
        return self.stop.load(.acquire); // another thread may call abort.stop.store(true, .release)
    }
};

var abort = Abort{};
ssh_tunnel.setHeartbeatMs(250); // call abortCheck 4 times per second
ssh_tunnel.setEventHandler(&abort);
defer ssh_tunnel.clearEventHandler();

This provides the percentage completion for any method involving network communications or time-consuming processing, assuming the progress can be measured as a percentage. This event is triggered only when it's possible and logical to express the operation's progress as a percentage. The pctDone argument will range from 1 to 100. For methods that finish quickly, the number of PercentDone callbacks may vary, but the final callback will have pctDone equal to 100. For longer operations, callbacks will not exceed one per percentage point (e.g., 1, 2, 3, ..., 98, 99, 100).

The PercentDone callback also acts as an AbortCheck event. For fast methods where PercentDone fires, an AbortCheck event may not trigger since the PercentDone callback already provides an opportunity to abort. For longer operations, where time between PercentDone callbacks is extended, AbortCheck callbacks enable more responsive operation termination.

To abort the operation, set the abort output argument to true. This will cause the method to terminate and return a failure status or corresponding failure value.

Example

const Progress = struct {
    pub fn percentDone(_: *Progress, pct: i32) bool {
        // pct ranges from 1 to 100.
        std.debug.print("Percent done: {d}\n", .{pct});
        return false; // return true to abort the method in progress
    }
};

var progress = Progress{};
ssh_tunnel.setEventHandler(&progress);
defer ssh_tunnel.clearEventHandler();

This event callback provides tag name/value pairs that detail what occurs during a method call. To discover existing tag names, create code to handle the event, emit the pairs, and review them. Most tag names are self-explanatory.

Note: Some Chilkat methods don't fire any ProgressInfo events.

Example

const Info = struct {
    pub fn progressInfo(_: *Info, name: [:0]const u8, value: [:0]const u8) void {
        std.debug.print("{s}: {s}\n", .{ name, value });
    }
};

var info = Info{};
ssh_tunnel.setEventHandler(&info);
defer ssh_tunnel.clearEventHandler();