services: tor: Make it easier to use UNIX sockets.

[jackhill/guix/guix.git] / doc / guix.texi

diff --git a/doc/guix.texi b/doc/guix.texi
index d2d278d..3a3368b 100644 (file)
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -11450,16 +11450,57 @@ detailed discussion of each configuration field.
 @end deftp
 
 @cindex Tor
-@deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}]
-Return a service to run the @uref{https://torproject.org, Tor} anonymous
-networking daemon.
+@defvr {Scheme Variable} 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
+@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.
+
+@end defvr
 
-The daemon runs as the @code{tor} unprivileged user.  It is passed
-@var{config-file}, a file-like object, with an additional @code{User tor} line
-and lines for hidden services added via @code{tor-hidden-service}.  Run
-@command{man tor} for information about the configuration file.
+@deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}]
+This procedure is deprecated and will be removed in a future release.  Return
+a service of the @code{tor-service-type} type.  @var{config-file} and
+@var{tor} have the same meaning as in @code{<tor-configuration>}.
 @end deffn
 
+@deftp {Data Type} tor-configuration
+@table @asis
+@item @code{tor} (default: @code{tor})
+The package that provides the Tor daemon.  This package is expected to provide
+the daemon at @file{bin/tor} relative to its output directory.  The default
+package is the @uref{https://www.torproject.org, Tor Project's}
+implementation.
+
+@item @code{config-file} (default: @code{(plain-file "empty" "")})
+The configuration file to use.  It will be appended to a default configuration
+file, and the final configuration file will be passed to @code{tor} via its
+@code{-f} option.  This may be any ``file-like'' object (@pxref{G-Expressions,
+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.
+
+@item @code{socks-socket-type} (default: @code{'tcp})
+The default socket type that Tor should use for its SOCKS socket.  This must
+be either @code{'tcp} or @code{'unix}.  If it is @code{'tcp}, then by default
+Tor will listen on TCP port 9050 on the loopback interface (i.e., localhost).
+If it is @code{'unix}, then Tor will listen on the UNIX domain socket
+@file{/var/run/tor/socks-sock}, which will be made writable by members of the
+@code{tor} group.
+
+If you want to customize the SOCKS socket in more detail, leave
+@code{socks-socket-type} at its default value of @code{'tcp} and use
+@code{config-file} to override the default by providing your own
+@code{SocksPort} option.
+@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