diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/contributing.texi | 10 | ||||
-rw-r--r-- | doc/guix.texi | 1281 |
2 files changed, 1241 insertions, 50 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index f167df067c..3baedb0654 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1086,10 +1086,12 @@ everything has been successfully built. This allows us to fix issues before they hit users, and to reduce the window during which pre-built binaries are not available. -Generally, branches other than @code{master} are considered -@emph{frozen} if there has been a recent evaluation, or there is a -corresponding @code{-next} branch. Please ask on the mailing list or -IRC if unsure where to place a patch. +When we decide to start building the @code{staging} or +@code{core-updates} branches, they will be forked and renamed with the +suffix @code{-frozen}, at which time only bug fixes may be pushed to the +frozen branches. The @code{core-updates} and @code{staging} branches +will remain open to accept patches for the next cycle. Please ask on +the mailing list or IRC if unsure where to place a patch. @c TODO: It would be good with badges on the website that tracks these @c branches. Or maybe even a status page. diff --git a/doc/guix.texi b/doc/guix.texi index 68155dcfe5..17636d9451 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -28,7 +28,7 @@ Copyright @copyright{} 2014, 2015, 2016 Alex Kost@* Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@* -Copyright @copyright{} 2015, 2016, 2017, 2019, 2020 Leo Famulari@* +Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari@* Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020 Ricardo Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@* @@ -45,7 +45,7 @@ Copyright @copyright{} 2017 Federico Beffa@* Copyright @copyright{} 2017, 2018 Carlo Zancanaro@* Copyright @copyright{} 2017 Thomas Danckaert@* Copyright @copyright{} 2017 humanitiesNerd@* -Copyright @copyright{} 2017 Christopher Allan Webber@* +Copyright @copyright{} 2017, 2021 Christopher Lemmer Webber@* Copyright @copyright{} 2017, 2018, 2019, 2020 Marius Bakke@* Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@* Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@* @@ -81,7 +81,7 @@ Copyright @copyright{} 2020 R Veera Kumar@* Copyright @copyright{} 2020 Pierre Langlois@* Copyright @copyright{} 2020 pinoaffe@* Copyright @copyright{} 2020 André Batista@* -Copyright @copyright{} 2020 Alexandru-Sergiu Marton@* +Copyright @copyright{} 2020, 2021 Alexandru-Sergiu Marton@* Copyright @copyright{} 2020 raingloom@* Copyright @copyright{} 2020 Daniel Brooks@* Copyright @copyright{} 2020 John Soo@* @@ -1492,7 +1492,7 @@ 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}}). +(@pxref{Common Build Options, @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 @@ -5560,6 +5560,12 @@ they should be defined in @file{.bash_profile}, which is sourced only by log-in shells. @xref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}, for details on Bash start-up files.}. +Exiting from a Guix environment is the same as exiting from the shell, +and will place the user back in the old environment before @command{guix +environment} was invoked. The next garbage collection (@pxref{Invoking +guix gc}) will clean up packages that were installed from within the +environment and are no longer used outside of it. + @vindex GUIX_ENVIRONMENT @command{guix environment} defines the @env{GUIX_ENVIRONMENT} variable in the shell it spawns; its value is the file name of the @@ -10821,7 +10827,7 @@ build daemon uses. To that end, the first thing to do is to use the @option{--keep-failed} or @option{-K} option of @command{guix build}, which will keep the failed build tree in @file{/tmp} or whatever directory you specified as -@env{TMPDIR} (@pxref{Invoking guix build, @option{--keep-failed}}). +@env{TMPDIR} (@pxref{Common Build Options, @option{--keep-failed}}). From there on, you can @command{cd} to the failed build tree and source the @file{environment-variables} file, which contains all the @@ -14726,6 +14732,7 @@ declaration. * Mail Services:: IMAP, POP3, SMTP, and all that. * Messaging Services:: Messaging services. * Telephony Services:: Telephony services. +* File-Sharing Services:: File-sharing services. * Monitoring Services:: Monitoring services. * Kerberos Services:: Kerberos services. * LDAP Services:: LDAP services. @@ -15615,13 +15622,15 @@ to add @var{device} to the kernel's entropy pool. The service will fail if @cindex priority @cindex realtime @cindex jackd +@cindex nofile +@cindex open file descriptors @deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}] Return a service that installs a configuration file for the @uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html, @code{pam_limits} module}. The procedure optionally takes a list of @code{pam-limits-entry} values, which can be used to specify -@code{ulimit} limits and nice priority limits to user sessions. +@code{ulimit} limits and @code{nice} priority limits to user sessions. The following limits definition sets two hard and soft limits for all login sessions of users in the @code{realtime} group: @@ -15637,6 +15646,22 @@ The first entry increases the maximum realtime priority for non-privileged processes; the second entry lifts any restriction of the maximum address space that can be locked in memory. These settings are commonly used for real-time audio systems. + +Another useful example is raising the maximum number of open file +descriptors that can be used: + +@lisp +(pam-limits-service + (list + (pam-limits-entry "*" 'both 'nofile 100000))) +@end lisp + +In the above example, the asterisk means the limit should apply to any +user. It is important to ensure the chosen value doesn't exceed the +maximum system value visible in the @file{/proc/sys/fs/file-max} file, +else the users would be prevented from login in. For more information +about the Pluggable Authentication Module (PAM) limits, refer to the +@samp{pam_limits} man page from the @code{linux-pam} package. @end deffn @node Scheduled Job Execution @@ -16578,6 +16603,14 @@ 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. + +@item @code{control-socket?} (default: @code{#f}) +Whether or not to provide a ``control socket'' by which Tor can be +controlled to, for instance, dynamically instantiate tor onion services. +If @code{#t}, Tor will listen for control commands on the UNIX domain socket +@file{/var/run/tor/control-sock}, which will be made writable by members of the +@code{tor} group. + @end table @end deftp @@ -19188,6 +19221,48 @@ tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web site} for more information. @end deffn +@cindex scanner access +@defvr {Scheme Variable} sane-service-type +This service provides access to scanners @i{via} +@uref{http://www.sane-project.org, SANE} by installing the necessary +udev rules. It is included in @code{%desktop-services} (@pxref{Desktop +Services}) and relies by default on @code{sane-backends-minimal} package +(see below) for hardware support. +@end defvr + +@defvr {Scheme Variable} sane-backends-minimal +The default package which the @code{sane-service-type} installs. It +supports many recent scanners. +@end defvr + +@defvr {Scheme Variable} sane-backends +This package includes support for all scanners that +@code{sane-backends-minimal} supports, plus older Hewlett-Packard +scanners supported by @code{hplip} package. In order to use this on +a system which relies on @code{%desktop-services}, you may use +@code{modify-services} (@pxref{Service Reference, +@code{modify-services}}) as illustrated below: + +@lisp +(use-modules (gnu)) +(use-service-modules + @dots{} + desktop) +(use-package-modules + @dots{} + scanner) + +(define %my-desktop-services + ;; List of desktop services that supports a broader range of scanners. + (modify-services %desktop-services + (sane-service-type _ => sane-backends))) + +(operating-system + @dots{} + (services %my-desktop-services) +@end lisp +@end defvr + @deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()] Return a configuration allowing an application to access GeoClue location data. @var{name} is the Desktop ID of the application, without @@ -19199,13 +19274,6 @@ this application is allowed location info access. An empty users list means that all users are allowed. @end deffn -@cindex scanner access -@deffn {Scheme Procedure} sane-service-type -This service provides access to scanners @i{via} -@uref{http://www.sane-project.org, SANE} by installing the necessary udev -rules. -@end deffn - @defvr {Scheme Variable} %standard-geoclue-applications The standard list of well-known GeoClue application configurations, granting authority to the GNOME date-and-time utility to ask for the @@ -22297,6 +22365,804 @@ If it is set your server will be linked by this host name instead. +@node File-Sharing Services +@subsection File-Sharing Services + +The @code{(gnu services file-sharing)} module provides services that +assist with transferring files over peer-to-peer file-sharing networks. + +@subsubheading Transmission Daemon Service + +@uref{https://transmissionbt.com/, Transmission} is a flexible +BitTorrent client that offers a variety of graphical and command-line +interfaces. A @code{transmission-daemon-service-type} service provides +Transmission's headless variant, @command{transmission-daemon}, as a +system service, allowing users to share files via BitTorrent even when +they are not logged in. + +@deffn {Scheme Variable} transmission-daemon-service-type +The service type for the Transmission Daemon BitTorrent client. Its +value must be a @code{transmission-daemon-configuration} object as in +this example: + +@lisp +(service transmission-daemon-service-type + (transmission-daemon-configuration + ;; Restrict access to the RPC ("control") interface + (rpc-authentication-required? #t) + (rpc-username "transmission") + (rpc-password + (transmission-password-hash + "transmission" ; desired password + "uKd1uMs9")) ; arbitrary salt value + + ;; Accept requests from this and other hosts on the + ;; local network + (rpc-whitelist-enabled? #t) + (rpc-whitelist '("::1" "127.0.0.1" "192.168.0.*")) + + ;; Limit bandwidth use during work hours + (alt-speed-down (* 1024 2)) ; 2 MB/s + (alt-speed-up 512) ; 512 kB/s + + (alt-speed-time-enabled? #t) + (alt-speed-time-day 'weekdays) + (alt-speed-time-begin + (+ (* 60 8) 30)) ; 8:30 am + (alt-speed-time-end + (+ (* 60 (+ 12 5)) 30)))) ; 5:30 pm +@end lisp +@end deffn + +Once the service is started, users can interact with the daemon through +its Web interface (at @code{http://localhost:9091/}) or by using the +@command{transmission-remote} command-line tool, available in the +@code{transmission} package. (Emacs users may want to also consider the +@code{emacs-transmission} package.) Both communicate with the daemon +through its remote procedure call (RPC) interface, which by default is +available to all users on the system; you may wish to change this by +assigning values to the @code{rpc-authentication-required?}, +@code{rpc-username} and @code{rpc-password} settings, as shown in the +example above and documented further below. + +The value for @code{rpc-password} must be a password hash of the type +generated and used by Transmission clients. This can be copied verbatim +from an existing @file{settings.json} file, if another Transmission +client is already being used. Otherwise, the +@code{transmission-password-hash} and @code{transmission-random-salt} +procedures provided by this module can be used to obtain a suitable hash +value. + +@deffn {Scheme Procedure} transmission-password-hash @var{password} @var{salt} +Returns a string containing the result of hashing @var{password} +together with @var{salt}, in the format recognized by Transmission +clients for their @code{rpc-password} configuration setting. + +@var{salt} must be an eight-character string. The +@code{transmission-random-salt} procedure can be used to generate a +suitable salt value at random. +@end deffn + +@deffn {Scheme Procedure} transmission-random-salt +Returns a string containing a random, eight-character salt value of the +type generated and used by Transmission clients, suitable for passing to +the @code{transmission-password-hash} procedure. +@end deffn + +These procedures are accessible from within a Guile REPL started with +the @command{guix repl} command (@pxref{Invoking guix repl}). This is +useful for obtaining a random salt value to provide as the second +parameter to `transmission-password-hash`, as in this example session: + +@example +$ guix repl +scheme@@(guix-user)> ,use (gnu services file-sharing) +scheme@@(guix-user)> (transmission-random-salt) +$1 = "uKd1uMs9" +@end example + +Alternatively, a complete password hash can generated in a single step: + +@example +scheme@@(guix-user)> (transmission-password-hash "transmission" +(transmission-random-salt)) +$2 = "@{c8bbc6d1740cd8dc819a6e25563b67812c1c19c9VtFPfdsX" +@end example + +The resulting string can be used as-is for the value of +@code{rpc-password}, allowing the password to be kept hidden even in the +operating-system configuration. + +Torrent files downloaded by the daemon are directly accessible only to +users in the ``transmission'' user group, who receive read-only access +to the directory specified by the @code{download-dir} configuration +setting (and also the directory specified by @code{incomplete-dir}, if +@code{incomplete-dir-enabled?} is @code{#t}). Downloaded files can be +moved to another directory or deleted altogether using +@command{transmission-remote} with its @code{--move} and +@code{--remove-and-delete} options. + +If the @code{watch-dir-enabled?} setting is set to @code{#t}, users in +the ``transmission'' group are able also to place @file{.torrent} files +in the directory specified by @code{watch-dir} to have the corresponding +torrents added by the daemon. (The @code{trash-original-torrent-files?} +setting controls whether the daemon deletes these files after processing +them.) + +Some of the daemon's configuration settings can be changed temporarily +by @command{transmission-remote} and similar tools. To undo these +changes, use the service's @code{reload} action to have the daemon +reload its settings from disk: + +@example +# herd reload transmission-daemon +@end example + +The full set of available configuration settings is defined by the +@code{transmission-daemon-configuration} data type. + +@deftp {Data Type} transmission-daemon-configuration +The data type representing configuration settings for Transmission +Daemon. These correspond directly to the settings recognized by +Transmission clients in their @file{settings.json} file. +@end deftp + +@c The following documentation was initially generated by +@c (generate-transmission-daemon-documentation) in (gnu services +@c file-sharing). Manually maintained documentation is better, so we +@c shouldn't hesitate to edit below as needed. However if the change +@c you want to make to this documentation can be done in an automated +@c way, it's probably easier to change (generate-documentation) than to +@c make it below and have to deal with the churn as Transmission Daemon +@c updates. + +@c %start of fragment + +Available @code{transmission-daemon-configuration} fields are: + +@deftypevr {@code{transmission-daemon-configuration} parameter} package transmission +The Transmission package to use. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer stop-wait-period +The period, in seconds, to wait when stopping the service for +@command{transmission-daemon} to exit before killing its process. This +allows the daemon time to complete its housekeeping and send a final +update to trackers as it shuts down. On slow hosts, or hosts with a +slow network connection, this value may need to be increased. + +Defaults to @samp{10}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} string download-dir +The directory to which torrent files are downloaded. + +Defaults to @samp{"/var/lib/transmission-daemon/downloads"}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean incomplete-dir-enabled? +If @code{#t}, files will be held in @code{incomplete-dir} while their +torrent is being downloaded, then moved to @code{download-dir} once the +torrent is complete. Otherwise, files for all torrents (including those +still being downloaded) will be placed in @code{download-dir}. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string incomplete-dir +The directory in which files from incompletely downloaded torrents will +be held when @code{incomplete-dir-enabled?} is @code{#t}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} umask umask +The file mode creation mask used for downloaded files. (See the +@command{umask} man page for more information.) + +Defaults to @samp{18}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rename-partial-files? +When @code{#t}, ``.part'' is appended to the name of partially +downloaded files. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} preallocation-mode preallocation +The mode by which space should be preallocated for downloaded files, one +of @code{none}, @code{fast} (or @code{sparse}) and @code{full}. +Specifying @code{full} will minimize disk fragmentation at a cost to +file-creation speed. + +Defaults to @samp{fast}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean watch-dir-enabled? +If @code{#t}, the directory specified by @code{watch-dir} will be +watched for new @file{.torrent} files and the torrents they describe +added automatically (and the original files removed, if +@code{trash-original-torrent-files?} is @code{#t}). + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string watch-dir +The directory to be watched for @file{.torrent} files indicating new +torrents to be added, when @code{watch-dir-enabled} is @code{#t}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean trash-original-torrent-files? +When @code{#t}, @file{.torrent} files will be deleted from the watch +directory once their torrent has been added (see +@code{watch-directory-enabled?}). + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-down-enabled? +When @code{#t}, the daemon's download speed will be limited to the rate +specified by @code{speed-limit-down}. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-down +The default global-maximum download speed, in kilobytes per second. + +Defaults to @samp{100}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-up-enabled? +When @code{#t}, the daemon's upload speed will be limited to the rate +specified by @code{speed-limit-up}. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-up +The default global-maximum upload speed, in kilobytes per second. + +Defaults to @samp{100}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-enabled? +When @code{#t}, the alternate speed limits @code{alt-speed-down} and +@code{alt-speed-up} are used (in place of @code{speed-limit-down} and +@code{speed-limit-up}, if they are enabled) to constrain the daemon's +bandwidth usage. This can be scheduled to occur automatically at +certain times during the week; see @code{alt-speed-time-enabled?}. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-down +The alternate global-maximum download speed, in kilobytes per second. + +Defaults to @samp{50}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-up +The alternate global-maximum upload speed, in kilobytes per second. + +Defaults to @samp{50}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-time-enabled? +When @code{#t}, the alternate speed limits @code{alt-speed-down} and +@code{alt-speed-up} will be enabled automatically during the periods +specified by @code{alt-speed-time-day}, @code{alt-speed-time-begin} and +@code{alt-time-speed-end}. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} day-list alt-speed-time-day +The days of the week on which the alternate-speed schedule should be +used, specified either as a list of days (@code{sunday}, @code{monday}, +and so on) or using one of the symbols @code{weekdays}, @code{weekends} +or @code{all}. + +Defaults to @samp{all}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-begin +The time of day at which to enable the alternate speed limits, expressed +as a number of minutes since midnight. + +Defaults to @samp{540}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-end +The time of day at which to disable the alternate speed limits, +expressed as a number of minutes since midnight. + +Defaults to @samp{1020}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv4 +The IP address at which to listen for peer connections, or ``0.0.0.0'' +to listen at all available IP addresses. + +Defaults to @samp{"0.0.0.0"}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv6 +The IPv6 address at which to listen for peer connections, or ``::'' to +listen at all available IPv6 addresses. + +Defaults to @samp{"::"}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean peer-port-random-on-start? +If @code{#t}, when the daemon starts it will select a port at random on +which to listen for peer connections, from the range specified +(inclusively) by @code{peer-port-random-low} and +@code{peer-port-random-high}. Otherwise, it listens on the port +specified by @code{peer-port}. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-low +The lowest selectable port number when @code{peer-port-random-on-start?} +is @code{#t}. + +Defaults to @samp{49152}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-high +The highest selectable port number when @code{peer-port-random-on-start} +is @code{#t}. + +Defaults to @samp{65535}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port +The port on which to listen for peer connections when +@code{peer-port-random-on-start?} is @code{#f}. + +Defaults to @samp{51413}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean port-forwarding-enabled? +If @code{#t}, the daemon will attempt to configure port-forwarding on an +upstream gateway automatically using @acronym{UPnP} and +@acronym{NAT-PMP}. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} encryption-mode encryption +The encryption preference for peer connections, one of +@code{prefer-unencrypted-connections}, +@code{prefer-encrypted-connections} or +@code{require-encrypted-connections}. + +Defaults to @samp{prefer-encrypted-connections}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm +The TCP congestion-control algorithm to use for peer connections, +specified using a string recognized by the operating system in calls to +@code{setsockopt} (or set to @code{disabled}, in which case the +operating-system default is used). + +Note that on GNU/Linux systems, the kernel must be configured to allow +processes to use a congestion-control algorithm not in the default set; +otherwise, it will deny these requests with ``Operation not permitted''. +To see which algorithms are available on your system and which are +currently permitted for use, look at the contents of the files +@file{tcp_available_congestion_control} and +@file{tcp_allowed_congestion_control} in the @file{/proc/sys/net/ipv4} +directory. + +As an example, to have Transmission Daemon use +@uref{http://www-ece.rice.edu/networks/TCP-LP/,the TCP Low Priority +congestion-control algorithm}, you'll need to modify your kernel +configuration to build in support for the algorithm, then update your +operating-system configuration to allow its use by adding a +@code{sysctl-service-type} service (or updating the existing one's +configuration) with lines like the following: + +@lisp +(service sysctl-service-type + (sysctl-configuration + (settings + ("net.ipv4.tcp_allowed_congestion_control" . + "reno cubic lp")))) +@end lisp + +The Transmission Daemon configuration can then be updated with + +@lisp +(peer-congestion-algorithm "lp") +@end lisp + +and the system reconfigured to have the changes take effect. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} tcp-type-of-service peer-socket-tos +The type of service to request in outgoing @acronym{TCP} packets, one of +@code{default}, @code{low-cost}, @code{throughput}, @code{low-delay} and +@code{reliability}. + +Defaults to @samp{default}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-global +The global limit on the number of connected peers. + +Defaults to @samp{200}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-per-torrent +The per-torrent limit on the number of connected peers. + +Defaults to @samp{50}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer upload-slots-per-torrent +The maximum number of peers to which the daemon will upload data +simultaneously for each torrent. + +Defaults to @samp{14}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-id-ttl-hours +The maximum lifespan, in hours, of the peer ID associated with each +public torrent before it is regenerated. + +Defaults to @samp{6}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean blocklist-enabled? +When @code{#t}, the daemon will ignore peers mentioned in the blocklist +it has most recently downloaded from @code{blocklist-url}. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string blocklist-url +The URL of a peer blocklist (in @acronym{P2P}-plaintext or eMule +@file{.dat} format) to be periodically downloaded and applied when +@code{blocklist-enabled?} is @code{#t}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean download-queue-enabled? +If @code{#t}, the daemon will be limited to downloading at most +@code{download-queue-size} non-stalled torrents simultaneously. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer download-queue-size +The size of the daemon's download queue, which limits the number of +non-stalled torrents it will download at any one time when +@code{download-queue-enabled?} is @code{#t}. + +Defaults to @samp{5}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean seed-queue-enabled? +If @code{#t}, the daemon will be limited to seeding at most +@code{seed-queue-size} non-stalled torrents simultaneously. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer seed-queue-size +The size of the daemon's seed queue, which limits the number of +non-stalled torrents it will seed at any one time when +@code{seed-queue-enabled?} is @code{#t}. + +Defaults to @samp{10}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean queue-stalled-enabled? +When @code{#t}, the daemon will consider torrents for which it has not +shared data in the past @code{queue-stalled-minutes} minutes to be +stalled and not count them against its @code{download-queue-size} and +@code{seed-queue-size} limits. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer queue-stalled-minutes +The maximum period, in minutes, a torrent may be idle before it is +considered to be stalled, when @code{queue-stalled-enabled?} is +@code{#t}. + +Defaults to @samp{30}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean ratio-limit-enabled? +When @code{#t}, a torrent being seeded will automatically be paused once +it reaches the ratio specified by @code{ratio-limit}. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-rational ratio-limit +The ratio at which a torrent being seeded will be paused, when +@code{ratio-limit-enabled?} is @code{#t}. + +Defaults to @samp{2.0}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean idle-seeding-limit-enabled? +When @code{#t}, a torrent being seeded will automatically be paused once +it has been idle for @code{idle-seeding-limit} minutes. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer idle-seeding-limit +The maximum period, in minutes, a torrent being seeded may be idle +before it is paused, when @code{idle-seeding-limit-enabled?} is +@code{#t}. + +Defaults to @samp{30}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean dht-enabled? +Enable @uref{http://bittorrent.org/beps/bep_0005.html,the distributed +hash table (@acronym{DHT}) protocol}, which supports the use of +trackerless torrents. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean lpd-enabled? +Enable @uref{https://en.wikipedia.org/wiki/Local_Peer_Discovery,local +peer discovery} (@acronym{LPD}), which allows the discovery of peers on +the local network and may reduce the amount of data sent over the public +Internet. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean pex-enabled? +Enable @uref{https://en.wikipedia.org/wiki/Peer_exchange,peer exchange} +(@acronym{PEX}), which reduces the daemon's reliance on external +trackers and may improve its performance. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean utp-enabled? +Enable @uref{http://bittorrent.org/beps/bep_0029.html,the micro +transport protocol} (@acronym{uTP}), which aims to reduce the impact of +BitTorrent traffic on other users of the local network while maintaining +full utilization of the available bandwidth. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-enabled? +If @code{#t}, enable the remote procedure call (@acronym{RPC}) +interface, which allows remote control of the daemon via its Web +interface, the @command{transmission-remote} command-line client, and +similar tools. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-bind-address +The IP address at which to listen for @acronym{RPC} connections, or +``0.0.0.0'' to listen at all available IP addresses. + +Defaults to @samp{"0.0.0.0"}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} port-number rpc-port +The port on which to listen for @acronym{RPC} connections. + +Defaults to @samp{9091}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-url +The path prefix to use in the @acronym{RPC}-endpoint @acronym{URL}. + +Defaults to @samp{"/transmission/"}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-authentication-required? +When @code{#t}, clients must authenticate (see @code{rpc-username} and +@code{rpc-password}) when using the @acronym{RPC} interface. Note this +has the side effect of disabling host-name whitelisting (see +@code{rpc-host-whitelist-enabled?}. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string rpc-username +The username required by clients to access the @acronym{RPC} interface +when @code{rpc-authentication-required?} is @code{#t}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-transmission-password-hash rpc-password +The password required by clients to access the @acronym{RPC} interface +when @code{rpc-authentication-required?} is @code{#t}. This must be +specified using a password hash in the format recognized by Transmission +clients, either copied from an existing @file{settings.json} file or +generated using the @code{transmission-password-hash} procedure. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-whitelist-enabled? +When @code{#t}, @acronym{RPC} requests will be accepted only when they +originate from an address specified in @code{rpc-whitelist}. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-whitelist +The list of IP and IPv6 addresses from which @acronym{RPC} requests will +be accepted when @code{rpc-whitelist-enabled?} is @code{#t}. Wildcards +may be specified using @samp{*}. + +Defaults to @samp{("127.0.0.1" "::1")}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-host-whitelist-enabled? +When @code{#t}, @acronym{RPC} requests will be accepted only when they +are addressed to a host named in @code{rpc-host-whitelist}. Note that +requests to ``localhost'' or ``localhost.'', or to a numeric address, +are always accepted regardless of these settings. + +Note also this functionality is disabled when +@code{rpc-authentication-required?} is @code{#t}. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-host-whitelist +The list of host names recognized by the @acronym{RPC} server when +@code{rpc-host-whitelist-enabled?} is @code{#t}. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} message-level message-level +The minimum severity level of messages to be logged (to +@file{/var/log/transmission.log}) by the daemon, one of @code{none} (no +logging), @code{error}, @code{info} and @code{debug}. + +Defaults to @samp{info}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean start-added-torrents? +When @code{#t}, torrents are started as soon as they are added; +otherwise, they are added in ``paused'' state. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean script-torrent-done-enabled? +When @code{#t}, the script specified by +@code{script-torrent-done-filename} will be invoked each time a torrent +completes. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-file-object script-torrent-done-filename +A file name or file-like object specifying a script to run each time a +torrent completes, when @code{script-torrent-done-enabled?} is +@code{#t}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean scrape-paused-torrents-enabled? +When @code{#t}, the daemon will scrape trackers for a torrent even when +the torrent is paused. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer cache-size-mb +The amount of memory, in megabytes, to allocate for the daemon's +in-memory cache. A larger value may increase performance by reducing +the frequency of disk I/O. + +Defaults to @samp{4}. + +@end deftypevr + +@deftypevr {@code{transmission-daemon-configuration} parameter} boolean prefetch-enabled? +When @code{#t}, the daemon will try to improve I/O performance by +hinting to the operating system which data is likely to be read next +from disk to satisfy requests from peers. + +Defaults to @samp{#t}. + +@end deftypevr + + +@c %end of fragment + + + @node Monitoring Services @subsection Monitoring Services @@ -24527,6 +25393,93 @@ gmnisrv} and @command{man gmnisrv.ini}. @end table @end deftp +@subsubheading Agate + +@cindex agate +The @uref{gemini://qwertqwefsday.eu/agate.gmi, Agate} +(@uref{https://github.com/mbrubeck/agate, GitHub page over HTTPS}) +program is a simple @uref{https://gemini.circumlunar.space/, Gemini} +protocol server written in Rust. + +@deffn {Scheme Variable} agate-service-type +This is the type of the agate service, whose value should be an +@code{agate-service-type} object, as in this example: + +@lisp +(service agate-service-type + (agate-configuration + (content "/srv/gemini") + (cert "/srv/cert.pem") + (key "/srv/key.rsa"))) +@end lisp + +The example above represents the minimal tweaking necessary to get Agate +up and running. Specifying the path to the certificate and key is +always necessary, as the Gemini protocol requires TLS by default. + +To obtain a certificate and a key, you could, for example, use OpenSSL, +running a command similar to the following example: + +@example +openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \ + -days 3650 -nodes -subj "/CN=example.com" +@end example + +Of course, you'll have to replace @i{example.com} with your own domain +name, and then point the Agate configuration towards the path of the +generated key and certificate. + +@end deffn + +@deftp {Data Type} agate-configuration +Data type representing the configuration of Agate. + +@table @asis +@item @code{package} (default: @code{agate}) +The package object of the Agate server. + +@item @code{content} (default: @file{"/srv/gemini"}) +The directory from which Agate will serve files. + +@item @code{cert} (default: @code{#f}) +The path to the TLS certificate PEM file to be used for encrypted +connections. Must be filled in with a value from the user. + +@item @code{key} (default: @code{#f}) +The path to the PKCS8 private key file to be used for encrypted +connections. Must be filled in with a value from the user. + +@item @code{addr} (default: @code{'("0.0.0.0:1965" "[::]:1965")}) +A list of the addresses to listen on. + +@item @code{hostname} (default: @code{#f}) +The domain name of this Gemini server. Optional. + +@item @code{lang} (default: @code{#f}) +RFC 4646 language code(s) for text/gemini documents. Optional. + +@item @code{silent?} (default: @code{#f}) +Set to @code{#t} to disable logging output. + +@item @code{serve-secret?} (default: @code{#f}) +Set to @code{#t} to serve secret files (files/directories starting with +a dot). + +@item @code{log-ip?} (default: @code{#t}) +Whether or not to output IP addresses when logging. + +@item @code{user} (default: @code{"agate"}) +Owner of the @code{agate} process. + +@item @code{group} (default: @code{"agate"}) +Owner's group of the @code{agate} process. + +@item @code{log-file} (default: @file{"/var/log/agate.log"}) +The file which should store the logging output of Agate. + +@end table +@end deftp + @node Certificate Services @subsection Certificate Services @@ -25454,9 +26407,12 @@ Defaults to @samp{()}. @cindex virtual private network (VPN) The @code{(gnu services vpn)} module provides services related to -@dfn{virtual private networks} (VPNs). It provides a @emph{client} service for -your machine to connect to a VPN, and a @emph{server} service for your machine -to host a VPN@. Both services use @uref{https://openvpn.net/, OpenVPN}. +@dfn{virtual private networks} (VPNs). + +@subsubheading OpenVPN + +It provides a @emph{client} service for your machine to connect to a +VPN, and a @emph{server} service for your machine to host a VPN@. @deffn {Scheme Procedure} openvpn-client-service @ [#:config (openvpn-client-configuration)] @@ -25835,6 +26791,70 @@ Defaults to @samp{#f}. @c %end of automatic openvpn-server documentation +@subsubheading Wireguard + +@defvr {Scheme Variable} wireguard-service-type +A service type for a Wireguard tunnel interface. Its value must be a +@code{wireguard-configuration} record as in this example: + +@lisp +(service wireguard-service-type + (wireguard-configuration + (peers + (list + (wireguard-peer + (name "my-peer") + (endpoint "my.wireguard.com:51820") + (public-key "hzpKg9X1yqu1axN6iJp0mWf6BZGo8m1wteKwtTmDGF4=") + (allowed-ips '("10.0.0.2/32"))))))) +@end lisp + +@end defvr + +@deftp {Data Type} wireguard-configuration +Data type representing the configuration of the Wireguard service. + +@table @asis +@item @code{wireguard} +The wireguard package to use for this service. + +@item @code{interface} (default: @code{"wg0"}) +The interface name for the VPN. + +@item @code{addresses} (default: @code{'("10.0.0.1/32")}) +The IP addresses to be assigned to the above interface. + +@item @code{private-key} (default: @code{"/etc/wireguard/private.key"}) +The private key file for the interface. It is automatically generated if +the file does not exist. + +@item @code{peers} (default: @code{'()}) +The authorized peers on this interface. This is a list of +@var{wireguard-peer} records. + +@end table +@end deftp + +@deftp {Data Type} wireguard-peer +Data type representing a Wireguard peer attached to a given interface. + +@table @asis +@item @code{name} +The peer name. + +@item @code{endpoint} (default: @code{#f}) +The optional endpoint for the peer, such as +@code{"demo.wireguard.com:51820"}. + +@item @code{public-key} +The peer public-key represented as a base64 string. + +@item @code{allowed-ips} +A list of IP addresses from which incoming traffic for this peer is +allowed and to which incoming traffic for this peer is directed. + +@end table +@end deftp @node Network File System @subsection Network File System @@ -26166,6 +27186,118 @@ The Cuirass package to use. @end table @end deftp +@cindex simple cuirass +@subsubheading Simple Cuirass + +The Cuirass service configuration described above can be a little +intimidating. In particular, getting the right @code{specifications} +can prove difficult. The @code{simple-cuirass-configuration->specs} +procedure offers a way to generate those @code{specifications} and thus +setup a continuous integration server more readily. + +@deffn {Scheme Procedure} simple-cuirass-configuration->specs @var{configuration} +This procedure takes a @code{simple-cuirass-configuration} record as +argument and returns the corresponding Cuirass specifications gexp. +@end deffn + +@deftp {Data Type} simple-cuirass-configuration +Data type representing the configuration of a simple Cuirass instance. + +@table @asis +@item @code{build} (default: @code{all}) +The packages to be built by Cuirass. It defaults to @code{all}, which +means that all the discovered packages in the subsequent @code{channels} +field are to be selected. + +It is also possible to set this field to a list of @code{build-manifest} +records, so that only the packages that are part of the declared +manifests are built. This record is described below. + +@deftp {Data Type} build-manifest +@table @asis +@item @code{channel-name} +The name of the channel where the manifest is located. + +@item @code{manifest} +The manifest path inside the channel. + +@end table +@end deftp + +@item @code{channels} (default: @code{%default-channels}) +The channels to be fetched by Cuirass (@pxref{Channels}). + +@item @code{non-package-channels} (default: @code{'()}) +List the channel names that must not be searched for packages. That is +often the case for the channel containing the manifest. + +@item @code{systems} (default: @code{(list (%current-system))}) +Build every discovered package for each system in this list. By default +only the current system is selected. + +@end table +@end deftp + +Here is an example of how to setup a Cuirass instance that builds all +the packages declared by Guix and a user repository. The package list +is re-evaluated each time a commit is pushed in one of the declared +channels. + +@lisp +(service cuirass-service-type + (cuirass-configuration + (specifications + (simple-cuirass-configuration->specs + (simple-cuirass-configuration + (build 'all) + (channels (cons (channel + (name 'my-guix) + (url "https://my-git-repo/guix.git")) + %default-channels))))))) +@end lisp + +In the same spirit, this builds all the packages that are part of the +@code{guix} or @code{my-guix} channels and declared in the manifest +located in the @code{conf} channel. + +@lisp +(service cuirass-service-type + (cuirass-configuration + (specifications + (simple-cuirass-configuration->specs + (simple-cuirass-configuration + (build (list + (build-manifest + (channel-name 'conf) + (manifest "guix/manifest.scm")))) + (channels (cons* (channel + (name 'my-guix) + (url "https://my-git-repo/guix.git")) + (channel + (name 'conf) + (url "https://my-git-repo/conf.git")) + %default-channels)) + (non-package-channels '(conf))))))) +@end lisp + +Finally, @code{simple-cuirass-services} takes as a second optional +argument a @code{cuirass-configuration} record. It can be used to +customize the configuration of the Cuirass instance. + +@lisp +(simple-cuirass-services + (simple-cuirass-configuration + (build 'all) + (channels (cons (channel + (name 'my-guix) + (url "https://my-git-repo/guix.git")) + %default-channels)) + (non-package-channels '(conf))) + (cuirass-configuration + (inherit %default-cuirass-config) + (host "0.0.0.0"))) ;listen on all interfaces. +@end lisp + @node Power Management Services @subsection Power Management Services @@ -29840,18 +30972,9 @@ The system user to run the service as. @item @code{coordinator} (default: @code{"http://localhost:8745"}) The URI to use when connecting to the coordinator. -@item @code{uuid} -The UUID of the agent. This should be generated by the coordinator -process, stored in the coordinator database, and used by the intended -agent. - -@item @code{password} (default: @code{#f}) -The password to use when connecting to the coordinator. A file to read -the password from can also be specified, and this is more secure. - -@item @code{password-file} (default: @code{#f}) -A file containing the password to use when connecting to the -coordinator. +@item @code{authentication} +Record describing how this agent should authenticate with the +coordinator. Possible record types are described below. @item @code{systems} (default: @code{#f}) The systems for which this agent should fetch builds. The agent process @@ -29871,6 +30994,73 @@ input store items aren't already available. @end table @end deftp +@deftp {Data Type} guix-build-coordinator-agent-password-auth +Data type representing an agent authenticating with a coordinator via a +UUID and password. + +@table @asis +@item @code{uuid} +The UUID of the agent. This should be generated by the coordinator +process, stored in the coordinator database, and used by the intended +agent. + +@item @code{password} +The password to use when connecting to the coordinator. + +@end table +@end deftp + +@deftp {Data Type} guix-build-coordinator-agent-password-file-auth +Data type representing an agent authenticating with a coordinator via a +UUID and password read from a file. + +@table @asis +@item @code{uuid} +The UUID of the agent. This should be generated by the coordinator +process, stored in the coordinator database, and used by the intended +agent. + +@item @code{password-file} +A file containing the password to use when connecting to the +coordinator. + +@end table +@end deftp + +@deftp {Data Type} guix-build-coordinator-agent-dynamic-auth +Data type representing an agent authenticating with a coordinator via a +dyanmic auth token and agent name. + +@table @asis +@item @code{agent-name} +Name of an agent, this is used to match up to an existing entry in the +database if there is one. When no existing entry is found, a new entry +is automatically added. + +@item @code{token} +Dynamic auth token, this is created and stored in the coordinator +database, and is used by the agent to authenticate. + +@end table +@end deftp + +@deftp {Data Type} guix-build-coordinator-agent-dynamic-auth-with-file +Data type representing an agent authenticating with a coordinator via a +dyanmic auth token read from a file and agent name. + +@table @asis +@item @code{agent-name} +Name of an agent, this is used to match up to an existing entry in the +database if there is one. When no existing entry is found, a new entry +is automatically added. + +@item @code{token-file} +File containing the dynamic auth token, this is created and stored in +the coordinator database, and is used by the agent to authenticate. + +@end table +@end deftp + The Guix Build Coordinator package contains a script to query an instance of the Guix Data Service for derivations to build, and then submit builds for those derivations to the coordinator. The service @@ -31626,8 +32816,7 @@ size of the image. @cindex System images, creation in various formats @cindex Creating system images in various formats -@item vm-image -@itemx image +@item image @itemx docker-image Return a virtual machine, disk image, or Docker image of the operating system declared in @var{file} that stands alone. By default, @@ -31671,15 +32860,15 @@ the image to it using the following command: The @code{--list-image-types} command lists all the available image types. -@cindex vm-image, creating virtual machine images -When using @code{vm-image}, the returned image is in qcow2 format, which -the QEMU emulator can efficiently use. @xref{Running Guix in a VM}, for -more information on how to run the image in a virtual machine. The -@code{grub-bootloader} bootloader is always used independently of what -is declared in the @code{operating-system} file passed as argument. -This is to make it easier to work with QEMU, which uses the SeaBIOS BIOS -by default, expecting a bootloader to be installed in the Master Boot -Record (MBR). +@cindex creating virtual machine images +When using the @code{qcow2} image type, the returned image is in qcow2 +format, which the QEMU emulator can efficiently use. @xref{Running Guix +in a VM}, for more information on how to run the image in a virtual +machine. The @code{grub-bootloader} bootloader is always used +independently of what is declared in the @code{operating-system} file +passed as argument. This is to make it easier to work with QEMU, which +uses the SeaBIOS BIOS by default, expecting a bootloader to be installed +in the Master Boot Record (MBR). @cindex docker-image, creating docker images When using @code{docker-image}, a Docker image is produced. Guix builds @@ -31774,7 +32963,7 @@ create a virtual machine image that contains provenance information, you can run: @example -guix system vm-image --save-provenance config.scm +guix system image -t qcow2 --save-provenance config.scm @end example That way, the resulting image will effectively ``embed its own source'' @@ -31797,10 +32986,10 @@ When this option is omitted, @command{guix system} uses the for burning on CDs and DVDs. @item --image-size=@var{size} -For the @code{vm-image} and @code{image} actions, create an image -of the given @var{size}. @var{size} may be a number of bytes, or it may -include a unit as a suffix (@pxref{Block size, size specifications,, -coreutils, GNU Coreutils}). +For the @code{image} action, create an image of the given @var{size}. +@var{size} may be a number of bytes, or it may include a unit as a +suffix (@pxref{Block size, size specifications,, coreutils, GNU +Coreutils}). When this option is omitted, @command{guix system} computes an estimate of the image size as a function of the size of the system declared in @@ -32163,7 +33352,7 @@ If you built your own image, you must copy it out of the store before you can use it. When invoking QEMU, you must choose a system emulator that is suitable for your hardware platform. Here is a minimal QEMU invocation that will boot the result of @command{guix system -vm-image} on x86_64 hardware: +image -t qcow2} on x86_64 hardware: @example $ qemu-system-x86_64 \ @@ -33364,7 +34553,7 @@ which has minimalist replacements for Awk, the GNU Core Utilities, Grep, Gzip, Sed, and Tar. The rest of the bootstrap binary seeds that were removed are now built from source. -Building the GNU System from source is currently only possibly by adding +Building the GNU System from source is currently only possible by adding some historical GNU packages as intermediate steps@footnote{Packages such as @code{gcc-2.95.3}, @code{binutils-2.14}, @code{glibc-2.2.5}, @code{gzip-1.2.4}, @code{tar-1.22}, and some others. For details, see |