diff mbox series

[bug#61789,11/27] services: tor: Deprecate 'tor-hidden-service' procedure.

Message ID 55d9d97eabbb72cf59713b31015e654d028d8623.1677350249.git.mirai@makinata.eu
State New
Headers show
Series Deprecate old-style services. | expand

Commit Message

Bruno Victal Feb. 25, 2023, 6:57 p.m. UTC 
Due to (now renamed) 'hidden-service' record type not being exported,
the only way hidden services could have worked is through the now deprecated
'tor-hidden-service' procedure which also had the issue that it can only
be used once since the returned service always had the same name.

This commit fixes the Tor service documentation and
deprecates 'tor-hidden-service' procedure, correcting some inconsistencies along the way.

* doc/guix.texi (Networking Services): Add examples for Tor hidden services.
Document <tor-hidden-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-hidden-service-configuration,
tor-hidden-service-configuration?, tor-hidden-service-configuration-name,
tor-hidden-service-configuration-mapping.
(<tor-configuration>)[control-socket?]: Rename accessor.
(<hidden-service>): Rename to ...
(<tor-hidden-service-configuration>): ... this.
(tor-configuration->torrc): Update record-type name.
(tor-activation): Ditto.
(tor-service-type): Tweak comment.
(tor-hidden-service-type): Remove variable.
(tor-hidden-service): Deprecate procedure.
---
 doc/guix.texi               | 55 +++++++++++++++++++++++--------------
 gnu/services/networking.scm | 47 +++++++++++++++++--------------
 2 files changed, 61 insertions(+), 41 deletions(-)

Comments

Ludovic Courtès March 3, 2023, 4:43 p.m. UTC | #1 
Bruno Victal <mirai@makinata.eu> skribis:

> Due to (now renamed) 'hidden-service' record type not being exported,
> the only way hidden services could have worked is through the now deprecated
> 'tor-hidden-service' procedure which also had the issue that it can only
> be used once since the returned service always had the same name.
>
> This commit fixes the Tor service documentation and
> deprecates 'tor-hidden-service' procedure, correcting some inconsistencies along the way.

I’m also leaving this one out for now.

Could you please make it a separate patch series, with each aspect in
its own patch?  I realize I’m asking you for extra boring work, but this
should help clarify the kind of changes we’re talking about.

Thanks,
Ludo’.
Bruno Victal March 5, 2023, 5:51 p.m. UTC | #2 
Hi Ludo’,

On 2023-03-03 16:43, Ludovic Courtès wrote:
> Bruno Victal <mirai@makinata.eu> skribis:
> 
>> Due to (now renamed) 'hidden-service' record type not being exported,
>> the only way hidden services could have worked is through the now deprecated
>> 'tor-hidden-service' procedure which also had the issue that it can only
>> be used once since the returned service always had the same name.
>>
>> This commit fixes the Tor service documentation and
>> deprecates 'tor-hidden-service' procedure, correcting some inconsistencies along the way.
> 
> I’m also leaving this one out for now.
> 
> Could you please make it a separate patch series, with each aspect in
> its own patch?  I realize I’m asking you for extra boring work, but this
> should help clarify the kind of changes we’re talking about.

I think it's difficult to split this one into meaningful patches, reason being that
'tor-hidden-service-type' can't be used alone since the record constructor for a
Tor hidden service (hidden-service, which is IMO a "collision prone" name) is not exported.

The fact that it isn't exported also means that the 'hidden-services field from <tor-configuration>
was impossible to configure. Extending 'tor-service-type' was also impossible save for the
(to be deprecated) 'tor-hidden-service' procedure which provisions a 'tor-hidden-service-type'
that is simply a service extension for 'tor-service-type'.

The 'tor-hidden-service' and 'tor-hidden-service-type' are extremely misleading to what will
happen behind the scenes should more than one hidden-service be provisioned (with 'tor-hidden-service').
Since it does so via a 'tor-hidden-service-type' which has its own name, only one of the hidden-services
will get configured, which one = dice roll.

IMO this 'tor-hidden-service-type' shouldn't exist at all and tor-hidden-service can safely be
converted into a simple-service that extends tor-service-type.


Cheers,
Bruno
Ludovic Courtès March 6, 2023, 4:05 p.m. UTC | #3 
HI,

Bruno Victal <mirai@makinata.eu> skribis:

> I think it's difficult to split this one into meaningful patches, reason being that
> 'tor-hidden-service-type' can't be used alone since the record constructor for a
> Tor hidden service (hidden-service, which is IMO a "collision prone" name) is not exported.
>
> The fact that it isn't exported also means that the 'hidden-services field from <tor-configuration>
> was impossible to configure. Extending 'tor-service-type' was also impossible save for the
> (to be deprecated) 'tor-hidden-service' procedure which provisions a 'tor-hidden-service-type'
> that is simply a service extension for 'tor-service-type'.
>
> The 'tor-hidden-service' and 'tor-hidden-service-type' are extremely misleading to what will
> happen behind the scenes should more than one hidden-service be provisioned (with 'tor-hidden-service').
> Since it does so via a 'tor-hidden-service-type' which has its own name, only one of the hidden-services
> will get configured, which one = dice roll.
>
> IMO this 'tor-hidden-service-type' shouldn't exist at all and tor-hidden-service can safely be
> converted into a simple-service that extends tor-service-type.

Hmm, can we still open a separate issue for it?  :-)

I can’t really make up my mind right now.  I think
‘tor-hidden-service-type’ brings a bit of clarity compared to
‘simple-service’, for instance when looking at ‘guix system
extension-graph’.

Then there’s the other issue that upstream calls this “onion services”
these days, so we should also change that.

Thanks,
Ludo’.
diff mbox series

Patch

