summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2013-12-10 00:23:33 +0100
committerLudovic Courtès <ludo@gnu.org>2013-12-10 00:24:02 +0100
commit4af2447e37f166aee7fb6852c2249a0de7d33a05 (patch)
treefad1fc5065c36bffe94f5f6241a714daa1f83423 /doc
parent4f62d8d6c74d1d9cec049cb5e22452b8d78655f5 (diff)
doc: First stab at documenting whole-system configuration.
* doc/guix.texi (Features): Add xref to "Using the Configuration System". (System Configuration, Using the Configuration System, Defining Services): New nodes.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi182
1 files changed, 181 insertions, 1 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 64ddb8539e..8483dbb4af 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -446,7 +446,9 @@ profile remains in its previous state, and remains usable.
In addition, any package transaction may be @emph{rolled back}. So, if,
for example, an upgrade installs a new version of a package that turns
out to have a serious bug, users may roll back to the previous instance
-of their profile, which was known to work well.
+of their profile, which was known to work well. Similarly, the global
+system configuration is subject to transactional upgrades and roll-back
+(@pxref{Using the Configuration System}).
All those packages in the package store may be @emph{garbage-collected}.
Guix can determine which packages are still referenced by the user
@@ -1785,6 +1787,7 @@ For information on porting to other architectures or kernels,
* Packaging Guidelines:: Growing the distribution.
* Bootstrapping:: GNU/Linux built from scratch.
* Porting:: Targeting another platform or kernel.
+* System Configuration:: Configuring a GNU system.
@end menu
Building this distribution is a cooperative effort, and you are invited
@@ -2205,6 +2208,183 @@ platform. Lastly, the generated binaries could be broken for some
reason.
+@node System Configuration
+@section System Configuration
+
+@emph{This section documents work-in-progress. As such it may be
+incomplete, outdated, or open to discussions. Please discuss it on
+@email{guix-devel@@gnu.org}.}
+
+@cindex system configuration
+The GNU system supports a consistent whole-system configuration
+mechanism. By that we mean that all aspects of the global system
+configuration---such as the available system services, timezone and
+locale settings, user accounts---are configured in a single place. Such
+a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
+
+This section describes this mechanism. First we focus on the system
+administrator's viewpoint---explaining how the system is configured and
+instantiated. Then we show how this mechanism can be extended, for
+instance to support new system services.
+
+@menu
+* Using the Configuration System:: Customizing your GNU system.
+* Defining Services:: Adding new service definitions.
+@end menu
+
+@node Using the Configuration System
+@subsection Using the Configuration System
+
+The operating system is configured by filling in an
+@code{operating-system} structure, as defined by the @code{(gnu system)}
+module. A simple setup, with the default system services, the default
+Linux-Libre kernel, initial RAM disk, and boot loader looks like this:
+
+@findex operating-system
+@lisp
+(use-modules (gnu system)
+ (gnu system shadow) ; for 'user-account'
+ (gnu system service) ; for 'lsh-service'
+ (gnu packages base) ; Coreutils, grep, etc.
+ (gnu packages bash) ; Bash
+ (gnu packages system) ; dmd, Inetutils
+ (gnu packages zile) ; Zile
+ (gnu packages less) ; less
+ (gnu packages guile) ; Guile
+ (gnu packages linux)) ; procps, psmisc
+
+(define %komputilo
+ (operating-system
+ (host-name "komputilo")
+ (timezone "Europe/Paris")
+ (locale "fr_FR.UTF-8")
+ (users (list (user-account
+ (name "alice")
+ (password "")
+ (uid 1000) (gid 100)
+ (comment "Bob's sister")
+ (home-directory "/home/alice"))))
+ (packages (list coreutils bash guile-2.0
+ guix dmd
+ inetutils
+ findutils grep sed
+ procps psmisc
+ zile less))
+ (services (cons (lsh-service #:port 2222 #:allow-root-login? #t)
+ %standard-services))))
+@end lisp
+
+This example should be self-describing. The @code{packages} field lists
+packages provides by the various @code{(gnu packages ...)} modules above;
+these are the packages that will be globally visible on the system, for
+all user accounts, in addition to the per-user profiles (@pxref{Invoking
+guix package}).
+
+The @code{services} field lists @dfn{system services} to be made
+available when the system starts. The @var{%standard-services} list,
+from the @code{(gnu system)} module, provides the basic services one
+would expect from a GNU system: a login service (mingetty) on each tty,
+syslogd, libc's name service cache daemon (nscd), etc.
+
+The @code{operating-system} declaration above specifies that, in
+addition to those services, we want the @command{lshd} secure shell
+daemon listening on port 2222, and allowing remote @code{root} logins
+(@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
+@code{lsh-service} arranges so that @code{lshd} is started with the
+right command-line options, possibly with supporting configuration files
+generated as needed (@pxref{Defining Services}).
+
+@c TODO: update when that command exists
+Assuming the above snippet is stored in the @file{my-system-config.scm}
+file, the (yet unwritten!) @command{guix system --boot
+my-system-config.scm} command instantiates that configuration, and makes
+it the default GRUB boot entry. The normal way to change the system's
+configuration is by updating this file and re-running the @command{guix
+system} command.
+
+At the Scheme level, the bulk of an @code{operating-system} declaration
+is instantiated with the following monadic procedure (@pxref{The Store
+Monad}):
+
+@deffn {Monadic Procedure} operating-system-derivation os
+Return a derivation that builds @var{os}, an @code{operating-system}
+object (@pxref{Derivations}).
+
+The output of the derivation is a single directory that refers to all
+the packages, configuration files, and other supporting files needed to
+instantiate @var{os}.
+@end deffn
+
+One of the advantages of putting all the system configuration under the
+control of Guix is that it makes it possible to roll-back to a previous
+system instantiation, should anything go wrong with the new one.
+Another one is that it makes it easy to replicate the very same
+configuration across different machines, or at different points in time,
+without having to resort to additional administration tools layered on
+top of the system's own tools.
+@c Yes, we're talking of Puppet, Chef, & co. here. ↑
+
+@node Defining Services
+@subsection Defining Services
+
+The @code{(gnu system dmd)} module defines several procedures that allow
+users to declare the operating system's services (@pxref{Using the
+Configuration System}). These procedures are @emph{monadic
+procedures}---i.e., procedures that return a monadic value in the store
+monad (@pxref{The Store Monad}). Examples of such procedures include:
+
+@table @code
+@item mingetty-service
+return the definition of a service that runs @command{mingetty} to
+offer a login service on the given console tty;
+
+@item nscd-service
+return a definition for libc's name service cache daemon (nscd);
+
+@item guix-service
+return a definition for a service that runs @command{guix-daemon}
+(@pxref{Invoking guix-daemon}).
+@end table
+
+@cindex service definition
+The monadic value returned by those procedures is a @dfn{service
+definition}---a structure as returned by the @code{service} form.
+Service definitions specifies the inputs the service depends on, and an
+expression to start and stop the service. Behind the scenes, service
+definitions are ``translated'' into the form suitable for the
+configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
+dmd Manual}).
+
+As an example, here is what the @code{nscd-service} procedure looks
+like:
+
+@lisp
+(define (nscd-service)
+ (mlet %store-monad ((nscd (package-file glibc "sbin/nscd")))
+ (return (service
+ (documentation "Run libc's name service cache daemon.")
+ (provision '(nscd))
+ (start `(make-forkexec-constructor ,nscd "-f" "/dev/null"
+ "--foreground"))
+ (stop `(make-kill-destructor))
+
+ (respawn? #f)
+ (inputs `(("glibc" ,glibc)))))))
+@end lisp
+
+@noindent
+The @code{inputs} field specifies that this service depends on the
+@var{glibc} package---the package that contains the @command{nscd}
+program. The @code{start} and @code{stop} fields are expressions that
+make use of dmd's facilities to start and stop processes (@pxref{Service
+De- and Constructors,,, dmd, GNU dmd Manual}). The @code{provision}
+field specifies the name under which this service is known to dmd, and
+@code{documentation} specifies on-line documentation. Thus, the
+commands @command{deco start ncsd}, @command{deco stop nscd}, and
+@command{deco doc nscd} will do what you would expect (@pxref{Invoking
+deco,,, dmd, GNU dmd Manual}).
+
+
@c *********************************************************************
@node Contributing
@chapter Contributing