diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 128 |
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 |