diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix.texi | 393 |
1 files changed, 392 insertions, 1 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index e52382e976..d46a7743d0 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -29,7 +29,8 @@ Copyright @copyright{} 2016 John Darrington@* Copyright @copyright{} 2016 ng0@* Copyright @copyright{} 2016 Jan Nieuwenhuizen@* Copyright @copyright{} 2016 Julien Lepiller@* -Copyright @copyright{} 2016 Alex ter Weele +Copyright @copyright{} 2016 Alex ter Weele@* +Copyright @copyright{} 2017 Clément Lassieur Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -204,6 +205,7 @@ Services * Desktop Services:: D-Bus and desktop services. * Database Services:: SQL databases. * Mail Services:: IMAP, POP3, SMTP, and all that. +* Messaging Services:: Messaging services. * Kerberos Services:: Kerberos services. * Web Services:: Web servers. * Network File System:: NFS related services. @@ -8110,6 +8112,7 @@ declaration. * Desktop Services:: D-Bus and desktop services. * Database Services:: SQL databases. * Mail Services:: IMAP, POP3, SMTP, and all that. +* Messaging Services:: Messaging services. * Kerberos Services:: Kerberos services. * Web Services:: Web servers. * Network File System:: NFS related services. @@ -11724,6 +11727,394 @@ remote servers. Run @command{man smtpd.conf} for more information. @end table @end deftp +@node Messaging Services +@subsubsection Messaging Services + +@cindex messaging +@cindex jabber +@cindex XMPP +The @code{(gnu services messaging)} module provides Guix service +definitions for messaging services: currently only Prosody is supported. + +@subsubheading Prosody Service + +@deffn {Scheme Variable} prosody-service-type +This is the type for the @uref{http://prosody.im, Prosody XMPP +communication server}. Its value must be a @code{prosody-configuration} +record as in this example: + +@example +(service prosody-service-type + (prosody-configuration + (modules-enabled (cons "groups" %default-modules-enabled)) + (int-components + (list + (int-component-configuration + (hostname "conference.example.net") + (plugin "muc") + (mod-muc (mod-muc-configuration))))) + (virtualhosts + (list + (virtualhost-configuration + (domain "example.net")))))) +@end example + +See below for details about @code{prosody-configuration}. + +@end deffn + +By default, Prosody does not need much configuration. Only one +@code{virtualhosts} field is needed: it specifies the domain you wish +Prosody to serve. + +Prosodyctl will help you generate X.509 certificates and keys: + +@example +prosodyctl cert request example.net +@end example + +The available configuration parameters follow. Each parameter +definition is preceded by its type; for example, @samp{string-list foo} +indicates that the @code{foo} parameter should be specified as a list of +strings. Types starting with @code{maybe-} denote parameters that won't +show up in @code{prosody.cfg.lua} when their value is @code{'disabled}. + +There is also a way to specify the configuration as a string, if you +have an old @code{prosody.cfg.lua} file that you want to port over from +some other system; see the end for more details. + +@c The following documentation was initially generated by +@c (generate-documentation) in (gnu services messaging). Manually maintained +@c documentation is better, so we shouldn't hesitate to edit below as +@c needed. However if the change you want to make to this documentation +@c can be done in an automated way, it's probably easier to change +@c (generate-documentation) than to make it below and have to deal with +@c the churn as Prosody updates. + +Available @code{prosody-configuration} fields are: + +@deftypevr {@code{prosody-configuration} parameter} package prosody +The Prosody package. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} file-name data-path +Location of the Prosody data storage directory. See +@url{http://prosody.im/doc/configure}. +Defaults to @samp{"/var/lib/prosody"}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} file-name-list plugin-paths +Additional plugin directories. They are searched in all the specified +paths in order. See @url{http://prosody.im/doc/plugins_directory}. +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string-list admins +This is a list of accounts that are admins for the server. Note that you +must create the accounts separately. See @url{http://prosody.im/doc/admins} and +@url{http://prosody.im/doc/creating_accounts}. +Example: @code{(admins '("user1@@example.com" "user2@@example.net"))} +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} boolean use-libevent? +Enable use of libevent for better performance under high load. See +@url{http://prosody.im/doc/libevent}. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled +This is the list of modules Prosody will load on startup. It looks for +@code{mod_modulename.lua} in the plugins folder, so make sure that exists too. +Documentation on modules can be found at: @url{http://prosody.im/doc/modules}. +Defaults to @samp{%default-modules-enabled}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled +@samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but +should you want to disable them then add them to this list. +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} file-name groups-file +Path to a text file where the shared groups are defined. If this path is +empty then @samp{mod_groups} does nothing. See +@url{http://prosody.im/doc/modules/mod_groups}. +Defaults to @samp{"/var/lib/prosody/sharedgroups.txt"}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} boolean allow-registration? +Disable account creation by default, for security. See +@url{http://prosody.im/doc/creating_accounts}. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl +These are the SSL/TLS-related settings. Most of them are disabled so to +use Prosody's defaults. If you do not completely understand these options, do +not add them to your config, it is easy to lower the security of your server +using them. See @url{http://prosody.im/doc/advanced_ssl_config}. + +Available @code{ssl-configuration} fields are: + +@deftypevr {@code{ssl-configuration} parameter} maybe-string protocol +This determines what handshake to use. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} file-name key +Path to your private key file, relative to @code{/etc/prosody}. +Defaults to @samp{"/etc/prosody/certs/key.pem"}. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} file-name certificate +Path to your certificate file, relative to @code{/etc/prosody}. +Defaults to @samp{"/etc/prosody/certs/cert.pem"}. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} file-name capath +Path to directory containing root certificates that you wish Prosody to +trust when verifying the certificates of remote servers. +Defaults to @samp{"/etc/ssl/certs"}. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-file-name cafile +Path to a file containing root certificates that you wish Prosody to trust. +Similar to @code{capath} but with all certificates concatenated together. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify +A list of verification options (these mostly map to OpenSSL's +@code{set_verify()} flags). +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-string-list options +A list of general options relating to SSL/TLS. These map to OpenSSL's +@code{set_options()}. For a full list of options available in LuaSec, see the +LuaSec source. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth +How long a chain of certificate authorities to check when looking for a +trusted root certificate. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers +An OpenSSL cipher string. This selects what ciphers Prosody will offer to +clients, and in what order. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam +A path to a file containing parameters for Diffie-Hellman key exchange. You +can create such a file with: +@code{openssl dhparam -out /etc/prosody/certs/dh-2048.pem 2048} +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-string curve +Curve for Elliptic curve Diffie-Hellman. Prosody's default is +@samp{"secp384r1"}. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext +A list of "extra" verification options. +@end deftypevr + +@deftypevr {@code{ssl-configuration} parameter} maybe-string password +Password for encrypted private keys. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption? +Whether to force all client-to-server connections to be encrypted or not. +See @url{http://prosody.im/doc/modules/mod_tls}. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption? +Whether to force all server-to-server connections to be encrypted or not. +See @url{http://prosody.im/doc/modules/mod_tls}. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth? +Whether to require encryption and certificate authentication. This +provides ideal security, but requires servers you communicate with to support +encryption AND present valid, trusted certificates. See +@url{http://prosody.im/doc/s2s#security}. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains +Many servers don't support encryption or have invalid or self-signed +certificates. You can list domains here that will not be required to +authenticate using certificates. They will be authenticated using DNS. See +@url{http://prosody.im/doc/s2s#security}. +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains +Even if you leave @code{s2s-secure-auth?} disabled, you can still require +valid certificates for some domains by specifying a list here. See +@url{http://prosody.im/doc/s2s#security}. +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string authentication +Select the authentication backend to use. The default provider stores +passwords in plaintext and uses Prosody's configured data storage to store the +authentication data. If you do not trust your server please see +@url{http://prosody.im/doc/modules/mod_auth_internal_hashed} for information +about using the hashed backend. See also +@url{http://prosody.im/doc/authentication} +Defaults to @samp{"internal_plain"}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} maybe-string log +Set logging options. Advanced logging configuration is not yet supported +by the GuixSD Prosody Service. See @url{http://prosody.im/doc/logging}. +Defaults to @samp{"*syslog"}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} file-name pidfile +File to write pid in. See @url{http://prosody.im/doc/modules/mod_posix}. +Defaults to @samp{"/var/run/prosody/prosody.pid"}. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts +A host in Prosody is a domain on which user accounts can be created. For +example if you want your users to have addresses like +@samp{"john.smith@@example.com"} then you need to add a host +@samp{"example.com"}. All options in this list will apply only to this host. + +Note: the name "virtual" host is used in configuration to avoid confusion with +the actual physical host that Prosody is installed on. A single Prosody +instance can serve many domains, each one defined as a VirtualHost entry in +Prosody's configuration. Conversely a server that hosts a single domain would +have just one VirtualHost entry. + +See @url{http://prosody.im/doc/configure#virtual_host_settings}. + +Available @code{virtualhost-configuration} fields are: + +all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, plus: +@deftypevr {@code{virtualhost-configuration} parameter} string domain +Domain you wish Prosody to serve. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-components +Components are extra services on a server which are available to clients, +usually on a subdomain of the main server (such as +@samp{"mycomponent.example.com"}). Example components might be chatroom +servers, user directories, or gateways to other protocols. + +Internal components are implemented with Prosody-specific plugins. To add an +internal component, you simply fill the hostname field, and the plugin you wish +to use for the component. + +See @url{http://prosody.im/doc/components}. +Defaults to @samp{()}. + +Available @code{int-component-configuration} fields are: + +all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, plus: +@deftypevr {@code{int-component-configuration} parameter} string hostname +Hostname of the component. +@end deftypevr + +@deftypevr {@code{int-component-configuration} parameter} string plugin +Plugin you wish to use for the component. +@end deftypevr + +@deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-muc +Multi-user chat (MUC) is Prosody's module for allowing you to create +hosted chatrooms/conferences for XMPP users. + +General information on setting up and using multi-user chatrooms can be found +in the "Chatrooms" documentation (@url{http://prosody.im/doc/chatrooms}), +which you should read if you are new to XMPP chatrooms. + +See also @url{http://prosody.im/doc/modules/mod_muc}. + +Available @code{mod-muc-configuration} fields are: + +@deftypevr {@code{mod-muc-configuration} parameter} string name +The name to return in service discovery responses. +Defaults to @samp{"Prosody Chatrooms"}. +@end deftypevr + +@deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation +If @samp{#t}, this will only allow admins to create new chatrooms. +Otherwise anyone can create a room. The value @samp{"local"} restricts room +creation to users on the service's parent domain. E.g. @samp{user@@example.com} +can create rooms on @samp{rooms.example.com}. The value @samp{"admin"} +restricts to service administrators only. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messages +Maximum number of history messages that will be sent to the member that has +just joined the room. +Defaults to @samp{20}. +@end deftypevr + +@end deftypevr + +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-components +External components use XEP-0114, which most standalone components +support. To add an external component, you simply fill the hostname field. See +@url{http://prosody.im/doc/components}. +Defaults to @samp{()}. + +Available @code{ext-component-configuration} fields are: + +all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, plus: +@deftypevr {@code{ext-component-configuration} parameter} string component-secret +Password which the component will use to log in. +@end deftypevr + +@deftypevr {@code{ext-component-configuration} parameter} string hostname +Hostname of the component. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports +Port(s) Prosody listens on for component connections. +@end deftypevr + +@deftypevr {@code{prosody-configuration} parameter} string component-interface +Interface Prosody listens on for component connections. +Defaults to @samp{"127.0.0.1"}. +@end deftypevr + +It could be that you just want to get a @code{prosody.cfg.lua} +up and running. In that case, you can pass an +@code{opaque-prosody-configuration} record as the value of +@code{prosody-service-type}. As its name indicates, an opaque configuration +does not have easy reflective capabilities. +Available @code{opaque-prosody-configuration} fields are: + +@deftypevr {@code{opaque-prosody-configuration} parameter} package prosody +The prosody package. +@end deftypevr + +@deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua +The contents of the @code{prosody.cfg.lua} to use. +@end deftypevr + +For example, if your @code{prosody.cfg.lua} is just the empty +string, you could instantiate a prosody service like this: + +@example +(service prosody-service-type + (opaque-prosody-configuration + (prosody.cfg.lua ""))) +@end example + @node Kerberos Services @subsubsection Kerberos Services @cindex Kerberos |