PHP Classes

PHP SSH Connection Session: Run arbitrary length commands in a server with SSH

Recommend this page to a friend!
  Info   Documentation   View files Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
StarStarStarStar 79%Total: 400 All time: 6,572 This week: 43Up
Version License PHP version Categories
ssh-session 1.0.9GNU General Publi...5.5Networking, PHP 5, Files and Folders
Description 

Author

This package can run arbitrary length commands in a server with SSH.

It can connect to a given ssh server and execute given commands.

If the commands exceed the maximum length, it write the commands to a file and executes it from there using the bash shell.

It can also execute file manipulation functions like uploading and downloading files, creating directories, changing file permissions, renaming files, reading or writing remote file contents, etc..

Innovation Award
PHP Programming Innovation award winner
August 2016
Winner


Prize: One downloadable e-book of choice by O'Reilly
SSH is a protocol to communicate with a remote server via a secure connection that allows to execute commands on a remote machine.

However, the length of the commands that can be executed is limited.

This package provides a workaround for this limitation that consists in creating a shell script to execute long commands and execute it using the bash shell.

Manuel Lemos
Picture of Christian Vigh
  Performance   Level  
Name: Christian Vigh <contact>
Classes: 32 packages by
Country: France France
Age: 58
All time rank: 13410 in France France
Week rank: 10 Up1 in France France Up
Innovation award
Innovation award
Nominee: 20x

Winner: 3x

Documentation

INTRODUCTION

The SshSession class (and all of its related classes) is intended to establish SSH connections to a remote host running an sshd server and allow you to execute commands remotely and retrieve their output, or access the remote filesystem using the SFTP protocol.

The class relies on the libssh2 PHP extension.

The following example illustrates a simple usage of this package ; it connects remotely, executes the "ls -al" command by redirectoring its output to file /tmp/ls.out, then retrieves file contents and display them :

require_once ( 'Session.phpclass' ) ;

// Create an instance for host 1.2.3.4 port 22 ; no connection exists at that stage
$session = new SshSession ( '1.2.3.4', 22 ) ; 		

