summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorEfraim Flashner <efraim@flashner.co.il>2017-03-13 23:08:49 +0200
committerEfraim Flashner <efraim@flashner.co.il>2017-03-13 23:08:49 +0200
commit3f9543aee1e49001d0f80542dd71ba73c44787c7 (patch)
tree50ee1bdd53b1e5ec69cb8655f23da79c332dde1e /doc
parent864a9590ad948df09f2ad6e9e929608a7587a5f7 (diff)
parenta71c863834448e2645518b31b60a96ef488dd761 (diff)
Merge remote-tracking branch 'origin/master' into core-updates
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi207
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