aboutsummaryrefslogtreecommitdiff
path: root/doc/guix.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/guix.texi')
-rw-r--r--doc/guix.texi120
1 files changed, 106 insertions, 14 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 12346c4b8e..3b7fa50d81 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -50,6 +50,7 @@ Copyright @copyright{} 2018 Oleg Pykhalov@*
Copyright @copyright{} 2018 Mike Gerwitz@*
Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
Copyright @copyright{} 2018 Gábor Boskovits@*
+Copyright @copyright{} 2018 Florian Pelz@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -101,8 +102,9 @@ package management tool written for the GNU system.
@c how to join your own translation team and how to report issues with the
@c translation.
This manual is also available in French (@pxref{Top,,, guix.fr, Manuel de
-référence de GNU Guix}). If you would like to translate it in your native
-language, consider joining the
+référence de GNU Guix}) and German (@pxref{Top,,, guix.de, Referenzhandbuch
+zu GNU Guix}). If you would like to translate it in your native language,
+consider joining the
@uref{https://translationproject.org/domain/guix-manual.html, Translation
Project}.
@@ -193,6 +195,7 @@ Utilities
* Invoking guix copy:: Copying to and from a remote store.
* Invoking guix container:: Process isolation.
* Invoking guix weather:: Assessing substitute availability.
+* Invoking guix processes:: Listing client processes.
Invoking @command{guix build}
@@ -1227,17 +1230,20 @@ etc. This helps achieve reproducible builds (@pxref{Features}).
When the daemon performs a build on behalf of the user, it creates a
build directory under @file{/tmp} or under the directory specified by
-its @code{TMPDIR} environment variable; this directory is shared with
-the container for the duration of the build. Be aware that using a
-directory other than @file{/tmp} can affect build results---for example,
-with a longer directory name, a build process that uses Unix-domain
-sockets might hit the name length limitation for @code{sun_path}, which
-it would otherwise not hit.
+its @code{TMPDIR} environment variable. This directory is shared with
+the container for the duration of the build, though within the container,
+the build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}.
The build directory is automatically deleted upon completion, unless the
build failed and the client specified @option{--keep-failed}
(@pxref{Invoking guix build, @option{--keep-failed}}).
+The daemon listens for connections and spawns one sub-process for each session
+started by a client (one of the @command{guix} sub-commands.) The
+@command{guix processes} command allows you to get an overview of the activity
+on your system by viewing each of the active sessions and clients.
+@xref{Invoking guix processes}, for more information.
+
The following command-line options are supported:
@table @code
@@ -6051,6 +6057,7 @@ the Scheme programming interface of Guix in a convenient way.
* Invoking guix copy:: Copying to and from a remote store.
* Invoking guix container:: Process isolation.
* Invoking guix weather:: Assessing substitute availability.
+* Invoking guix processes:: Listing client processes.
@end menu
@node Invoking guix build
@@ -8751,6 +8758,61 @@ with the @code{-m} option of @command{guix package} (@pxref{Invoking
guix package}).
@end table
+@node Invoking guix processes
+@section Invoking @command{guix processes}
+
+The @command{guix processes} command can be useful to developers and system
+administrators, especially on multi-user machines and on build farms: it lists
+the current sessions (connections to the daemon), as well as information about
+the processes involved@footnote{Remote sessions, when @command{guix-daemon} is
+started with @option{--listen} specifying a TCP endpoint, are @emph{not}
+listed.}. Here's an example of the information it returns:
+
+@example
+$ sudo guix processes
+SessionPID: 19002
+ClientPID: 19090
+ClientCommand: guix environment --ad-hoc python
+
+SessionPID: 19402
+ClientPID: 19367
+ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{}
+
+SessionPID: 19444
+ClientPID: 19419
+ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
+LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock
+LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock
+LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock
+ChildProcess: 20495: guix offload x86_64-linux 7200 1 28800
+ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800
+ChildProcess: 27793: guix offload x86_64-linux 7200 1 28800
+@end example
+
+In this example we see that @command{guix-daemon} has three clients:
+@command{guix environment}, @command{guix publish}, and the Cuirass continuous
+integration tool; their process identifier (PID) is given by the
+@code{ClientPID} field. The @code{SessionPID} field gives the PID of the
+@command{guix-daemon} sub-process of this particular session.
+
+The @code{LockHeld} fields show which store items are currently locked by this
+session, which corresponds to store items being built or substituted (the
+@code{LockHeld} field is not displayed when @command{guix processes} is not
+running as root.) Last, by looking at the @code{ChildProcess} field, we
+understand that these three builds are being offloaded (@pxref{Daemon Offload
+Setup}).
+
+The output is in Recutils format so we can use the handy @command{recsel}
+command to select sessions of interest (@pxref{Selection Expressions,,,
+recutils, GNU recutils manual}). As an example, the command shows the command
+line and PID of the client that triggered the build of a Perl package:
+
+@example
+$ sudo guix processes | \
+ recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
+ClientPID: 19419
+ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
+@end example
@c *********************************************************************
@node GNU Distribution
@@ -13895,7 +13957,7 @@ Users need to be in the @code{lp} group to access the D-Bus service.
@cindex PulseAudio, sound support
The @code{(gnu services sound)} module provides a service to configure the
-Advanced Linux Sound Architecture (ALSA) system, which making PulseAudio the
+Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the
preferred ALSA output driver.
@deffn {Scheme Variable} alsa-service-type
@@ -16104,10 +16166,10 @@ before switching over to opus audio codec.
How deep channels can be nested at maximum.
@item @code{channelname-regex} (default: @code{#f})
-A string in from of a Qt regular expression that channel names must conform to.
+A string in form of a Qt regular expression that channel names must conform to.
@item @code{username-regex} (default: @code{#f})
-A string in from of a Qt regular expression that user names must conform to.
+A string in form of a Qt regular expression that user names must conform to.
@item @code{text-message-length} (default: @code{5000})
Maximum size in bytes that a user can send in one text chat message.
@@ -16119,7 +16181,7 @@ Maximum size in bytes that a user can send in one image message.
If it is set to @code{#t} clients that use weak password authentification
will not be accepted. Users must have completed the certificate wizard to join.
-@item @code{remember-channel?} (defualt @code{#f})
+@item @code{remember-channel?} (default: @code{#f})
Should murmur remember the last channel each user was in when they disconnected
and put them into the remembered channel when they rejoin.
@@ -16144,7 +16206,7 @@ Murmur also stores logs in the database, which are accessible via RPC.
The default is 31 days of months, but you can set this setting to 0 to keep logs forever,
or -1 to disable logging to the database.
-@item @code{obfuscate-ips?} (default @code{#t})
+@item @code{obfuscate-ips?} (default: @code{#t})
Should logged ips be obfuscated to protect the privacy of users.
@item @code{ssl-cert} (default: @code{#f})
@@ -16546,7 +16608,7 @@ the nginx web server, and also a fastcgi wrapper daemon.
@deffn {Scheme Variable} httpd-service-type
Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server
(@dfn{httpd}). The value for this service type is a
-@code{https-configuration} record.
+@code{httpd-configuration} record.
A simple example configuration is given below.
@@ -16612,6 +16674,10 @@ within the store, for example @code{(file-append mod-wsgi
@end table
@end deffn
+@defvr {Scheme Variable} %default-httpd-modules
+A default list of @code{httpd-module} objects.
+@end defvr
+
@deffn {Data Type} httpd-config-file
This data type represents a configuration file for the httpd service.
@@ -16620,6 +16686,32 @@ This data type represents a configuration file for the httpd service.
The modules to load. Additional modules can be added here, or loaded by
additional configuration.
+For example, in order to handle requests for PHP files, you can use Apache’s
+@code{mod_proxy_fcgi} module along with @code{php-fpm-service-type}:
+
+@example
+(service httpd-service-type
+ (httpd-configuration
+ (config
+ (httpd-config-file
+ (modules (cons*
+ (httpd-module
+ (name "proxy_module")
+ (file "modules/mod_proxy.so"))
+ (httpd-module
+ (name "proxy_fcgi_module")
+ (file "modules/mod_proxy_fcgi.so"))
+ %default-httpd-modules))
+ (extra-config (list "\
+<FilesMatch \\.php$>
+ SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\"
+</FilesMatch>"))))))
+(service php-fpm-service-type
+ (php-fpm-configuration
+ (socket "/var/run/php-fpm.sock")
+ (socket-group "httpd")))
+@end example
+
@item @code{server-root} (default: @code{httpd})
The @code{ServerRoot} in the configuration file, defaults to the httpd
package. Directives including @code{Include} and @code{LoadModule} are