3.1. Host properties changeable via Univention Management Console

Currently there's only one host property that can be changed via the Univention Management Console :-

• XMPP domain(s)^ This is a multivalued property that determines which XMPP domains this service should be responsible for. For each of these domains, the service spawns a separate instance that allows communication between all users having an XMPP ID with exactly this domain.

  This value does not affect authentication. Authentication (in this case: permission to connect at all) is always done using the UID alone, just like in all other services integrated into the UCS system.

3.2. Host properties changeable via Univention Configuration Registry

There are configuration parameters which aren't likely to be changed frequently. Those can be tweaked using the Univention Configuration Registry variables on the host itself.

You have to log on as root on the given server. Issuing the command ucr search plucs will print out all related variables, their values and a short explanation.

To ensure consistent configuration across hosts, you can create UCR policies which will be applied to multiple hosts.

• General server parameters^

  • plucs/autostart: Automatically start the ejabberd service at system startup ^ You can disable the start of the XMPP daemon here. Normally, you should not change this value because it will follow many other conditions:-

    • The XMPP Enabled setting of the host object

    • The fact that at least one XMPP domain is set for this host object

    • The autostart value of the XMPP service in the service control panel of the given host.

  • plucs/language: the language used by the XMPP daemon ^ This is the language the XMPP daemon uses when talking language dependent things to clients, such as welcome messages. The initial language was determined from the host's locale settings at install time.

  • plucs/restart/listener: allow restart of XMPP daemon by Listener/Notifier ^ With this parameter, you can control if the Listener/Notifier is allowed to restart the XMPP daemon whenever it detects changes at the corresponding host object. The default value is true , meaning that the daemon will be restarted 15 seconds after any change related to the configuration of the eJabberD daemon.

    If you have switched on the mod_filter functionality you may rethink this setting because it would restart your eJabberD on every change of permission properties of groups.

  • plucs/loglevel: the log verbosity level of the XMPP daemon ^ This log level relates to the XMPP daemon and the underlying Erlang libraries. It ranges from 0 (no output at all) to 5 (Debug). Level 3 (Info) seems to be a good starting point; later on you can lower the log level as you see fit. Refer to the EjabberD documentation for details.

  • plucs/mod/filter: switch on mod_filter functionality ^ Starting with v0.2-2, plucs comes with the possibility to restrict Presence (visibility) and Message (talk) packets based on group membership of any given user. This setting allows switching this feature on and off. Default is 'off', just to keep backwards compatibility. Read more about this feature in Section 4.2.2.

• Client-related parameters^

  • plucs/certfile: certificate file to be presented to clients ^ The certificate file being used here is converted from the host certificate which was automatically generated and deployed while joining the UCS domain. If you want to provide a different certificate here it must adhere to the requirements of the XMPP daemon: it is required in PEM format, with the private key and the certificate in one file.

  • plucs/tls: announce TLS availability to clients ^ With this parameter set to true, the XMPP daemon will announce TLS (Transport Level Security) availability to clients.

    Starting with plucs 0.2-1, besides the boolean 'true' and 'false' values, this parameter is now allowed to have the value 'required' which will enforce the use of STARTTLS by any clients.

• LDAP directory-related parameters ^

  • plucs/ldap/port: the port used to issue LDAP queries ^ We don't have to specify the host name, because the LDAP host is already known to any member server, and will be updated accordingly when server roles change. Note: Using the default LDAP ports (389 and 636) is not safe, especially if you intend to install Samba 4 as replacement for a Windows Domain Controller.

  • plucs/ldap/tls: controls whether or not TLS is used for LDAP queries ^ Regardless of this setting, LDAP queries are always done using an authenticated bind via the credentials of the machine account. This setting is intended to provide an additional layer of security. Note: The underlying Erlang libraries aren't able to use the STARTTLS feature to switch a plain text channel to TLS. This is why you need to specify a LDAP port which initially listens in TLS mode (636 or 7636).

  • plucs/userlabel: the 'display name' property of users ^ With this parameter, you can define which LDAP property of the user objects will be used by the XMPP server whenever it displays a user name. Important is to ensure the given property is set. Note: User objects without that property will be displayed nevertheless; you can't control how any given client will display such users.

  • plucs/grouplabel: the 'display name' property of groups ^ With this parameter, you set the LDAP property of group objects which will be used to display the names of XMPP groups. Groups without this property won't appear in XMPP client rosters; clients usually choose a fallback group ( Ungrouped etc.) to display members of such groups, as if the users don't belong to any group at all.

