InstallGuide c2sConfiguration
Go up: ParentWiki
The c2s.xml file configures the client-to-server Jabberd component. The c2s component handles communications with Jabber clients, and the settings in c2s.xml are primarily concerned with client communication:
- PID File
- Communication with the Router
- Logging
- Network Configuration
- Input/Output Control
- Client Authentication and Registration
- Authentication Encryption
Below is an overview of the settings in the c2s.xml file.
The pid section specifies the location of the PID file. This section may be commented if a PID file is not needed.
The router section controls communication with the router component. The default ip and port should be fine for most installations, although note that if c2s is running on a separate server, an external IP address would be specified here.
The user and pass sub-sections specify the user name for connecting to the router. These must match against a pair specified in router-users.xml as explained in Section 9. Basic security procedures dictate that the default password should be changed for production systems.
The pemfile section specifies the certificate and private key to be used for communication with the router. See Section 6.3 and Appendix: Generating A Self-Signed SSL Key for more information about setting up SSL on Jabberd. Commenting this section has the effect of disabling SSL communication between c2s and router.
The retry section specifies how c2s should try to reconnect to the router if the connection cannot be established during startup or if the connection is lost during operation. The default settings prevent c2s from indefinitely attempting to reconnect if this connection cannot be made. These default settings will essentially cause c2s to die if the router dies or is killed.
Jabberd logging defaults to the syslog. If you prefer c2s to write its own log file, change the log type to file, and specify a location for the log.
The local section specifies network configuration for c2s. For most installations, the id should be the same as the ID specified in sm.xml. The realm attribute can be used in cases where multiple jabber servers are relying on the same authentication database. This might be the case for a large company with several Jabber servers that authenticate via LDAP. The default IP address and port should be fine for most installations (the 0.0.0.0 setting allows c2s to listen on all available IP addresses).
The pemfile sub-section of the local section specifies the certificate and private key to be used for client communications. See Section 5.2 and Appendix: Generating A Self-Signed SSL Key for more information about setting up SSL on Jabberd. Commenting this section has the effect of disabling SSL communication between Jabberd and clients. Note that this key pair does not need to be the same key pair used for internal Jabberd communications.
The i/o section controls the following input/output options:
- Connection Limiting
- Rate Limiting
- IP Access Control
Note that the default settings for these subsections should be fine for most installations.
Jabberd sets a limit on the number of connections via the max_fds (maximum file descriptors) setting. Jabberd uses a file descriptor for each connection. Thus, setting a maximum number of file descriptors for c2s has the effect of limiting the number of concurrent client connections for the Jabberd server. As the c2s.xml file notes, c2s itself can use up to 5 connections (with other Jabberd components); therefore, the maximum number of file descriptors set here is actually slightly greater than the number of potential concurrent connections.
The limits subsection dictates throttling for individual connections. This section is tantamount to a simplified karma setup as found in Jabberd 1.4. The default for both bytes and connects is 0. Thus, these limits are disabled by default. Administrators of servers under heavy load may wish to set limits here to prevent users from controlling excessive server resources. The c2s.xml file contains examples for setting rate limiting on connections.
The access subsection specifies IP addresses that should be allowed or denied access to c2s. IP addresses denied access to c2s cannot have their packets handled and are thus denied access to Jabberd server functions.
The order subsection specifies the order of rule checking (checking of allow rules then deny rules versus checking of deny rules then allow rules). IP restrictions are set using either an allow or a deny tag below the order within the access subsection. Omission of both a deny and allow rule causes all connections to be accepted — as is the default setting.
The check section handles checking of connections with other Jabber clients. By default, these checks are disabled (interval is set to 0). To enable checking, set an interval in seconds, and then set intervals for queue expiry, invalid route expiry and/or keep alives.
The authreg section controls aspects of client authentication and registration:
- Authentication Package
- Public Registration
- Password Change
- Authentication Mechanisms
- Authentication Package Configuration
These sub-sections are described below.
The module subsection specifies the authentication data package to use. Jabberd sets this module during build according to your configuration choice, and so you should not need to edit this unless you change the authentication data package after installing Jabberd.
The enable subsection of register controls whether registration is publicly open for new users. Public registration is enabled by default. Comment the enable tag to disable public registration.
The password subsection of register specifies whether users can change their own passwords. Password change is disabled by default. As c2s.xml notes, it may be useful to enable password change if public user registration is disabled.
The mechanisms sub-section specifies which authentication encryption methods will be offered to clients. As c2s.xml notes, you should comment out any mechanisms that you do not want to offer.
The last sub-section of authreg controls connectivity with your authentication data package. The default settings should be fine for most installations unless your authentication data package is running on a separate server.
- '''path''': the absolute path where the authreg_*.so files are, default is $PREFIX/lib/jabberd. Example: <path>/usr/local/lib/jabberd</path>
- '''module''': the authentication module to use. default is 'mysql'. Available choices as of jabberd-2.1.19 are '''mysql''' (for a MySQL database), '''pgsql''' (for a PostgreSQL database), '''oracle''' (for an Oracle database), '''sqlite''' (for an SQLite integrated databse), '''db''' (for a Berkeley DB (bdb) database), '''ldap''' (for an LDAP directory such as OpenLDAP, ActiveDirectory, eDirectory etc...), or '''pipe''' (executes a given program to check authentication through a unix pipe)
- '''mechanisms''': what auth mechanisms to expose to the client over an unencrypted connection (what works also depends on what your chosen backend module supports) - '''traditional''': (todo: explain diff with SASL?) - '''<plain/>''' sends password in clear text (dangerous over an unencrypted channel) - '''<digest/>''' sends a hash of the password - '''sasl''': - '''<plain/>''' sends password in clear text (dangerous over an unencrypted channel) - '''<digest-md5/>''' sends an MD5 hash of the password - '''<anonymous/>''' allows anonymous auth (what support does Jabberd have of this?)
- '''ssl-mechanisms''': like previous section, but over an encrypted connection
- '''mysql''': configuration parameters for a MySQL backend. - TODO
- '''pgsql''': configuration parameters for a PostgreSQL backend. - TODO
- '''oracle''': configuration parameters for an Oracle backend. - TODO
- '''sqlite''': configuration parameters for an SQLitebackend. - TODO
- '''db''': configuration parameters for a Berkeley DB (bdb) backend. - TODO - '''pipe''': configuration for a unix pipe backend. - '''exec''': which program to launch to check authentication. Example: /usr/local/bin/pipe-auth.pl
- '''ldap''': configuration parameters for a LDAP directory backend. It is assumed you know the vocabulary of an LDAP server (such as 'DN', 'bind'...) - '''host''': the hostname on your network of the LDAP directory - '''port''': which port to connect to. Default is 389 for unencrypted or TLS, 636 for SSL - '''<v3/>''': enables use of the LDAP-v3 protocol. Enable this if you can, most LDAP directories handle it. - '''<starttls/>''': whether to use startTLS encryption mechanism (starts encyption on the standard unencrypted port). This is preferred over SSL, which uses a dedicated port. - '''<ssl/>''': whether to use standard SSL encyption mechanism (most LDAP servers do this on the 636 port, rather than the standard 389 port) - '''binddn''': some LDAP servers are configured such that you need to login to the server before making a search. If yours does this, put the DN here, and the password in '''bindpw''' - '''bindpw''': some LDAP servers are configured such that you need to login to the server before making a search. If yours does this, put the password here, and the DN to bind as in '''binddn''' - '''uidattr''': which LDAP attribute to search for the username in. The username is the part before '@' in the JID (wishlist: this is a basic configuration of search. Let the user specify a more complex filter) - '''<append-realm/>''': will append the user's realm (part after and including '@' in the JID) to the username before searching in LDAP. (wishlist: this is a basic configuration of search. Let the user specify a more complex filter) - '''basedn''': the base DN in the LDAP server to search in (example: dc=company,dc=com). You may specify a DN for each realm your server manages by adding the '''realm="yourrealm"''' attribute to the basedn XML element.
© 2003 Will Kamishlian and Robert Norris
Image(http://jabberd.jabberstudio.org/2/docs/ccommons.gif, right)This work is licensed under the Creative Commons Attribution-!NonCommercial-!ShareAlike License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/1.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
