README

Welcome to the Multi-User Conferencing component for Jabber.
------------------------------------------------------------

Introduction:
---

This is based on the existing conference component, now designed
to support XEP-0045 (http://www.xmpp.org/extensions/xep-0045.html)

The currently existing components are conference v0.4 and conference-v2.
These both implement the GroupChat protocol (gc-1.0) and a test
conferencing protocol which never really was adopted. The aim of the XEP
and this project was to take the gc-1.0 protocol and extend it to become
a more flexible and featureful conferencing system, superceeding the
implementations that came before.

Thanks to Peter Saint-Andre for getting this cleanup done.
Thanks to Alexey Shchepin for the support in tkabber during development
Thanks to Paul Curtis for debug help, the JCR runtime and running the alpha copy for testing
Thanks to Peter Millard for help debugging whilst adding support in Exodus

Requirements:
---

* You will need a copy of libglib-2, expat and libidn11 installed, along with the development package (for packaged based solutions, such as Debian, Mandrake and RedHat)
* You will also need pkg-config


New Features:
---
Note: This is not an exhaustive list. For a complete overview of the feature
      set, check out the XEP link given in the introduction

* Backward compatibility with gc-1.0
* User 'levels' (known as roles and affiliations)
* Native Room logging
* Dynamic room configuration
* Moderated rooms
* Password protected rooms
* Non-anonymous rooms
* Member-only rooms
* Room bans
* "Kick" user
* Persistant reconfigurable rooms

Comments:
---

Unlike the original conference component, rooms can now be dynamically set public or private.

* A Public room is a room which can be found by anyone browsing the conference component.

* A Private room is a room which can only be browsed for by a user already in the room. 

Installation:
---

Unpack it and type 'make' to build the mu-conference binary.


Configuration:
---

[Note: if you want this service to be accessible from other servers,
       change any 'conference.localhost' listed below to a fully
       qualified domain name!]


* Enable your Jabber server to advertise the service to your users.

  On jabberd14 server it is done by adding the following line in the browse section of the jsm :

  -----8<-----8<-----8<-----8<-----8<-----8<-----8<-----8<-----8<-----8<-----
  <item category="conference" type="public" jid="conference.localhost" name="Public Conferencing">
    <ns>http://jabber.org/protocol/muc</ns>
  </item>
  -----8<-----8<-----8<-----8<-----8<-----8<-----8<-----8<-----8<-----8<-----

  On jabberd2 server, there's nothing to do here.

* Authorize the service to connect to the Jabber server.

  On jabberd14, this is done by adding the following section in the jabber.xml file:

  ---8<-----8<-----8<-----8<-----8<-----8<-----8<-----8<-----8<-----8<-----
  <service id="muclinker">
    <host>conference.localhost</host>
    <accept>
      <ip>127.0.0.1</ip>
      <port>31518</port>
      <secret>secret</secret>
    </accept>
  </service>
  ---8<-----8<-----8<-----8<-----8<-----8<-----8<-----8<-----8<-----8<-----
  * Change the port and secret to your own preferences.

  On Jabberd2, you don't have to do anything, the default port to use is 5347, you must just set the <secret/> in the file router.xml

* Copy the file muc-default.xml to muc.xml
* Edit muc.xml, and ensure that the settings are the same as you defined in your jabber server configuration

Settings:
---
Global Settings:

* The <public/> tag makes all rooms default to Public when first created.
  Simply remove this tag for rooms to default to Private

* The <history> tag specifies the maximum number of lines to be held as a room
  history.

* The <logdir> tag specifies the direction in which log files will be stored. 
  The directory must exist, and will default to the current working directory.

* The <defaults/> tag makes a room have defaults set up automatically, so the
  the room creator doesn't have to submit the configuration form to unlock 
  the room.

* The <roomlock/> tag stops users from creating any new rooms. Only persistent
  rooms will be created on startup. Note: the service admin (sadmin) is 
  unaffected by this directive. This flag overrides the <defaults/> flag, if
  set.

* The <dynamic/> tag specifies that no persistent rooms can be created. Rooms
  will exist only as long as there is at least one user in the room. Once a 
  room is empty, the room will be destroyed after approximately 5 minutes.

* The <persistent/> tag specifies that persistent rooms will be created 
  rather than dynamic ones. This flag will override the <dynamic/> flag, if 
  set.

* The <sadmin> tag specifies users who are considered an owner of all rooms. 
  You can specify multiple <user> tags. Each <user> tag must contain the bare
  jid of the user.

* The <locknicks/> tag enforces that a user must use the name part of their 
  jid as their nick.

Notice Settings:

* The <join> tag specifies the message shown when someone enters a room
* The <leave> tag specifies the message shown when someone leaves a room
* The <rename> tag specifies the message shown when someone changes their nick

Note: All persistant rooms are now stored when created. This replaces the old system
of configuring persistant rooms in the jabber.xml file

Starting:
---

o Start the mu-conference process, with the command:
   src/mu-conference -c muc.xml &

---