# Net::LibSSH

XS Perl binding for libssh — SSH library without SFTP dependency.

## What It Is

Net::LibSSH wraps the C libssh library (NOT libssh2). Key difference from
Net::SSH2: file operations use SSH exec channels, not SFTP. The SFTP support
is optional and returns `undef` gracefully when the subsystem is absent.

## Module Structure

- `Net::LibSSH` — session: connect, auth, channel(), sftp()
- `Net::LibSSH::Channel` — exec, read, write, send_eof, exit_status, close
- `Net::LibSSH::SFTP` — stat() (optional, undef if no SFTP subsystem)

## Usage

```perl
use Net::LibSSH;

my $ssh = Net::LibSSH->new;
$ssh->option(host => 'server.example.com');
$ssh->option(user => 'root');
$ssh->connect or die $ssh->error;
$ssh->auth_agent or die $ssh->error;

my $ch = $ssh->channel;
$ch->exec('uname -r');
print $ch->read;
print "exit: ", $ch->exit_status, "\n";
$ch->close;
```

## Build (XS)

This is an XS module — requires a C compiler and libssh headers.

```bash
# Alien::libssh provides libssh if not available system-wide
perl Makefile.PL
make
make test
```

Or via Dist::Zilla (uses `[@Author::GETTY]` bundle with `xs_alien = Alien::libssh`):

```bash
dzil build
dzil test
```

## Key Implementation Notes

- XS file is `LibSSH.xs` — generated C is `LibSSH.c` (not committed)
- `ppport.h` generated by Devel::PPPort for backwards compatibility
- SFTP `stat()` returns undef (not die) when SFTP subsystem absent — this is
  intentional and used by Rex::LibSSH to detect SFTP availability

## Dependencies

- `Alien::libssh` (build dep — provides libssh C library and headers)
