5.3 Command line client

This example application is a classical ssh command line client for POSIX platforms.

Our client has to handle multiple data streams to communicate with the remote host and drive the terminal. In order not to get blocked by an I/O operation on one of the file descriptors, we need to use the poll system call. This example shows how the API of libassh can be used to deal with this programming model, polling in both directions, so that neither read nor write calls are blocking.

The details of the library initialization as well as other topics covered in the previous examples are not detailed again here.

The application is composed of two loops: the main loop that polls on the various file descriptors and the nested libassh event loop that handles the library events.

We have four file descriptors based data endpoints to deal with:

• The incoming ssh network stream read from the sock socket file descriptor,

• The outgoing ssh network stream transmitted over the same file descriptor,

• The terminal input read from standard input file descriptor 0,

• The terminal output written to the standard output file descriptor 1.

Before entering the main loop, we do declare the pollfd objects needed to monitor the file descriptors:

We need to transfer data between those file descriptors and the following interfaces provided by the library:

• The library network input pulled by the ASSH_EVENT_READ events,

• The library network output pushed by the ASSH_EVENT_WRITE events,

• The remote process output reported by the ASSH_EVENT_CHANNEL_DATA events,

• The remote process input that is sent over the channel by the assh_channel_data_send function.

Because the interactive session is not started immediately, only the network stream needs to be transferred initially. Moreover, we do not always have data to write to the file descriptors. That's why the POLLIN and POLLOUT flags are set conditionally on each iteration of the main loop. The assh_channel_more_data and assh_transport_has_output functions are used to test if the library has some output data to report:

We are almost ready to call the poll function. Because this system call is also able to return after a delay, it is useful to retrieve the next ssh2 protocol timeout delay from the library:

As in the remote command execution example, the application relies on an helper state machine in order to manage the interactive session. Because we only want to run a single session, we have to initiate a disconnection from the remote server when the single session terminates:

We can then deal with data transfered from the local standard input to the remote process input, provided that the interactive session has started and some data are available. The data is written to the open ssh2 channel as explained in the previous example:

If we are not able to read more data from the standard input, an end of file is reported to the remote host. In the same way, if we are not able to write, a channel close is requested. This will makes the library report the ASSH_EVENT_CHANNEL_CLOSE event.

As stated previously, the other data transfers are performed on library events. We then need to handle libassh events at this point. We use an other loop to process those events. This nested loop handle as many events as possible without blocking. This loop is in implemented in the separate ssh_loop function:

The ssh_loop function returns 0 if there are no more events to report. This occurs at the end of the ssh2 session and breaks the main loop.

The ssh_loop function contains the libassh event loop, as stated previously:

Only data transfer related events are shown here, as handling of other events mostly rely on helper functions that deal with user authentication and interactive session management. This is detailed in the remote command execution example.

Because the ASSH_EVENT_READ event wants data available from the socket file descriptor, the loop is interrupted if the poll system call did not allow us to read yet. We yield to the enclosing I/O polling loop in this case.

The event processing loop is interrupted just before trying any I/O operation that may block. The POLLIN flag is cleared so that a single read is allowed between calls to the poll function.

The same mechanism is used for write system calls:

Transferring data from the channel to the terminal requires more work because no helper function is used, but the approach is still the same:

The event handling loop ends as usual:

This non-blocking event loop is sufficient to implement our poll based command line ssh2 client. Note that we rely on helper functions that query the user on the terminal about the validity of the host key. In order to obtain a truly non-blocking event loop, handling of the related events should be re-implemented as well, depending on the application user interface.