Extension:XMLRC/udp2xmpp.py

  implements a bridge for recent-changes notification from UDP packets to XMPP messages as part of the XMLRC extension. It supports direct XMPP chat messages to a single user (aka Jabber) as well as posting messages to multi user chat rooms (MUC). This runs standalone as a python program, and does not interact with the web server.

Note that udp2xmpp.py can handle notifications for multiple wikis. Each recent-changes item (the XML contained in the UDP packets emitted by the XMLRC_UDP transport, see above) contains a wikiid. In the configuration, you can provide a destination (that is, a Jabbber user or a MUC room) for the notifications from each wiki.

Installation
is located in the  directory of the XMLRC extension. You can place this directory anywhere on your system. In fact, for security reasons, it is recommended to move it to a location that is not accessible from the web or by the web server.

To run udp2xmpp.py, you need python 2.5 and the xmpppy library from . Make sure python can find the library, e.g. by adjusting the PYTHONPATH environment variable.

You also need an account on an XMPP (Jabber) server for use by udp2xmpp.py. The credentials for this account then need to be entered into the configuration file for udp2xmpp, see below.

Configuration
In order to configure udp2xmpp for use with your wiki, rename  to , and    to

The configuration files uses the INI file syntax.

udp2xmpp.ini
udp2xmpp.ini contains the configuration for the bridge, and is structured into three sections:


 * [udp2xmpp] contains configuration for the bridge as such
 * wiki-info-file: the location of the  file. This may be given relative to the location of the   file. This may be overwritten by the --wiki-info command line option. If nither is given, udp2xmpp-wikis.ini will be looked for in the directory where udp2xmpp.py is located.
 * wiki-info-section: name of a wiki info section in this config file; must be the wikiid of the target wiki. If this is set, udp2xmpp-wikis.ini is ignored. This is useful if you only need a single wiki.
 * [UDP] contains configuration for receiving UDP packets
 * port: the UDP port to listen to. Default is 4455
 * interface: the IP address of the network interface to bind to. Default is 0.0.0.0, which means "all devices". Set it to 127.0.0.1 to only listen on the local loopback interface.
 * buffer-size: maximum expected size of UDP packets. This should be larger than the XML representation of any recent changes item could get, but not larger than the size the network stack can handle. Default is 8192. Increase this if you have problems with the XML getting cut off.
 * [XMPP] contains configuration for connecting to an XMPP service
 * jid: the Jabber ID (JID) to use to connect to the XMPP service, e.g. mywiki-xmlrc@jabber.example.com
 * password: the password for logging into the XMPP service. NOTE: make sure this file is not accessible via the web!

udp2xmpp-wikis.ini
udp2xmpp-wikis.ini contains configuration for each wiki that shall be handled by the bridge. The name of each section must be the wikiid of the wiki for which it applies, as reported by the web API when asked for general site info. A wiki's ID, as defined internally by wfWikiID, is generally the name of the database the wiki uses ( $wgDBname ) plus, if applicable, the table prefix, separated by a dash ( $wgDBname-$wgDBprefix ). You can find these values in you LocalSettings.php.

Each section must specify the channel and channel-type options. In addition, base-url or both of page-url and script-url have to be defined:


 * base-url: the base URL of your wiki, equivalent to $wgScriptPath. Must end with "/".
 * page-url: the URL of pages in your wiki, with $1 as a placeholder for the page name. If not given, defaults to {base-url}index.php/$1
 * script-url: the URL of the main entry point for the wiki ("ugly" URL for index.php). If not given, defaults to {base-url}index.php
 * channel-type: type of the notification channel. can be 'jabber' or 'muc'.
 * channel: the channel's name/address. The meaning depends on the channel type, but for both 'jabber' and 'muc' this is the XMPP JID of the target user or chat group respectively.

If you only need to handle a single wiki, you can put the section for this wiki directly into udp2xmpp.ini and point wiki-info-section to that section. In that case, udp2xmpp-wikis.ini is ignored.

Running the bridge
When everything is configured, you can start udp2xmpp.py simply by typing:

python udp2xmpp.py

Since this is a long running process, it's advisable to put it into a screen session on a server.

udp2xmpp.py accepts the following command line arguments:


 * --help: print a help message an exit.
 * --config: configuration file to use. If not given, udp2xmpp.ini will be looked for the the directory where udp2xmpp.py is located.
 * --wiki-info: configuration file to use. If not given, udp2xmpp-wikis.ini will be looked for in the location given by the wiki-info-file option in udp2xmpp.ini. If that is also not provided, it will be looked for in the directory where udp2xmpp.py is located.
 * --debug: sets verbosity to debug level
 * --quiet: sets verbosity to quiet, only output warnings and errors.

udp2xmpp.py also accepts commands from standard input. These must start with "/":


 * /quit: terminates udp2xmpp
 * /send <...>: sends a message to *all* channels
 * /debug: sets verbosity to debug (noisy) level
 * /verbose: sets verbosity to normal (informative) level
 * /quiet: sets verbosity to quiet, only output warnings and errors.