diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 207 |
1 files changed, 171 insertions, 36 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index a537433bf6..aba207c856 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -32,7 +32,8 @@ Copyright @copyright{} 2016 Julien Lepiller@* Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2017 Clément Lassieur@* Copyright @copyright{} 2017 Mathieu Othacehe@* -Copyright @copyright{} 2017 Federico Beffa +Copyright @copyright{} 2017 Federico Beffa@* +Copyright @copyright{} 2017 Carlo Zancanaro Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -118,6 +119,7 @@ Package Management * Packages with Multiple Outputs:: Single source package, multiple outputs. * Invoking guix gc:: Running the garbage collector. * Invoking guix pull:: Fetching the latest Guix and distribution. +* Invoking guix pack:: Creating software bundles. * Invoking guix archive:: Exporting and importing store files. Programming Interface @@ -529,6 +531,14 @@ by running the following command in the Guix source tree: make guix-binary.@var{system}.tar.xz @end example +@noindent +... which, in turn, runs: + +@example +guix pack -s @var{system} guix +@end example + +@xref{Invoking guix pack}, for more info on this handy tool. @node Requirements @section Requirements @@ -543,6 +553,10 @@ GNU Guix depends on the following packages: @itemize @item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.7 or later; @item @url{http://gnupg.org/, GNU libgcrypt}; +@item +@uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings +(@pxref{Guile Preparations, how to install the GnuTLS bindings for +Guile,, gnutls-guile, GnuTLS-Guile}); @item @url{http://www.gnu.org/software/make/, GNU Make}. @end itemize @@ -550,15 +564,6 @@ The following dependencies are optional: @itemize @item -Installing @uref{http://gnutls.org/, GnuTLS-Guile} will allow you to -access @code{https} URLs for substitutes, which is highly recommended -(@pxref{Substitutes}). It also allows you to access HTTPS URLs with the -@command{guix download} command (@pxref{Invoking guix download}), the -@command{guix import pypi} command, and the @command{guix import cpan} -command. @xref{Guile Preparations, how to install the GnuTLS bindings -for Guile,, gnutls-guile, GnuTLS-Guile}. - -@item Installing @url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will allow you to use the @command{guix import pypi} command (@pxref{Invoking @@ -1426,6 +1431,7 @@ guix package -i emacs-guix * Packages with Multiple Outputs:: Single source package, multiple outputs. * Invoking guix gc:: Running the garbage collector. * Invoking guix pull:: Fetching the latest Guix and distribution. +* Invoking guix pack:: Creating software bundles. * Invoking guix archive:: Exporting and importing store files. @end menu @@ -2002,8 +2008,7 @@ or to client tools such as @command{guix package} (@pxref{client-substitute-urls,, client @option{--substitute-urls} option}). -Substitute URLs can be either HTTP or HTTPS@footnote{For HTTPS access, -the Guile bindings of GnuTLS must be installed. @xref{Requirements}.} +Substitute URLs can be either HTTP or HTTPS. HTTPS is recommended because communications are encrypted; conversely, using HTTP makes all communications visible to an eavesdropper, who could use the information gathered to determine, for instance, whether @@ -2382,6 +2387,60 @@ useful to Guix developers. @end table +@node Invoking guix pack +@section Invoking @command{guix pack} + +Occasionally you want to pass software to people who are not (yet!) +lucky enough to be using Guix. You'd tell them to run @command{guix +package -i @var{something}}, but that's not possible in this case. This +is where @command{guix pack} comes in. + +@cindex pack +@cindex bundle +@cindex application bundle +@cindex software bundle +The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or +@dfn{software bundle}: it creates a tarball or some other archive +containing the binaries of the software you're interested in, and all +its dependencies. The resulting archive can be used on any machine that +does not have Guix, and people can run the exact same binaries as those +you have with Guix. + +For example, to create a bundle containing Guile, Emacs, Geiser, and all +their dependencies, you can run: + +@example +$ guix pack guile emacs geiser +@dots{} +/gnu/store/@dots{}-pack.tar.gz +@end example + +The result here is a tarball containing a @file{/gnu/store} directory +with all the relevant packages. The resulting tarball contains a +@dfn{profile} with the three packages of interest; the profile is the +same as would be created by @command{guix package -i}. It is this +mechanism that is used to create Guix's own standalone binary tarball +(@pxref{Binary Installation}). + +Several command-line options allow you to customize your pack: + +@table @code +@item --system=@var{system} +@itemx -s @var{system} +Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of +the system type of the build host. + +@item --compression=@var{tool} +@itemx -C @var{tool} +Compress the resulting tarball using @var{tool}---one of @code{gzip}, +@code{bzip2}, @code{xz}, or @code{lzip}. +@end table + +In addition, @command{guix pack} supports all the common build options +(@pxref{Common Build Options}) and all the package transformation +options (@pxref{Package Transformation Options}). + + @node Invoking guix archive @section Invoking @command{guix archive} @@ -6812,7 +6871,7 @@ Few system services are currently supported out-of-the-box (@pxref{Services}). @item -More than 4,000 packages are available, but you may +More than 5,000 packages are available, but you may occasionally find that a useful package is missing. @item @@ -9336,18 +9395,30 @@ false, users have to use other authentication method. Authorized public keys are stored in @file{~/.ssh/authorized_keys}. This is used only by protocol version 2. -@item @code{rsa-authentication?} (default: @code{#t}) -When true, users may log in using pure RSA authentication. When false, -users have to use other means of authentication. This is used only by -protocol 1. - @item @code{x11-forwarding?} (default: @code{#f}) When true, forwarding of X11 graphical client connections is enabled---in other words, @command{ssh} options @option{-X} and @option{-Y} will work. -@item @code{protocol-number} (default: @code{2}) -The SSH protocol number to use. +@item @code{challenge-response-authentication?} (default: @code{#f}) +Specifies whether challenge response authentication is allowed (e.g. via +PAM). + +@item @code{use-pam?} (default: @code{#t}) +Enables the Pluggable Authentication Module interface. If set to +@code{#t}, this will enable PAM authentication using +@code{challenge-response-authentication?} and +@code{password-authentication?}, in addition to PAM account and session +module processing for all authentication types. + +Because PAM challenge response authentication usually serves an +equivalent role to password authentication, you should disable either +@code{challenge-response-authentication?} or +@code{password-authentication?}. + +@item @code{print-last-log?} (default: @code{#t}) +Specifies whether @command{sshd} should print the date and time of the +last user login when a user logs in interactively. @end table @end deftp @@ -10928,8 +10999,9 @@ Defaults to @samp{()}. Available @code{unix-listener-configuration} fields are: -@deftypevr {@code{unix-listener-configuration} parameter} file-name path -The file name on which to listen. +@deftypevr {@code{unix-listener-configuration} parameter} string path +Path to the file, relative to @code{base-dir} field. This is also used as +the section name. @end deftypevr @deftypevr {@code{unix-listener-configuration} parameter} string mode @@ -10950,8 +11022,9 @@ Defaults to @samp{""}. Available @code{fifo-listener-configuration} fields are: -@deftypevr {@code{fifo-listener-configuration} parameter} file-name path -The file name on which to listen. +@deftypevr {@code{fifo-listener-configuration} parameter} string path +Path to the file, relative to @code{base-dir} field. This is also used as +the section name. @end deftypevr @deftypevr {@code{fifo-listener-configuration} parameter} string mode @@ -12211,6 +12284,45 @@ remote servers. Run @command{man smtpd.conf} for more information. @end table @end deftp +@subsubheading Exim Service + +@deffn {Scheme Variable} exim-service-type +This is the type of the @uref{https://exim.org, Exim} service, whose value +should be an @code{exim-configuration} object as in this example: + +@example +(service exim-service-type + (exim-configuration + (config-file (local-file "./my-exim.conf")) + (aliases '(("postmaster" "bob") + ("bob" "bob@@example.com" "bob@@example2.com"))))) +@end example +@end deffn + +@deftp {Data Type} exim-configuration +Data type representing the configuration of exim. + +@table @asis +@item @code{package} (default: @var{exim}) +Package object of the Exim server. + +@item @code{config-file} (default: @code{#f}) +File-like object of the Exim configuration file to use. If its value is +@code{#f} then use the default configuration file from the package +provided in @code{package}. The resulting configuration file is loaded +after setting the @code{exim_user} and @code{exim_group} configuration +variables. + +@item @code{aliases} (default: @code{'()}) +List of aliases to use when delivering mail on this system. The +@code{car} of each list is used to match incoming mail, with the +@code{cdr} of each list designating how to deliver it. There may be many +delivery methods provided, in which case the mail is delivered to them +all. + +@end table +@end deftp + @node Messaging Services @subsubsection Messaging Services @@ -13840,9 +13952,9 @@ kernel modules that may be needed to achieve that. The @code{initrd} field of an @code{operating-system} declaration allows you to specify which initrd you would like to use. The @code{(gnu -system linux-initrd)} module provides two ways to build an initrd: the -high-level @code{base-initrd} procedure, and the low-level -@code{expression->initrd} procedure. +system linux-initrd)} module provides three ways to build an initrd: the +high-level @code{base-initrd} procedure and the low-level +@code{raw-initrd} and @code{expression->initrd} procedures. The @code{base-initrd} procedure is intended to cover most common uses. For example, if you want to add a bunch of kernel modules to be loaded @@ -13863,9 +13975,16 @@ The @code{base-initrd} procedure also handles common use cases that involves using the system as a QEMU guest, or as a ``live'' system with volatile root file system. -The initial RAM disk produced by @code{base-initrd} honors several -options passed on the Linux kernel command line (that is, arguments -passed @i{via} the @code{linux} command of GRUB, or the +The @code{base-initrd} procedure is built from @code{raw-initrd} procedure. +Unlike @code{base-initrd}, @code{raw-initrd} doesn't do anything high-level, +such as trying to guess which kernel modules and packages should be included +to the initrd. An example use of @code{raw-initrd} is when a user has +a custom Linux kernel configuration and default kernel modules included by +@code{base-initrd} are not available. + +The initial RAM disk produced by @code{base-initrd} or @code{raw-initrd} +honors several options passed on the Linux kernel command line +(that is, arguments passed @i{via} the @code{linux} command of GRUB, or the @code{-append} option of QEMU), notably: @table @code @@ -13904,19 +14023,23 @@ Manual}, for more information on Guile's REPL. @end table Now that you know all the features that initial RAM disks produced by -@code{base-initrd} provide, here is how to use it and customize it -further. +@code{base-initrd} and @code{raw-initrd} provide, +here is how to use it and customize it further. @cindex initrd @cindex initial RAM disk -@deffn {Monadic Procedure} base-initrd @var{file-systems} @ - [#:qemu-networking? #f] [#:virtio? #t] [#:volatile-root? #f] @ - [#:extra-modules '()] [#:mapped-devices '()] -Return a monadic derivation that builds a generic initrd. @var{file-systems} is +@deffn {Monadic Procedure} raw-initrd @var{file-systems} @ + [#:linux-modules '()] [#:mapped-devices '()] @ + [#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f] +Return a monadic derivation that builds a raw initrd. @var{file-systems} is a list of file systems to be mounted by the initrd, possibly in addition to the root file system specified on the kernel command line via @code{--root}. +@var{linux-modules} is a list of kernel modules to be loaded at boot time. @var{mapped-devices} is a list of device mappings to realize before @var{file-systems} are mounted (@pxref{Mapped Devices}). +@var{helper-packages} is a list of packages to be copied in the initrd. It may +include @code{e2fsck/static} or other packages needed by the initrd to check +root partition. When @var{qemu-networking?} is true, set up networking with the standard QEMU parameters. When @var{virtio?} is true, load additional modules so that the @@ -13924,6 +14047,18 @@ initrd can be used as a QEMU guest with para-virtualized I/O drivers. When @var{volatile-root?} is true, the root file system is writable but any changes to it are lost. +@end deffn + +@deffn {Monadic Procedure} base-initrd @var{file-systems} @ + [#:mapped-devices '()] [#:qemu-networking? #f] [#:volatile-root? #f]@ + [#:virtio? #t] [#:extra-modules '()] +Return a monadic derivation that builds a generic initrd. @var{file-systems} is +a list of file systems to be mounted by the initrd like for @code{raw-initrd}. +@var{mapped-devices}, @var{qemu-networking?} and @var{volatile-root?} +also behaves as in @code{raw-initrd}. + +When @var{virtio?} is true, load additional modules so that the +initrd can be used as a QEMU guest with para-virtualized I/O drivers. The initrd is automatically populated with all the kernel modules necessary for @var{file-systems} and for the given options. However, additional kernel |