---

13.3.6 Secure Shell

The OpenSSH package includes a client, the ssh command, that allows you to connect to remote machines using the SSH (secure shell) protocol. With the (gnu home services ssh) module, you can set up OpenSSH so that it works in a predictable fashion, almost independently of state on the local machine. To do that, you instantiate home-openssh-service-type in your Home configuration, as explained below.

Scheme Variable: home-openssh-service-type

This is the type of the service to set up the OpenSSH client. It takes care of several things:

• providing a ~/.ssh/config file based on your configuration so that ssh knows about hosts you regularly connect to and their associated parameters;
• providing a ~/.ssh/authorized_keys, which lists public keys that the local SSH server, sshd, may accept to connect to this user account;
• optionally providing a ~/.ssh/known_hosts file so that ssh can authenticate hosts you connect to.

Here is an example of a service and its configuration that you could add to the services field of your home-environment:

(service home-openssh-service-type
         (home-openssh-configuration
          (hosts
           (list (openssh-host (name "ci.guix.gnu.org")
                               (user "charlie"))
                 (openssh-host (name "chbouib")
                               (host-name "chbouib.example.org")
                               (user "supercharlie")
                               (port 10022))))
          (authorized-keys (list (local-file "alice.pub")))))

The example above lists two hosts and their parameters. For instance, running ssh chbouib will automatically connect to chbouib.example.org on port 10022, logging in as user ‘supercharlie’. Further, it marks the public key in alice.pub as authorized for incoming connections.

The value associated with a home-openssh-service-type instance must be a home-openssh-configuration record, as describe below.

Data Type: home-openssh-configuration

This is the datatype representing the OpenSSH client and server configuration in one’s home environment. It contains the following fields:

hosts (default: '())

A list of openssh-host records specifying host names and associated connection parameters (see below). This host list goes into ~/.ssh/config, which ssh reads at startup.

known-hosts (default: *unspecified*)

This must be either:

• *unspecified*, in which case home-openssh-service-type leaves it up to ssh and to the user to maintain the list of known hosts at ~/.ssh/known_hosts, or
• a list of file-like objects, in which case those are concatenated and emitted as ~/.ssh/known_hosts.

The ~/.ssh/known_hosts contains a list of host name/host key pairs that allow ssh to authenticate hosts you connect to and to detect possible impersonation attacks. By default, ssh updates it in a TOFU, trust-on-first-use fashion, meaning that it records the host’s key in that file the first time you connect to it. This behavior is preserved when known-hosts is set to *unspecified*.

If you instead provide a list of host keys upfront in the known-hosts field, your configuration becomes self-contained and stateless: it can be replicated elsewhere or at another point in time. Preparing this list can be relatively tedious though, which is why *unspecified* is kept as a default.

authorized-keys (default: '())

This must be a list of file-like objects, each of which containing an SSH public key that should be authorized to connect to this machine.

Concretely, these files are concatenated and made available as ~/.ssh/authorized_keys. If an OpenSSH server, sshd, is running on this machine, then it may take this file into account: this is what sshd does by default, but be aware that it can also be configured to ignore it.

Data Type: openssh-host

Available openssh-host fields are:

name (type: string)

Name of this host declaration.

host-name (type: maybe-string)

Host name—e.g., "foo.example.org" or "192.168.1.2".

address-family (type: address-family)

Address family to use when connecting to this host: one of AF_INET (for IPv4 only), AF_INET6 (for IPv6 only), or *unspecified* (allowing any address family).

identity-file (type: maybe-string)

The identity file to use—e.g., "/home/charlie/.ssh/id_ed25519".

port (type: maybe-natural-number)

TCP port number to connect to.

user (type: maybe-string)

User name on the remote host.

forward-x11? (default: #f) (type: boolean)

Whether to forward remote client connections to the local X11 graphical display.

forward-x11-trusted? (default: #f) (type: boolean)

Whether remote X11 clients have full access to the original X11 graphical display.

forward-agent? (default: #f) (type: boolean)

Whether the authentication agent (if any) is forwarded to the remote machine.

compression? (default: #f) (type: boolean)

Whether to compress data in transit.

proxy-command (type: maybe-string)

The command to use to connect to the server. As an example, a command to connect via an HTTP proxy at 192.0.2.0 would be: "nc -X connect -x 192.0.2.0:8080 %h %p".

host-key-algorithms (type: maybe-string-list)

The list of accepted host key algorithms—e.g., '("ssh-ed25519").

accepted-key-types (type: maybe-string-list)

The list of accepted user public key types.

extra-content (default: "") (type: raw-configuration-string)

Extra content appended as-is to this Host block in ~/.ssh/config.