PHP ssh2_exec() Function: Usage and Examples

ssh2_exec() executes a command over an authenticated SSH connection and returns a stream.

What It Does

ssh2_exec() executes a command over an authenticated SSH connection and returns a stream. The following examples distinguish a normal use case, a boundary case and a practical application.

Requirements and Compatibility

PECL ssh2, an approved SSH server, trusted host-key pinning and valid SSH credentials. This optional extension is not part of core PHP.

PECL ssh2 host fingerprints are typically exposed as SHA-1 or MD5; always compare a trusted, pre-approved host key value before authenticating, and prefer mature clients with stronger host-key policies where practical.

Syntax, Parameters and Return Value

ssh2_exec(resource $session, string $command, ...): resource|false

Requires an authenticated session; a successful call returns a readable command channel, not the command output string directly.

Example 1: Basic Behavior

Demonstrate the extension API with an explicitly trusted test server.

<?php
$session = ssh2_connect('ssh.example.test', 22);
if (!$session) throw new RuntimeException('SSH connection failed');
$expected = getenv('SSH_HOST_FINGERPRINT_SHA1');
if (!$expected || !hash_equals(strtolower($expected), strtolower(ssh2_fingerprint($session, SSH2_FINGERPRINT_SHA1 | SSH2_FINGERPRINT_HEX)))) throw new RuntimeException('Untrusted SSH server');
$user = getenv('SSH_USERNAME'); $password = getenv('SSH_PASSWORD');
if (!$user || !$password || !ssh2_auth_password($session, $user, $password)) throw new RuntimeException('SSH authentication failed');
$command = ssh2_exec($session, 'id -u');
if ($command === false) throw new RuntimeException('Execution failed');
stream_set_blocking($command, true);
echo stream_get_contents($command);
fclose($command);
ssh2_disconnect($session);

This example depends on an installed extension, third-party library or configured service and is not a standalone local test.

Example 2: Another Case

Use a second approved host and check the operation result.

<?php
$session = ssh2_connect('internal-ssh.example.test', 22);
if (!$session) throw new RuntimeException('SSH connection failed');
$expected = getenv('SSH_HOST_FINGERPRINT_SHA1');
if (!$expected || !hash_equals(strtolower($expected), strtolower(ssh2_fingerprint($session, SSH2_FINGERPRINT_SHA1 | SSH2_FINGERPRINT_HEX)))) throw new RuntimeException('Untrusted SSH server');
$user = getenv('SSH_USERNAME'); $password = getenv('SSH_PASSWORD');
if (!$user || !$password || !ssh2_auth_password($session, $user, $password)) throw new RuntimeException('SSH authentication failed');
$command = ssh2_exec($session, 'hostname');
if ($command === false) throw new RuntimeException('Execution failed');
stream_set_blocking($command, true);
echo stream_get_contents($command);
fclose($command);
ssh2_disconnect($session);

This example depends on an installed extension, third-party library or configured service and is not a standalone local test.

Practical Example: Putting It to Use

Apply the operation in a controlled backup or administrative workflow; never pass arbitrary user commands.

<?php
$session = ssh2_connect('backup-ssh.example.test', 22);
if (!$session) throw new RuntimeException('SSH connection failed');
$expected = getenv('SSH_HOST_FINGERPRINT_SHA1');
if (!$expected || !hash_equals(strtolower($expected), strtolower(ssh2_fingerprint($session, SSH2_FINGERPRINT_SHA1 | SSH2_FINGERPRINT_HEX)))) throw new RuntimeException('Untrusted SSH server');
$user = getenv('SSH_USERNAME'); $password = getenv('SSH_PASSWORD');
if (!$user || !$password || !ssh2_auth_password($session, $user, $password)) throw new RuntimeException('SSH authentication failed');
$command = ssh2_exec($session, 'date -u');
if ($command === false) throw new RuntimeException('Execution failed');
stream_set_blocking($command, true);
echo stream_get_contents($command);
fclose($command);
ssh2_disconnect($session);

This example depends on an installed extension, third-party library or configured service and is not a standalone local test.

Important Behavior and Edge Cases

Do not concatenate untrusted data into shell commands; read stdout/stderr and exit behavior deliberately.

Comparison with Related Functions or Approaches

Common Beginner Mistakes

Key Takeaways

• ssh2_exec() executes a command over an authenticated SSH connection and returns a stream.
• Do not concatenate untrusted data into shell commands; read stdout/stderr and exit behavior deliberately.
• Use SSH exec for fixed administrative tasks, not as a substitute for safe local data APIs.

Before adapting these examples, verify the return values, test the failure paths and confirm that your application meets its security and environment requirements.