spatie / ssh
A lightweight package to execute commands over an SSH connection
Fund package maintenance!
spatie.be/open-source/support-us
Installs: 1 970 403
Dependents: 35
Suggesters: 2
Security: 0
Stars: 782
Watchers: 11
Forks: 85
Open Issues: 4
Requires
- php: ^7.4|^8.0
- symfony/process: ^4.4|^5.3|^6.0|^7.0
Requires (Dev)
- pestphp/pest: ^1.22
- spatie/pest-plugin-snapshots: ^1.1
- symfony/var-dumper: ^5.3|6.0|^7.0
README
You can execute an SSH command like this:
Ssh::create('user', 'host')->execute('your favorite command');
It will return an instance of Symfony's Process
.
Support us
We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.
Installation
You can install the package via composer:
composer require spatie/ssh
Usage
You can execute an SSH command like this:
$process = Ssh::create('user', 'example.com')->execute('your favorite command');
It will return an instance of Symfony's Process
.
If you don't want to wait until the execute commands complete, you can call executeAsync
$process = Ssh::create('user', 'example.com')->executeAsync('your favorite command');
Getting the result of a command
To check if your command ran ok
$process->isSuccessful();
This is how you can get the output
$process->getOutput();
Running multiple commands
To run multiple commands pass an array to the execute method.
$process = Ssh::create('user', 'example.com')->execute([ 'first command', 'second command', ]);
Choosing a port
You can choose a port by passing it to the constructor.
$port = 123; Ssh::create('user', 'host', $port);
Alternatively you can use the usePort
function:
Ssh::create('user', 'host')->usePort($port);
Setting a timeout
You can set a timeout for the command.
Ssh::create('user', 'host')->setTimeout(100);
Specifying a jump host
If using a jump/proxy/bastion host, the useJumpHost
function allows you to set the jump hosts details:
Ssh::create('user', 'host')->useJumpHost("$jumpuser@$jumphost:$jumpport");
Using SSH multiplexing
If making many connections to the same host, SSH multiplexing enables re-using one TCP connection. Call useMultiplexing
function to set control master options:
Ssh::create('user', 'host')->useMultiplexing($controlPath, $controlPersist); // Ssh::create('user', 'host')->useMultiplexing('/home/.ssh/control_masters/%C', '15m');
Specifying the private key to use
You can use usePrivateKey
to specify a path to a private SSH key to use.
Ssh::create('user', 'host')->usePrivateKey('/home/user/.ssh/id_rsa');
Disable Strict host key checking
By default, strict host key checking is enabled. You can disable strict host key checking using disableStrictHostKeyChecking
.
Ssh::create('user', 'host')->disableStrictHostKeyChecking();
Enable quiet mode
By default, the quiet mode is disabled. You can enable quiet mode using enableQuietMode
.
Ssh::create('user', 'host')->enableQuietMode();
Disable Password Authentication
By default, the password authentication is enabled. You can disable password authentication using disablePasswordAuthentication
.
Ssh::create('user', 'host')->disablePasswordAuthentication();
Uploading & downloading files and directories
You can upload files & directories to a host using:
Ssh::create('user', 'host')->upload('path/to/local/file', 'path/to/host/file');
Or download them:
Ssh::create('user', 'host')->download('path/to/host/file', 'path/to/local/file');
Under the hood the process will use scp
.
Modifying the Symfony process
Behind the scenes all commands will be performed using Symfonys Process
.
You can configure to the Process
by using the configureProcess
method. Here's an example where we disable the timeout.
Ssh::create('user', 'host')->configureProcess(fn (Process $process) => $process->setTimeout(null));
Immediately responding to output
You can get notified whenever your command produces output by passing a closure to onOutput
.
Ssh::create('user', 'host')->onOutput(function($type, $line) {echo $line;})->execute('whoami');
Whenever there is output that closure will get called with two parameters:
type
: this can beSymfony\Component\Process\Process::OUT
for regular output andSymfony\Component\Process\Process::ERR
for error outputline
: the output itself
Windows Target
If your target is a Windows machine, you can use the removeBash
method to remove the bash command from the command line.
Ssh::create('user', 'host')->removeBash();
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security
If you've found a bug regarding security please mail security@spatie.be instead of using the issue tracker.
Alternatives
If you need some more features, take a look at DivineOmega/php-ssh-connection.
Credits
The Ssh
class contains code taken from laravel/envoy
License
The MIT License (MIT). Please see License File for more information.