diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 12 | ||||
| -rw-r--r-- | doc/guix.texi | 241 |
2 files changed, 237 insertions, 16 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 1b1875fa0c..1dd3ea8e1d 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -309,6 +309,12 @@ please run through this check list: @enumerate @item +If the authors of the packaged software provide a cryptographic +signature for the release tarball, make an effort to verify the +authenticity of the archive. For a detached GPG signature file this +would be done with the @code{gpg --verify} command. + +@item Take some time to provide an adequate synopsis and description for the package. @xref{Synopses and Descriptions}, for some guidelines. @@ -336,12 +342,6 @@ updates for a given software package in a single place and have them affect the whole system---something that bundled copies prevent. @item -If the authors of the packaged software provide a cryptographic -signature for the release tarball, make an effort to verify the -authenticity of the archive. For a detached GPG signature file this -would be done with the @code{gpg --verify} command. - -@item Take a look at the profile reported by @command{guix size} (@pxref{Invoking guix size}). This will allow you to notice references to other packages unwillingly retained. It may also help determine diff --git a/doc/guix.texi b/doc/guix.texi index 983d0e52e4..d4a2a696a4 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -221,6 +221,7 @@ Services * Database Services:: SQL databases, key-value stores, etc. * Mail Services:: IMAP, POP3, SMTP, and all that. * Messaging Services:: Messaging services. +* Telephony Services:: Telephony services. * Monitoring Services:: Monitoring services. * Kerberos Services:: Kerberos services. * Web Services:: Web servers. @@ -1235,9 +1236,12 @@ this optimization. Tell whether the garbage collector (GC) must keep outputs of live derivations. +@cindex GC roots +@cindex garbage collector roots When set to ``yes'', the GC will keep the outputs of any live derivation available in the store---the @code{.drv} files. The default is ``no'', meaning that derivation outputs are kept only if they are GC roots. +@xref{Invoking guix gc}, for more on GC roots. @item --gc-keep-derivations[=yes|no] Tell whether the garbage collector (GC) must keep derivations @@ -2337,12 +2341,16 @@ collector to reclaim space from the @file{/gnu/store} directory. It is the @emph{only} way to remove files from @file{/gnu/store}---removing files or directories manually may break it beyond repair! +@cindex GC roots +@cindex garbage collector roots The garbage collector has a set of known @dfn{roots}: any file under @file{/gnu/store} reachable from a root is considered @dfn{live} and cannot be deleted; any other file is considered @dfn{dead} and may be -deleted. The set of garbage collector roots includes default user -profiles, and may be augmented with @command{guix build --root}, for -example (@pxref{Invoking guix build}). +deleted. The set of garbage collector roots (``GC roots'' for short) +includes default user profiles; by default, the symlinks under +@file{/var/guix/gcroots} represent these GC roots. New GC roots can be +added with @command{guix build --root}, for example (@pxref{Invoking +guix build}). Prior to running @code{guix gc --collect-garbage} to make space, it is often useful to remove old generations from user profiles; that way, old @@ -5534,9 +5542,17 @@ packages. @item --root=@var{file} @itemx -r @var{file} +@cindex GC roots, adding +@cindex garbage collector roots, adding Make @var{file} a symlink to the result, and register it as a garbage collector root. +Consequently, the results of this @command{guix build} invocation are +protected from garbage collection until @var{file} is removed. When +that option is omitted, build results are eligible for garbage +collection as soon as the build completes. @xref{Invoking guix gc}, for +more on GC roots. + @item --log-file Return the build log file names or URLs for the given @var{package-or-derivation}, or raise an error if build logs are @@ -6901,7 +6917,8 @@ collection, to make it ``persistent''. When this option is omitted, the environment is protected from garbage collection only for the duration of the @command{guix environment} session. This means that next time you recreate the same environment, -you could have to rebuild or re-download packages. +you could have to rebuild or re-download packages. @xref{Invoking guix +gc}, for more on GC roots. @item --expression=@var{expr} @itemx -e @var{expr} @@ -8055,7 +8072,7 @@ types.}. For the ESP, if you have one and assuming it is mkfs.fat -F32 /dev/sda2 @end example -Preferably, assign partitions a label so that you can easily and +Preferably, assign file systems a label so that you can easily and reliably refer to them in @code{file-system} declarations (@pxref{File Systems}). This is typically done using the @code{-L} option of @command{mkfs.ext4} and related commands. So, assuming the target root @@ -8080,9 +8097,9 @@ cryptsetup open --type luks /dev/sda1 my-partition mkfs.ext4 -L my-root /dev/mapper/my-partition @end example -Once that is done, mount the target root partition under @file{/mnt} +Once that is done, mount the target file system under @file{/mnt} with a command like (again, assuming @code{my-root} is the label of the -root partition): +root file system): @example mount LABEL=my-root /mnt @@ -9308,6 +9325,7 @@ declaration. * Database Services:: SQL databases, key-value stores, etc. * Mail Services:: IMAP, POP3, SMTP, and all that. * Messaging Services:: Messaging services. +* Telephony Services:: Telephony services. * Monitoring Services:: Monitoring services. * Kerberos Services:: Kerberos services. * Web Services:: Web servers. @@ -9812,9 +9830,6 @@ List of extra command-line options for @command{guix-daemon}. File where @command{guix-daemon}'s standard output and standard error are written. -@item @code{lsof} (default: @var{lsof}) -The lsof package to use. - @item @code{http-proxy} (default: @code{#f}) The HTTP proxy used for downloading fixed-output derivations and substitutes. @@ -14189,6 +14204,212 @@ string, you could instantiate a prosody service like this: (prosody.cfg.lua ""))) @end example + +@node Telephony Services +@subsubsection Telephony Services + +@cindex Murmur (VoIP server) +@cindex VoIP server +This section describes how to set up and run a Murmur server. Murmur is +the server of the @uref{https://mumble.info, Mumble} voice-over-IP +(VoIP) suite. + +@deftp {Data Type} murmur-configuration +The service type for the Murmur server. An example configuration can +look like this: + +@example +(service murmur-service-type + (murmur-configuration + (welcome-text + "Welcome to this Mumble server running on GuixSD!") + (cert-required? #t) ;disallow text password logins + (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem") + (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem"))) +@end example + +After reconfiguring your system, you can manually set the murmur @code{SuperUser} +password with the command that is printed during the activation phase. + +It is recommended to register a normal Mumble user account +and grant it admin or moderator rights. +You can use the @code{mumble} client to +login as new normal user, register yourself, and log out. +For the next step login with the name @code{SuperUser} use +the @code{SuperUser} password that you set previously, +and grant your newly registered mumble user administrator or moderator +rights and create some channels. + +Available @code{murmur-configuration} fields are: + +@table @asis +@item @code{package} (default: @code{mumble}) +Package that contains @code{bin/murmurd}. + +@item @code{user} (default: @code{"murmur"}) +User who will run the Murmur server. + +@item @code{group} (default: @code{"murmur"}) +Group of the user who will run the murmur server. + +@item @code{port} (default: @code{64738}) +Port on which the server will listen. + +@item @code{welcome-text} (default: @code{""}) +Welcome text sent to clients when they connect. + +@item @code{server-password} (default: @code{""}) +Password the clients have to enter in order to connect. + +@item @code{max-users} (default: @code{100}) +Maximum of users that can be connected to the server at once. + +@item @code{max-user-bandwidth} (default: @code{#f}) +Maximum voice traffic a user can send per second. + +@item @code{database-file} (default: @code{"/var/lib/murmur/db.sqlite"}) +File name of the sqlite database. +The service's user will become the owner of the directory. + +@item @code{log-file} (default: @code{"/var/log/murmur/murmur.log"}) +File name of the log file. +The service's user will become the owner of the directory. + +@item @code{autoban-attempts} (default: @code{10}) +Maximum number of logins a user can make in @code{autoban-timeframe} +without getting auto banned for @code{autoban-time}. + +@item @code{autoban-timeframe} (default: @code{120}) +Timeframe for autoban in seconds. + +@item @code{autoban-time} (default: @code{300}) +Amount of time in seconds for which a client gets banned +when violating the autoban limits. + +@item @code{opus-threshold} (default: @code{100}) +Percentage of clients that need to support opus +before switching over to opus audio codec. + +@item @code{channel-nesting-limit} (default: @code{10}) +How deep channels can be nested at maximum. + +@item @code{channelname-regex} (default: @code{#f}) +A string in from of a Qt regular expression that channel names must conform to. + +@item @code{username-regex} (default: @code{#f}) +A string in from of a Qt regular expression that user names must conform to. + +@item @code{text-message-length} (default: @code{5000}) +Maximum size in bytes that a user can send in one text chat message. + +@item @code{image-message-length} (default: @code{(* 128 1024)}) +Maximum size in bytes that a user can send in one image message. + +@item @code{cert-required?} (default: @code{#f}) +If it is set to @code{#t} clients that use weak password authentification +will not be accepted. Users must have completed the certificate wizard to join. + +@item @code{remember-channel?} (defualt @code{#f}) +Should murmur remember the last channel each user was in when they disconnected +and put them into the remembered channel when they rejoin. + +@item @code{allow-html?} (default: @code{#f}) +Should html be allowed in text messages, user comments, and channel descriptions. + +@item @code{allow-ping?} (default: @code{#f}) +Setting to true exposes the current user count, the maximum user count, and +the server's maximum bandwidth per client to unauthenticated users. In the +Mumble client, this information is shown in the Connect dialog. + +Disabling this setting will prevent public listing of the server. + +@item @code{bonjour?} (default: @code{#f}) +Should the server advertise itself in the local network through the bonjour protocol. + +@item @code{send-version?} (default: @code{#f}) +Should the murmur server version be exposed in ping requests. + +@item @code{log-days} (default: @code{31}) +Murmur also stores logs in the database, which are accessible via RPC. +The default is 31 days of months, but you can set this setting to 0 to keep logs forever, +or -1 to disable logging to the database. + +@item @code{obfuscate-ips?} (default @code{#t}) +Should logged ips be obfuscated to protect the privacy of users. + +@item @code{ssl-cert} (default: @code{#f}) +File name of the SSL/TLS certificate used for encrypted connections. + +@example +(ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem") +@end example +@item @code{ssl-key} (default: @code{#f}) +Filepath to the ssl private key used for encrypted connections. +@example +(ssl-key "/etc/letsencrypt/live/example.com/privkey.pem") +@end example + +@item @code{ssl-dh-params} (default: @code{#f}) +File name of a PEM-encoded file with Diffie-Hellman parameters +for the SSL/TLS encryption. Alternatively you set it to +@code{"@@ffdhe2048"}, @code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"} +or @code{"@@ffdhe8192"} to use bundled parameters from RFC 7919. + +@item @code{ssl-ciphers} (default: @code{#f}) +The @code{ssl-ciphers} option chooses the cipher suites to make available for use +in SSL/TLS. + +This option is specified using +@uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT, +OpenSSL cipher list notation}. + +It is recommended that you try your cipher string using 'openssl ciphers <string>' +before setting it here, to get a feel for which cipher suites you will get. +After setting this option, it is recommend that you inspect your Murmur log +to ensure that Murmur is using the cipher suites that you expected it to. + +Note: Changing this option may impact the backwards compatibility of your +Murmur server, and can remove the ability for older Mumble clients to be able +to connect to it. + +@item @code{public-registration} (default: @code{#f}) +Must be a @code{<murmur-public-registration-configuration>} record or @code{#f}. + +You can optionally register your server in the public server list that the +@code{mumble} client shows on startup. +You cannot register your server if you have set a @code{server-password}, +or set @code{allow-ping} to @code{#f}. + +It might take a few hours until it shows up in the public list. + +@item @code{file} (default: @code{#f}) +Optional alternative override for this configuration. +@end table +@end deftp + +@deftp {Data Type} murmur-public-registration-configuration +Configuration for public registration of a murmur service. + +@table @asis +@item @code{name} +This is a display name for your server. Not to be confused with the hostname. + +@item @code{password} +A password to identify your registration. +Subsequent updates will need the same password. Don't lose your password. + +@item @code{url} +This should be a @code{http://} or @code{https://} link to your web +site. + +@item @code{hostname} (default: @code{#f}) +By default your server will be listed by its IP address. +If it is set your server will be linked by this host name instead. +@end table +@end deftp + + + @node Monitoring Services @subsubsection Monitoring Services |