Using SSH and SCP in Phing

Phing allows the running of SSH commands on servers and the copying of files to servers via SCP. Before you can use SSH and SCP commands in Phing you need to install the PECL extension SSH2. The SSH2 PECL extension requires the libssh2 package, so you need to install that before you can get started. The following install instructions are based on a Linux environment.

Download the libssh2 package from www.libssh2.org and install it by using the following commands. Your package version may vary.

sudo tar -zxvf libssh2-1.3.0.tar.gz
cd libssh2-1.3.0
./configure
make
sudo make install

You'll need the sudo on the last command to allow the make installer access to certain system directories.

Next, you need to install the SSH2 PECL extension, but because it's currently in a beta state you will need to give the full path to the library version along with the normal install command.

sudo pecl install pecl.php.net/ssh2-0.11.3

If you get an error about not setting things in your php.ini file then you need to add the following into your php.ini file. On my version of Ubuntu I have different php.ini files for apache and cli, but when using Phing you only need to add this to your cli file. To see where the loaded php.ini files are, type in the command php --ini. The heading line is optional here, but I added for clarity.

[ssh2]
extension=ssh2.so

With all this in place you can now start using the SSH and SCP tasks in Phing.

The SSH task in Phing is used to send a single command to the server in question. This might be things like changing permissions on directories or cleaning log files, but it is essentially anything you would do via normal SSH access. You can only issue one command at a time, which means you can't change directories on one command and then do something in the same directory in the next. If you need to do complex commands like that then you might want to consider using a bash script. The following is an example of connecting to a server at an internal IP address and printing out the present working directory using the pwd command. The username, password and command fields are all required by this task.

<?xml version="1.0"?>
<project name="sshtest" default="main"> 
  <target name="main">
    <ssh username="username" password="password" host="192.168.1.200" command="pwd" />
  </target>
</project>

Note that the rest of the build file is included here for convenience, but is excluded in later examples for reasons of brevity.

Anything you do that creates output is read back by Phing and can be made to either print it out or assign it to a property. The default behaviour (listed in the above example) is to print out the returned output as the task is run. To assign the output to a property you need to use the property attribute of the SSH task. The below example is similar to the above one, but in this instance the returned value will be printed out as a variable in an echo task. The display attribute is set to false to repress the printing out of the returned output.

<ssh username="username" password="password" host="192.168.1.200" command="pwd" property="mypwd" display="false" />
<echo>The present working directory is ${mypwd}</echo>

That's about it for the SSH task, there are a number of other attributes available to allow connecting to different ssh setups, but the above details are the essentials of how it works. To find out more about the ssh task take a look at the Phing SSH Task manual.

The SCP task is similar to the SSH task in that it has the same set of connection parameters but is designed to allow file copying from or to a server. The simplest example is to copy a file to the remote server, which the following snippet will do when run. The todir attribute is used to let the script know which directory to copy the files to and the file attribute is used to determine which file will be copied.

<scp username="username" password="password" host="192.168.1.200" todir="/var/www/" file="index.php" />

To copy more than one file you need to exclude the file attribute and include a fileset element within the SCP task. The following snippet will copy any PHP file from the project directory (excluding any PHP file ending with Test) and a file called README.txt to the remote server.

<scp username="username" password="password" host="192.168.1.200" todir="/var/www/">
  <fileset dir="project">
    <exclude name="*Test.php" />
    <include name="*.php" />
    <include name="README.txt" />
  </fileset>
</scp>

It is also possible to fetch files from the remote server by use of the fetch attribute. By default this is set to false, but if you explicitly set it to true then it will fetch files from the server.

<scp username="username" password="password" host="192.168.1.200" fetch="true" todir="./" file="/var/www/index.php" />

This is useful when downloading single files, but it is not currently possible to include fileset elements (and therefore multiple files) within the SCP task when using the fetch method.

There is also an attribute called autocreate which will either allow (if set to the default of true) or restrict the auto creation of directories. If this attribute is set to false then when you are copying a project to a remote server no directories will be created automatically. This means that your builds can fail if any file are dependent on being with a pre-determined directory structure.

The level attribute will accept a number of different values. These are error, warning, info, verbose, and debug. This setting just changes the way in which Phing reports on the the copying process and is set to be verbose as a default. Setting this to error, warning and info will make Phing print out every file that was copied, giving a synopsis at the end, and changing the colour of the outputted messages to red, purple and normal respectively. Verbose and debug will just print out the number of files that were copied but can be used by custom loggers to do different things.

To find out more about the other options available in the SCP task (mainly to do with the additional SSH connection parameters) have a look at the SCP task documentation on the Phing website.