<a id="exp-ssh-interface"></a>

# SSH interface

<!-- @artefact ssh interface -->

The SSH interface
provides access to the host system’s SSH agent
from inside the workshop,
allowing it to securely use the host’s SSH keys and configuration.

By using the interface,
the SDK publisher allows the workshop to connect to the host’s SSH agent,
which can be useful in various SDK-specific tasks
such as cloning private repositories, accessing remote machines, and so on.

<a id="exp-ssh-plug"></a>

## SSH interface plug

An essential element here is the SSH interface plug,
which is declared in the SDK definition.

Its structure includes just the name of the plug and the interface;
both must be set to `ssh-agent`.

Defining the plug in an SDK
allows the workshops using this SDK to connect to the host’s SSH agent,
which can be useful in various SDK-specific tasks
such as cloning private repositories, accessing remote machines, and so on.

<a id="exp-ssh-slot"></a>

## SSH interface slot

To let SDKs in a workshop access the host’s SSH agent,
**Workshop** provides an SSH interface slot
that multiple SSH interface plugs can access.

When the SDK is installed at runtime during launch and refresh operations,
**Workshop** checks that the plug targeting the slot
passes [validation](https://ubuntu.com/workshop/docs//explanation/interfaces/concepts.md#exp-interfaces-validation);
if it does,
it can be connected.

## Connection

The interface isn’t connected automatically at launch and refresh
for security reasons.
The **workshop connect** and **workshop disconnect** commands
can be invoked manually after the workshop has started:

<!-- @artefact workshop connect -->
<!-- @artefact workshop disconnect -->
```console
$ workshop connect ws/ssh-sdk:ssh-agent
$ workshop disconnect ws/ssh-sdk:ssh-agent
```

Establishing a connection means
a proxy Unix domain socket has been created
and a corresponding `$SSH_AUTH_SOCK` value
has been set for the `workshop` user,
so the host’s SSH identities and configuration
are available inside the workshop.

To check if the interface is connected:

<!-- @artefact workshop connections -->
```console
$ workshop connections --all

  INTERFACE  PLUG                  SLOT                 NOTES
  ...
  ssh-agent  ws/ssh-sdk:ssh-agent  ws/system:ssh-agent  manual
```

This means the host’s SSH identities and configuration
are available inside the workshop:

<!-- @artefact workshop shell -->
```console
$ workshop shell ws
workshop@ws-8584e571$ echo $SSH_AUTH_SOCK

  /var/lib/workshop/run/ssh-agent.sock

workshop@ws-8584e571$ ssh-add -l

  4096 SHA256:cb19/bE/6irqhII1KbQqRmo1royWi58qcUD9MEn/9fE user@example.com (RSA)
```

## See also

Explanation:

- [Interface concepts](https://ubuntu.com/workshop/docs//explanation/interfaces/concepts.md#exp-interface-concepts)
- [Plugs and slots](https://ubuntu.com/workshop/docs//explanation/interfaces/concepts.md#exp-plugs-slots)
- [SDK definition](https://ubuntu.com/workshop/docs//explanation/sdks/concepts.md#exp-sdk-definition)
- [Workshop definition](https://ubuntu.com/workshop/docs//explanation/workshops/concepts.md#exp-workshop-definition)

Reference:

- [workshop connect](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-connect)
- [workshop connections](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-connections)
- [workshop disconnect](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-disconnect)
- [workshop launch](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-launch)
- [workshop refresh](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-refresh)
- [workshop shell](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-shell)