summary refs log tree commit diff
path: root/doc
diff options
context:
space:
mode:
authorClément Lassieur <clement@lassieur.org>2017-01-08 20:08:14 +0100
committerLudovic Courtès <ludo@gnu.org>2017-01-08 23:39:36 +0100
commit78cef99b9812f1bb43708f84d316d286a1599bdf (patch)
treed052bd6cb2cc3999b1c376c6a15bbecc8a114e87 /doc
parent84bf2a2e74b3f40e150554d0f8d3bce1986b8089 (diff)
downloadguix-78cef99b9812f1bb43708f84d316d286a1599bdf.tar.gz
gnu: Add Prosody service.
* gnu/services/messaging.scm: New file.
* gnu/services/configuration.scm: New exported procedures.
* gnu/local.mk (GNU_SYSTEM_MODULES): Add gnu/services/messaging.scm.
* doc/guix.texi (Messaging Services): New section.

Signed-off-by: Ludovic Courtès <ludo@gnu.org>
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi393
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