pollita Mon Dec 27 18:18:44 2004 EDT
Modified files:
/phpdoc/en/reference/ssh2/functions ssh2-connect.xml
Log:
Flesh out ssh2_connect()
http://cvs.php.net/diff.php/phpdoc/en/reference/ssh2/functions/ssh2-connect.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/ssh2/functions/ssh2-connect.xml
diff -u phpdoc/en/reference/ssh2/functions/ssh2-connect.xml:1.1
phpdoc/en/reference/ssh2/functions/ssh2-connect.xml:1.2
--- phpdoc/en/reference/ssh2/functions/ssh2-connect.xml:1.1 Fri Dec 24
20:03:17 2004
+++ phpdoc/en/reference/ssh2/functions/ssh2-connect.xml Mon Dec 27 18:18:43 2004
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc.
-->
<refentry id="function.ssh2-connect">
<refnamediv>
@@ -18,10 +18,252 @@
<methodparam
choice="opt"><type>array</type><parameter>callbacks</parameter></methodparam>
</methodsynopsis>
- <para>
+ <simpara>
Establish a connection to a remote SSH server and return a resource on
success, false on error
+ </simpara>
+
+ <simpara>
+ <parameter>methods</parameter> may be an associative array with up to
four parameters
+ as described below.
+ </simpara>
+
+ <para>
+ <table>
+ <title><parameter>methods</parameter> may be an associative array
+ with any or all of the following parameters.</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Index</entry>
+ <entry>Meaning</entry>
+ <entry>Supported Values*</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>kex</entry>
+ <entry>
+ List of key exchange methods to advertise, coma separated
+ in order of preference.
+ </entry>
+ <entry>
+ <literal>diffie-hellman-group1-sha1</literal>,
+ <literal>diffie-hellman-group4-sha1</literal>, and
+ <literal>diffie-hellman-group-exchange-sha1</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>hostkey</entry>
+ <entry>
+ List of hostkey methods to advertise, come separated
+ in order of preference.
+ </entry>
+ <entry>
+ <literal>ssh-rsa</literal> and
+ <literal>ssh-dss</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>client_to_server</entry>
+ <entry>
+ Associative array containing crypt, compression, and
+ message authentication code (MAC) method preferences
+ for messages sent from client to server.
+ </entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>server_to_client</entry>
+ <entry>
+ Associative array containing crypt, compression, and
+ message authentication code (MAC) method preferences
+ for messages sent from client to server.
+ </entry>
+ <entry/>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <simpara>
+ * - Supported Values are dependent on methods supported by underlying
library.
+ See <ulink url="&url.libssh2;">libssh2</ulink> documentation for
additional
+ information.
+ </simpara>
+
+ <para>
+ <table>
+ <title>
+ <parameter>client_to_server</parameter> and
+ <parameter>server_to_client</parameter> may be an associative array
+ with any or all of the following parameters.
+ </title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Index</entry>
+ <entry>Meaning</entry>
+ <entry>Supported Values*</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>crypt</entry>
+ <entry>List of crypto methods to advertise, coma separated
+ in order of preference.</entry>
+ <entry>
+ <literal>[EMAIL PROTECTED]</literal>,
+ <literal>aes256-cbc</literal>,
+ <literal>aes192-cbc</literal>,
+ <literal>aes128-cbc</literal>,
+ <literal>3des-cbc</literal>,
+ <literal>blowfish-cbc</literal>,
+ <literal>cast128-cbc</literal>,
+ <literal>arcfour</literal>, and
+ <literal>none**</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>comp</entry>
+ <entry>List of compression methods to advertise, coma separated
+ in order of preference.</entry>
+ <entry>
+ <literal>zlib</literal> and
+ <literal>none</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>mac</entry>
+ <entry>List of MAC methods to advertise, come separated
+ in order of preference.</entry>
+ <entry>
+ <literal>hmac-sha1</literal>,
+ <literal>hmac-sha1-96</literal>,
+ <literal>hmac-ripemd160</literal>,
+ <literal>[EMAIL PROTECTED]</literal>, and
+ <literal>none**</literal>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <note>
+ <title>Crypt and MAC method "<literal>none</literal>"</title>
+ <simpara>
+ For security reasons, <literal>none</literal> is disabled by the
underlying
+ <ulink url="&url.libssh2;">libssh2</ulink> library unless explicitly
enabled
+ during build time by using the appropriate ./configure options. See
documentation
+ for the underlying library for more information.
+ </simpara>
+ </note>
+
+ <para>
+ <table>
+ <title><parameter>callbackss</parameter> may be an associative array
+ with any or all of the following parameters.</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Index</entry>
+ <entry>Meaning</entry>
+ <entry>Prototype</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>ignore</entry>
+ <entry>
+ Name of function to call when an
+ <constant>SSH2_MSG_IGNORE</constant>
+ packet is received
+ </entry>
+ <entry>void ignore_cb($message)</entry>
+ </row>
+ <row>
+ <entry>debug</entry>
+ <entry>
+ Name of function to call when an
+ <constant>SSH2_MSG_DEBUG</constant>
+ packet is received
+ </entry>
+ <entry>void debug_cb($message, $language, $always_display)</entry>
+ </row>
+ <row>
+ <entry>macerror</entry>
+ <entry>
+ Name of function to call when a
+ packet is received but the message authentication
+ code failed. If the callback returns &true;,
+ the mismatch will be ignored, otherwise the
+ connection will be terminated.
+ </entry>
+ <entry>bool macerror_cb($packet)</entry>
+ </row>
+ <row>
+ <entry>disconnect</entry>
+ <entry>
+ Name of function to call when an
+ <constant>SSH2_MSG_DISCONNECT</constant>
+ packet is received
+ </entry>
+ <entry>void disconnect_cb($reason, $message, $language)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</para>
+ <example>
+ <title>
+ 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.
+ </title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+/* Notify the user if the server terminates the connection */
+function my_ssh_disconnect($reason, $message, $language) {
+ printf("Server disconnected with reason code [%d] and message: %s\n",
+ $reason, $message);
+}
+
+$methods = array(
+ 'kex' => 'diffie-hellman-group1-sha1',
+ 'client_to_server' => array(
+ 'crypt' => '3des-cbc',
+ 'comp' => 'none'),
+ 'server_to_client' => array(
+ 'crypt' => 'aes256-cbc,aes192-cbc,aes128-cbc',
+ 'comp' => 'none'));
+
+$callbacks = array('disconnect' => 'my_ssh_disconnect');
+
+$connection = ssh2_connect('shell.example.com', 22, $methods, $callbacks);
+if (!$connect) die('Connection failed');
+?>
+]]>
+ </programlisting>
+ </example>
+
+ <simpara>
+ Once connected, the client should verify the server's hostkey
+ using <function>ssh2_fingerprint</function>, then authenticate
+ using either password or public key.
+ </simpara>
+
+ <simpara>
+ See Also:
+ <function>ssh2_fingerprint</function>,
+ <function>ssh2_auth_none</function>,
+ <function>ssh2_auth_password</function>, and
+ <function>ssh2_auth_pubkey_file</function>
+ </simpara>
+
</refsect1>
</refentry>
