summary refs log tree commit diff
path: root/doc/guix.texi
diff options
context:
space:
mode:
authorMark H Weaver <mhw@netris.org>2018-01-19 23:59:20 -0500
committerMark H Weaver <mhw@netris.org>2018-01-19 23:59:20 -0500
commite074a655dd6497daafbd62737e3b63f3d5aa7985 (patch)
tree2b198ba5c664cdd58e155f3c0113d1cebde0fc91 /doc/guix.texi
parent6d7b26a39faf42c37f15dc64a30a77e5e194ea23 (diff)
parentccb5cac17be98aaa9c3225605d6170c675d8e8e6 (diff)
downloadguix-e074a655dd6497daafbd62737e3b63f3d5aa7985.tar.gz
Merge branch 'master' into core-updates
Diffstat (limited to 'doc/guix.texi')
-rw-r--r--doc/guix.texi243
1 files changed, 218 insertions, 25 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 6245d54e8d..1ecdcd2182 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2659,6 +2659,12 @@ 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.
 
+@quotation Note
+If you are looking for ways to exchange binaries among machines that
+already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix
+publish}, and @ref{Invoking guix archive}.
+@end quotation
+
 @cindex pack
 @cindex bundle
 @cindex application bundle
@@ -2794,10 +2800,16 @@ options (@pxref{Package Transformation Options}).
 @cindex @command{guix archive}
 @cindex archive
 The @command{guix archive} command allows users to @dfn{export} files
-from the store into a single archive, and to later @dfn{import} them.
+from the store into a single archive, and to later @dfn{import} them on
+a machine that runs Guix.
 In particular, it allows store files to be transferred from one machine
 to the store on another machine.
 
+@quotation Note
+If you're looking for a way to produce archives in a format suitable for
+tools other than Guix, @pxref{Invoking guix pack}.
+@end quotation
+
 @cindex exporting store items
 To export store files as an archive to standard output, run:
 
