diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 28 | ||||
| -rw-r--r-- | doc/guix.texi | 217 |
2 files changed, 214 insertions, 31 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 1dd3ea8e1d..01f8aad9fb 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -193,6 +193,34 @@ facilities to directly operate on the syntax tree, such as raising an s-expression or wrapping it, swallowing or rejecting the following s-expression, etc. +@cindex code snippets +@cindex templates +@cindex reducing boilerplate +We also provide templates for common git commit messages and package +definitions in the @file{etc/snippets} directory. These templates can +be used with @url{http://joaotavora.github.io/yasnippet/, YASnippet} to +expand short trigger strings to interactive text snippets. You may want +to add the snippets directory to the @var{yas-snippet-dirs} variable in +Emacs. + +@lisp +;; @r{Assuming the Guix checkout is in ~/src/guix.} +(with-eval-after-load 'yasnippet + (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) +@end lisp + +The commit message snippets depend on @url{https://magit.vc/, Magit} to +display staged files. When editing a commit message type @code{add} +followed by @kbd{TAB} to insert a commit message template for adding a +package; type @code{update} followed by @kbd{TAB} to insert a template +for updating a package. + +The main snippet for @code{scheme-mode} is triggered by typing +@code{package...} followed by @kbd{TAB}. This snippet also inserts the +trigger string @code{origin...}, which can be expanded further. The +@code{origin} snippet in turn may insert other trigger strings ending on +@code{...}, which also can be expanded further. + @node Coding Style @section Coding Style diff --git a/doc/guix.texi b/doc/guix.texi index c14df7fcd3..3bb29db960 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -43,7 +43,8 @@ Copyright @copyright{} 2017 Maxim Cournoyer@* Copyright @copyright{} 2017 Tobias Geerinckx-Rice@* Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017 Andy Wingo@* -Copyright @copyright{} 2017 Arun Isaac +Copyright @copyright{} 2017 Arun Isaac@* +Copyright @copyright{} 2017 nee Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -1065,6 +1066,15 @@ regular expression like this: # guix offload test machines.scm '\.gnu\.org$' @end example +@cindex offload status +To display the current load of all build hosts, run this command on the +main node: + +@example +# guix offload status +@end example + + @node Invoking guix-daemon @section Invoking @command{guix-daemon} @@ -1550,7 +1560,7 @@ features. This chapter describes the main features of Guix, as well as the package management tools it provides. Along with the command-line interface described below (@pxref{Invoking guix package, @code{guix -package}}), you may also use Emacs Interface (@pxref{Top,,, +package}}), you may also use the Emacs-Guix interface (@pxref{Top,,, emacs-guix, The Emacs-Guix Reference Manual}), after installing @code{emacs-guix} package (run @kbd{M-x guix-help} command to start with it): @@ -8690,6 +8700,9 @@ also specified. @xref{Mapped Devices} and @ref{File Systems}. @itemx @code{groups} (default: @var{%base-groups}) List of user accounts and groups. @xref{User Accounts}. +If the @code{users} list lacks a user account with UID@tie{}0, a +``root'' account with UID@tie{}0 is automatically added. + @item @code{skeletons} (default: @code{(default-skeletons)}) A list target file name/file-like object tuples (@pxref{G-Expressions, file-like objects}). These are the skeleton files that will be added to @@ -14813,10 +14826,7 @@ A simple example configuration is given below. (server-blocks (list (nginx-server-configuration (server-name '("www.example.com")) - (root "/srv/http/www.example.com") - (https-port #f) - (ssl-certificate #f) - (ssl-certificate-key #f)))))) + (root "/srv/http/www.example.com")))))) @end example In addition to adding server blocks to the service configuration @@ -14826,9 +14836,6 @@ blocks, as in this example: @example (simple-service 'my-extra-server nginx-service-type (list (nginx-server-configuration - (https-port #f) - (ssl-certificate #f) - (ssl-certificate-key #f) (root "/srv/http/extra-website") (try-files (list "$uri" "$uri/index.html"))))) @end example @@ -14873,10 +14880,7 @@ HTTPS. (server-blocks (list (nginx-server-configuration (server-name '("www.example.com")) - (root "/srv/http/www.example.com") - (https-port #f) - (ssl-certificate #f) - (ssl-certificate-key #f)))))) + (root "/srv/http/www.example.com")))))) @end example @item @code{upstream-blocks} (default: @code{'()}) @@ -14899,9 +14903,6 @@ requests with two servers. (list (nginx-server-configuration (server-name '("www.example.com")) (root "/srv/http/www.example.com") - (https-port #f) - (ssl-certificate #f) - (ssl-certificate-key #f) (locations (list (nginx-location-configuration @@ -14925,6 +14926,13 @@ This can be useful if you have an existing configuration file, or it's not possible to do what is required through the other parts of the nginx-configuration record. +@item @code{server-names-hash-bucket-size} (default: @code{#f}) +Bucket size for the server names hash tables, defaults to @code{#f} to +use the size of the processors cache line. + +@item @code{server-names-hash-bucket-max-size} (default: @code{#f}) +Maximum bucket size for the server names hash tables. + @end table @end deffn @@ -14933,17 +14941,15 @@ Data type representing the configuration of an nginx server block. This type has the following parameters: @table @asis -@item @code{http-port} (default: @code{80}) -Nginx will listen for HTTP connection on this port. Set it at @code{#f} if -nginx should not listen for HTTP (non secure) connection for this -@dfn{server block}. - -@item @code{https-port} (default: @code{443}) -Nginx will listen for HTTPS connection on this port. Set it at @code{#f} if -nginx should not listen for HTTPS (secure) connection for this @dfn{server block}. +@item @code{listen} (default: @code{'("80" "443 ssl")}) +Each @code{listen} directive sets the address and port for IP, or the +path for a UNIX-domain socket on which the server will accept requests. +Both address and port, or only address or only port can be specified. +An address may also be a hostname, for example: -Note that nginx can listen for HTTP and HTTPS connections in the same -@dfn{server block}. +@example +'("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000") +@end example @item @code{server-name} (default: @code{(list 'default)}) A list of server names this server represents. @code{'default} represents the @@ -14965,17 +14971,20 @@ Nginx will send the list of files in the directory. A list of files whose existence is checked in the specified order. @code{nginx} will use the first file it finds to process the request. -@item @code{ssl-certificate} (default: @code{"/etc/nginx/cert.pem"}) +@item @code{ssl-certificate} (default: @code{#f}) Where to find the certificate for secure connections. Set it to @code{#f} if you don't have a certificate or you don't want to use HTTPS. -@item @code{ssl-certificate-key} (default: @code{"/etc/nginx/key.pem"}) +@item @code{ssl-certificate-key} (default: @code{#f}) Where to find the private key for secure connections. Set it to @code{#f} if you don't have a key or you don't want to use HTTPS. @item @code{server-tokens?} (default: @code{#f}) Whether the server should add its configuration to response. +@item @code{raw-content} (default: @code{'()}) +A list of raw lines added to the server block. + @end table @end deftp @@ -15086,6 +15095,145 @@ capability also has to be configured on the front-end as well. @end table @end deftp +@cindex php-fpm +PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI implementation +with some additional features useful for sites of any size. + +These features include: +@itemize @bullet +@item Adaptive process spawning +@item Basic statistics (similar to Apache's mod_status) +@item Advanced process management with graceful stop/start +@item Ability to start workers with different uid/gid/chroot/environment +and different php.ini (replaces safe_mode) +@item Stdout & stderr logging +@item Emergency restart in case of accidental opcode cache destruction +@item Accelerated upload support +@item Support for a "slowlog" +@item Enhancements to FastCGI, such as fastcgi_finish_request() - +a special function to finish request & flush all data while continuing to do +something time-consuming (video converting, stats processing, etc.) +@end itemize +... and much more. + +@defvr {Scheme Variable} php-fpm-service-type +A Service type for @code{php-fpm}. +@end defvr + +@deftp {Data Type} php-fpm-configuration +Data Type for php-fpm service configuration. +@table @asis +@item @code{php} (default: @code{php}) +The php package to use. +@item @code{socket} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")}) +The address on which to accept FastCGI requests. Valid syntaxes are: +@table @asis +@item @code{"ip.add.re.ss:port"} +Listen on a TCP socket to a specific address on a specific port. +@item @code{"port"} +Listen on a TCP socket to all addresses on a specific port. +@item @code{"/path/to/unix/socket"} +Listen on a unix socket. +@end table + +@item @code{user} (default: @code{php-fpm}) +User who will own the php worker processes. +@item @code{group} (default: @code{php-fpm}) +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}) +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 +once the service has started. +@item @code{log-file} (default: @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")}) +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: +@table @asis +@item @code{<php-fpm-dynamic-process-manager-configuration>} +@item @code{<php-fpm-static-process-manager-configuration>} +@item @code{<php-fpm-on-demand-process-manager-configuration>} +@end table +@item @code{display-errors} (default @code{#f}) +Determines wether php errors and warning should be sent to clients +and displayed in their browsers. +This is useful for local php development, but a security risk for public sites, +as error messages can reveal passwords and personal data. +@item @code{workers-logfile} (default @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log")}) +This file will log the @code{stderr} outputs of php worker processes. +Can be set to @code{#f} to disable logging. +@item @code{file} (default @code{#f}) +An optional override of the whole configuration. +You can use the @code{mixed-text-file} function or an absolute filepath for it. +@end table +@end deftp + +@deftp {Data type} php-fpm-dynamic-process-manager-configuration +Data Type for the @code{dynamic} php-fpm process manager. With the +@code{dynamic} process manager, spare worker processes are kept around +based on it's configured limits. +@table @asis +@item @code{max-children} (default: @code{5}) +Maximum of worker processes. +@item @code{start-servers} (default: @code{2}) +How many worker processes should be started on start-up. +@item @code{min-spare-servers} (default: @code{1}) +How many spare worker processes should be kept around at minimum. +@item @code{max-spare-servers} (default: @code{3}) +How many spare worker processes should be kept around at maximum. +@end table +@end deftp + +@deftp {Data type} php-fpm-static-process-manager-configuration +Data Type for the @code{static} php-fpm process manager. With the +@code{static} process manager, an unchanging number of worker processes +are created. +@table @asis +@item @code{max-children} (default: @code{5}) +Maximum of worker processes. +@end table +@end deftp + +@deftp {Data type} php-fpm-on-demand-process-manager-configuration +Data Type for the @code{on-demand} php-fpm process manager. With the +@code{on-demand} process manager, worker processes are only created as +requests arrive. +@table @asis +@item @code{max-children} (default: @code{5}) +Maximum of worker processes. +@item @code{process-idle-timeout} (default: @code{10}) +The time in seconds after which a process with no requests is killed. +@end table +@end deftp + + +@deffn {Scheme Procedure} nginx-php-fpm-location @ + [#:nginx-package nginx] @ + [socket (string-append "/var/run/php" @ + (version-major (package-version php)) @ + "-fpm.sock")] +A helper function to quickly add php to an @code{nginx-server-configuration}. +@end deffn + +A simple services setup for nginx with php can look like this: +@example +(services (cons* (dhcp-client-service) + (service php-fpm-service-type) + (service nginx-service-type + (nginx-server-configuration + (server-name '("example.com")) + (root "/srv/http/") + (locations + (list (nginx-php-location))) + (https-port #f) + (ssl-certificate #f) + (ssl-certificate-key #f))) + %base-services)) +@end example + @node Certificate Services @subsubsection Certificate Services @@ -15206,7 +15354,7 @@ and one slave, is: (operating-system ;; ... (services (cons* (service knot-service-type - (knot-confifguration + (knot-configuration (remotes (list plop-master)) (zones (list master-zone slave-zone)))) ;; ... @@ -17545,7 +17693,7 @@ serve the default @file{/srv/git} over HTTPS might be: (server-blocks (list (nginx-server-configuration - (http-port #f) + (listen '("443 ssl")) (server-name "git.my-host.org") (ssl-certificate "/etc/letsencrypt/live/git.my-host.org/fullchain.pem") @@ -18228,7 +18376,6 @@ system. A possibly empty list of @code{menu-entry} objects (see below), denoting entries to appear in the bootloader menu, in addition to the current system entry and the entry pointing to previous system generations. -generations. @item @code{default-entry} (default: @code{0}) The index of the default boot menu entry. Index 0 is for the entry of the @@ -18609,6 +18756,14 @@ Build Options}). In addition, @var{options} can contain one of the following: @table @option +@item --expression=@var{expr} +@itemx -e @var{expr} +Consider the operating-system @var{expr} evaluates to. +This is an alternative to specifying a file which evaluates to an +operating system. +This is used to generate the GuixSD installer @pxref{Building the +Installation Image}). + @item --system=@var{system} @itemx -s @var{system} Attempt to build for @var{system} instead of the host system type. |