readme.config

jabber server jabber server jabber server jabber server

The Jabberd Config file(s) are broken up by "instances".  A jabberd instance determines what to do with packets of a certain type, and to a certain hostname.

There are 3 main instance types, log, service, and xdb.  log instance handle logging packets, i.e. whether to log to a file, or copy the logs to a jid.  service instances handle the standard jabber protocol packets (message,presence and iq).  and xdb instances handle xdb packets, or requests to get data from a persistant storage device.

Each instance has to have a <host/> tag in it, defining the hostname for that instance. There can be more than one <host/> tags, or there can be a single empty <host/> tag, to signify that that instance recives packets for ALL the hostnames.

------------------

The Jabberd config file is a powerfull tool for describing your jabber server.  It can be very simple, consisting of only one main "jsm" service, or very complex, spanning mulitple config files.  The core of the jabberd server is the jsm service, and the main xdb handler.  

Take a look at a sample jsm service configuration:

  <service id="session manager">
    <host>localhost</host>

    <load main="jsm">
      <jsm>./libjabberdsm.so</jsm>
      <mod_stat>./libjabberdsm.so</mod_stat>
      <mod_echo>./libjabberdsm.so</mod_echo>
      <mod_roster>./libjabberdsm.so</mod_roster>
      <mod_time>./libjabberdsm.so</mod_time>
      <mod_last>./libjabberdsm.so</mod_last>
      <mod_version>./libjabberdsm.so</mod_version>
      <mod_announce>./libjabberdsm.so</mod_announce>
      <mod_agents>./libjabberdsm.so</mod_agents>
      <mod_browse>./libjabberdsm.so</mod_browse>
      <mod_disco>./libjabberdsm.so</mod_disco>
      <mod_admin>./libjabberdsm.so</mod_admin>
      <mod_offline>./libjabberdsm.so</mod_offline>
      <mod_presence>./libjabberdsm.so</mod_presence>
      <mod_auth_digest>./libjabberdsm.so</mod_auth_digest>
      <mod_auth_plain>./libjabberdsm.so</mod_auth_plain>
      <mod_log>./libjabberdsm.so</mod_log>
      <mod_register>./libjabberdsm.so</mod_register>
      <mod_xml>./libjabberdsm.so</mod_xml>
    </load>
    <jsm xmlns="jabberd:jsm:config">
      <agents/>
      <register/>
    </jsm>
  </service>

this section constits of the instance tag "service" to denote that it is a service instance, and it has a <host/> tag, specifying the hostname of the server.  you can have as many hostnames as you like, each will have their own userspace, i.e. for virtual domain hosting.

the <load/> section is for loading shared objects into the jabberd process.  in this case, all the server modules are loaded as well, from the same .so file.

Each section may have extra config data, that it can retrieve by a xmlns attribute.  In the case of jsm, it's xmlns is "jabberd:jsm:config".  this contains private configuration data for that module... in this case, <register/> allows users to register with the srever, and <agents/> is the server's list of agents.


--------------------

In addition to being able to load shared objects in memory, there are other ways to execute module code.

the <exec/> tag is used to execute a command line, and pass xml packets back and forth with STDIN and STDOUT.

for example:

  <service id="perl transport">
    <host>perlt.jabber.org</host>
    <exec>./perlt --host perlt.jabber.org</exec>
  </service>

this will execute the command "pert --host perlt.jabber.org" in the current directory, and pass data to the script though STDIN.

--------------------

you may also connect to a transport or listen on a port for a transport connection (as was the case for the 1.0 server) with <connect/>  and <accept/> tags.

both tags are used in a similar manner:
 

  <connect>
   <ip>12.34.56.78</ip>
   <secret>foo</secret>
   <port>5123</port>
  </connect>

--------------------

all of these tags that describe how to load/execute an instance are defined in the jabberd base modules.

the current base modules are:

Base Module       Valid Tags           Notes
--------------------------------------------------------
- (deliver.c)       <host/>         Every instance must have one or more
- (deliver.c)       <logtype/>      Filters out by log types
- (deliver.c)	    <ns/>	    Filters out by namespaces (xdb only)
- (deliver.c)	    <null/>	    Drop anything routed to this service
- (deliver.c)       <uplink/>	    Handle everything what is not handled otherwise
- (load.c)          <load/>         loads shared objects into memory
base_accept         <accept/>       listens on a socket for an xml stream
base_connect        <connect/>      connects an xml stream to a remote socket
base_dynamic
base_exec           <exec/>         executes a file and passes xml on stdin/out
base_file           <file/>         to log to a file
base_format         <format/>       changes the text of log messages...
                                    "host: %h, type: %t, date: %d, text: %s"
base_stderr         <stderr/>       Only valid in log instances
base_stdout         <stdout/>       packets get copied to stdout for this instance
base_to             <to/>           Only valid in log instances for sending to a jid
base_unsubscribe    <unsubscribe/>  Unsubscribe to received presences