diff options
| -rw-r--r-- | doc/guix.texi | 176 | ||||
| -rw-r--r-- | gnu/home/services/ssh.scm | 254 | ||||
| -rw-r--r-- | gnu/local.mk | 1 | ||||
| -rw-r--r-- | po/guix/POTFILES.in | 1 |
4 files changed, 431 insertions, 1 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index eda0956260..86348fc02c 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -39296,6 +39296,7 @@ services)}. * Shells: Shells Home Services. POSIX shells, Bash, Zsh. * Mcron: Mcron Home Service. Scheduled User's Job Execution. * Shepherd: Shepherd Home Service. Managing User's Daemons. +* SSH: Secure Shell. Setting up the secure shell client. * Desktop: Desktop Home Services. Services for graphical environments. @end menu @c In addition to that Home Services can provide @@ -39616,7 +39617,7 @@ GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,, mcron, GNU@tie{}mcron}). The information about system's mcron is applicable here (@pxref{Scheduled Job Execution}), the only difference for home services is that they have to be declared in a -@code{home-envirnoment} record instead of an @code{operating-system} +@code{home-environment} record instead of an @code{operating-system} record. @defvr {Scheme Variable} home-mcron-service-type @@ -39684,6 +39685,179 @@ mechanism instead (@pxref{Shepherd Services}). @end table @end deftp +@node Secure Shell +@subsection Secure Shell + +@cindex secure shell client, configuration +@cindex SSH client, configuration +The @uref{https://www.openssh.com, OpenSSH package} includes a client, +the @command{ssh} command, that allows you to connect to remote machines +using the @acronym{SSH, secure shell} protocol. With the @code{(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 @code{home-openssh-service-type} in your +Home configuration, as explained below. + +@defvr {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: + +@itemize +@item +providing a @file{~/.ssh/config} file based on your configuration so +that @command{ssh} knows about hosts you regularly connect to and their +associated parameters; + +@item +providing a @file{~/.ssh/authorized_keys}, which lists public keys that +the local SSH server, @command{sshd}, may accept to connect to this user +account; + +@item +optionally providing a @file{~/.ssh/known_hosts} file so that @file{ssh} +can authenticate hosts you connect to. +@end itemize + +Here is a sample configuration you could add to the @code{services} +field of your @code{home-environment}: + +@lisp +(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")))) +@end lisp + +The example above lists two hosts and their parameters. For instance, +running @command{ssh chbouib} will automatically connect to +@code{chbouib.example.org} on port 10022, logging in as user +@samp{supercharlie}. Further, it marks the public key in +@file{alice.pub} as authorized for incoming connections. + +The value associated with a @code{home-openssh-service-type} instance +must be a @code{home-openssh-configuration} record, as describe below. +@end defvr + +@deftp {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: + +@table @asis +@item @code{hosts} (default: @code{'()}) +A list of @code{openssh-host} records specifying host names and +associated connection parameters (see below). This host list goes into +@file{~/.ssh/config}, which @command{ssh} reads at startup. + +@item @code{known-hosts} (default: @code{*unspecified*}) +This must be either: + +@itemize +@item +@code{*unspecified*}, in which case @code{home-openssh-service-type} +leaves it up to @command{ssh} and to the user to maintain the list of +known hosts at @file{~/.ssh/known_hosts}, or + +@item +a list of file-like objects, in which case those are concatenated and +emitted as @file{~/.ssh/known_hosts}. +@end itemize + +The @file{~/.ssh/known_hosts} contains a list of host name/host key +pairs that allow @command{ssh} to authenticate hosts you connect to and +to detect possible impersonation attacks. By default, @command{ssh} +updates it in a @dfn{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 @code{known-hosts} is set to +@code{*unspecified*}. + +If you instead provide a list of host keys upfront in the +@code{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 +@code{*unspecified*} is kept as a default. + +@item @code{authorized-keys} (default: @code{'()}) +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 +@file{~/.ssh/authorized_keys}. If an OpenSSH server, @command{sshd}, is +running on this machine, then it @emph{may} take this file into account: +this is what @command{sshd} does by default, but be aware that it can +also be configured to ignore it. +@end table +@end deftp + +@c %start of fragment + +@deftp {Data Type} openssh-host +Available @code{openssh-host} fields are: + +@table @asis +@item @code{name} (type: string) +Name of this host declaration. + +@item @code{host-name} (type: maybe-string) +Host name---e.g., @code{"foo.example.org"} or @code{"192.168.1.2"}. + +@item @code{address-family} (type: address-family) +Address family to use when connecting to this host: one of +@code{AF_INET} (for IPv4 only), @code{AF_INET6} (for IPv6 only), or +@code{*unspecified*} (allowing any address family). + +@item @code{identity-file} (type: maybe-string) +The identity file to use---e.g., @code{"/home/charlie/.ssh/id_ed25519"}. + +@item @code{port} (type: maybe-natural-number) +TCP port number to connect to. + +@item @code{user} (type: maybe-string) +User name on the remote host. + +@item @code{forward-x11?} (default: @code{#f}) (type: boolean) +Whether to forward remote client connections to the local X11 graphical +display. + +@item @code{forward-x11-trusted?} (default: @code{#f}) (type: boolean) +Whether remote X11 clients have full access to the original X11 +graphical display. + +@item @code{forward-agent?} (default: @code{#f}) (type: boolean) +Whether the authentication agent (if any) is forwarded to the remote +machine. + +@item @code{compression?} (default: @code{#f}) (type: boolean) +Whether to compress data in transit. + +@item @code{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: @code{"nc -X connect +-x 192.0.2.0:8080 %h %p"}. + +@item @code{host-key-algorithms} (type: maybe-string-list) +The list of accepted host key algorithms---e.g., +@code{'("ssh-ed25519")}. + +@item @code{accepted-key-types} (type: maybe-string-list) +The list of accepted user public key types. + +@item @code{extra-content} (default: @code{""}) (type: raw-configuration-string) +Extra content appended as-is to this @code{Host} block in +@file{~/.ssh/config}. + +@end table + +@end deftp + + +@c %end of fragment + + @node Desktop Home Services @subsection Desktop Home Services diff --git a/gnu/home/services/ssh.scm b/gnu/home/services/ssh.scm new file mode 100644 index 0000000000..ff2992766c --- /dev/null +++ b/gnu/home/services/ssh.scm @@ -0,0 +1,254 @@ +;;; GNU Guix --- Functional package management for GNU +;;; Copyright © 2022 Ludovic Courtès <ludo@gnu.org> +;;; +;;; This file is part of GNU Guix. +;;; +;;; GNU Guix is free software; you can redistribute it and/or modify it +;;; under the terms of the GNU General Public License as published by +;;; the Free Software Foundation; either version 3 of the License, or (at +;;; your option) any later version. +;;; +;;; GNU Guix is distributed in the hope that it will be useful, but +;;; WITHOUT ANY WARRANTY; without even the implied warranty of +;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;; GNU General Public License for more details. +;;; +;;; You should have received a copy of the GNU General Public License +;;; along with GNU Guix. If not, see <http://www.gnu.org/licenses/>. + +(define-module (gnu home services ssh) + #:use-module (guix gexp) + #:use-module (guix records) + #:use-module (guix diagnostics) + #:use-module (guix i18n) + #:use-module (gnu services) + #:use-module (gnu services configuration) + #:use-module (guix modules) + #:use-module (gnu home services) + #:use-module ((gnu home services utils) + #:select (object->camel-case-string)) + #:autoload (gnu packages base) (glibc-utf8-locales) + #:use-module (srfi srfi-1) + #:use-module (srfi srfi-34) + #:use-module (srfi srfi-35) + #:use-module (ice-9 match) + #:export (home-openssh-configuration + home-openssh-configuration-authorized-keys + home-openssh-configuration-known-hosts + home-openssh-configuration-hosts + + openssh-host + openssh-host-host-name + openssh-host-identity-file + openssh-host-name + openssh-host-port + openssh-host-user + openssh-host-forward-x11? + openssh-host-forward-x11-trusted? + openssh-host-forward-agent? + openssh-host-compression? + openssh-host-proxy-command + openssh-host-host-key-algorithms + openssh-host-accepted-key-types + openssh-host-extra-content + + home-openssh-service-type)) + +(define (serialize-field-name name) + (match name + ('accepted-key-types "PubkeyAcceptedKeyTypes") + (_ + (let ((name (let ((str (symbol->string name))) + (if (string-suffix? "?" str) + (string->symbol (string-drop-right str 1)) + name)))) + (object->camel-case-string name 'upper))))) + +(define (serialize-string field value) + (string-append " " (serialize-field-name field) + " " value "\n")) + +(define (address-family? obj) + (memv obj (list *unspecified* AF_INET AF_INET6))) + +(define (serialize-address-family field family) + (if (unspecified? family) + "" + (string-append " " (serialize-field-name field) " " + (cond ((= family AF_INET) "inet") + ((= family AF_INET6) "inet6") + ;; The 'else' branch is unreachable. + (else (raise (condition (&error))))) + "\n"))) + +(define (natural-number? obj) + (and (integer? obj) (exact? obj) (> obj 0))) + +(define (serialize-natural-number field value) + (string-append " " (serialize-field-name field) " " + (number->string value) "\n")) + +(define (serialize-boolean field value) + (string-append " " (serialize-field-name field) " " + (if value "yes" "no") "\n")) + +(define-maybe string) +(define-maybe natural-number) + +(define (serialize-raw-configuration-string field value) + (string-append value "\n")) +(define raw-configuration-string? string?) + +(define (string-list? lst) + (and (pair? lst) (every string? lst))) +(define (serialize-string-list field lst) + (string-append " " (serialize-field-name field) " " + (string-join lst ",") "\n")) + +(define-maybe string-list) + +(define-configuration openssh-host + (name + (string) + "Name of this host declaration.") + (host-name + maybe-string + "Host name---e.g., @code{\"foo.example.org\"} or @code{\"192.168.1.2\"}.") + (address-family + address-family + "Address family to use when connecting to this host: one of +@code{AF_INET} (for IPv4 only), @code{AF_INET6} (for IPv6 only), or +@code{*unspecified*} (allowing any address family).") + (identity-file + maybe-string + "The identity file to use---e.g., +@code{\"/home/charlie/.ssh/id_ed25519\"}.") + (port + maybe-natural-number + "TCP port number to connect to.") + (user + maybe-string + "User name on the remote host.") + (forward-x11? + (boolean #f) + "Whether to forward remote client connections to the local X11 graphical +display.") + (forward-x11-trusted? + (boolean #f) + "Whether remote X11 clients have full access to the original X11 graphical +display.") + (forward-agent? + (boolean #f) + "Whether the authentication agent (if any) is forwarded to the remote +machine.") + (compression? + (boolean #f) + "Whether to compress data in transit.") + (proxy-command + 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: @code{\"nc -X +connect -x 192.0.2.0:8080 %h %p\"}.") + (host-key-algorithms + maybe-string-list + "The list of accepted host key algorithms---e.g., +@code{'(\"ssh-ed25519\")}.") + (accepted-key-types + maybe-string-list + "The list of accepted user public key types.") + (extra-content + (raw-configuration-string "") + "Extra content appended as-is to this @code{Host} block in +@file{~/.ssh/config}.")) + +(define (serialize-openssh-host config) + (define (openssh-host-name-field? field) + (eq? (configuration-field-name field) 'name)) + + (string-append + "Host " (openssh-host-name config) "\n" + (string-concatenate + (map (lambda (field) + ((configuration-field-serializer field) + (configuration-field-name field) + ((configuration-field-getter field) config))) + (remove openssh-host-name-field? + openssh-host-fields))))) + +(define-record-type* <home-openssh-configuration> + home-openssh-configuration make-home-openssh-configuration + home-openssh-configuration? + (authorized-keys home-openssh-configuration-authorized-keys ;list of file-like + (default '())) + (known-hosts home-openssh-configuration-known-hosts ;unspec | list of file-like + (default *unspecified*)) + (hosts home-openssh-configuration-hosts ;list of <openssh-host> + (default '()))) + +(define (openssh-configuration->string config) + (string-join (map serialize-openssh-host + (home-openssh-configuration-hosts config)) + "\n")) + +(define* (file-join name files #:optional (delimiter " ")) + "Return a file in the store called @var{name} that is the concatenation +of all the file-like objects listed in @var{files}, with @var{delimited} +inserted after each of them." + (computed-file name + (with-imported-modules '((guix build utils)) + #~(begin + (use-modules (guix build utils)) + + ;; Support non-ASCII file names. + (setenv "GUIX_LOCPATH" + #+(file-append glibc-utf8-locales + "/lib/locale")) + (setlocale LC_ALL "en_US.utf8") + + (call-with-output-file #$output + (lambda (output) + (for-each (lambda (file) + (call-with-input-file file + (lambda (input) + (dump-port input output))) + (display #$delimiter output)) + '#$files))))))) + +(define (openssh-configuration-files config) + (let ((config (plain-file "ssh.conf" + (openssh-configuration->string config))) + (known-hosts (home-openssh-configuration-known-hosts config)) + (authorized-keys (file-join + "authorized_keys" + (home-openssh-configuration-authorized-keys config) + "\n"))) + `((".ssh/authorized_keys" ,authorized-keys) + ,@(if (unspecified? known-hosts) + '() + `((".ssh/known_hosts" + ,(file-join "known_hosts" known-hosts "\n")))) + (".ssh/config" ,config)))) + +(define openssh-activation + (with-imported-modules (source-module-closure + '((gnu build activation))) + #~(begin + (use-modules (gnu build activation)) + + ;; Make sure ~/.ssh is #o700. + (let* ((home (getenv "HOME")) + (dot-ssh (string-append home "/.ssh"))) + (mkdir-p/perms dot-ssh (getpw (getuid)) #o700))))) + +(define home-openssh-service-type + (service-type + (name 'home-openssh) + (extensions + (list (service-extension home-files-service-type + openssh-configuration-files) + (service-extension home-activation-service-type + (const openssh-activation)))) + (description "Configure the OpenSSH @acronym{SSH, secure shell} client +by providing a @file{~/.ssh/config} file, which is honored by the OpenSSH +client,@command{ssh}, and by other tools such as @command{guix deploy}.") + (default-value (home-openssh-configuration)))) diff --git a/gnu/local.mk b/gnu/local.mk index e38eb05205..8044c9010b 100644 --- a/gnu/local.mk +++ b/gnu/local.mk @@ -85,6 +85,7 @@ GNU_SYSTEM_MODULES = \ %D%/home/services/fontutils.scm \ %D%/home/services/shells.scm \ %D%/home/services/shepherd.scm \ + %D%/home/services/ssh.scm \ %D%/home/services/mcron.scm \ %D%/home/services/utils.scm \ %D%/home/services/xdg.scm \ diff --git a/po/guix/POTFILES.in b/po/guix/POTFILES.in index 6b8bd92bb7..201e5dcc87 100644 --- a/po/guix/POTFILES.in +++ b/po/guix/POTFILES.in @@ -6,6 +6,7 @@ gnu/services.scm gnu/system.scm gnu/services/shepherd.scm gnu/home/services.scm +gnu/home/services/ssh.scm gnu/home/services/symlink-manager.scm gnu/system/file-systems.scm gnu/system/image.scm |