<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <title>Secure Shell 2</title> </head> <body><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="wrappers.phar.html">phar://</a></div> <div class="next" style="text-align: right; float: right;"><a href="wrappers.rar.html">rar://</a></div> <div class="up"><a href="wrappers.html">Supported Protocols and Wrappers</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div><hr /><div id="wrappers.ssh2" class="refentry"> <div class="refnamediv"> <h1 class="refname">ssh2://</h1> <p class="refpurpose"><span class="refname">ssh2://</span> — <span class="dc-title">Secure Shell 2</span></p> </div> <div class="refsect1 description" id="refsect1-wrappers.ssh2-description"> <h3 class="title">Description</h3> <p class="para"> <var class="filename">ssh2.shell://</var> <var class="filename">ssh2.exec://</var> <var class="filename">ssh2.tunnel://</var> <var class="filename">ssh2.sftp://</var> <var class="filename">ssh2.scp://</var> PHP 4.3.0 and up (PECL) </p> <blockquote class="note"><p><strong class="note">Note</strong>: <strong>This wrapper is not enabled by default</strong><br /> <span class="simpara"> In order to use the <var class="filename">ssh2.*://</var> wrappers you must install the <a href="http://pecl.php.net/package/ssh2" class="link external">» SSH2</a> extension available from <a href="http://pecl.php.net/" class="link external">» PECL</a>. </span> </p></blockquote> <p class="simpara"> In addition to accepting traditional URI login details, the ssh2 wrappers will also reuse open connections by passing the connection resource in the host portion of the URL. </p> </div> <div class="refsect1 usage" id="refsect1-wrappers.ssh2-usage"> <h3 class="title">Usage</h3> <ul class="itemizedlist"> <li class="listitem"><span class="simpara"><var class="filename">ssh2.shell://user:pass@example.com:22/xterm</var></span></li> <li class="listitem"><span class="simpara"><var class="filename">ssh2.exec://user:pass@example.com:22/usr/local/bin/somecmd</var></span></li> <li class="listitem"><span class="simpara"><var class="filename">ssh2.tunnel://user:pass@example.com:22/192.168.0.1:14</var></span></li> <li class="listitem"><span class="simpara"><var class="filename">ssh2.sftp://user:pass@example.com:22/path/to/filename</var></span></li> </ul> </div> <div class="refsect1 options" id="refsect1-wrappers.ssh2-options"> <h3 class="title">Options</h3> <p class="para"> <table class="doctable table"> <caption><strong>Wrapper Summary</strong></caption> <thead> <tr> <th>Attribute</th> <th>ssh2.shell</th> <th>ssh2.exec</th> <th>ssh2.tunnel</th> <th>ssh2.sftp</th> <th>ssh2.scp</th> </tr> </thead> <tbody class="tbody"> <tr> <td>Restricted by <a href="filesystem.configuration.html#ini.allow-url-fopen" class="link">allow_url_fopen</a></td> <td>Yes</td> <td>Yes</td> <td>Yes</td> <td>Yes</td> <td>Yes</td> </tr> <tr> <td>Allows Reading</td> <td>Yes</td> <td>Yes</td> <td>Yes</td> <td>Yes</td> <td>Yes</td> </tr> <tr> <td>Allows Writing</td> <td>Yes</td> <td>Yes</td> <td>Yes</td> <td>Yes</td> <td>No</td> </tr> <tr> <td>Allows Appending</td> <td>No</td> <td>No</td> <td>No</td> <td>Yes (When supported by server)</td> <td>No</td> </tr> <tr> <td>Allows Simultaneous Reading and Writing</td> <td>Yes</td> <td>Yes</td> <td>Yes</td> <td>Yes</td> <td>No</td> </tr> <tr> <td>Supports <span class="function"><a href="function.stat.html" class="function">stat()</a></span></td> <td>No</td> <td>No</td> <td>No</td> <td>Yes</td> <td>No</td> </tr> <tr> <td>Supports <span class="function"><a href="function.unlink.html" class="function">unlink()</a></span></td> <td>No</td> <td>No</td> <td>No</td> <td>Yes</td> <td>No</td> </tr> <tr> <td>Supports <span class="function"><a href="function.rename.html" class="function">rename()</a></span></td> <td>No</td> <td>No</td> <td>No</td> <td>Yes</td> <td>No</td> </tr> <tr> <td>Supports <span class="function"><a href="function.mkdir.html" class="function">mkdir()</a></span></td> <td>No</td> <td>No</td> <td>No</td> <td>Yes</td> <td>No</td> </tr> <tr> <td>Supports <span class="function"><a href="function.rmdir.html" class="function">rmdir()</a></span></td> <td>No</td> <td>No</td> <td>No</td> <td>Yes</td> <td>No</td> </tr> </tbody> </table> </p> <p class="para"> <table class="doctable table"> <caption><strong>Context options</strong></caption> <thead> <tr> <th>Name</th> <th>Usage</th> <th>Default</th> </tr> </thead> <tbody class="tbody"> <tr> <td><em>session</em></td> <td>Preconnected ssh2 resource to be reused</td> <td class="empty"> </td> </tr> <tr> <td><em>sftp</em></td> <td>Preallocated sftp resource to be reused</td> <td class="empty"> </td> </tr> <tr> <td><em>methods</em></td> <td>Key exchange, hostkey, cipher, compression, and MAC methods to use</td> <td class="empty"> </td> </tr> <tr> <td><em>callbacks</em></td> <td class="empty"> </td> <td class="empty"> </td> </tr> <tr> <td><em>username</em></td> <td>Username to connect as</td> <td class="empty"> </td> </tr> <tr> <td><em>password</em></td> <td>Password to use with password authentication</td> <td class="empty"> </td> </tr> <tr> <td><em>pubkey_file</em></td> <td>Name of public key file to use for authentication</td> <td class="empty"> </td> </tr> <tr> <td><em>privkey_file</em></td> <td>Name of private key file to use for authentication</td> <td class="empty"> </td> </tr> <tr> <td><em>env</em></td> <td>Associate array of environment variables to set</td> <td class="empty"> </td> </tr> <tr> <td><em>term</em></td> <td>Terminal emulation type to request when allocating a pty</td> <td class="empty"> </td> </tr> <tr> <td><em>term_width</em></td> <td>Width of terminal requested when allocating a pty</td> <td class="empty"> </td> </tr> <tr> <td><em>term_height</em></td> <td>Height of terminal requested when allocating a pty</td> <td class="empty"> </td> </tr> <tr> <td><em>term_units</em></td> <td>Units to use with term_width and term_height</td> <td><strong><code>SSH2_TERM_UNIT_CHARS</code></strong></td> </tr> </tbody> </table> </p> </div> <div class="refsect1 examples" id="refsect1-wrappers.ssh2-examples"> <h3 class="title">Examples</h3> <div class="example" id="example-323"> <p><strong>Example #1 Opening a stream from an active connection</strong></p> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"> <span style="color: #0000BB"><?php<br />$session </span><span style="color: #007700">= </span><span style="color: #0000BB">ssh2_connect</span><span style="color: #007700">(</span><span style="color: #DD0000">'example.com'</span><span style="color: #007700">, </span><span style="color: #0000BB">22</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">ssh2_auth_pubkey_file</span><span style="color: #007700">(</span><span style="color: #0000BB">$session</span><span style="color: #007700">, </span><span style="color: #DD0000">'username'</span><span style="color: #007700">, </span><span style="color: #DD0000">'/home/username/.ssh/id_rsa.pub'</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'/home/username/.ssh/id_rsa'</span><span style="color: #007700">, </span><span style="color: #DD0000">'secret'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$stream </span><span style="color: #007700">= </span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #DD0000">"ssh2.tunnel://</span><span style="color: #0000BB">$session</span><span style="color: #DD0000">/remote.example.com:1234"</span><span style="color: #007700">, </span><span style="color: #DD0000">'r'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span> </span> </code></div> </div> </div> <div class="example" id="example-324"> <p><strong>Example #2 This <var class="varname"><var class="varname">$session</var></var> variable must be kept available!</strong></p> <div class="example-contents"><p> In order to use the <var class="filename">ssh2.*://$session</var> wrappers you must keep the <var class="varname"><var class="varname">$session</var></var> resouce variable. The code below will not have the desired effect: </p></div> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"> <span style="color: #0000BB"><?php<br />$session </span><span style="color: #007700">= </span><span style="color: #0000BB">ssh2_connect</span><span style="color: #007700">(</span><span style="color: #DD0000">'example.com'</span><span style="color: #007700">, </span><span style="color: #0000BB">22</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">ssh2_auth_pubkey_file</span><span style="color: #007700">(</span><span style="color: #0000BB">$session</span><span style="color: #007700">, </span><span style="color: #DD0000">'username'</span><span style="color: #007700">, </span><span style="color: #DD0000">'/home/username/.ssh/id_rsa.pub'</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'/home/username/.ssh/id_rsa'</span><span style="color: #007700">, </span><span style="color: #DD0000">'secret'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$connection_string </span><span style="color: #007700">= </span><span style="color: #DD0000">"ssh2.sftp://</span><span style="color: #0000BB">$session</span><span style="color: #DD0000">/"</span><span style="color: #007700">;<br />unset(</span><span style="color: #0000BB">$session</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$stream </span><span style="color: #007700">= </span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #0000BB">$connection_string </span><span style="color: #007700">. </span><span style="color: #DD0000">"path/to/file"</span><span style="color: #007700">, </span><span style="color: #DD0000">'r'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span> </span> </code></div> </div> <div class="example-contents"><p> unset() closes the session, because <var class="varname"><var class="varname">$connection_string</var></var> does not hold a reference to the <var class="varname"><var class="varname">$session</var></var> variable, just a string cast derived from it. This also happens when the <span class="function"><a href="function.unset.html" class="function">unset()</a></span> is implicit because of leaving scope (like in a function). </p></div> </div> </div> </div><hr /><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="wrappers.phar.html">phar://</a></div> <div class="next" style="text-align: right; float: right;"><a href="wrappers.rar.html">rar://</a></div> <div class="up"><a href="wrappers.html">Supported Protocols and Wrappers</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div></body></html>