diff --git a/doc/guix.texi b/doc/guix.texi
index f9ca809e47..eeb2efa488 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -20494,11 +20494,21 @@  Networking Services
 
 @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.
 
+In addition to adding Tor @dfn{hidden service}s records to the service
+configuration directly, this service can be extended by other services to add
+hidden services, as in this example:
+
+@lisp
+(simple-service 'my-extra-hidden-service tor-service-type
+                (list (tor-hidden-service-configuration
+                        (name "extra-hidden-service")
+                        (mapping '((80 "127.0.0.1:8080"))))))
+@end lisp
 @end defvar
 
 @deftp {Data Type} tor-configuration
@@ -20517,11 +20527,10 @@  Networking Services
 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-hidden-service-configuration>} 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.
 
 @item @code{socks-socket-type} (default: @code{'tcp})
 The default socket type that Tor should use for its SOCKS socket.  This must
@@ -20546,26 +20555,32 @@  Networking Services
 @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:
+@cindex hidden service, tor
+@deftp {Data Type} tor-hidden-service-configuration
+Data Type representing a Tor @dfn{hidden service} configuration.
+See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
+project's documentation} for more information.
+
+@table @asis
+@item @code{name} (type: string)
+Name for the Tor @dfn{hidden service}.
+This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory,
+where the @file{hostname} file contains the @samp{.onion} host name for
+the hidden service.
+
+@item @code{mapping} (type: list-of-list)
+List of host---@dfn{hidden-service} port mappings, such as:
 
 @example
- '((22 "127.0.0.1:22")
-   (80 "127.0.0.1:8080"))
+'((22 "127.0.0.1:22")
+  (80 "127.0.0.1:8080"))
 @end example
 
 In this example, port 22 of the hidden service is mapped to local port 22, and
 port 80 is mapped to local port 8080.
 
-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.
-
-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:
 
diff --git a/gnu/services/networking.scm b/gnu/services/networking.scm
index dacf64c2d1..d6e1877ef5 100644
--- a/gnu/services/networking.scm
+++ b/gnu/services/networking.scm
@@ -138,7 +138,16 @@  (define-module (gnu services networking)
 
             tor-configuration
             tor-configuration?
-            tor-hidden-service
+            tor-configuration-tor
+            tor-configuration-config-file
+            tor-configuration-hidden-services
+            tor-configuration-socks-socket-type
+            tor-configuration-control-socket-path
+            tor-hidden-service-configuration
+            tor-hidden-service-configuration?
+            tor-hidden-service-configuration-name
+            tor-hidden-service-configuration-mapping
+            tor-hidden-service  ; deprecated
             tor-service-type
 
             network-manager-configuration
@@ -919,7 +928,7 @@  (define-record-type* <tor-configuration>
                     (default '()))
   (socks-socket-type tor-configuration-socks-socket-type ; 'tcp or 'unix
                      (default 'tcp))
-  (control-socket?  tor-control-socket-path
+  (control-socket?  tor-configuration-control-socket-path
                     (default #f)))
 
 (define %tor-accounts
@@ -933,11 +942,11 @@  (define %tor-accounts
          (home-directory "/var/empty")
          (shell (file-append shadow "/sbin/nologin")))))
 
-(define-record-type <hidden-service>
-  (hidden-service name mapping)
-  hidden-service?
-  (name    hidden-service-name)                   ;string
-  (mapping hidden-service-mapping))               ;list of port/address tuples
+(define-record-type <tor-hidden-service-configuration>
+  (tor-hidden-service-configuration name mapping)
+  tor-hidden-service-configuration?
+  (name    tor-hidden-service-configuration-name)      ;string
+  (mapping tor-hidden-service-configuration-mapping))  ;list of port/address tuples
 
 (define (tor-configuration->torrc config)
   "Return a 'torrc' file for CONFIG."
@@ -977,7 +986,7 @@  (define (tor-configuration->torrc config)
                                                 tcp-port host))
                                       ports hosts)))
                          '#$(map (match-lambda
-                                   (($ <hidden-service> name mapping)
+                                   (($ <tor-hidden-service-configuration> name mapping)
                                     (cons name mapping)))
                                  hidden-services))
 
@@ -1064,7 +1073,7 @@  (define (tor-activation config)
       (chmod "/var/lib" #o755)
 
       (for-each initialize
-                '#$(map hidden-service-name
+                '#$(map tor-hidden-service-configuration-name
                         (tor-configuration-hidden-services config)))))
 
 (define tor-service-type
@@ -1077,7 +1086,7 @@  (define tor-service-type
                        (service-extension activation-service-type
                                           tor-activation)))
 
-                ;; This can be extended with hidden services.
+                ;; This can be extended with tor hidden services.
                 (compose concatenate)
                 (extend (lambda (config services)
                           (tor-configuration
@@ -1090,15 +1099,8 @@  (define tor-service-type
                  "Run the @uref{https://torproject.org, Tor} anonymous
 networking daemon.")))
 
-(define tor-hidden-service-type
-  ;; A type that extends Tor with hidden services.
-  (service-type (name 'tor-hidden-service)
-                (extensions
-                 (list (service-extension tor-service-type list)))
-                (description
-                 "Define a new Tor @dfn{hidden service}.")))
-
-(define (tor-hidden-service name mapping)
+(define-deprecated (tor-hidden-service name mapping)
+  #f
   "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:
 
@@ -1116,8 +1118,11 @@  (define (tor-hidden-service name mapping)
 
 See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
 project's documentation} for more information."
-  (service tor-hidden-service-type
-           (hidden-service name mapping)))
+  (simple-service 'tor-hidden-service
+                  tor-service-type
+                  (list (tor-hidden-service-configuration
+                         (name name)
+                         (mapping mapping)))))
 
 
 ;;;