Establishing a Shell Connection with an OBC

The shell service is used to provide shell access and commanding from mission operations or a development environment to the OBC.

Pre-Requisites

We’ll be using the shell client in order to communicate with the shell service on our OBC, which is automatically included with the Kubos SDK (as of v1.8.0).

If you are using a local development environment, instead of an instance of the SDK, you’ll need to clone the repo and navigate to the clients/kubos-shell-client folder. You’ll then run the program with cargo run -- {command args}.

Syntax

The shell client has the following command syntax:

kubos-shell-client [options] (start | list | join | kill)

Required arguments:

  • Operation to perform

    • start - Start a new shell session
    • list - List current shell sessions
    • join - Join an existing shell session
    • kill - Kill an existing shell session
    • help - Display the help message

Optional arguments:

  • -i {remote IP} - Default: 0.0.0.0. IP address of the shell service to connect to.
  • -p {remote port} - Default: 8010. UDP port of the shell service to connect to.

Starting a New Shell Session

We’ll start by creating a new shell session between our dev environment and the OBC.

Our command should look like this:

$ kubos-shell-client -i 10.0.2.20 -p 8010 start

Or, from your local dev environment:

$ cargo run -- -i 10.0.2.20 -p 8010 start

The output from the client should look like this:

Starting shell client -> 10.0.2.20:8010
Starting shell session -> 672612
Press enter to send input to the shell session
Press Control-D to detach from the session
$

The shell service has spawned an instance of /bin/bash on the remote system. Any lines on input given to the shell client will be sent to the shell service and executed by the bash instance.

A simple shell session would look like this:

Starting shell client -> 10.0.2.20:8010
Starting shell session -> 672612
Press enter to send input to the shell session
Press Control-D to detach from the session
$ cd /home/kubos
$ pwd
/home/kubos
$ whoami
kubos

You can enter the exit command to quit this bash session, or you can hit Control-D to detach from the session.

Listing Existing Shell Sessions

Next we will look at listing the existing shell sessions on the OBC.

Our command should look like this:

$ kubos-shell-client -i 10.0.2.20 -p 8010 list

The output from the client will look like this because we just started a session in the previous step:

Starting shell client -> 10.0.2.20:8010
Fetching existing shell sessions:
    672612   { path = '/bin/bash', pid = 24939 }

The entries in the sessions list are structured like so:

[channel-id] { path = [process-path], pid = [process-id] }

The channel ID is the unique identifier which can be used with the shell client’s join and kill commands. The process path is the path to the executable running in the session. The process ID is the PID of the running executable on the remote system.

If no sessions exist, then the output from the client will look like this:

Starting shell client -> 10.0.2.20:8010
Fetching existing shell sessions:
    No active sessions found

Joining an Existing Shell Session

If sessions already exist on the OBC then we are able to join them using the join command.

The join command has the following syntax:

kubos-shell-client join -c <channel_id>

The channel ID should belong to a shell session which was previously started.

To join the session started earlier, our command will look like this:

$ kubos-shell-client -i 10.0.2.20 -p 8010 join -c 672612

The output from the client should look like this:

Starting shell client -> 10.0.2.20:8010
Joining existing shell session 672612
Press enter to send input to the shell session
Press Control-D to detach from the session
$

Killing an Existing Shell Session

If sessions already exist on the OBC then we are also able to end them using the kill command. Shell sessions will not end unless the process exits or the kill command is used.

The kill command has the following syntax:

kubos-shell-client kill -c <channel_id> [-s signal]

The kill command requires a channel ID to know which session to kill. Optionally, a signal number may also be passed in. If no signal is specified, then SIGKILL will be sent.

Our command should look like this:

$ kubos-shell-client -i 10.0.2.20 -p 8010 kill -c 672612

The output from the client should look like this:

Starting shell client -> 10.0.2.20:8010
Killing existing shell session -c 672712