5.5 POSIX server

This example application is a toy server able to handle connection sharing. It allows the client user to login and execute commands remotely. Multiple interactive sessions on the server side run separate processes started by a single client. The server code executes in the parent process and relies on libassh in order to manage the connection with the client and the children I/O streams.

We first introduce a few functions designed to execute a child process and setup related I/O redirections. This is the interactive session management code, provided by the application. Then we detail code of the event loops used to run the ssh server session. Those loops are similar to what is implemented in the client example application, but multiple channels and I/O streams are involved here.

The states of interactive sessions are stored in instances of the its_s structure declared below. Our server application has to create those objects when execution of a new interactive session is requested by the client.

This structure contains a state field along with a reference to the associated libassh channel as well as some child process handles:

Our small finite state machine is designed to track the status of an interactive session and is updated by the application functions presented in this section. Here are the existing states:

Because the main loop needs to poll on file descriptors associated with all child processes, we have to keep track of existing its_s objects in a table:

The application functions described below manage the its_s instances. This consists in calling POSIX functions in order to create the child process and redirect its I/O. The content of these functions is not detailed here because an explanation of their behavior is enough to understand the libassh related part of the application that follows.

The its_open function allocates a new its_s object, set its state to ITS_PIPE and store a reference to the channel associated to the interactive session:

The its_pty function changes the state from ITS_PIPE to ITS_PTY. This is an optional step before calling the its_exec function that allows using a pseudo terminal device to redirect the child process I/O instead of relying on some file descriptor pipes .

The its_exec function forks the current process, executes the requested child command and setups redirections of its I/O. This also makes the state of our interactive session object change to ITS_OPEN.

The following three functions are used to manage the flow of data between the ssh2 channels and the child processes.

The its_poll_setup function is used to append some pollfd entries for monitoring child I/O file descriptors prior to invoking poll in the main loop:

The its_child2channel function is then used to handle POLLIN events reported by poll. It processes child inputs and pushes data to the interactive session associated channel. This function is also responsible for closing and half closing the channel when an I/O error is reported by poll. In this case, the state is changed to ITS_HALF_NO_SEND or ITS_CLOSED.

Data flow in the other direction is handled when libassh reports incoming channel data from the remote host. This is handled by the its_channel2child function which writes the incoming data to the standard input stream of the child process.

Finally, the its_eof and its_close functions are called when the library reports that the remote client has closed its I/O streams. The its_eof function changes the state of our interactive session related object to ITS_HALF_NO_RECV or ITS_CLOSED, depending on its previous state. The its_close function simply releases the its_s instance.

The assh event loop is invoked from the I/O event loop. It is designed to handle as many library events as possible without blocking.

The event loop has the same layout as in the client example:

Handling of the ASSH_EVENT_READ, ASSH_EVENT_WRITE and ASSH_EVENT_SESSION_ERROR events has already been covered in previous examples.

The library queries the server application about user authentication methods that must be made available to the remote client. This occurs before the first authentication attempt as well as before retries.

The user authentication relies on helper functions. When the authentication is successful, the user ID of the current process is changed. This is handled by this simple code:

Then comes the channels and requests related events. This is where our interactive session objects are created and managed thanks to the functions defined above.

Our server has to accept channel open messages from the client when starting of an interactive session is requested. This is the case when the channel type reported by the event is "session". The library then keeps the channel object alive until the ASSH_EVENT_CHANNEL_CLOSE event is reported.

Because requests are used to let the client select the command it wants to run on the server, we have to handle the ASSH_EVENT_REQUEST event as well. Any such request can only be related to one of the channel we accepted to open. That's why we are able retrieve the pointer to the associated its_s object we have attached previously. Global requests are rejected.

The "pty-req" request may optionally be used by the client. This requires us to call our its_pty function discussed previously. The asshh_inter_decode_pty_req helper function is used here to validate and decode the data attached to the request but its content is not used in this simple server.

When the client eventually requests execution of a "shell" process, the its_exec function is called:

Note that we do not query the operating system about the actual shell binary to execute in this toy server.

When the client requests execution of an arbitrary command instead of a shell, a similar action is performed. In this case we need to parse the data attached to the request in order to get the command string before calling the its_exec function:

Finally, this event needs to be acknowledged, as usual:

The client may request half-closing the channel if it has no more data to transmit. When this occurs, the ASSH_EVENT_CHANNEL_EOF event is reported and we rely on our its_eof function to handle it:

In any case, libassh will report the ASSH_EVENT_CHANNEL_CLOSE event at some point. This may be due to the client properly closing a single channel or due to a broken connection. This behavior of libassh ensures that we will always be able to properly release resources we have attached to channels by just handling the reported events.

Incoming channel data is handled by our its_channel2child function described previously. If we are not sure it is possible to write to the child input stream without blocking according to the pollfd array, the function returns 1. This interrupts the libassh event loop and yield to the enclosing I/O event loop:

Any other unhandled event is acknowledged, as usual:

The I/O event loop is the main loop of the process that handle a single incoming client connection.

The function below is executed in a new process when a client connects to the server. It creates a new libassh session and starts the I/O polling loop:

The poll system call is used to monitor the network connection to the client as well as I/O of the child processes. Our its_poll_setup function will fill the pollfd array with interactive session related entries.

As shown previously, the poll function is also used to let the library check for ssh2 protocol timeouts:

Our its_child2channel function may now perform the transfer of data from the child processes to the remote client:

The libassh event loop described above is then executed. It may wait for more I/O events or terminate the connection:

Our server main loop implements a simple forking server. Note that the maximum number to connections is not limited.