Merge branch 'master' into core-updates

1 files changed, 126 insertions, 2 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index dfa1e22fcc..e8c4e0eaf3 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -158,6 +158,7 @@ Utilities
 * Invoking guix challenge::     Challenging substitute servers.
 * Invoking guix copy::          Copying to and from a remote store.
 * Invoking guix container::     Process isolation.
+* Invoking guix weather::       Assessing substitute availability.
 
 Invoking @command{guix build}
 
@@ -2201,6 +2202,9 @@ authenticates substitute information itself, as explained above, which
 is what we care about (whereas X.509 certificates are about
 authenticating bindings between domain names and public keys.)
 
+You can get statistics on the substitutes provided by a server using the
+@command{guix weather} command (@pxref{Invoking guix weather}).
+
 The substitute mechanism can be disabled globally by running
 @code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
 guix-daemon}).  It can also be disabled temporarily by passing the
@@ -4933,6 +4937,7 @@ the Scheme programming interface of Guix in a convenient way.
 * Invoking guix challenge::     Challenging substitute servers.
 * Invoking guix copy::          Copying to and from a remote store.
 * Invoking guix container::     Process isolation.
+* Invoking guix weather::       Assessing substitute availability.
 @end menu
 
 @node Invoking guix build
@@ -6869,7 +6874,8 @@ serves them.  This ``on-the-fly'' mode is convenient in that it requires
 no setup and is immediately available.  However, when serving lots of
 clients, we recommend using the @option{--cache} option, which enables
 caching of the archives before they are sent to clients---see below for
-details.
+details.  The @command{guix weather} command provides a handy way to
+check what a server provides (@pxref{Invoking guix weather}).
 
 As a bonus, @command{guix publish} also serves as a content-addressed
 mirror for source files referenced in @code{origin} records
@@ -7269,6 +7275,73 @@ must be PID 1 of the container or one of its child processes.
 
 @end table
 
+@node Invoking guix weather
+@section Invoking @command{guix weather}
+
+Occasionally you're grumpy because substitutes are lacking and you end
+up building packages by yourself (@pxref{Substitutes}).  The
+@command{guix weather} command reports on substitute availability on the
+specified servers so you can have an idea of whether you'll be grumpy
+today.  It can sometimes be useful info as a user, but it is primarily
+useful to people running @command{guix publish} (@pxref{Invoking guix
+publish}).
+
+@cindex statistics, for substitutes
+@cindex availability of substitutes
+@cindex substitute availability
+@cindex weather, substitute availability
+Here's a sample run:
+
+@example
+$ guix weather --substitute-urls=https://guix.example.org
+computing 5,872 package derivations for x86_64-linux...
+looking for 6,128 store items on https://guix.example.org..
+updating list of substitutes from 'https://guix.example.org'... 100.0%
+https://guix.example.org
+  43.4% substitutes available (2,658 out of 6,128)
+  7,032.5 MiB of nars (compressed)
+  19,824.2 MiB on disk (uncompressed)
+  0.030 seconds per request (182.9 seconds in total)
+  33.5 requests per second
+@end example
+
+As you can see, it reports the fraction of all the packages for which
+substitutes are available on the server---regardless of whether
+substitutes are enabled, and regardless of whether this server's signing
+key is authorized.  It also reports the size of the compressed archives
+(``nars'') provided by the server, the size the corresponding store
+items occupy in the store (assuming deduplication is turned off), and
+the server's throughput.
+
+To achieve that, @command{guix weather} queries over HTTP(S) meta-data
+(@dfn{narinfos}) for all the relevant store items.  Like @command{guix
+challenge}, it ignores signatures on those substitutes, which is
+innocuous since the command only gathers statistics and cannot install
+those substitutes.
+
+Among other things, it is possible to query specific system types and
+specific package sets.  The available options are listed below.
+
+@table @code
+@item --substitute-urls=@var{urls}
+@var{urls} is the space-separated list of substitute server URLs to
+query.  When this option is omitted, the default set of substitute
+servers is queried.
+
+@item --system=@var{system}
+@itemx -s @var{system}
+Query substitutes for @var{system}---e.g., @code{aarch64-linux}.  This
+option can be repeated, in which case @command{guix weather} will query
+substitutes for several system types.
+
+@item --manifest=@var{file}
+Instead of querying substitutes for all the packages, only ask for those
+specified in @var{file}.  @var{file} must contain a @dfn{manifest}, as
+with the @code{-m} option of @command{guix package} (@pxref{Invoking
+guix package}).
+@end table
+
+
 @c *********************************************************************
 @node GNU Distribution
 @chapter GNU Distribution
@@ -13658,7 +13731,8 @@ Local accounts with lower values will silently fail to authenticate.
 @cindex web
 @cindex www
 @cindex HTTP
-The @code{(gnu services web)} module provides the following service:
+The @code{(gnu services web)} module provides the nginx web server and
+also a fastcgi wrapper daemon.
 
 @deffn {Scheme Procedure} nginx-service [#:nginx nginx] @
        [#:log-directory ``/var/log/nginx''] @
@@ -13810,6 +13884,56 @@ body of a named location block cannot contain location blocks.
 @end table
 @end deftp
 
+@cindex fastcgi
+@cindex fcgiwrap
+FastCGI is an interface between the front-end and the back-end of a web
+service.  It is a somewhat legacy facility; new web services should
+generally just talk HTTP between the front-end and the back-end.
+However there are a number of back-end services such as PHP or the
+optimized HTTP Git repository access that use FastCGI, so we have
+support for it in Guix.
+
+To use FastCGI, you configure the front-end web server (e.g., nginx) to
+dispatch some subset of its requests to the fastcgi backend, which
+listens on a local TCP or UNIX socket.  There is an intermediary
+@code{fcgiwrap} program that sits between the actual backend process and
+the web server.  The front-end indicates which backend program to run,
+passing that information to the @code{fcgiwrap} process.
+
+@defvr {Scheme Variable} fcgiwrap-service-type
+A service type for the @code{fcgiwrap} FastCGI proxy.
+@end defvr
+
+@deftp {Data Type} fcgiwrap-configuration
+Data type representing the configuration of the @code{fcgiwrap} serice.
+This type has the following parameters:
+@table @asis
+@item @code{package} (default: @code{fcgiwrap})
+The fcgiwrap package to use.
+
+@item @code{socket} (default: @code{tcp:127.0.0.1:9000})
+The socket on which the @code{fcgiwrap} process should listen, as a
+string.  Valid @var{socket} values include
+@code{unix:@var{/path/to/unix/socket}},
+@code{tcp:@var{dot.ted.qu.ad}:@var{port}} and
+@code{tcp6:[@var{ipv6_addr}]:port}.
+
+@item @code{user} (default: @code{fcgiwrap})
+@itemx @code{group} (default: @code{fcgiwrap})
+The user and group names, as strings, under which to run the
+@code{fcgiwrap} process.  The @code{fastcgi} service will ensure that if
+the user asks for the specific user or group names @code{fcgiwrap} that
+the corresponding user and/or group is present on the system.
+
+It is possible to configure a FastCGI-backed web service to pass HTTP
+authentication information from the front-end to the back-end, and to
+allow @code{fcgiwrap} to run the back-end process as a corresponding
+local user.  To enable this capability on the back-end., run
+@code{fcgiwrap} as the @code{root} user and group.  Note that this
+capability also has to be configured on the front-end as well.
+@end table
+@end deftp
+
 
 @node DNS Services
 @subsubsection DNS Services