Quick Start

Remote Command Execution

uses libssh2;

var sess := Connect('server.example.com', 22);
AuthPassword(sess, 'deploy', 'secret');

var r := Exec(sess, 'df -h /');
WriteLn(r.Stdout);
WriteLn('Exit code: ' + IntToStr(r.ExitCode));

Disconnect(sess);

SFTP Upload & Directory Listing

uses libssh2;

var sess := Connect('server.example.com', 22);
AuthPublicKey(sess, 'deploy', '/home/user/.ssh/id_rsa.pub',
              '/home/user/.ssh/id_rsa', '');

var sftp := OpenSFTP(sess);
SFTPUpload(sftp, 'C:\builds\app', '/home/deploy/app');
WriteLn('Upload OK');

var files := SFTPListDir(sftp, '/home/deploy');
for var f in files do
  WriteLn(f.Name + '  ' + IntToStr(f.Size) + ' bytes');

CloseSFTP(sftp);
Disconnect(sess);

TCP Tunnel through SSH Bastion

uses libssh2;

{ Connect to a database through SSH bastion }
var sess := Connect('bastion.example.com', 22);
AuthAgent(sess, 'admin');

var ch := OpenTunnel(sess, 'internal-db.lan', 5432);
{ use ChannelRead/ChannelWrite to communicate with PostgreSQL }
ChannelClose(ch);
Disconnect(sess);

Session API

A session represents a single TCP connection to an SSH server. All operations require an active, authenticated session.

Authentication API

Authentication must be performed after Connect and before any channel or SFTP operations. Use GetAuthMethods to discover what the server supports.

Remote Execution API

Execute shell commands on the remote server. Exec is the simplest path for single commands; ExecOpen gives streaming access to stdout/stderr for long-running processes.

SFTP API

SFTP (SSH File Transfer Protocol) is the recommended way to transfer files over SSH. It supports directory listing, stat, rename, delete, and partial reads/writes — unlike SCP.

SCP API

SCP is a simpler single-file transfer protocol built directly on SSH channels. It lacks directory listing, rename, and stat operations.

Port Forwarding

Open a TCP tunnel through the SSH connection to reach services on the remote network that are not directly accessible from the client.

Tunnel example: talk to an internal PostgreSQL server

uses libssh2;

var sess := Connect('bastion.example.com', 22);
AuthPublicKey(sess, 'jump-user',
  '/home/ci/.ssh/id_ed25519.pub',
  '/home/ci/.ssh/id_ed25519', '');

{ open tunnel to internal PostgreSQL port }
var ch := OpenTunnel(sess, 'db.internal.lan', 5432);

{ send PostgreSQL startup message, read authentication response, etc. }
ChannelWrite(ch, startupMsg);
var resp := ChannelRead(ch, 4096);

ChannelClose(ch);
Disconnect(sess);

TSFTPFileInfo Record

Returned by SFTPListDir and SFTPStat. Contains metadata for a remote filesystem entry.

Listing example

uses libssh2;

var sftp  := OpenSFTP(sess);
var files := SFTPListDir(sftp, '/var/www/html');

for var f in files do begin
  if f.IsDir then
    WriteLn('[DIR]  ' + f.Name)
  else
    WriteLn(Format('%-32s  %8d bytes  mode=%o',
      [f.Name, f.Size, f.Permissions and $1FF]));
end;

Key Concepts

Recommended session pattern

uses libssh2;

var sess := Connect('host', 22);
try begin
  { 1. verify host key before trusting the server }
  var hk := GetHostKey(sess);
  if hk.SHA256 <> KNOWN_FINGERPRINT then
    raise 'Host key mismatch — possible MITM attack';

  { 2. authenticate with a key pair }
  AuthPublicKey(sess, 'deploy',
    '/run/secrets/id_ed25519.pub',
    '/run/secrets/id_ed25519', '');

  { 3. do work }
  var r := Exec(sess, 'systemctl restart app');
  if r.ExitCode <> 0 then
    raise 'Restart failed: ' + r.Stderr;
  WriteLn('Restarted OK');
end except
  WriteLn('SSH error: ' + GetExceptionMessage());
end;

Disconnect(sess);