// Authenticate using the specified user/password
$session -> Authenticate ( new SshPasswordAuthentication ( $session, 'myuser', 'mypassword' ) ;

// Execute the ls command and redirect its output to file /tmp/ls.out
$status 	=  $session -> Execute ( "ls -al / >tmp/ls.out' ) ;

// Get a reference object to the remote filesystem
$fs 		=  $session -> GetFileSystem ( ) ;

// Retrieve then display /tmp/ls.out file contents
echo $fs -> file_get_contents ( '/tmp/ls.out' ) ;

// Remove temporary file
$fs -> unlink ( '/tmp/ls.out' ) ;

Of course, you can also use authentication using public and private keys defined in external files ; just replace the following code :

$session -> Authenticate ( new SshPasswordAuthentication ( $session, 'myuser', 'mypassword' ) ;

with :

$session -> Authenticate ( new SshPublicKeyAuthentication ( $session, 'myuser', 'mypublickey.ppk', 'myprivatekey.ppk' ) ;

FEATURES

The SshSession class tries to protect you from some issues found with the libssh2 PHP extension (especially on Windows) and from some limitations of the SSH protocol :

  • Commands can be of arbitrary length ; if commands are longer than the maximum authorized command-line length, they will be transparently put into a temporary file on the remote system before being executed using the bash shell. This way, you don't have to worry about command-line length.
  • You will always be able to retrieve the status of the latest command that was executed (see the Execute() method of the SshSession class)
  • Once a connection has been established, you will be able to use the SshFileSystem object (see the GetFileSystem()* method of theSshSession class) to remotely manipulate files and directories
  • At least on Windows systems, the following two cases will bring you an error : - Execute a command, then an SFTP operation, then another command - Execute two commands consecutively

    The SshSession class handles the burden of such situations by automatically disconnecting you then reconnecting before the next operation to be performed, in order to avoid you to have to deal with such errors.

PREREQUISITES

The remote systems you will be accessing will need the following : - An up-and-running sshd server - A version of PHP with the libssh2 library installed and configured as an extension library (either in CLI mode or when running with a web server) - If you want to authenticate using public and private keys, the user on your remote server will need to have your public key in the authorized_keys file of the .ssh directory located in the home directory for this user.

WARNING FOR USERS OF PHP > 5.6.27

PHP 5.6.28 broke something (or radically changed something) in the way the ssh2.sftp wrapper parses a file specification. This led to errors when using the opendir() function, for example.

This became "less worse" with PHP 7.0, but resource id strings in path specifications remain unrecognized, unlike in versions <= 5.6.27 (the Ssh Session classes has been fixed to handle this new case).

PHP 7.1 solved the problem ; however, on Windows platforms, using multiple SFTP sessions within the same script can lead to errors when trying to access existing remote files. More annoying is that an access violation is generated at the end of the script in php_libssh2.dll. This problem, which is linked to the current implementation of the libssh2 extension, is currently under investigation.

PACKAGE DESCRIPTION

This package contains 4 main classes :

  • SshSession : the main object you will have to instantiate for gaining access to your remote system
  • SshAuthentication : An abstract base class for authenticating yourself to a remote system ; it has 6 derived classes (see the SshSession::Authenticate() method) : - SshPasswordAuthentication : Used for authenticating yourself using a user/password. - SshPublicKeyAuthentication : Used for authenticating yourself with a public and private key. - SshKeyBaseAuthentication : Another way of authentication (not tested). - SshHostBaseAuthentication : A way to authenticate yourself using public and private keys coming from a third-party host (not tested). - SshAgentAuthentication : A way to authenticate using an SSH agent and a username (not tested). - SshAuthenticationNone : Not tested. To tell the truth, I did not completely understand the utility of this authentication method, although I'm sure there is one.

The classes you are likely to use most often will probably be SshPasswordAuthentication and SshPublicKeyAuthentication.

  • SshFileSystem : An object that you can retrieve using the SshSession::GetFileSystem() method, which will give you access to the remote files and directories.
  • SshConnection : A class used internally to coordinate all of the above.

CLASS REFERENCE

SshSession class

METHODS

__construct ( $host\_or\_resource = null, $port = 22, $methods = null, $callbacks = null ) ;

Builds an Ssh session, including access to shell and sftp.

Note that instantiating an SshSession object does not establish a connection to the remote system : you must call the Connect() method before that.

The parameters are the following :

  • host\_or\_resource (string, resource or SshConnection object) : Remote host to connect to. It can have one of the following types : - string : Host name or ip address that will be supplied to the ssh2_connect() function. - resource : An already existing ssh connection. Note that in this case, the Host, Port, Methods and Callbacks properties of this SshConnection object will be undefined. - SshConnection object : Duplicates the parameters of an existing SshConnection object.
  • port (integer) : Ssh port to be used for the connection. Default port is 22.
  • methods (array) : Associative array. See the ssh2_connect() function help for for a description of its entries.
  • callbacks (array) : An associative array providing the names of callback functions (see the ssh2_connect() function). Note that all the callbacks must be implemented in the SshConnection class . This parameter can be used to override existing callbacks in derived classes.

$session -> Authenticate ( $auth_object )

Authenticates on an already connected session using the specified SshAuthentication class-derived object.

$connection = $session -> Connect ( $host_or_resource = null, $port = 22, $methods = null, $callbacks = null )

Connects to the specified remote host. See the class constructor help for an explanation about the method parameters.

Returns an SshConnection object.

$status = $session -> Disconnect ( )

Disconnects from an existing SSH session.

Returns true if disconnection was successful, false otherwise (for example, when no connection was established).

$status = $session -> Execute ( $command, &$output = null, $env = null ) ;

Executes a command on a remote server.

The parameters are the following :

  • $command (string) - Command(s) to be executed.
  • $output (array or callback) - If specified as an array, will receive the output lines generated by the executed command(s). If null, results will be output (almost) in real time.
  • $env (array) - Optional associative array that defines environment variable names/values to be used when executing the command.

Returns the status of the last executed command (the $? variable value of the bash/sh shell interpreter).

_NOTES_ :

  • At least on Windows systems, getting the output and error output of a remote command execution is a real nightmare ; standard error is not included by default in the stream returned by ssh2_exec(), and calling ssh2_fetch_stream() to obtain a standard error stream does not solve the problem, either : even if both stderr and stdout contain data, reading the first will succeed, but reading the second will result in a never ending call, whatever the order of data reads (stdout then stderr, or stderr then stdout).

For those reasons, the Execute() method transforms the supplied input commands to the following script :

bash 2>&1  <<END
	$commands
END

The drawback is that stderr is interspersed with stdout, but in the order it has been output.

  • Status of the last executed command is returned by appending "echo $?" after the last command.

$fs = $session -> GetFileSystem ( ) ;

Creates an SshFileSystem object (if not already created) to allow remote access to the server files.

$session -> Reconnect ( ) ;

Disconnects, reconnects then re-authenticates.

Added mainly as a workaround for the libssh2 bug which prevents ANYTHING to be executed or transferred after a command has been executed (apparently, it concerns only Windows implementations).

$status = $session -> IsConnected ( ) ;

Returns true if the session object has established a connection to the remote server.

Note that being connected does not necessarily mean being authenticated.

$status = $session -> IsAuthenticated ( ) ;

Returns true if the connection is opened and a user has been authenticated.

PROPERTIES

Connection

Returns an SshConnection object.

SshFileSystem class

An object of type SshFileSystem provides access to a remote file system.

It can be retrieved using the GetFileSystem() method of the SshSession class, once connected and authenticated (an exception is thrown if no connection has been established or if no user has been authenticated).

Most of the methods of this class mimic their classic PHP counterpart.

METHODS

$path = $fs -> SshPath ( $path ) ;

Returns a path using the ssh2.sftp:// stream wrapper.

$old_cwd = $fs -> chdir ( $path ) ;

Changes the current working directory on the remote server and returns the previous one

$status = $fs -> chmod ( $remote_file, $mode ) ;

Changes the permissions for the specified file on the remote server. See the chmod() function for an explanation on the $mode parameter.

$fs -> closedir ( $resource ) ;

Closes a directory opened by the opendir() method.

$status = $fs -> fclose ( $fp ) ;

Closes a file opened by the fopen() method.

$data = $fs -> fgets ( $fp, $data, $length = null ) ;

Reads a line from the specified file opened by the fopen() method.

$lines = $fs -> file ( $filename, $flags = 0, $context = null )

Gets remote file contents, as an array of lines.

$status = $fs -> file\_exists ( $filename ) ;

Checks if the specified file exists on the remote host.

$fs -> file\_get\_contents ( $filename, $use\_include\_path = false, $context = null, $offset = -1 ) ;

Retrieves the contents of a remote file, using the ssh2.sftp wrapper.

Note that the $maxlen parameter of the traditional PHP file\_get\_contents function is not used, since it always gives empty results.

$fs -> file\_put\_contents ( $filename, $data, $flags = 0, $context = null ) ;

Replaces the contents of a remote file, using the ssh2.sftp wrapper.

$fp = $fs -> fopen ( $remote\_file, $mode, $use\_include\_path = false, $context = false ) ;

Opens a file on the remote host.

$data = $fs -> passthru ( $fp ) ;

Reads an already opened file until the end and returns its data.

$status = $fs -> fprintf ( $fp, $format, ... ) ;

fprintf() function, on a remote file.

$status = $fs -> fputs ( $fp, $data, $length = null ) ;

fputs() function, on a remote file.

$data = $fs -> fread ( $fp, $length = null ) ;

fread() function, on a remote file.

$status = $fs -> fseek ( $fp, $offset, $whence = SEEK_SET ) ;

Seeks on a remote file.

$offset = $fs -> ftell ( $fp )

Returns the current offset of remote file.

$status = $fs -> fwrite ( $fp, $data, $length = null ) ;

fwrite() function, on a remote file.

$cwd = $fs -> getcwd ( ) ;

Returns the current working directory, which is evaluated through the realpath() method upon connection.

$status = $fs -> gzclose ( $fp ) ;

Closes an opened gzipped file.

$fp = $fs -> gzopen ( $remote\_file, $mode, $use\_include\_path = false ) ;

Opens a remote gzipped file.

$data = $fs -> gzread ( $fp, $length = null ) ;

gzread() function, on a remote file.

$status = $fs -> is\_dir ( $remote\_file ) ;

Checks if the specified file exists on the remote host and is a directory.

$status = $fs -> is\_file ( $remote\_file ) ;

Checks if the specified file exists on the remote host and is a plain file.

$status = $fs -> lstat ( $remote\_file ) ;

Stats a remote symbolic link target.

$status = $fs -> mkdir ( $remote\_directory, $mode = 0755, $recursive = false ) ;

Creates a directory on the remote host.

$rs = $fs -> opendir ( $path ) ;

Opens a remote directory.

$result = $fs -> readdir ( $resource ) ;

Reads the next directory entry.

$path = $fs -> readlink ( $remote\_file ) ;

Returns the target path of a symbolic link on the remote host.

$path = $fs -> realpath ( $remote\_file ) ;

Returns the real path of a file on the remote host.

$status = $fs -> receive ( $remote\_file, $local\_file ) ;

Receives a file from the remote server.

$status = $fs -> rename ( $old\_name, $new\_name ) ;

Renames a file on the remote host.

$status = $fs -> rewind ( $fp ) ;

Rewinds an already opened file on the remote server.

$status = $fs -> rmdir ( $remote\_directory ) ;

Removes a directory from the remote host.

$status = $fs -> send ( $local\_file, $remote\_file, $mode = 0644 ) ;

Sends a file to the remote server.

$result = $fs -> stat ( $remote_file ) ;

Stats a remote file.

$status = $fs -> symlink ( $file, $target ) ;

Creates a symbolic link.

$status = $fs -> unlink ( $remote\_file ) ;

Deletes a file from the remote host.

PROPERTIES

Session

Returns the SshSession parent object for this file system.

SftpSession

A resource returned by the PHP ssh2\_sftp() function.

Cwd

Current working directory on the remote server.

AUTHENTICATION CLASSES

An object of a type belonging to one of the classes derived from SshAuthentication needs to be supplied to the Connect() method. This section describes the constructors of these various classes.

SshPasswordAuthentication class

Use this class when you need to authenticate using a user and password combination ; the constructor has the following form :

__construct ( $session, $username, $password ) ;

Where :

  • $session is an SshSession object you already instantiated
  • $user and password are your user/password strings.

SshPublicKeyAuthentication class

Use this class when you need to authenticate using public/private keys ; the constructor has the following form :

__construct ( $session, $username, $public_key_file, $private_key_file, $passphrase = null ) 

The parameters are the following :

  • $session : An object of type SshSession
  • username : Username to be used for authentication.
  • public\_key\_file : File containing your public key.
  • private\_key\_file: File containing your private key.
  • $passphrase : If your secret key has a passphrase, then this is the right place to specify it.

This class has not been tested yet.

SshHostBasedAuthentication

Use this class when you need to authenticate using public/private keys that are located on a third-party server.

The constructor has the following form :

__construct ( $session, $username, $host, $public_key_file, $private_key_file, $passphrase = null ) ;

SshAgentAuthentication

This class has not been tested yet.

The constructor has the following form :

__construct ( $session, $username ) ;

SshAuthenticationNone

This class has not been tested yet.

The constructor has the following form :

__construct ( $session, $username ) ;

Details

HOW TO RUN THE EXAMPLES ?

You have to edit the file example.inc.php ; it contains variables that you MUST set to your own configuration needs before running the examples :

  • $host : Host name or IP address of your remote server.
  • port : Port number of the sshd server on your remote system (usually, 22).
  • $user : the user you want to connect to on your remote system.
  • $password : User password (set this variable if you want to run the example.password.php script, which uses password-based authentication)
  • $private\_key\_file, $public\_key\_file : Paths to the files containing your private and public ssh keys (set these variables if you want to run the example.key.php script, which uses ssh key-based authentication)

PREREQUISITES

  • Your remote system MUST be a Unix system for the examples to run as is
  • If you used puttygen to generate your public and private keys, you have to know that the key that is labelled :

    Public key for pasting into OpenSSH authorized_keys file

will not have the correct format for using it as a public key on Unix systems. You will have to go to the Conversions menu and chose the "Export OpenSSH key" option.

  • On your remote Unix system, you must add your public key in the .ssh/authorized_keys file of your remote user
  • And, of course, you must have an sshd server up and running on your remote system !

  Files folder image Files (11)  
File Role Description
Plain text file Authentication.phpclass Class Class source
Plain text file Connection.phpclass Class Class source
Accessible without login Plain text file example.inc.php Conf. Configuration script
Accessible without login Plain text file example.key.php Example Example script
Accessible without login Plain text file example.password.php Example Example script
Plain text file FileSystem.phpclass Class Class source
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file NOTICE Data Auxiliary data
Accessible without login Plain text file README.examples.md Doc. Documentation
Accessible without login Plain text file README.md Doc. Documentation
Plain text file Session.phpclass Class Class source

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Unique User Downloads Download Rankings  
 100%
Total:400
This week:0
All time:6,572
This week:43Up
User Ratings User Comments (1)
 All time
Utility:100%StarStarStarStarStarStar
Consistency:100%StarStarStarStarStarStar
Documentation:95%StarStarStarStarStar
Examples:100%StarStarStarStarStarStar
Tests:-
Videos:-
Overall:79%StarStarStarStar
Rank:25
 
nice
7 years ago (muabshir)
80%StarStarStarStarStar