• Parameters to control the HTTP request handler^ The HTTP request handler of the EJabberD daemon is a generic HTTP server listening at port 5280 of your host. Refer to the XMPP wiki for a description. Our integration only uses the functionality of tunneling BOSH requests (see the XMPP documentation for details).

  The request handler is configured to listen on 127.0.0.1:5280 only. JavaScript clients must nevertheless establish their BOSH connection into the same namespace where they were loaded from (usually http://yourhost:80 or :443), so there's no point in exposing the port 5280 to the public.

  Parameters are:-

  • plucs/http/proxy: switches on HTTP proxy^ Switch on HTTP proxy in Apache configuration. This enables the /http-bind/ and /http-poll/ URLs into the normal namespace of your server. Whenever you change this setting you have to reload your Apache web server. With this parameter set to false, the HTTP request handler will be entirely invisible to the outside. The configured URLs are equally mapped into the http:// and https:// schemes, so if your client can speak BOSH over HTTPS you can make use of this.

  • plucs/http/bind: switch on http bind function^ This enables the http bind functionality of the HTTP request handler.

  • plucs/http/bind/url: define the URL base for the http bind request handler^ You can set the base URL where the http bind handler will serve requests. The URL is forced to match as an absolute URL. The default value is set to /http-bind/ just like most of the clients require. A reload of your Apache server is required when you change this parameter.

  • plucs/http/poll: switch on http poll function^ This enables the http poll functionality of the HTTP request handler.

  • plucs/http/poll/url: define the URL base for the http poll request handler^ You can set the base URL where the http poll handler will serve requests. The URL is forced to match as an absolute URL. The default value is set to /http-poll/ just like most of the clients require. A reload of your Apache server is required when you change this parameter.

• Parameters to control server-to-server (S2S) connections ^

  • plucs/s2s: enables server-to-server communication ^ This allows the communication of your server to other XMPP servers. Technically, it enables your server to listen on port 5269, the normal server-to-server communication port.

  • plucs/s2s/certfile: the certificate to use for server-to-server communication ^ Initially this is set to the same certificate file the server will use for client communications. TLS availability is always announced on S2S connections.

  • plucs/s2s/tls: deny/allow/enforce TLS usage on S2S connections^ This allows to control the usage of TLS encryption on S2S connections. Allowed values are:-

    • false:^ Don't allow or advertise TLS at all.

    • optional:^ Try TLS first, but allow fallback to unencrypted.

    • required:^ Always use TLS, refuse connections that don't offer encryption.

    • required_trusted:^ Act like required, but additionally enforce peer certificates to be known and trusted.

    To keep backwards compatibility with plucs before 0.2-1, the value 'true' continues to be valid, and will automatically be mapped to 'optional'.

    The current eJabberD version (2.1.10) does not yet understand detailed TLS options (s2s_transport_options and s2s_ciphers) as they are already implemented in the latest upstream version (14.12). At least, the current version resolves Debian Bug #724992 which forbids SSL v2.

3.3. Additional configuration

You may want to customize the configuration of your XMPP server(s) beyond the normal settings. This section covers some of the configuration areas where customization can make sense. Note that these tasks apply to any kind of XMPP service. Your first reference should always be the eJabberD documentation and the other documents found there in the doc directory.

• Use a publicly-recognized certificate ^ This can make sense if you're planning to allow Server-to-server connections, or if you intend to open your XMPP service to clients outside of your corporate network. No matter which of the certificates (client or s2s, or both) you want to replace, you always have to meet the requirements of the XMPP daemon:

  • The certificate is required to be in the PEM format .

  • The certificate is required to contain both the private key and the public certificate . If the certificate in question is not directly issued by the root CA you have to include the certificates of intermediate CAs too.

    You can also provide two files, <filename>.pem (containing one or more certificates) and <filename>.key (containing the private key). The configuration directive must refer to the PEM file in this case.

  The whole process has been described at many places over the net. As an example, please refer to the LinuxWall Wiki or this blog entry

• Support autodetection^ For client computers in your domain, you can arrange for deployment of an XMPP client on the users' desktop, along with a configuration that matches your server setup. But if you leave the choice of clients to the users you should help clients to get their configuration automatically.

  • Clients can ask the DNS server of the XMPP domain about the name or address of the host serving XMPP for that domain. This is accomplished by a so-called SRV record . The record in question should look like this:-

    _xmpp-client._tcp.yourdomain.tld. 86400 IN	SRV	5 0 5222 xmpphost.yourdomain.tld

    If the domain in question is managed by a UCS server you can easily add the corresponding service record to the DNS. Refer to the UCS documentation for details.

    Refer to the XMPP Wiki about the full amount of SRV records related to XMPP.

• Secure LDAP connections^

  • The LDAP server of an UCS domain always supports TLS in the first place as well as STARTTLS. For backwards compatibility, it keeps listening on unsecured ports, but every application issuing LDAP queries is strongly urged not to use unsecured connections, be it inside of your organization or to the outside world. Your XMPP daemon is able to use TLS (not STARTTLS), so you should set plucs/ldap/tls to true and plucs/ldap/port to 7636.

    For future compatibility, you should avoid using port 636 here because this would break your ability to install and use Samba 4 as a replacement for a Windows Domain Controller.

• Secure client connections^

  • Give your users some kind of confidence about the security. It is a good idea to ensure the domain CA certificate to be enrolled onto all client computers. That way, the users' XMPP clients should never complain about self-signed or unknown certificates on first connect.

• Open your XMPP service to the public ^ You may want to allow your XMPP server to be usable from the public internet

  • Allow clients outside of your corporate network to connect to your XMPP server: you have to establish port forwarding for TCP port 5222 at your corporate firewall. This step can be omitted if your XMPP server is already exposed (hosted publicly, or configured as exposed DMZ host).

  • Allow servers of other XMPP domains to contact your server, for cross-domain communication: you have to ensure that TCP port 5269 is reachable from the public internet.

  • Arrange for the so-called SRV records (see Service Records ) to be visible in the public DNS of your domain. If you have established port forwarding (see above) the service records have to point to the IP of your firewall.

4.1. User administration

Users have to be enabled individually for XMPP. Besides being enabled, the user must be assigned to one of the hosted XMPP domains in your organization. The current model enforces that a given user can only belong to one XMPP domain.

The XMPP domain you enter here is not validated. It means you can even assign users to a notexistant domain, and add the domain to any of your XMPP hosts later.

You have to choose which property of users is to be displayed. The installer chooses the gecos field which belongs to the POSIX account object class of users. You can change this by setting the value of the UCR variable plucs/userlabel

To ease the creation of directory objects with a predefined set of properties, Univention Corporate Server provides the concept of templates . Refer to the Manual for users and administrators for details about user templates.

---

4.1.1. Default values

To ease the daily work of the administrator, the values of XMPP enabled and XMPP domain now have sensible default values. New users created from now on will be XMPP-enabled by default, and will be assigned to the primary DNS domain. The default domain is furthermore changed whenever there's only one XMPP domain hosted in your UCS domain. As always, you can change these defaults whenever you wish:

udm settings/extended_attribute modify \
	--dn="cn=UniventionXMPP-User-Domain,cn=xmpp,cn=custom attributes,cn=univention,$ldap_base" \
	--set default='any.domain.name'

and

udm settings/extended_attribute modify \
	--dn="cn=UniventionXMPP-User-Enabled,cn=xmpp,cn=custom attributes,cn=univention,$ldap_base" \
	--set default='TRUE'

The boolean value for the 'enabled' attribute must be in uppercase, only 'TRUE' and 'FALSE' are accepted.

4.2. Group administration

4.2.1. Shared Roster

The XMPP daemon has a feature called shared roster , that can maintain groups and users to appear in the users' contact roster. This means that users don't have to manually confirm each other for inclusion into their respective roster (the so-called authorization ). You (the administrator) can assign users to groups, and therefore enable groups to appear in the roster whenever one or more group members are online.

It is necessary to choose which property of any given group is to be used as the group name . This is done by setting the UCR variable plucs/userlabel to the desired property. The default setting (set on first install of PLUCS on any given host) is the CN . If you forget to set that property for a group, the group would be presented as having no name. XMPP clients usually compensate for this by assigning a generic name, usually "Buddies" or "Ungrouped".

Some remarks to these groups:-

• The permission to use XMPP for any given user doesn't depend on a group membership. This means you can't switch off a group of users by simply disabling a group.

• Any XMPP user can be member of any number of groups. It is up to the individual user-client as to how users that are members of multiple groups are to be displayed.

• Groups in this sense can't be used to limit which users are visible to other users. The visibility scope is always the XMPP domain of the given user. If you want to restrict communication you can now use the feature mod_filter as described in Section 4.2.2.

• The eJabberD module that realizes the "shared roster" functionality has somewhat undocumented behaviour as of when it decides to reread LDAP group membership (it maintains some kind of cache), and additionally there's no definite API to notify clients about changes in group membership. So don't be too impatient when any given change will show up at the users' clients.

---

4.2.2. Restricting communication

Starting with plucs 0.2-2, plucs comes with the feature to restrict communication based on group membership. This is a slightly complicated scheme, so it deserves a separate section. The feature will be realized by a distinct module named mod_filter. Using the UCR directive plucs/mod/filter you can switch on and off this module. For backwards compatibility, the module is left switched off if you update from any earlier version.

The module can restrict four different classes of so-called stanzas which can be roughly thought of as being network packets. The current integration only restricts two of those types:-

• Message is the type of stanza that carries the pure communication, so this is what we can consider the permission to talk. Even if one can select an user from the roster (or eventually from a central directory) the other one would not even notice any talk attempts if the message permission is set to drop those packets.

• Presence is the type of stanza that causes a given user to be visible to others. Given the fact that different clients handle visibility differently, you should carefully think if you plan to set the presence permissions to something different from the message permissions. For instance, users allowed to talk but not allowed to be visible will normally be shown as being "offline" to each other. It can easily confuse users confronted with this seemingly inconsistent behaviour of their client programs.

The feature will be tied to groups. This means, any permissions given to groups apply to all of their respective members. Note that eJabberD doesn't have the notion of groups at all; the whole feature is implemented such that groups (coming from our central LDAP directory) are translated into access control lists (ACLs) that can be addressed by eJabberD as if they were groups. In LDAP (or, for that matter, in Univention Directory Manager), the following group properties are defined:-

• message-allowed groups^ This is a list of groups that this group is allowed to talk to.

• presence-allowed groups^ This is a list of groups that this group is allowed to see (receive presence information).

  Technically, the presence permission is implemented in reverse: the other groups have the permission to send presence stanzas to this group.

  Note that presence is not automatically reissused when permissions change. Some clients refresh presence periodically (and/or perhaps have a config setting to change that), some issue presence only on login/logout. So there's always a timespan where visibility does not necessarily reflect the real permissions.

  Note that even the group itself is not automatically included into the permission list, so you can even implement groups whose members aren't allowed to talk to each other.

To get a behaviour that is manageable and understandable by the Administrator, the general model is that everything is forbidden except it was explicitly allowed. This means if you switch on this feature without having set any permissions on groups, you'll end up in a situation where nobody can see anybody, and nobody can talk to anybody. If the permission scheme you want to achieve is based on different thinking there are some advanced controls that help you set a different default behaviour. These are the so-called policies that apply to every group that doesn't have any permissions set. These policies can have the following values:-

• allow means: as long as the allowed groups list for a given permission is empty the permission is granted as if ALL groups were listed there. But as soon as you insert at least one group only the listed groups are allowed for the given permission.

• deny With this setting, the permission is always only granted for groups listed, so if none are listed then it boils down to not allow anything.

Here are the UCR variables you can set:-

• plucs/mod/filter/message_policy^ This is the policy to apply for the message permission.

• plucs/mod/filter/presence_policy^ This is the policy to apply for the presence permission.

The default value for these two policies, according to the permission model mentioned above, is deny.

Note that the policy values are directly evaluated as config values in eJabberD, so if you misspell one of these keywords your eJabberD will treat this as a syntax error in a configuration file, and will most likely refuse to start.

Note that configuration is only regenerated whenever some properties of LDAP objects have changed. So if you have changed the policies you have to manually trigger the regeneration of config files:- univention-directory-listener-ctrl resync plucs-groups This will regenerate the configuration and (after the usual wait time of 15 secs) the reload of the permissions into the eJabberD server.

4.3. Client administration

It depends heavily on the overall design of your domain/organization. The list here refers you to sources of further information.

• If you're deploying the Univention Corporate Client you have some possibilities to customize the XMPP client too. Read the UCC documentation for details.

• For other deployment scenarios you have to find out yourself what applies to you. A comprehensive list of client applications can be found at the XMPP wiki .