Open main menu

Extension:XMLRC/udp2xmpp.py

< 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.

InstallationEdit

udp2xmpp.py is located in the bridge 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 <http://xmpppy.sourceforge.net/>. 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.

ConfigurationEdit

In order to configure udp2xmpp for use with your wiki, rename udp2xmpp.ini.sample to udp2xmpp.ini, and udp2xmpp-wikis.ini.sample to udp2xmpp-wikis.ini

The configuration files uses the INI file syntax.

udp2xmpp.iniEdit

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 udp2xmpp-wikis.ini file. This may be given relative to the location of the udp2xmpp.ini 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.iniEdit

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 bridgeEdit

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.