diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 505 |
1 files changed, 494 insertions, 11 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index ee10e65be0..c01eb3a656 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -758,6 +758,11 @@ Support for build offloading (@pxref{Daemon Offload Setup}) and version 0.10.2 or later. @item +When @url{https://www.nongnu.org/lzip/lzlib.html, lzlib} is available, lzlib +substitutes can be used and @command{guix publish} can compress substitutes +with lzlib. + +@item When @url{http://www.bzip.org, libbz2} is available, @command{guix-daemon} can use it to compress build logs. @end itemize @@ -9656,12 +9661,20 @@ accept connections from any interface. Change privileges to @var{user} as soon as possible---i.e., once the server socket is open and the signing key has been read. -@item --compression[=@var{level}] -@itemx -C [@var{level}] -Compress data using the given @var{level}. When @var{level} is zero, -disable compression. The range 1 to 9 corresponds to different gzip -compression levels: 1 is the fastest, and 9 is the best (CPU-intensive). -The default is 3. +@item --compression[=@var{method}[:@var{level}]] +@itemx -C [@var{method}[:@var{level}]] +Compress data using the given @var{method} and @var{level}. @var{method} is +one of @code{lzip} and @code{gzip}; when @var{method} is omitted, @code{gzip} +is used. + +When @var{level} is zero, disable compression. The range 1 to 9 corresponds +to different compression levels: 1 is the fastest, and 9 is the best +(CPU-intensive). The default is 3. + +Usually, @code{lzip} compresses noticeably better than @code{gzip} for a small +increase in CPU usage; see +@uref{https://nongnu.org/lzip/lzip_benchmark.html,benchmarks on the lzip Web +page}. Unless @option{--cache} is used, compression occurs on the fly and the compressed streams are not @@ -9672,6 +9685,11 @@ run @command{guix publish} behind a caching proxy, or to use allows @command{guix publish} to add @code{Content-Length} HTTP header to its responses. +This option can be repeated, in which case every substitute gets compressed +using all the selected methods, and all of them are advertised. This is +useful when users may not support all the compression methods: they can select +the one they support. + @item --cache=@var{directory} @itemx -c @var{directory} Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory} @@ -13623,11 +13641,11 @@ Directory to look for faces. @item @code{default-path} (default "/run/current-system/profile/bin") Default PATH to use. -@item @code{minimum-uid} (default 1000) -Minimum UID to display in SDDM. +@item @code{minimum-uid} (default: 1000) +Minimum UID displayed in SDDM and allowed for log-in. -@item @code{maximum-uid} (default 2000) -Maximum UID to display in SDDM +@item @code{maximum-uid} (default: 2000) +Maximum UID to display in SDDM. @item @code{remember-last-user?} (default #t) Remember last user. @@ -16703,6 +16721,297 @@ variables. @end table @end deftp +@subsubheading Getmail service + +@cindex IMAP +@cindex POP + +@deffn {Scheme Variable} getmail-service-type +This is the type of the @uref{http://pyropus.ca/software/getmail/, Getmail} +mail retriever, whose value should be an @code{getmail-configuration}. +@end deffn + +Available @code{getmail-configuration} fields are: + +@deftypevr {@code{getmail-configuration} parameter} symbol name +A symbol to identify the getmail service. + +Defaults to @samp{"unset"}. + +@end deftypevr + +@deftypevr {@code{getmail-configuration} parameter} package package +The getmail package to use. + +@end deftypevr + +@deftypevr {@code{getmail-configuration} parameter} string user +The user to run getmail as. + +Defaults to @samp{"getmail"}. + +@end deftypevr + +@deftypevr {@code{getmail-configuration} parameter} string group +The group to run getmail as. + +Defaults to @samp{"getmail"}. + +@end deftypevr + +@deftypevr {@code{getmail-configuration} parameter} string directory +The getmail directory to use. + +Defaults to @samp{"/var/lib/getmail/default"}. + +@end deftypevr + +@deftypevr {@code{getmail-configuration} parameter} getmail-configuration-file rcfile +The getmail configuration file to use. + +Available @code{getmail-configuration-file} fields are: + +@deftypevr {@code{getmail-configuration-file} parameter} getmail-retriever-configuration retriever +What mail account to retrieve mail from, and how to access that account. + +Available @code{getmail-retriever-configuration} fields are: + +@deftypevr {@code{getmail-retriever-configuration} parameter} string type +The type of mail retriever to use. Valid values include @samp{passwd} +and @samp{static}. + +Defaults to @samp{"SimpleIMAPSSLRetriever"}. + +@end deftypevr + +@deftypevr {@code{getmail-retriever-configuration} parameter} string server +Space separated list of arguments to the userdb driver. + +Defaults to @samp{unset}. + +@end deftypevr + +@deftypevr {@code{getmail-retriever-configuration} parameter} string username +Space separated list of arguments to the userdb driver. + +Defaults to @samp{unset}. + +@end deftypevr + +@deftypevr {@code{getmail-retriever-configuration} parameter} non-negative-integer port +Space separated list of arguments to the userdb driver. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{getmail-retriever-configuration} parameter} string password +Override fields from passwd. + +Defaults to @samp{""}. + +@end deftypevr + +@deftypevr {@code{getmail-retriever-configuration} parameter} list password-command +Override fields from passwd. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{getmail-retriever-configuration} parameter} string keyfile +PEM-formatted key file to use for the TLS negotiation + +Defaults to @samp{""}. + +@end deftypevr + +@deftypevr {@code{getmail-retriever-configuration} parameter} string certfile +PEM-formatted certificate file to use for the TLS negotiation + +Defaults to @samp{""}. + +@end deftypevr + +@deftypevr {@code{getmail-retriever-configuration} parameter} string ca-certs +CA certificates to use + +Defaults to @samp{""}. + +@end deftypevr + +@deftypevr {@code{getmail-retriever-configuration} parameter} parameter-alist extra-parameters +Extra retriever parameters + +Defaults to @samp{()}. + +@end deftypevr + +@end deftypevr + +@deftypevr {@code{getmail-configuration-file} parameter} getmail-destination-configuration destination +What to do with retrieved messages. + +Available @code{getmail-destination-configuration} fields are: + +@deftypevr {@code{getmail-destination-configuration} parameter} string type +The type of mail destination. Valid values include @samp{Maildir}, +@samp{Mboxrd} and @samp{MDA_external}. + +Defaults to @samp{unset}. + +@end deftypevr + +@deftypevr {@code{getmail-destination-configuration} parameter} string-or-filelike path +The path option for the mail destination. The behaviour depends on the +chosen type. + +Defaults to @samp{""}. + +@end deftypevr + +@deftypevr {@code{getmail-destination-configuration} parameter} parameter-alist extra-parameters +Extra destination parameters + +Defaults to @samp{()}. + +@end deftypevr + +@end deftypevr + +@deftypevr {@code{getmail-configuration-file} parameter} getmail-options-configuration options +Configure getmail. + +Available @code{getmail-options-configuration} fields are: + +@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer verbose +If set to @samp{0}, getmail will only print warnings and errors. A +value of @samp{1} means that messages will be printed about retrieving +and deleting messages. If set to @samp{2}, getmail will print messages +about each of it's actions. + +Defaults to @samp{1}. + +@end deftypevr + +@deftypevr {@code{getmail-options-configuration} parameter} boolean read-all +If true, getmail will retrieve all available messages. Otherwise it +will only retrieve messages it hasn't seen previously. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{getmail-options-configuration} parameter} boolean delete +If set to true, messages will be deleted from the server after +retrieving and successfully delivering them. Otherwise, messages will +be left on the server. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-after +Getmail will delete messages this number of days after seeing them, if +they have not been delivered. This means messages will be left on the +server this number of days after delivering them. A value of @samp{0} +disabled this feature. + +Defaults to @samp{0}. + +@end deftypevr + +@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-bigger-than +Delete messages larger than this of bytes after retrieving them, even if +the delete and delete-after options are disabled. A value of @samp{0} +disables this feature. + +Defaults to @samp{0}. + +@end deftypevr + +@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-bytes-per-session +Retrieve messages totalling up to this number of bytes before closing +the session with the server. A value of @samp{0} disables this feature. + +Defaults to @samp{0}. + +@end deftypevr + +@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-message-size +Don't retrieve messages larger than this number of bytes. A value of +@samp{0} disables this feature. + +Defaults to @samp{0}. + +@end deftypevr + +@deftypevr {@code{getmail-options-configuration} parameter} boolean delivered-to +If true, getmail will add a Delivered-To header to messages. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{getmail-options-configuration} parameter} boolean received +If set, getmail adds a Received header to the messages. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{getmail-options-configuration} parameter} string message-log +Getmail will record a log of its actions to the named file. A value of +@samp{""} disables this feature. + +Defaults to @samp{""}. + +@end deftypevr + +@deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-syslog +If true, getmail will record a log of its actions using the system +logger. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-verbose +If true, getmail will log information about messages not retrieved and +the reason for not retrieving them, as well as starting and ending +information lines. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{getmail-options-configuration} parameter} parameter-alist extra-parameters +Extra options to include. + +Defaults to @samp{()}. + +@end deftypevr + +@end deftypevr + +@end deftypevr + +@deftypevr {@code{getmail-configuration} parameter} list idle +A list of mailboxes that getmail should wait on the server for new mail +notifications. This depends on the server supporting the IDLE +extension. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{getmail-configuration} parameter} list environment-variables +Environment variables to set for getmail. + +Defaults to @samp{()}. + +@end deftypevr + @subsubheading Mail Aliases Service @cindex email aliases @@ -19085,6 +19394,180 @@ Additional arguments to pass to the @command{varnishd} process. @end table @end deftp +@subsubheading Patchwork +@cindex Patchwork +Patchwork is a patch tracking system. It can collect patches sent to a +mailing list, and display them in a web interface. + +@defvr {Scheme Variable} patchwork-service-type +Service type for Patchwork. +@end defvr + +The following example is an example of a minimal service for Patchwork, for +the @code{patchwork.example.com} domain. + +@example +(service patchwork-service-type + (patchwork-configuration + (domain "patchwork.example.com") + (settings-module + (patchwork-settings-module + (allowed-hosts (list domain)) + (default-from-email "patchwork@@patchwork.example.com"))) + (getmail-retriever-config + (getmail-retriever-configuration + (type "SimpleIMAPSSLRetriever") + (server "imap.example.com") + (port 993) + (username "patchwork") + (password-command + (list (file-append coreutils "/bin/cat") + "/etc/getmail-patchwork-imap-password")) + (extra-parameters + '((mailboxes . ("Patches")))))))) + +@end example + +There are three records for configuring the Patchwork service. The +@code{<patchwork-configuration>} relates to the configuration for Patchwork +within the HTTPD service. + +The @code{settings-module} field within the @code{<patchwork-configuration>} +record can be populated with the @code{<patchwork-settings-module>} record, +which describes a settings module that is generated within the Guix store. + +For the @code{database-configuration} field within the +@code{<patchwork-settings-module>}, the +@code{<patchwork-database-configuration>} must be used. + +@deftp {Data Type} patchwork-configuration +Data type representing the Patchwork service configuration. This type has the +following parameters: + +@table @asis +@item @code{patchwork} (default: @code{patchwork}) +The Patchwork package to use. + +@item @code{domain} +The domain to use for Patchwork, this is used in the HTTPD service virtual +host. + +@item @code{settings-module} +The settings module to use for Patchwork. As a Django application, Patchwork +is configured with a Python module containing the settings. This can either be +an instance of the @code{<patchwork-settings-module>} record, any other record +that represents the settings in the store, or a directory outside of the +store. + +@item @code{static-path} (default: @code{"/static/"}) +The path under which the HTTPD service should serve the static files. + +@item @code{getmail-retriever-config} +The getmail-retriever-configuration record value to use with +Patchwork. Getmail will be configured with this value, the messages will be +delivered to Patchwork. + +@end table +@end deftp + +@deftp {Data Type} patchwork-settings-module +Data type representing a settings module for Patchwork. Some of these +settings relate directly to Patchwork, but others relate to Django, the web +framework used by Patchwork, or the Django Rest Framework library. This type +has the following parameters: + +@table @asis +@item @code{database-configuration} (default: @code{(patchwork-database-configuration)}) +The database connection settings used for Patchwork. See the +@code{<patchwork-database-configuration>} record type for more information. + +@item @code{secret-key-file} (default: @code{"/etc/patchwork/django-secret-key"}) +Patchwork, as a Django web application uses a secret key for cryptographically +signing values. This file should contain a unique unpredictable value. + +If this file does not exist, it will be created and populated with a random +value by the patchwork-setup shepherd service. + +This setting relates to Django. + +@item @code{allowed-hosts} +A list of valid hosts for this Patchwork service. This should at least include +the domain specified in the @code{<patchwork-configuration>} record. + +This is a Django setting. + +@item @code{default-from-email} +The email address from which Patchwork should send email by default. + +This is a Patchwork setting. + +@item @code{static-url} (default: @code{#f}) +The URL to use when serving static assets. It can be part of a URL, or a full +URL, but must end in a @code{/}. + +If the default value is used, the @code{static-path} value from the +@code{<patchwork-configuration>} record will be used. + +This is a Django setting. + +@item @code{admins} (default: @code{'()}) +Email addresses to send the details of errors that occur. Each value should +be a list containing two elements, the name and then the email address. + +This is a Django setting. + +@item @code{debug?} (default: @code{#f}) +Whether to run Patchwork in debug mode. If set to @code{#t}, detailed error +messages will be shown. + +This is a Django setting. + +@item @code{enable-rest-api?} (default: @code{#t}) +Whether to enable the Patchwork REST API. + +This is a Patchwork setting. + +@item @code{enable-xmlrpc?} (default: @code{#t}) +Whether to enable the XML RPC API. + +This is a Patchwork setting. + +@item @code{force-https-links?} (default: @code{#t}) +Whether to use HTTPS links on Patchwork pages. + +This is a Patchwork setting. + +@item @code{extra-settings} (default: @code{""}) +Extra code to place at the end of the Patchwork settings module. + +@end table +@end deftp + +@deftp {Data Type} patchwork-database-configuration +Data type representing the database configuration for Patchwork. + +@table @asis +@item @code{engine} (default: @code{"django.db.backends.postgresql_psycopg2"}) +The database engine to use. + +@item @code{name} (default: @code{"patchwork"}) +The name of the database to use. + +@item @code{user} (default: @code{"httpd"}) +The user to connect to the database as. + +@item @code{password} (default: @code{""}) +The password to use when connecting to the database. + +@item @code{host} (default: @code{""}) +The host to make the database connection to. + +@item @code{port} (default: @code{""}) +The port on which to connect to the database. + +@end table +@end deftp + @subsubheading FastCGI @cindex fastcgi @cindex fcgiwrap @@ -24132,7 +24615,7 @@ The bootloader theme object describing the theme to use. If no theme is provided, some bootloaders might use a default theme, that's true for GRUB. -@item @code{terminal-outputs} (default: @code{'gfxterm}) +@item @code{terminal-outputs} (default: @code{'(gfxterm)}) The output terminals used for the bootloader boot menu, as a list of symbols. GRUB accepts the values: @code{console}, @code{serial}, @code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, |