Copyright @copyright{} 2019 Jakob L. Kreuze@*
Copyright @copyright{} 2019 Kyle Andrews@*
Copyright @copyright{} 2019 Alex Griffin@*
+Copyright @copyright{} 2019 Guillaume Le Vaillant@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
* Channels:: Customizing the package collection.
+* Invoking guix time-machine:: Running an older revision of Guix.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
* Invoking guix archive:: Exporting and importing store files.
* Virtualization Services:: Virtualization services.
* Version Control Services:: Providing remote access to Git repositories.
* Game Services:: Game servers.
+* PAM Mount Service:: Service to mount volumes when logging in.
* Miscellaneous Services:: Other services.
Defining Services
This means that substitutes may be downloaded from @var{urls}, as long
as they are signed by a trusted signature (@pxref{Substitutes}).
-@cindex build hook
-@item --no-build-hook
-Do not use the @dfn{build hook}.
-
-The build hook is a helper program that the daemon can start and to
-which it submits build requests. This mechanism is used to offload
-builds to other machines (@pxref{Daemon Offload Setup}).
+@cindex offloading
+@item --no-offload
+Do not use offload builds to other machines (@pxref{Daemon Offload
+Setup}). That is, always build things locally instead of offloading
+builds to remote machines.
@item --cache-failures
Cache build failures. By default, only successful builds are cached.
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
* Channels:: Customizing the package collection.
+* Invoking guix time-machine:: Running an older revision of Guix.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
* Invoking guix archive:: Exporting and importing store files.
@cindex profile declaration
@cindex profile manifest
Create a new generation of the profile from the manifest object
-returned by the Scheme code in @var{file}.
+returned by the Scheme code in @var{file}. This option can be repeated
+several times, in which case the manifests are concatenated.
This allows you to @emph{declare} the profile's contents rather than
constructing it through a sequence of @code{--install} and similar
@end lisp
The @command{guix describe --format=channels} command can even generate this
-list of channels directly (@pxref{Invoking guix describe}).
+list of channels directly (@pxref{Invoking guix describe}). The resulting
+file can be used with the -C options of @command{guix pull}
+(@pxref{Invoking guix pull}) or @command{guix time-machine}
+(@pxref{Invoking guix time-machine}).
At this point the two machines run the @emph{exact same Guix}, with access to
the @emph{exact same packages}. The output of @command{guix build gimp} on
will---some sort of ``meta reproducibility'' capabilities, if you will.
@xref{Inferiors}, for another way to take advantage of these super powers.
+@node Invoking guix time-machine
+@section Invoking @command{guix time-machine}
+
+@cindex @command{guix time-machine}
+@cindex pinning, channels
+@cindex replicating Guix
+@cindex reproducibility, of Guix
+
+The @command{guix time-machine} command provides access to other
+revisions of Guix, for example to install older versions of packages,
+or to reproduce a computation in an identical environment. The revision
+of Guix to be used is defined by a commit or by a channel
+description file created by @command{guix describe}
+(@pxref{Invoking guix describe}).
+
+The general syntax is:
+
+@example
+guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
+@end example
+
+where @var{command} and @var{arg}@dots{} are passed unmodified to the
+@command{guix} command if the specified revision. The @var{options} that define
+this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
+
+@table @code
+@item --url=@var{url}
+@itemx --commit=@var{commit}
+@itemx --branch=@var{branch}
+Use the @code{guix} channel from the specified @var{url}, at the
+given @var{commit} (a valid Git commit ID represented as a hexadecimal
+string), or @var{branch}.
+
+@item --channels=@var{file}
+@itemx -C @var{file}
+Read the list of channels from @var{file}. @var{file} must contain
+Scheme code that evaluates to a list of channel objects.
+@xref{Channels} for more information.
+@end table
+
+As for @command{guix pull}, the absence of any options means that the
+the latest commit on the master branch will be used. The command
+
+@example
+guix time-machine -- build hello
+@end example
+
+will thus build the package @code{hello} as defined in the master branch,
+which is in general a newer revison of Guix than you have installed.
+Time travel works in both directions!
+
+Note that @command{guix time-machine} can trigger builds of channels and
+their dependencies, and these are controlled by the standard build
+options (@pxref{Common Build Options}).
+
@node Inferiors
@section Inferiors
@item --manifest=@var{file}
@itemx -m @var{file}
Create an environment for the packages contained in the manifest object
-returned by the Scheme code in @var{file}.
+returned by the Scheme code in @var{file}. This option can be repeated
+several times, in which case the manifests are concatenated.
This is similar to the same-named option in @command{guix package}
(@pxref{profile-manifest, @option{--manifest}}) and uses the same
@item --manifest=@var{file}
@itemx -m @var{file}
Use the packages contained in the manifest object returned by the Scheme
-code in @var{file}.
+code in @var{file}. This option can be repeated several times, in which
+case the manifests are concatenated.
This has a similar purpose as the same-named option in @command{guix
package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
One use case for this is the Guix self-contained binary tarball
(@pxref{Binary Installation}).
+@item --derivation
+@itemx -d
+Print the name of the derivation that builds the pack.
+
@item --bootstrap
Use the bootstrap binaries to build the pack. This option is only
useful to Guix developers.
@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
[#:recursive? #f] [#:select? (const #t)]
-Return an object representing local file @var{file} to add to the store; this
-object can be used in a gexp. If @var{file} is a relative file name, it is looked
-up relative to the source file where this form appears. @var{file} will be added to
-the store under @var{name}--by default the base name of @var{file}.
+Return an object representing local file @var{file} to add to the store;
+this object can be used in a gexp. If @var{file} is a literal string
+denoting a relative file name, it is looked up relative to the source
+file where it appears; if @var{file} is not a literal string, it is
+looked up relative to the current working directory at run time.
+@var{file} will be added to the store under @var{name}--by default the
+base name of @var{file}.
When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
designates a flat file and @var{recursive?} is true, its contents are added, and its
@xref{Debugging Build Failures}, for tips and tricks on how to debug
build issues.
-This option has no effect when connecting to a remote daemon with a
-@code{guix://} URI (@pxref{The Store, the @code{GUIX_DAEMON_SOCKET}
-variable}).
+This option implies @option{--no-offload}, and it has no effect when
+connecting to a remote daemon with a @code{guix://} URI (@pxref{The
+Store, the @code{GUIX_DAEMON_SOCKET} variable}).
@item --keep-going
@itemx -k
(@pxref{Invoking guix archive}), then rebuilding, and finally comparing
the two results.
-@item --no-build-hook
-Do not attempt to offload builds @i{via} the ``build hook'' of the daemon
-(@pxref{Daemon Offload Setup}). That is, always build things locally
-instead of offloading builds to remote machines.
+@item --no-offload
+Do not use offload builds to other machines (@pxref{Daemon Offload
+Setup}). That is, always build things locally instead of offloading
+builds to remote machines.
@item --max-silent-time=@var{seconds}
When the build or substitution process remains silent for more than
ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
@end example
-
@node System Configuration
@chapter System Configuration
* Virtualization Services:: Virtualization services.
* Version Control Services:: Providing remote access to Git repositories.
* Game Services:: Game servers.
+* PAM Mount Service:: Service to mount volumes when logging in.
* Guix Services:: Services relating specifically to Guix.
* Miscellaneous Services:: Other services.
@end menu
the capability to suspend the system if the user is logged in locally.
@end deffn
+@defvr {Scheme Variable} polkit-wheel-service
+Service that adds the @code{wheel} group as admins to the Polkit
+service. This makes it so that users in the @code{wheel} group are queried
+for their own passwords when performing administrative actions instead of
+@code{root}'s, similar to the behaviour used by @code{sudo}.
+@end defvr
+
@defvr {Scheme Variable} upower-service-type
Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a
system-wide monitor for power consumption and battery levels, with the given
It is possible to configure a FastCGI-backed web service to pass HTTP
authentication information from the front-end to the back-end, and to
allow @code{fcgiwrap} to run the back-end process as a corresponding
-local user. To enable this capability on the back-end., run
+local user. To enable this capability on the back-end, run
@code{fcgiwrap} as the @code{root} user and group. Note that this
capability also has to be configured on the front-end as well.
@end table
Group of the worker processes.
@item @code{socket-user} (default: @code{php-fpm})
User who can speak to the php-fpm socket.
-@item @code{socket-group} (default: @code{php-fpm})
+@item @code{socket-group} (default: @code{nginx})
Group that can speak to the php-fpm socket.
@item @code{pid-file} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")})
The process id of the php-fpm process is written to this file
Log for the php-fpm master process.
@item @code{process-manager} (default: @code{(php-fpm-dynamic-process-manager-configuration)})
Detailed settings for the php-fpm process manager.
-Must be either:
+Must be one of:
@table @asis
@item @code{<php-fpm-dynamic-process-manager-configuration>}
@item @code{<php-fpm-static-process-manager-configuration>}
(server-name '("example.com"))
(root "/srv/http/")
(locations
- (list (nginx-php-location)))
+ (list (nginx-php-fpm-location)))
(listen '("80"))
(ssl-certificate #f)
(ssl-certificate-key #f)))
@end deftp
+@node PAM Mount Service
+@subsection PAM Mount Service
+@cindex pam-mount
+
+The @code{(gnu services pam-mount)} module provides a service allowing
+users to mount volumes when they log in. It should be able to mount any
+volume format supported by the system.
+
+@defvar {Scheme Variable} pam-mount-service-type
+Service type for PAM Mount support.
+@end defvar
+
+@deftp {Data Type} pam-mount-configuration
+Data type representing the configuration of PAM Mount.
+
+It takes the following parameters:
+
+@table @asis
+@item @code{rules}
+The configuration rules that will be used to generate
+@file{/etc/security/pam_mount.conf.xml}.
+
+The configuration rules are SXML elements (@pxref{SXML,,, guile, GNU
+Guile Reference Manual}), and the the default ones don't mount anything
+for anyone at login:
+
+@lisp
+`((debug (@@ (enable "0")))
+ (mntoptions (@@ (allow ,(string-join
+ '("nosuid" "nodev" "loop"
+ "encryption" "fsck" "nonempty"
+ "allow_root" "allow_other")
+ ","))))
+ (mntoptions (@@ (require "nosuid,nodev")))
+ (logout (@@ (wait "0")
+ (hup "0")
+ (term "no")
+ (kill "no")))
+ (mkmountpoint (@@ (enable "1")
+ (remove "true"))))
+@end lisp
+
+Some @code{volume} elements must be added to automatically mount volumes
+at login. Here's an example allowing the user @code{alice} to mount her
+encrypted @code{HOME} directory and allowing the user @code{bob} to mount
+the partition where he stores his data:
+
+@lisp
+(define pam-mount-rules
+`((debug (@@ (enable "0")))
+ (volume (@@ (user "alice")
+ (fstype "crypt")
+ (path "/dev/sda2")
+ (mountpoint "/home/alice")))
+ (volume (@@ (user "bob")
+ (fstype "auto")
+ (path "/dev/sdb3")
+ (mountpoint "/home/bob/data")
+ (options "defaults,autodefrag,compress")))
+ (mntoptions (@@ (allow ,(string-join
+ '("nosuid" "nodev" "loop"
+ "encryption" "fsck" "nonempty"
+ "allow_root" "allow_other")
+ ","))))
+ (mntoptions (@@ (require "nosuid,nodev")))
+ (logout (@@ (wait "0")
+ (hup "0")
+ (term "no")
+ (kill "no")))
+ (mkmountpoint (@@ (enable "1")
+ (remove "true")))))
+
+(service pam-mount-service-type
+ (pam-mount-configuration
+ (rules pam-mount-rules)))
+@end lisp
+
+The complete list of possible options can be found in the man page for
+@uref{http://pam-mount.sourceforge.net/pam_mount.conf.5.html, pam_mount.conf}.
+@end table
+@end deftp
+
+
@node Guix Services
@subsection Guix Services
@item @code{build-locally?} (default: @code{#t})
If false, system derivations will be built on the machine being deployed to.
@item @code{system}
-The Nix system type describing the architecture of the machine being deployed
-to. This should look something like ``x86_64-linux''.
+The system type describing the architecture of the machine being deployed
+to---e.g., @code{"x86_64-linux"}.
@item @code{authorize?} (default: @code{#t})
If true, the coordinator's signing key will be added to the remote's ACL
keyring.
HCoop / jackhill / guix / guix.git / blobdiff