services: ssh: Deprecate 'lsh-service' procedure.

* doc/guix.texi (Networking Services): Remove mention of lsh-service.
Document lsh-service-type and lsh-service-configuration.
* gnu/services/ssh.scm (<lsh-configuration>): Set default values based
on the now deprecated 'lsh-service' procedure.
(lsh-service-type): Set default value.
(lsh-service): Deprecate procedure.

Signed-off-by: Ludovic Courtès <ludo@gnu.org>

1 files changed, 64 insertions, 34 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 1edbad33c6..9c30e97466 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -20725,41 +20725,71 @@ Furthermore, @code{(gnu services ssh)} provides the following services.
 @cindex SSH
 @cindex SSH server
 
-@deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
-       [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
-       [#:allow-empty-passwords? #f] [#:root-login? #f] @
-       [#:syslog-output? #t] [#:x11-forwarding? #t] @
-       [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
-       [#:public-key-authentication? #t] [#:initialize? #t]
-Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
-@var{host-key} must designate a file containing the host key, and readable
-only by root.
-
-When @var{daemonic?} is true, @command{lshd} will detach from the
-controlling terminal and log its output to syslogd, unless one sets
-@var{syslog-output?} to false.  Obviously, it also makes lsh-service
-depend on existence of syslogd service.  When @var{pid-file?} is true,
-@command{lshd} writes its PID to the file called @var{pid-file}.
-
-When @var{initialize?} is true, automatically create the seed and host key
-upon service activation if they do not exist yet.  This may take long and
-require interaction.
-
-When @var{initialize?} is false, it is up to the user to initialize the
-randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
-a key pair with the private key stored in file @var{host-key} (@pxref{lshd
-basics,,, lsh, LSH Manual}).
-
-When @var{interfaces} is empty, lshd listens for connections on all the
-network interfaces; otherwise, @var{interfaces} must be a list of host names
-or addresses.
-
-@var{allow-empty-passwords?} specifies whether to accept log-ins with empty
-passwords, and @var{root-login?} specifies whether to accept log-ins as
-root.
+@defvar lsh-service-type
+Type of the service that runs the GNU@tie{}lsh secure shell (SSH)
+daemon, @command{lshd}.  The value for this service is a
+@code{<lsh-configuration>} object.
+@end defvar
 
-The other options should be self-descriptive.
-@end deffn
+@deftp {Data Type} lsh-configuration
+Data type representing the configuration of @command{lshd}.
+
+@table @asis
+@item @code{lsh} (default: @code{lsh}) (type: file-like)
+The package object of the GNU@tie{}lsh secure shell (SSH) daemon.
+
+@item @code{daemonic?} (default: @code{#t}) (type: boolean)
+Whether to detach from the controlling terminal.
+
+@item @code{host-key} (default: @code{"/etc/lsh/host-key"}) (type: string)
+File containing the @dfn{host key}.  This file must be readable by
+root only.
+
+@item @code{interfaces} (default: @code{()}) (type: list)
+List of host names or addresses that @command{lshd} will listen on.
+If empty, @command{lshd} listens for connections on all the network
+interfaces.
+
+@item @code{port-number} (default: @code{22}) (type: integer)
+Port to listen on.
+
+@item @code{allow-empty-passwords?} (default: @code{#f}) (type: boolean)
+Whether to accept log-ins with empty passwords.
+
+@item @code{root-login?} (default: @code{#f}) (type: boolean)
+Whether to accept log-ins as root.
+
+@item @code{syslog-output?} (default: @code{#t}) (type: boolean)
+Whether to log @command{lshd} standard output to syslogd.
+This will make the service depend on the existence of a syslogd service.
+
+@item @code{pid-file?} (default: @code{#f}) (type: boolean)
+When @code{#t}, @command{lshd} writes its PID to the file specified in
+@var{pid-file}.
+
+@item @code{pid-file} (default: @code{"/var/run/lshd.pid"}) (type: string)
+File that @command{lshd} will write its PID to.
+
+@item @code{x11-forwarding?} (default: @code{#t}) (type: boolean)
+Whether to enable X11 forwarding.
+
+@item @code{tcp/ip-forwarding?} (default: @code{#t}) (type: boolean)
+Whether to enable TCP/IP forwarding.
+
+@item @code{password-authentication?} (default: @code{#t}) (type: boolean)
+Whether to accept log-ins using password authentication.
+
+@item @code{public-key-authentication?} (default: @code{#t}) (type: boolean)
+Whether to accept log-ins using public key authentication.
+
+@item @code{initialize?} (default: @code{#t}) (type: boolean)
+When @code{#f}, it is up to the user to initialize the randomness
+generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
+a key pair with the private key stored in file @var{host-key}
+(@pxref{lshd basics,,, lsh, LSH Manual}).
+
+@end table
+@end deftp
 
 @cindex SSH
 @cindex SSH server