aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
author√Čric Bischoff <eric@bureau-cornavin.com>2010-08-27 16:20:17 +0200
committerAndreas Schneider <asn@cynapses.org>2010-08-27 16:20:17 +0200
commit31ad140d20c37669ed0ed931e0eed0e4c7aa3f44 (patch)
treecd1d9754d742c6a78d4472cb8fc8a4fdb6b4abce /doc
parentbcf4e56fe02042af1accd01b207870a55e1c65b4 (diff)
downloadlibssh-31ad140d20c37669ed0ed931e0eed0e4c7aa3f44.tar.gz
libssh-31ad140d20c37669ed0ed931e0eed0e4c7aa3f44.tar.xz
libssh-31ad140d20c37669ed0ed931e0eed0e4c7aa3f44.zip
doc: More work on the tutorial.
Diffstat (limited to 'doc')
-rw-r--r--doc/forwarding.dox63
-rw-r--r--doc/guided_tour.dox38
-rw-r--r--doc/introduction.dox2
-rw-r--r--doc/scp.dox252
-rw-r--r--doc/sftp.dox2
-rw-r--r--doc/tbd.dox31
6 files changed, 349 insertions, 39 deletions
diff --git a/doc/forwarding.dox b/doc/forwarding.dox
new file mode 100644
index 0000000..f6a2869
--- /dev/null
+++ b/doc/forwarding.dox
@@ -0,0 +1,63 @@
+/**
+@page forwarding Chapter 7: Forwarding connections
+@section forwarding_connections Forwarding connections
+
+Port forwarding comes in SSH protocol in two different flavours:
+direct or reverse port forwarding. Direct port forwarding is also
+named local port forwardind, and reverse port forwarding is also called
+remote port forwarding.
+
+
+
+@subsection forwarding_direct Direct port forwarding
+
+Direct port forwarding is from client to server. The client opens a tunnel,
+and forwards whatever data to the server. Then, the server connects to an
+end point. The end point can reside on another machine or on the SSH
+server itself.
+
+Example of use of direct port forwarding:
+@verbatim
+Mail client application Google Mail
+ | ^
+ 5555 (arbitrary) |
+ | 143 (IMAP2)
+ V |
+ SSH client =====> SSH server
+
+Legend:
+--P-->: port connexion through port P
+=====>: SSH tunnel
+@endverbatim
+A mail client connects to port 5555 of a client. An encrypted tunnel is
+established to the server. The server connects to port 143 of Google Mail (the
+end point). Now the local mail client can retreive mail.
+
+
+@subsection forwarding_reverse Reverse port forwarding
+
+The reverse forwarding is slightly different. It goes from server to client,
+even though the client has the initiative of establishing the tunnel.
+Once the tunnel is established, the server will listen on a port. Whenever
+a connection to this port is made, the server forwards the data to the client.
+
+Example of use of reverse port forwarding:
+@verbatim
+ Local mail server Mail client application
+ ^ |
+ | 5555 (arbitrary)
+ 143 (IMAP2) |
+ | V
+ SSH client <===== SSH server
+
+Legend:
+--P-->: port connexion through port P
+=====>: SSH tunnel
+@endverbatim
+In this example, the SSH client establishes the tunnel,
+but it is used to forward the connections established at
+the server to the client.
+
+*** To be written ***
+
+*/
diff --git a/doc/guided_tour.dox b/doc/guided_tour.dox
index 3d41a3b..5f7a100 100644
--- a/doc/guided_tour.dox
+++ b/doc/guided_tour.dox
@@ -36,9 +36,6 @@ A SSH session goes through the following steps:
The sftp and scp subsystems use channels, but libssh hides them to
the programmer. If you want to use those subsystems, instead of a channel,
you'll usually open a "sftp session" or a "scp session".
-
-All the libssh functions which return an error code also set an error message.
-Error codes are typically SSH_ERROR for integer values, or NULL for pointers.
@subsection setup Creating the session and setting options
@@ -418,12 +415,41 @@ int show_remote_processes(ssh_session session)
}
@endcode
-That's the end of our step-by-step discovery of a SSH connection.
-The next chapter describes more in depth the authentication mechanisms.
-
@see @ref opening_shell
@see @ref remote_commands
@see @ref sftp_subsystem
@see @ref scp_subsystem
+
+@subsection errors Handling the errors
+
+All the libssh functions which return an error value also set an English error message
+describing the problem.
+
+Error values are typically SSH_ERROR for integer values, or NULL for pointers.
+
+The function ssh_get_error() returns a pointer to the static error message.
+
+ssh_error_code() returns the error code number : SSH_NO_ERROR,
+SSH_REQUEST_DENIED, SSH_INVALID_REQUEST, SSH_CONNECTION_LOST, SSH_FATAL,
+or SSH_INVALID_DATA. SSH_REQUEST_DENIED means the ssh server refused your
+request, but the situation is recoverable. The others mean something happened
+to the connection (some encryption problems, server problems, ...).
+SSH_INVALID_REQUEST means the library got some garbage from server, but
+might be recoverable. SSH_FATAL means the connection has an important
+problem and isn't probably recoverable.
+
+Most of time, the error returned are SSH_FATAL, but some functions
+(generaly the ssh_request_xxx ones) may fail because of server denying request.
+In these cases, SSH_REQUEST_DENIED is returned.
+
+ssh_get_error() and ssh_get_error_code() take a ssh_session as a parameter.
+That's for thread safety, error messages that can be attached to a session
+aren't static anymore. Any error that happens during ssh_options_xxx()
+or ssh_connect() (i.e., outside of any session) can be retrieved by
+giving NULL as argument.
+
+The SFTP subsystem has its own error codes, in addition to libssh ones.
+
+
*/
diff --git a/doc/introduction.dox b/doc/introduction.dox
index 9026a9d..4c51d14 100644
--- a/doc/introduction.dox
+++ b/doc/introduction.dox
@@ -41,6 +41,8 @@ Table of contents:
@subpage scp
+@subpage forwarding
+
@subpage tbd
*/
diff --git a/doc/scp.dox b/doc/scp.dox
index 811b51f..fdf589e 100644
--- a/doc/scp.dox
+++ b/doc/scp.dox
@@ -2,6 +2,256 @@
@page scp Chapter 6: The SCP subsystem
@section scp_subsystem The SCP subsystem
-*** To be written ***
+The SCP subsystem has far less functionnality than the SFTP subsystem.
+However, if you only need to copy files from and to the remote system,
+it does its job.
+
+
+@subsection scp_session Opening and closing a SCP session
+
+Like in the SFTP subsystem, you don't handle the SSH channels directly.
+Instead, you open a "SCP session".
+
+When you open your SCP session, you have to choose between read or write mode.
+You can't do both in the same session. So you specify either SSH_SCP_READ or
+SSH_SCP_WRITE as the second parameter of function ssh_scp_new().
+
+Another important mode flag for opening your SCP session is SSH_SCP_RECURSIVE.
+When you use SSH_SCP_RECURSIVE, you declare that you are willing to emulate
+the behaviour of "scp -r" command in your program, no matter it is for
+reading or for writing.
+
+Once your session is created, you initialize it with ssh_scp_init(). When
+you have finished transferring files, you terminate the SCP connection with
+ssh_scp_close(). Finally, you can dispose the SCP connection with
+ssh_scp_free().
+
+The example below does the maintenance work to open a SCP connection for writing in
+recursive mode:
+
+@code
+int scp_write(ssh_session session)
+{
+ ssh_scp scp;
+ int rc;
+
+ scp = ssh_scp_new
+ (session, SSH_SCP_WRITE | SSH_SCP_RECURSIVE, ".");
+ if (scp == NULL)
+ {
+ fprintf(stderr, "Error allocating scp session: %s\n", ssh_get_error(session));
+ return SSH_ERROR;
+ }
+
+ rc = ssh_scp_init(scp);
+ if (rc != SSH_OK)
+ {
+ fprintf(stderr, "Error initializing scp session: %s\n", ssh_get_error(session));
+ ssh_scp_free(scp);
+ return rc;
+ }
+
+ ...
+
+ ssh_scp_close(scp);
+ ssh_scp_free(scp);
+ return SSH_OK;
+}
+@endcode
+
+The example below shows how to open a connection to read a single file:
+
+@code
+int scp_read(ssh_session session)
+{
+ ssh_scp scp;
+ int rc;
+
+ scp = ssh_scp_new
+ (session, SSH_SCP_READ, "helloworld/helloworld.txt");
+ if (scp == NULL)
+ {
+ fprintf(stderr, "Error allocating scp session: %s\n", ssh_get_error(session));
+ return SSH_ERROR;
+ }
+
+ rc = ssh_scp_init(scp);
+ if (rc != SSH_OK)
+ {
+ fprintf(stderr, "Error initializing scp session: %s\n", ssh_get_error(session));
+ ssh_scp_free(scp);
+ return rc;
+ }
+
+ ...
+
+ ssh_scp_close(scp);
+ ssh_scp_free(scp);
+ return SSH_OK;
+}
+
+@endcode
+
+
+@subsection scp_write Creating files and directories
+
+You create directories with ssh_scp_push_directory(). In recursive mode,
+you are placed in this directory once it is created. If the directory
+already exists and if you are in recursive mode, you simply enter that
+directory.
+
+Creating files is done in two steps. First, you prepare the writing with
+ssh_scp_push_file(). Then, you write the data with ssh_scp_write().
+The length of the data to write must be identical between both function calls.
+There's no need to "open" nor "close" the file, this is done automatically
+on the remote end. If the file already exists, it is overwritten and truncated.
+
+The following example creates a new directory named "helloworld/", then creates
+a file named "helloworld.txt" in that directory:
+
+@code
+int scp_helloworld(ssh_session session, ssh_scp scp)
+{
+ int rc;
+ const char *helloworld = "Hello, world!\n";
+ int length = strlen(helloworld);
+
+ rc = ssh_scp_push_directory(scp, "helloworld", S_IRWXU);
+ if (rc != SSH_OK)
+ {
+ fprintf(stderr, "Can't create remote directory: %s\n", ssh_get_error(session));
+ return rc;
+ }
+
+ rc = ssh_scp_push_file
+ (scp, "helloworld.txt", length, S_IRUSR | S_IWUSR);
+ if (rc != SSH_OK)
+ {
+ fprintf(stderr, "Can't open remote file: %s\n", ssh_get_error(session));
+ return rc;
+ }
+
+ rc = ssh_scp_write(scp, helloworld, length);
+ if (rc != SSH_OK)
+ {
+ fprintf(stderr, "Can't write to remote file: %s\n", ssh_get_error(session));
+ return rc;
+ }
+
+ return SSH_OK;
+}
+@endcode
+
+
+@subsection scp_recursive_write Copying full directory trees to the remote server
+
+Let's say you want to copy the following tree of files to the remote site:
+
+@verbatim
+ +-- file1
+ +-- B --+
+ | +-- file2
+-- A --+
+ | +-- file3
+ +-- C --+
+ +-- file4
+@endverbatim
+
+You would do it that way:
+ - open the session in recursive mode
+ - enter directory A
+ - enter its subdirectory B
+ - create file1 in B
+ - create file2 in B
+ - leave directory B
+ - enter subdirectory C
+ - create file3 in C
+ - create file4 in C
+ - leave directory C
+ - leave directory A
+
+To leave a directory, call ssh_scp_leave_directory().
+
+
+@subsection scp_read Reading files and directories
+
+
+To receive files, you pull requests from the other side with ssh_scp_pull_request().
+If this function returns SSH_SCP_REQUEST_NEWFILE, then you must get ready for
+the reception. You can get the size of the data to receive with ssh_scp_request_get_size()
+and allocate a buffer accordingly. When you are ready, you accept the request with
+ssh_scp_accept_request(), then read the data with ssh_scp_read().
+
+The following example receives a single file. The name of the file to
+receive has been given earlier, when the scp session was opened:
+
+@code
+int scp_receive(ssh_session session, ssh_scp scp)
+{
+ int rc;
+ int size, mode;
+ char *filename, *buffer;
+
+ rc = ssh_scp_pull_request(scp);
+ if (rc != SSH_SCP_REQUEST_NEWFILE)
+ {
+ fprintf(stderr, "Error receiving information about file: %s\n", ssh_get_error(session));
+ return SSH_ERROR;
+ }
+
+ size = ssh_scp_request_get_size(scp);
+ filename = strdup(ssh_scp_request_get_filename(scp));
+ mode = ssh_scp_request_get_permissions(scp);
+ printf("Receiving file %s, size %d, permisssions 0%o\n", filename, size, mode);
+ free(filename);
+
+ buffer = malloc(size);
+ if (buffer == NULL)
+ {
+ fprintf(stderr, "Memory allocation error\n");
+ return SSH_ERROR;
+ }
+
+ ssh_scp_accept_request(scp);
+ rc = ssh_scp_read(scp, buffer, size);
+ if (rc == SSH_ERROR)
+ {
+ fprintf(stderr, "Error receiving file data: %s\n", ssh_get_error(session));
+ free(buffer);
+ return rc;
+ }
+ printf("Done\n");
+
+ write(1, buffer, size);
+ free(buffer);
+
+ rc = ssh_scp_pull_request(scp);
+ if (rc != SSH_SCP_REQUEST_EOF)
+ {
+ fprintf(stderr, "Unexpected request: %s\n", ssh_get_error(session));
+ return SSH_ERROR;
+ }
+
+ return SSH_OK;
+}
+@endcode
+
+In this example, since we just requested a single file, we expect ssh_scp_request()
+to return SSH_SCP_REQUEST_NEWFILE first, then SSH_SCP_REQUEST_EOF. That's quite a
+naive approach; for example, the remote server might send a warning as well
+(return code SSH_SCP_REQUEST_WARNING) and the example would fail. A more comprehensive
+reception program would receive the requests in a loop and analyze them carefully
+until SSH_SCP_REQUEST_EOF has been received.
+
+
+@subsection scp_recursive_read Receiving full directory trees from the remote server
+
+If you opened the SCP session in recursive mode, the remote end will be
+telling you when to change directory.
+
+In that case, when ssh_scp_pull_request() answers
+SSH_SCP_REQUEST_NEWDIRECTORY, you should make that local directory (if
+it does not exist yet) and enter it. When ssh_scp_pull_request() answers
+SSH_SCP_REQUEST_ENDDIRECTORY, you should leave the current directory.
*/
diff --git a/doc/sftp.dox b/doc/sftp.dox
index 6f9bcde..7306be5 100644
--- a/doc/sftp.dox
+++ b/doc/sftp.dox
@@ -29,7 +29,7 @@ The current implemented version of the SFTP protocol is version 3. All functions
aren't implemented yet, but the most important are.
-@subsection sftp_section Opening and closing a SFTP session
+@subsection sftp_session Opening and closing a SFTP session
Unlike with remote shells and remote commands, when you use the SFTP subsystem,
you don't handle directly the SSH channels. Instead, you open a "SFTP session".
diff --git a/doc/tbd.dox b/doc/tbd.dox
index 4ee5ab8..1e256fd 100644
--- a/doc/tbd.dox
+++ b/doc/tbd.dox
@@ -1,40 +1,9 @@
/**
@page tbd To be done
-@section errors Handling the errors
-
-When some function returns an error code, it's always possible to get an
-english message describing the problem.
-
-The function ssh_get_error() returns a pointer to the static error buffer.
-
-ssh_error_code() returns the error code number : SSH_NO_ERROR,
-SSH_REQUEST_DENIED, SSH_INVALID_REQUEST, SSH_CONNECTION_LOST, SSH_FATAL,
-or SSH_INVALID_DATA. SSH_REQUEST_DENIED means the ssh server refused your
-request, but the situation is recoverable. The others mean something happened
-to the connection (some encryption problems, server problems, ...).
-SSH_INVALID_REQUEST means the library got some garbage from server, but
-might be recoverable. SSH_FATAL means the connection has an important
-problem and isn't probably recoverable.
-
-Most of time, the error returned are SSH_FATAL, but some functions
-(generaly the ssh_request_xxx ones) may fail because of server denying request.
-In these cases, SSH_REQUEST_DENIED is returned.
-
-ssh_get_error() and ssh_get_error_code() take a ssh_session as a parameter.
-That's for thread safety, error messages that can be attached to a session
-aren't static anymore. Any error that happens during ssh_options_xxx()
-or ssh_connect() (i.e., outside of any session) can be retrieved by
-giving NULL as argument.
-
-
@section threads Working with threads
*** To be written ***
-@section forwarding_connections Forwarding connections
-
-*** To be written ***
-
@section sshd Writing a libssh-based server
*** To be written ***