@@ -3683,10 +3695,10 @@ Go build mechanisms}.
 The user is expected to provide a value for the key @code{#:import-path}
 and, in some cases, @code{#:unpack-path}.  The
 @url{https://golang.org/doc/code.html#ImportPaths, import path}
-corresponds to the filesystem path expected by the package's build
+corresponds to the file system path expected by the package's build
 scripts and any referring packages, and provides a unique way to
 refer to a Go package.  It is typically based on a combination of the
-package source code's remote URI and filesystem hierarchy structure.  In
+package source code's remote URI and file system hierarchy structure.  In
 some cases, you will need to unpack the package's source code to a
 different directory structure than the one indicated by the import path,
 and @code{#:unpack-path} should be used in such cases.
@@ -10689,21 +10701,6 @@ See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
 project's documentation} for more information.
 @end deffn
 
-@deffn {Scheme Procedure} bitlbee-service [#:bitlbee bitlbee] @
-         [#:interface "127.0.0.1"] [#:port 6667] @
-         [#:extra-settings ""]
-Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
-acts as a gateway between IRC and chat networks.
-
-The daemon will listen to the interface corresponding to the IP address
-specified in @var{interface}, on @var{port}.  @code{127.0.0.1} means that only
-local clients can connect, whereas @code{0.0.0.0} means that connections can
-come from any networking interface.
-
-In addition, @var{extra-settings} specifies a string to append to the
-configuration file.
-@end deffn
-
 The @code{(gnu services rsync)} module provides the following services:
 
 You might want an rsync daemon if you have files that you want available
@@ -14425,6 +14422,47 @@ string, you could instantiate a prosody service like this:
           (prosody.cfg.lua "")))
 @end example
 
+@subsubheading BitlBee Service
+
+@cindex IRC (Internet Relay Chat)
+@cindex IRC gateway
+@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC
+interface to a variety of messaging protocols such as XMPP.
+
+@defvr {Scheme Variable} bitlbee-service-type
+This is the service type for the @url{http://bitlbee.org,BitlBee} IRC
+gateway daemon.  Its value is a @code{bitlbee-configuration} (see
+below).
+
+To have BitlBee listen on port 6667 on localhost, add this line to your
+services:
+
+@example
+(service bitlbee-service-type)
+@end example
+@end defvr
+
+@deftp {Data Type} bitlbee-configuration
+This is the configuration for BitlBee, with the following fields:
+
+@table @asis
+@item @code{interface} (default: @code{"127.0.0.1"})
+@itemx @code{port} (default: @code{6667})
+Listen on the network interface corresponding to the IP address
+specified in @var{interface}, on @var{port}.
+
+When @var{interface} is @code{127.0.0.1}, only local clients can
+connect; when it is @code{0.0.0.0}, connections can come from any
+networking interface.
+
+@item @code{package} (default: @code{bitlbee})
+The BitlBee package to use.
+
+@item @code{extra-settings} (default: @code{""})
+Configuration snippet added as-is to the BitlBee configuration file.
+@end table
+@end deftp
+
 
 @node Telephony Services
 @subsubsection Telephony Services
@@ -14916,8 +14954,162 @@ Local accounts with lower values will silently fail to authenticate.
 @cindex web
 @cindex www
 @cindex HTTP
-The @code{(gnu services web)} module provides the nginx web server and
-also a fastcgi wrapper daemon.
+The @code{(gnu services web)} module provides the Apache HTTP Server,
+the nginx web server, and also a fastcgi wrapper daemon.
+
+@subsubheading Apache HTTP Server
+
+@deffn {Scheme Variable} httpd-service-type
+Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server
+(@dfn{httpd}).  The value for this service type is a
+@code{https-configuration} record.
+
+A simple example configuration is given below.
+
+@example
+(service httpd-service-type
+         (httpd-configuration
+           (config
+             (httpd-config-file
+               (server-name "www.example.com")
+               (document-root "/srv/http/www.example.com")))))
+@end example
+
+Other services can also extend the @code{httpd-service-type} to add to
+the configuration.
+
+@example
+(simple-service 'my-extra-server httpd-service-type
+                (list
+                  (httpd-virtualhost
+                    "*:80"
+                    (list (string-append
+                           "ServerName "www.example.com
+                            DocumentRoot \"/srv/http/www.example.com\"")))))
+@end example
+@end deffn
+
+The details for the @code{httpd-configuration}, @code{httpd-module},
+@code{httpd-config-file} and @code{httpd-virtualhost} record types are
+given below.
+
+@deffn {Data Type} httpd-configuration
+This data type represents the configuration for the httpd service.
+
+@table @asis
+@item @code{package} (default: @code{httpd})
+The httpd package to use.
+
+@item @code{pid-file} (default: @code{"/var/run/httpd"})
+The pid file used by the shepherd-service.
+
+@item @code{config} (default: @code{(httpd-config-file)})
+The configuration file to use with the httpd service. The default value
+is a @code{httpd-config-file} record, but this can also be a different
+G-expression that generates a file, for example a @code{plain-file}. A
+file outside of the store can also be specified through a string.
+
+@end table
+@end deffn
+
+@deffn {Data Type} httpd-module
+This data type represents a module for the httpd service.
+
+@table @asis
+@item @code{name}
+The name of the module.
+
+@item @code{file}
+The file for the module. This can be relative to the httpd package being
+used, the absolute location of a file, or a G-expression for a file
+within the store, for example @code{(file-append mod-wsgi
+"/modules/mod_wsgi.so")}.
+
+@end table
+@end deffn
+
+@deffn {Data Type} httpd-config-file
+This data type represents a configuration file for the httpd service.
+
+@table @asis
+@item @code{modules} (default: @code{%default-httpd-modules})
+The modules to load. Additional modules can be added here, or loaded by
+additional configuration.
+
+@item @code{server-root} (default: @code{httpd})
+The @code{ServerRoot} in the configuration file, defaults to the httpd
+package. Directives including @code{Include} and @code{LoadModule} are
+taken as relative to the server root.
+
+@item @code{server-name} (default: @code{#f})
+The @code{ServerName} in the configuration file, used to specify the
+request scheme, hostname and port that the server uses to identify
+itself.
+
+This doesn't need to be set in the server config, and can be specifyed
+in virtual hosts. The default is @code{#f} to not specify a
+@code{ServerName}.
+
+@item @code{document-root} (default: @code{"/srv/http"})
+The @code{DocumentRoot} from which files will be served.
+
+@item @code{listen} (default: @code{'("80")})
+The list of values for the @code{Listen} directives in the config
+file. The value should be a list of strings, when each string can
+specify the port number to listen on, and optionally the IP address and
+protocol to use.
+
+@item @code{pid-file} (default: @code{"/var/run/httpd"})
+The @code{PidFile} to use. This should match the @code{pid-file} set in
+the @code{httpd-configuration} so that the Shepherd service is
+configured correctly.
+
+@item @code{error-log} (default: @code{"/var/log/httpd/error_log"})
+The @code{ErrorLog} to which the server will log errors.
+
+@item @code{user} (default: @code{"httpd"})
+The @code{User} which the server will answer requests as.
+
+@item @code{group} (default: @code{"httpd"})
+The @code{Group} which the server will answer requests as.
+
+@item @code{extra-config} (default: @code{(list "TypesConfig etc/httpd/mime.types")})
+A flat list of strings and G-expressions which will be added to the end
+of the configuration file.
+
+Any values which the service is extended with will be appended to this
+list.
+
+@end table
+@end deffn
+
+@deffn {Data Type} httpd-virtualhost
+This data type represents a virtualhost configuration block for the httpd service.
+
+These should be added to the extra-config for the httpd-service.
+
+@example
+(simple-service 'my-extra-server httpd-service-type
+                (list
+                  (httpd-virtualhost
+                    "*:80"
+                    (list (string-append
+                           "ServerName "www.example.com
+                            DocumentRoot \"/srv/http/www.example.com\"")))))
+@end example
+
+@table @asis
+@item @code{addresses-and-ports}
+The addresses and ports for the @code{VirtualHost} directive.
+
+@item @code{contents}
+The contents of the @code{VirtualHost} directive, this should be a list
+of strings and G-expressions.
+
+@end table
+@end deffn
+
+@subsubheading NGINX
 
 @deffn {Scheme Variable} nginx-service-type
 Service type for the @uref{https://nginx.org/,NGinx} web server.  The
@@ -15122,11 +15314,12 @@ URI which this location block matches.
 
 @anchor{nginx-location-configuration body}
 @item @code{body}
-Body of the location block, specified as a string. This can contain many
+Body of the location block, specified as a list of strings. This can contain
+many
 configuration directives.  For example, to pass requests to a upstream
 server group defined using an @code{nginx-upstream-configuration} block,
-the following directive would be specified in the body @samp{proxy_pass
-http://upstream-name;}.
+the following directive would be specified in the body @samp{(list "proxy_pass
+http://upstream-name;")}.
 
 @end table
 @end deftp
@@ -15655,7 +15848,7 @@ The backend to store the keys in.  Can be @code{'pem} or @code{'pkcs11}.
 @item @code{config} (default: @code{"/var/lib/knot/keys/keys"})
 The configuration string of the backend.  An example for the PKCS#11 is:
 @code{"pkcs11:token=knot;pin-value=1234 /gnu/store/.../lib/pkcs11/libsofthsm2.so"}.
-For the pem backend, the string reprensents a path in the filesystem.
+For the pem backend, the string reprensents a path in the file system.
 
 @end table
 @end deftp
@@ -17727,7 +17920,7 @@ service:
 (service qemu-binfmt-service-type
          (qemu-binfmt-configuration
            (platforms (lookup-qemu-platforms "arm"))
-           (qemu-support? #t)))
+           (guix-support? #t)))
 @end example
 
 You can run: