[[ch-xmppreference]]
== XMPP Reference

XMPP is a protocol that supports both private instant messages, and group 
instant messages. The server also supports features such as roster management,
for keeping track of contacts and showing who is and is not online. Here is a 
broad overview of what the symbiosis-xmpp package supports:

 * Federation - this is where users of your XMPP server may communicate with
   users of any other correctly configured XMPP server, with their own, locally hosted account. This will
   also allow a user to connect to multiple user chats (see below) on the local server or remote
   servers, should they wish to do so. 
 * Roster (contact list) management - before receiving messages from a new 
   contact, each user must add the other to their contact list. The server will
   then remember contacts, such that they will be known on all a user's XMPP
   clients. 
 * Private messages - a user is able to speak to any of their online contacts
 * Multiple user chat (MUC) - this feature enables users to communicate in groups, 
   rather than one on one. These chats will often be named
   after the intended subject of discussion, eg "office" or "managers". If you
   wish, you can host a MUC that anyone else can connect to and use to chat.
   Think of this as being a cross between an instant message and a mailing list.
   
Symbiosis uses http://prosody.im[Prosody] as its XMPP server.

To configure your domain to start using XMPP, create the file
'config/xmpp'.
(((config/,xmpp)))

=== Adjusting the XMPP configuration

Domains' XMPP configuration is kept in
[directory]'/etc/prosody/config.d' with each domain having its own
snippet.  Feel free to edit these snippets as you see fit, as once
edited they will never get overwritten automatically.

If you do wish to restore the configuration to the default, you can
run `symbiosis-xmpp-configure --force --verbose`.

Symbiosis uses a configuration template for the XMPP server.  This is
kept in '/etc/symbiosis/xmpp.d/prosody.template.erb'.  This is the
place to adjust things for all domains running on the server.

Once you've adjusted that to your liking, you can run
`symbiosis-xmpp-configure --verbose` to apply your changes.


