diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix.texi | 283 |
1 files changed, 256 insertions, 27 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 784114f0bb..c031c8d880 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -17059,7 +17059,7 @@ I/O faster, and thus paging out unused portions of program memory will expand the RAM available for such caching. For a more detailed description of how memory is managed from the -viewpoint of a monolithic kernel, @xref{Memory +viewpoint of a monolithic kernel, @pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}. The Linux kernel has support for swap partitions and swap files: the @@ -18408,9 +18408,6 @@ udev rules can be provided as a list of files through the @var{rules} variable. The procedures @code{udev-rule}, @code{udev-rules-service} and @code{file->udev-rule} from @code{(gnu services base)} simplify the creation of such rule files. - -The @command{herd rules udev} command, as root, returns the name of the -directory containing all the active udev rules. @end deffn @deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}] @@ -18939,9 +18936,8 @@ gexps to introduce job definitions that are passed to mcron ;; job's action as a Scheme procedure. #~(job '(next-hour '(3)) (lambda () - (execl (string-append #$findutils "/bin/updatedb") - "updatedb" - "--prunepaths=/tmp /var/tmp /gnu/store")) + (system* (string-append #$findutils "/bin/updatedb") + "--prunepaths=/tmp /var/tmp /gnu/store")) "updatedb")) (define garbage-collector-job @@ -18979,6 +18975,12 @@ the job would appear as ``Lambda function'' in the output of @command{herd schedule mcron}, which is not nearly descriptive enough! @end quotation +@quotation Tip +Avoid calling the Guile procedures @code{execl}, @code{execle} or +@code{execlp} inside a job specification, else mcron won't be able to +output the completion status of the job. +@end quotation + For more complex jobs defined in Scheme where you need control over the top level, for instance to introduce a @code{use-modules} form, you can move your code to a separate program using the @code{program-file} procedure of the @@ -19580,6 +19582,10 @@ This is the list of available plugins for virtual private networks (VPNs). An example of this is the @code{network-manager-openvpn} package, which allows NetworkManager to manage VPNs @i{via} OpenVPN. +@item @code{iwd?} (default: @code{#f}) +NetworkManager will use iwd as a backend for wireless networking if this +option is set to @code{#t}, otherwise it will use wpa-supplicant. + @end table @end deftp @@ -28119,7 +28125,7 @@ The zabbix-server package. @item @code{user} (default: @code{"zabbix"}) (type: string) User who will run the Zabbix server. -@item @code{group} (default: @code{"zabbix"}) (type: group) +@item @code{group} (default: @code{"zabbix"}) (type: string) Group who will run the Zabbix server. @item @code{db-host} (default: @code{"127.0.0.1"}) (type: string) @@ -28205,7 +28211,7 @@ The zabbix-agent package. @item @code{user} (default: @code{"zabbix"}) (type: string) User who will run the Zabbix agent. -@item @code{group} (default: @code{"zabbix"}) (type: group) +@item @code{group} (default: @code{"zabbix"}) (type: string) Group who will run the Zabbix agent. @item @code{hostname} (default: @code{""}) (type: string) @@ -28446,6 +28452,8 @@ Local accounts with lower values will silently fail to authenticate. @node LDAP Services @subsection LDAP Services @cindex LDAP + +@subsubheading Authentication against LDAP with nslcd @cindex nslcd, LDAP service The @code{(gnu services authentication)} module provides the @@ -28922,6 +28930,189 @@ Defaults to @samp{()}. @c %end of generated documentation for nslcd-configuration +@subsubheading LDAP Directory Server +@cindex LDAP, server + +The @code{(gnu services ldap)} module provides the +@code{directory-server-service-type}, which can be used to create and +launch an LDAP server instance. + +Here is an example configuration of the +@code{directory-server-service-type}: + +@lisp +(use-service-modules ldap) + +... +(operating-system + ... + (services + (cons + (service directory-server-service-type + (directory-server-instance-configuration + (slapd + (slapd-configuration + (root-password "@{PBKDF2_SHA256@}AAAgAG@dots{}ABSOLUTELYSECRET"))))) + %base-services))) +@end lisp + +The root password should be generated with the @command{pwdhash} utility +that is provided by the @code{389-ds-base} package. + +Note that changes to the directory server configuration will not be +applied to existing instances. You will need to back up and restore +server data manually. Only new directory server instances will be +created upon system reconfiguration. + +@c %start of generated documentation for directory-server-instance-configuration +@deftp {Data Type} directory-server-instance-configuration +Available @code{directory-server-instance-configuration} fields are: + +@table @asis +@item @code{package} (default: @code{389-ds-base}) (type: file-like) +The @code{389-ds-base} package. + +@item @code{config-version} (default: @code{2}) (type: number) +Sets the format version of the configuration file. To use the INF file +with @command{dscreate}, this parameter must be 2. + +@item @code{full-machine-name} (default: @code{"localhost"}) (type: string) +Sets the fully qualified hostname (FQDN) of this system. + +@item @code{selinux} (default: @code{#false}) (type: boolean) +Enables SELinux detection and integration during the installation of +this instance. If set to @code{#true}, @command{dscreate} auto-detects +whether SELinux is enabled. + +@item @code{strict-host-checking} (default: @code{#true}) (type: boolean) +Sets whether the server verifies the forward and reverse record set in +the @code{full-machine-name} parameter. When installing this instance with +GSSAPI authentication behind a load balancer, set this parameter to +@code{#false}. + +@item @code{systemd} (default: @code{#false}) (type: boolean) +Enables systemd platform features. If set to @code{#true}, +@command{dscreate} auto-detects whether systemd is installed. + +@item @code{slapd} (type: slapd-configuration) +Configuration of slapd. + +@deftp {Data Type} slapd-configuration +Available @code{slapd-configuration} fields are: + +@table @asis +@item @code{instance-name} (default: @code{"localhost"}) (type: string) +Sets the name of the instance. You can refer to this value in other +parameters of this INF file using the @code{@{instance_name@}} variable. +Note that this name cannot be changed after the installation! + +@item @code{user} (default: @code{"dirsrv"}) (type: string) +Sets the user name the ns-slapd process will use after the service +started. + +@item @code{group} (default: @code{"dirsrv"}) (type: string) +Sets the group name the ns-slapd process will use after the service +started. + +@item @code{port} (default: @code{389}) (type: number) +Sets the TCP port the instance uses for LDAP connections. + +@item @code{secure-port} (default: @code{636}) (type: number) +Sets the TCP port the instance uses for TLS-secured LDAP connections +(LDAPS). + +@item @code{root-dn} (default: @code{"cn=Directory Manager"}) (type: string) +Sets the @dfn{Distinquished Name} (DN) of the administrator account for this +instance. + +@item @code{root-password} (default: @code{"@{invalid@}YOU-SHOULD-CHANGE-THIS"}) (type: string) +Sets the password of the account specified in the @code{root-dn} +parameter. You can either set this parameter to a plain text password +@command{dscreate} hashes during the installation or to a +"@{algorithm@}hash" string generated by the @command{pwdhash} utility. +Note that setting a plain text password can be a security risk if +unprivileged users can read this INF file! + +@item @code{self-sign-cert} (default: @code{#true}) (type: boolean) +Sets whether the setup creates a self-signed certificate and enables TLS +encryption during the installation. This is not suitable for +production, but it enables administrators to use TLS right after the +installation. You can replace the self-signed certificate with a +certificate issued by a certificate authority. + +@item @code{self-sign-cert-valid-months} (default: @code{24}) (type: number) +Set the number of months the issued self-signed certificate will be +valid. + +@item @code{backup-dir} (default: @code{"/var/lib/dirsrv/slapd-@{instance_name@}/bak"}) (type: string) +Set the backup directory of the instance. + +@item @code{cert-dir} (default: @code{"/etc/dirsrv/slapd-@{instance_name@}"}) (type: string) +Sets the directory of the instance's Network Security Services (NSS) +database. + +@item @code{config-dir} (default: @code{"/etc/dirsrv/slapd-@{instance_name@}"}) (type: string) +Sets the configuration directory of the instance. + +@item @code{db-dir} (default: @code{"/var/lib/dirsrv/slapd-@{instance_name@}/db"}) (type: string) +Sets the database directory of the instance. + +@item @code{initconfig-dir} (default: @code{"/etc/dirsrv/registry"}) (type: string) +Sets the directory of the operating system's rc configuration directory. + +@item @code{ldif-dir} (default: @code{"/var/lib/dirsrv/slapd-@{instance_name@}/ldif"}) (type: string) +Sets the LDIF export and import directory of the instance. + +@item @code{lock-dir} (default: @code{"/var/lock/dirsrv/slapd-@{instance_name@}"}) (type: string) +Sets the lock directory of the instance. + +@item @code{log-dir} (default: @code{"/var/log/dirsrv/slapd-@{instance_name@}"}) (type: string) +Sets the log directory of the instance. + +@item @code{run-dir} (default: @code{"/run/dirsrv"}) (type: string) +Sets PID directory of the instance. + +@item @code{schema-dir} (default: @code{"/etc/dirsrv/slapd-@{instance_name@}/schema"}) (type: string) +Sets schema directory of the instance. + +@item @code{tmp-dir} (default: @code{"/tmp"}) (type: string) +Sets the temporary directory of the instance. +@end table +@end deftp + +@item @code{backend-userroot} (type: backend-userroot-configuration) +Configuration of the userroot backend. + +@deftp {Data Type} backend-userroot-configuration +Available @code{backend-userroot-configuration} fields are: + +@table @asis +@item @code{create-suffix-entry?} (default: @code{#false}) (type: boolean) +Set this parameter to @code{#true} to create a generic root node entry +for the suffix in the database. + +@item @code{require-index?} (default: @code{#false}) (type: boolean) +Set this parameter to @code{#true} to refuse unindexed searches in this +database. + +@item @code{sample-entries} (default: @code{"no"}) (type: string) +Set this parameter to @code{"yes"} to add latest version of sample +entries to this database. Or, use @code{"001003006"} to use the 1.3.6 +version sample entries. Use this option, for example, to create a +database for testing purposes. + +@item @code{suffix} (type: maybe-string) +Sets the root suffix stored in this database. If you do not set the +suffix attribute the install process will not create the backend/suffix. +You can also create multiple backends/suffixes by duplicating this +section. + +@end table +@end deftp +@end table +@end deftp +@c end of generated documentation for directory-server + @node Web Services @subsection Web Services @@ -34058,6 +34249,10 @@ To override a setting, you must use the configuration type for that service: @item @code{file-storage-paths} (default: @code{'()}) List of allowed directories for file storage backend. +@item @code{hooks} (default: @code{#f}) +When set, this should be a file-like object containing a directory with +@url{https://docs.ganeti.org/docs/ganeti/3.0/html/hooks.html,cluster execution hooks}. + @item @code{os} (default: @code{%default-ganeti-os}) List of @code{<ganeti-os>} records. @end table @@ -37202,6 +37397,15 @@ The Nix package to use. @item @code{sandbox} (default: @code{#t}) Specifies whether builds are sandboxed by default. +@item @code{build-directory} (default: @code{"/tmp"}) +The directory where build directory are stored during builds. +This is useful to change if, for example, the default location does not +have enough space to hold build trees for big packages. + +This is similar to setting the @env{TMPDIR} environment variable for +@command{guix-daemon}. @ref{Build Environment Setup, @env{TMPDIR}}, +for more info. + @item @code{build-sandbox-items} (default: @code{'()}) This is a list of strings or objects appended to the @code{build-sandbox-items} field of the configuration file. @@ -37990,8 +38194,9 @@ The type of a bootloader configuration declaration. @cindex BIOS, bootloader The bootloader to use, as a @code{bootloader} object. For now @code{grub-bootloader}, @code{grub-efi-bootloader}, -@code{grub-efi-netboot-bootloader}, @code{grub-efi-removable-bootloader}, -@code{extlinux-bootloader} and @code{u-boot-bootloader} are supported. +@code{grub-efi-removable-bootloader}, @code{grub-efi-netboot-bootloader}, +@code{grub-efi-netboot-removable-bootloader}, @code{extlinux-bootloader} +and @code{u-boot-bootloader} are supported. @cindex ARM, bootloaders @cindex AArch64, bootloaders @@ -38000,15 +38205,29 @@ modules. In particular, @code{(gnu bootloader u-boot)} contains definitions of bootloaders for a wide range of ARM and AArch64 systems, using the @uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}. +@vindex grub-bootloader +@code{grub-bootloader} allows you to boot in particular Intel-based machines +in ``legacy'' BIOS mode. + @vindex grub-efi-bootloader @code{grub-efi-bootloader} allows to boot on modern systems using the @dfn{Unified Extensible Firmware Interface} (UEFI). This is what you should use if the installation image contains a @file{/sys/firmware/efi} directory when you boot it on your system. -@vindex grub-bootloader -@code{grub-bootloader} allows you to boot in particular Intel-based machines -in ``legacy'' BIOS mode. +@vindex grub-efi-removable-bootloader +@code{grub-efi-removable-bootloader} allows you to boot your system from +removable media by writing the GRUB file to the UEFI-specification location of +@file{/EFI/BOOT/BOOTX64.efi} of the boot directory, usually @file{/boot/efi}. +This is also useful for some UEFI firmwares that ``forget'' their configuration +from their non-volatile storage. Like @code{grub-efi-bootloader}, this can only +be used if the @file{/sys/firmware/efi} directory is available. + +@quotation Note +This @emph{will} overwrite the GRUB file from any other operating systems that +also place their GRUB file in the UEFI-specification location; making them +unbootable. +@end quotation @vindex grub-efi-netboot-bootloader @code{grub-efi-netboot-bootloader} allows you to boot your system over network @@ -38017,9 +38236,10 @@ build a diskless Guix system. The installation of the @code{grub-efi-netboot-bootloader} generates the content of the TFTP root directory at @code{targets} (@pxref{Bootloader -Configuration, @code{targets}}), to be served by a TFTP server. You may -want to mount your TFTP server directories onto the @code{targets} to -move the required files to the TFTP server automatically. +Configuration, @code{targets}}) below the sub-directory @file{efi/Guix}, to be +served by a TFTP server. You may want to mount your TFTP server directories +onto the @code{targets} to move the required files to the TFTP server +automatically during installation. If you plan to use an NFS root file system as well (actually if you mount the store from an NFS share), then the TFTP server needs to serve the file @@ -38048,25 +38268,34 @@ this constellation the symlinks will work. For other constellations you will have to program your own bootloader installer, which then takes care to make necessary files from the store accessible through TFTP, for example by copying them into the TFTP root -directory to your @code{targets}. +directory for your @code{targets}. It is important to note that symlinks pointing outside the TFTP root directory may need to be allowed in the configuration of your TFTP server. Further the store link exposes the whole store through TFTP@. Both points need to be -considered carefully for security aspects. +considered carefully for security aspects. It is advised to disable any TFTP +write access! + +Please note, that this bootloader will not modify the ‘UEFI Boot Manager’ of +the system. Beside the @code{grub-efi-netboot-bootloader}, the already mentioned TFTP and NFS servers, you also need a properly configured DHCP server to make the booting over netboot possible. For all this we can currently only recommend you to look for instructions about @acronym{PXE, Preboot eXecution Environment}. -@vindex grub-efi-removable-bootloader -@code{grub-efi-removable-bootloader} allows you to boot your system from -removable media by writing the GRUB file to the UEFI-specification location of -@file{/EFI/BOOT/BOOTX64.efi} of the boot directory, usually @file{/boot/efi}. -This is also useful for some UEFI firmwares that ``forget'' their configuration -from their non-volatile storage. Like @code{grub-efi-bootloader}, this can only -be used if the @file{/sys/firmware/efi} directory is available. +If a local EFI System Partition (ESP) or a similar partition with a FAT +file system is mounted in @code{targets}, then symlinks cannot be +created. In this case everything will be prepared for booting from +local storage, matching the behavior of @code{grub-efi-bootloader}, with +the difference that all GRUB binaries are copied to @code{targets}, +necessary for booting over the network. + +@vindex grub-efi-netboot-removable-bootloader +@code{grub-efi-netboot-removable-bootloader} is identical to +@code{grub-efi-netboot-bootloader} with the exception that the +sub-directory @file{efi/boot} will be used instead of @file{efi/Guix} to +comply with the UEFI specification for removable media. @quotation Note This @emph{will} overwrite the GRUB file from any other operating systems that @@ -43141,7 +43370,7 @@ bootstrap stack, working towards a Full Source Bootstrap. Also ongoing is work to bring these bootstraps to the @code{arm-linux} and @code{aarch64-linux} architectures and to the Hurd. -If you are interested, join us on @samp{#bootstrappable} on the Freenode +If you are interested, join us on @samp{#bootstrappable} on the Libera.Chat IRC network or discuss on @email{bug-mes@@gnu.org} or @email{gash-devel@@nongnu.org}. |