5.1 Remote command execution

The simple client application presented in this section is designed to connect to an ssh2 server and request execution of a command. It can be invoked like this:

The first thing to do in the program main function is initialization of the external libraries. libassh does not actually need this, but some other libraries like Libgcrypt and OpenSSL used by modules may require calling a global initialization function. If you do not want to bother about which third party libraries are involved in your build of libassh, just call the assh_deps_init function:

If you know that your build of libassh on your specific platform do not need this, you can skip this step.

Our application then parses command line arguments and setups a TCP socket to the remote server. This part of the program is not quoted here. All it does is proper initialization of the sock file descriptor and of the command string variables from command line arguments.

An struct assh_session_s object is needed in order to store the state of the whole ssh2 session. This requires an struct assh_context_s object used to store resources that may be shared by multiple sessions. That's why initializing a new library context is the first thing to do. Modules can then be registered on the new context:

Note that error handling is minimalist here as we just make the application exit if something goes wrong.

Our struct assh_session_s object can then be initialized and attached to the context:

Our application will need to handle the user authentication related events originating from the server and reported by the library. That's why we have to keep track of user authentication methods we want to use. A variable will be update to reflect methods that have not been already tried:

The interactive session part of the connection protocol runs on the highest layer of ssh2. This component is used to request execution of a process on the remote server. Note that despite his name, the interactive session concept is not related to the struct assh_session_s type presented above.

Even if more advanced applications will want to implement interactive sessions directly, the library provides a small helper state machine that performs basic handling of client interactive sessions. This is used below to handle request and channel related events that allow remote execution of the user command. The code of the helper is not an internal part of the library. Feel free to study and paste the code of this helper state machine directly in your application, as a starting point for more complex constructs.

At this point, we just need to initializes a state object for this helper:

Then comes the event loop, as described in the Event based API section:

The I/O events are reported by the library in order to let the application transfer the ssh2 stream over the network. In this example, this is left to an helper function designed to read and write the ssh2 network stream using the application provided socket file descriptor:

Error notifications are also reported as events by the library. This event is handled here without relying on an helper function. That's why the application has to take care of acknowledging the event by making a direct call to the assh_event_done function:

Note that this event is only used for notification and must not result in exiting the event processing loop. The library may still report more events, allowing the application to clean open channels and other resources properly.

Then come events that are only reported during specific phases of the protocol. Those are related to the key-exchange process and to the currently running service.

When the server sends its host key during the key-exchange process, our client needs to check if it is a known key or if the user accept the new key. An helper function handles this by looking in the ~/.ssh/known_hosts file. This helper also queries the user on the terminal if needed.

The application could have handled this in a custom way in order to adapt the usage or support a specific target platform API.

Once again an helper function is used to handle the user authentication events. It takes care of querying the system user database and reads user public key files:

Then comes execution of the interactive sessions FSM that allows starting a process on a remote host. The ssh2 protocol is able to multiplex many application channels over a session. However, our simple tool only wants to start a single command, that's why we choose to properly shutdown the ssh2 session when our single interactive session ends:

Because the library still needs to exchange packets in order to properly terminate the connection, we still have to run the loop after calling the assh_session_disconnect function. The assh_event_get function will stop reporting more events at some point, breaking our main loop as appropriate.

Then comes handling of data transferred over the interactive session channel. When the remote command writes data to its standard output, the remote server forwards it to our client through the only existing struct assh_channel_s object we have. We may then write the data to the standard output on the local side:

We do not want to handle any other type of event that the library may report, but we still have to acknowledge them:

When we eventually exit from the loop, the struct assh_session_s and struct assh_context_s objects can be released: