services: tor: Deprecate 'tor-hidden-service' procedure.

Due to (now renamed) 'hidden-service' record type not being exported, the only
way Onion services (formely hidden services) could have worked is through the
now deprecated 'tor-hidden-service' procedure.

This commit updates the Tor service documentation, corrects some inconsistently
named accessors in <tor-configuration> record-type, renames and refactors
tor-hidden-service-configuration to tor-onion-service-configuration using
define-configuration and also exports it, allowing Onion services to be
configured directly within a <tor-configuration> record.
Lastly, it also deprecates the 'tor-hidden-service' procedure.

* doc/guix.texi (Networking Services): Substitute mentions of “Hidden services”
with “Onion Services”. Add a Tor Onion service configuration example.
Document <tor-onion-service-configuration>. Remove mention of
'tor-hidden-service' procedure.
* gnu/services/networking.scm: Export tor-configuration-tor,
tor-configuration-config-file, tor-configuration-hidden-services,
tor-configuration-socks-socket-type, tor-configuration-control-socket-path,
tor-onion-service-configuration, tor-onion-service-configuration?,
tor-onion-service-configuration-name, tor-onion-service-configuration-mapping.
(<tor-configuration>)[control-socket?]: Rename accessor.
(<hidden-service>): Replace with …
(<tor-onion-service-configuration>): … this.
(tor-configuration->torrc): Update record-type name.
(tor-activation): Ditto.
(tor-hidden-service-type): Remove variable.
(tor-hidden-service): Deprecate procedure.

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

1 files changed, 38 insertions, 24 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index db222dd6df..46e7fd3908 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -20604,11 +20604,22 @@ Spawn a proxy server listening to TLS connections on the specified port.
 
 @cindex Tor
 @defvar tor-service-type
-This is the type for a service that runs the @uref{https://torproject.org,
-Tor} anonymous networking daemon.  The service is configured using a
+Type for a service that runs the @uref{https://torproject.org, Tor}
+anonymous networking daemon.  The service is configured using a
 @code{<tor-configuration>} record.  By default, the Tor daemon runs as the
 @code{tor} unprivileged user, which is a member of the @code{tor} group.
 
+@cindex onion services, for Tor
+Services of this type can be extended by other services to specify
+@dfn{onion services} (in addition to those already specified in
+@code{tor-configuration}) as in this example:
+
+@lisp
+(simple-service 'my-extra-onion-service tor-service-type
+                (list (tor-onion-service-configuration
+                        (name "extra-onion-service")
+                        (mapping '((80 . "127.0.0.1:8080"))))))
+@end lisp
 @end defvar
 
 @deftp {Data Type} tor-configuration
@@ -20627,11 +20638,10 @@ file-like objects}).  See @code{man tor} for details on the configuration file
 syntax.
 
 @item @code{hidden-services} (default: @code{'()})
-The list of @code{<hidden-service>} records to use.  For any hidden service
-you include in this list, appropriate configuration to enable the hidden
-service will be automatically added to the default configuration file.  You
-may conveniently create @code{<hidden-service>} records using the
-@code{tor-hidden-service} procedure described below.
+The list of @code{<tor-onion-service-configuration>} records to use.
+For any onion service you include in this list, appropriate
+configuration to enable the onion service will be automatically added to
+the default configuration file.
 
 @item @code{socks-socket-type} (default: @code{'tcp})
 The default socket type that Tor should use for its SOCKS socket.  This must
@@ -20656,26 +20666,30 @@ If @code{#t}, Tor will listen for control commands on the UNIX domain socket
 @end table
 @end deftp
 
-@cindex hidden service
-@deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
-Define a new Tor @dfn{hidden service} called @var{name} and implementing
-@var{mapping}.  @var{mapping} is a list of port/host tuples, such as:
-
-@example
- '((22 "127.0.0.1:22")
-   (80 "127.0.0.1:8080"))
-@end example
+@cindex onion service, tor
+@deftp {Data Type} tor-onion-service-configuration
+Data Type representing a Tor @dfn{Onion Service} configuration.
+See @url{https://community.torproject.org/onion-services/, the Tor
+project's documentation} for more information.
+Available @code{tor-onion-service-configuration} fields are:
 
-In this example, port 22 of the hidden service is mapped to local port 22, and
-port 80 is mapped to local port 8080.
+@table @asis
+@item @code{name} (type: string)
+Name for this Onion Service.  This creates a
+@file{/var/lib/tor/hidden-services/@var{name}} directory, where the
+@file{hostname} file contains the @indicateurl{.onion} host name for this Onion
+Service.
 
-This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, where
-the @file{hostname} file contains the @code{.onion} host name for the hidden
-service.
+@item @code{mapping} (type: alist)
+Association list of port to address mappings.  The following example:
+@lisp
+'((22 . "127.0.0.1:22")
+  (80 . "127.0.0.1:8080"))
+@end lisp
+maps ports 22 and 80 of the Onion Service to the local ports 22 and 8080.
 
-See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
-project's documentation} for more information.
-@end deffn
+@end table
+@end deftp
 
 The @code{(gnu services rsync)} module provides the following services: