<!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>Connect to an SSH server</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.ssh2-auth-pubkey-file.html">ssh2_auth_pubkey_file</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.ssh2-exec.html">ssh2_exec</a></div>
<div class="up"><a href="ref.ssh2.html">SSH2 Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.ssh2-connect" class="refentry">
<div class="refnamediv">
<h1 class="refname">ssh2_connect</h1>
<p class="verinfo">(PECL ssh2 >= 0.9.0)</p><p class="refpurpose"><span class="refname">ssh2_connect</span> — <span class="dc-title">Connect to an SSH server</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.ssh2-connect-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">resource</span> <span class="methodname"><strong>ssh2_connect</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$host</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$port</code><span class="initializer"> = 22</span></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$methods</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$callbacks</code></span>
]]] )</div>
<p class="para rdfs-comment">
Establish a connection to a remote SSH server.
</p>
<p class="para">
Once connected, the client should verify the server's hostkey using
<span class="function"><a href="function.ssh2-fingerprint.html" class="function">ssh2_fingerprint()</a></span>, then authenticate using either
password or public key.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.ssh2-connect-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">host</code></em></span>
<dd>
<p class="para">
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">port</code></em></span>
<dd>
<p class="para">
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">methods</code></em></span>
<dd>
<p class="para">
<em><code class="parameter">methods</code></em> may be an associative array with up to four parameters
as described below.
</p>
<p class="para">
<table class="doctable table">
<caption><strong><em><code class="parameter">methods</code></em> may be an associative array
with any or all of the following parameters.</strong></caption>
<thead>
<tr>
<th>Index</th>
<th>Meaning</th>
<th>Supported Values*</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>kex</td>
<td>
List of key exchange methods to advertise, comma separated
in order of preference.
</td>
<td>
<em>diffie-hellman-group1-sha1</em>,
<em>diffie-hellman-group14-sha1</em>, and
<em>diffie-hellman-group-exchange-sha1</em>
</td>
</tr>
<tr>
<td>hostkey</td>
<td>
List of hostkey methods to advertise, comma separated
in order of preference.
</td>
<td>
<em>ssh-rsa</em> and
<em>ssh-dss</em>
</td>
</tr>
<tr>
<td>client_to_server</td>
<td>
Associative array containing crypt, compression, and
message authentication code (MAC) method preferences
for messages sent from client to server.
</td>
<td class="empty"> </td>
</tr>
<tr>
<td>server_to_client</td>
<td>
Associative array containing crypt, compression, and
message authentication code (MAC) method preferences
for messages sent from server to client.
</td>
<td class="empty"> </td>
</tr>
</tbody>
</table>
</p>
<p class="para">
* - Supported Values are dependent on methods supported by underlying library.
See <a href="http://libssh2.org/" class="link external">» libssh2</a> documentation for additional
information.
</p>
<p class="para">
<table class="doctable table">
<caption><strong>
<em><code class="parameter">client_to_server</code></em> and
<em><code class="parameter">server_to_client</code></em> may be an associative array
with any or all of the following parameters.
</strong></caption>
<thead>
<tr>
<th>Index</th>
<th>Meaning</th>
<th>Supported Values*</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>crypt</td>
<td>List of crypto methods to advertise, comma separated
in order of preference.</td>
<td>
<em>rijndael-cbc@lysator.liu.se</em>,
<em>aes256-cbc</em>,
<em>aes192-cbc</em>,
<em>aes128-cbc</em>,
<em>3des-cbc</em>,
<em>blowfish-cbc</em>,
<em>cast128-cbc</em>,
<em>arcfour</em>, and
<em>none**</em>
</td>
</tr>
<tr>
<td>comp</td>
<td>List of compression methods to advertise, comma separated
in order of preference.</td>
<td>
<em>zlib</em> and
<em>none</em>
</td>
</tr>
<tr>
<td>mac</td>
<td>List of MAC methods to advertise, comma separated
in order of preference.</td>
<td>
<em>hmac-sha1</em>,
<em>hmac-sha1-96</em>,
<em>hmac-ripemd160</em>,
<em>hmac-ripemd160@openssh.com</em>, and
<em>none**</em>
</td>
</tr>
</tbody>
</table>
</p>
<p class="para">
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>Crypt and MAC method "<em>none</em>"</strong><br />
<p class="para">
For security reasons, <em>none</em> is disabled by the underlying
<a href="http://libssh2.org/" class="link external">» libssh2</a> library unless explicitly enabled
during build time by using the appropriate ./configure options. See documentation
for the underlying library for more information.
</p>
</p></blockquote>
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">callbacks</code></em></span>
<dd>
<p class="para">
<em><code class="parameter">callbacks</code></em> may be an associative array with any
or all of the following parameters.
<table class="doctable table">
<caption><strong>
Callbacks parameters
</strong></caption>
<thead>
<tr>
<th>Index</th>
<th>Meaning</th>
<th>Prototype</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>ignore</td>
<td>
Name of function to call when an
<strong><code>SSH2_MSG_IGNORE</code></strong> packet is received
</td>
<td>void ignore_cb($message)</td>
</tr>
<tr>
<td>debug</td>
<td>
Name of function to call when an
<strong><code>SSH2_MSG_DEBUG</code></strong> packet is received
</td>
<td>void debug_cb($message, $language, $always_display)</td>
</tr>
<tr>
<td>macerror</td>
<td>
Name of function to call when a packet is received but the
message authentication code failed. If the callback returns
<strong><code>TRUE</code></strong>, the mismatch will be ignored, otherwise the connection
will be terminated.
</td>
<td>bool macerror_cb($packet)</td>
</tr>
<tr>
<td>disconnect</td>
<td>
Name of function to call when an
<strong><code>SSH2_MSG_DISCONNECT</code></strong> packet is received
</td>
<td>void disconnect_cb($reason, $message, $language)</td>
</tr>
</tbody>
</table>
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.ssh2-connect-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns a resource on success, or <strong><code>FALSE</code></strong> on error.
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.ssh2-connect-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-4610">
<p><strong>Example #1 <span class="function"><strong>ssh2_connect()</strong></span> example</strong></p>
<div class="example-contents"><p>
Open a connection forcing 3des-cbc when sending packets, any strength
aes cipher when receiving packets, no compression in either direction,
and Group1 key exchange.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/* Notify the user if the server terminates the connection */<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">my_ssh_disconnect</span><span style="color: #007700">(</span><span style="color: #0000BB">$reason</span><span style="color: #007700">, </span><span style="color: #0000BB">$message</span><span style="color: #007700">, </span><span style="color: #0000BB">$language</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">printf</span><span style="color: #007700">(</span><span style="color: #DD0000">"Server disconnected with reason code [%d] and message: %s\n"</span><span style="color: #007700">,<br /> </span><span style="color: #0000BB">$reason</span><span style="color: #007700">, </span><span style="color: #0000BB">$message</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #0000BB">$methods </span><span style="color: #007700">= array(<br /> </span><span style="color: #DD0000">'kex' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'diffie-hellman-group1-sha1'</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'client_to_server' </span><span style="color: #007700">=> array(<br /> </span><span style="color: #DD0000">'crypt' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'3des-cbc'</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'comp' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'none'</span><span style="color: #007700">),<br /> </span><span style="color: #DD0000">'server_to_client' </span><span style="color: #007700">=> array(<br /> </span><span style="color: #DD0000">'crypt' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'aes256-cbc,aes192-cbc,aes128-cbc'</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'comp' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'none'</span><span style="color: #007700">));<br /><br /></span><span style="color: #0000BB">$callbacks </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'disconnect' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'my_ssh_disconnect'</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$connection </span><span style="color: #007700">= </span><span style="color: #0000BB">ssh2_connect</span><span style="color: #007700">(</span><span style="color: #DD0000">'shell.example.com'</span><span style="color: #007700">, </span><span style="color: #0000BB">22</span><span style="color: #007700">, </span><span style="color: #0000BB">$methods</span><span style="color: #007700">, </span><span style="color: #0000BB">$callbacks</span><span style="color: #007700">);<br />if (!</span><span style="color: #0000BB">$connection</span><span style="color: #007700">) die(</span><span style="color: #DD0000">'Connection failed'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-function.ssh2-connect-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.ssh2-fingerprint.html" class="function" rel="rdfs-seeAlso">ssh2_fingerprint()</a> - Retrieve fingerprint of remote server</span></li>
<li class="member"> <span class="function"><a href="function.ssh2-auth-none.html" class="function" rel="rdfs-seeAlso">ssh2_auth_none()</a> - Authenticate as "none"</span></li>
<li class="member"> <span class="function"><a href="function.ssh2-auth-password.html" class="function" rel="rdfs-seeAlso">ssh2_auth_password()</a> - Authenticate over SSH using a plain password</span></li>
<li class="member"> <span class="function"><a href="function.ssh2-auth-pubkey-file.html" class="function" rel="rdfs-seeAlso">ssh2_auth_pubkey_file()</a> - Authenticate using a public key</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.ssh2-auth-pubkey-file.html">ssh2_auth_pubkey_file</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.ssh2-exec.html">ssh2_exec</a></div>
<div class="up"><a href="ref.ssh2.html">SSH2 Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
