social/plugins/Xmpp

XMPP (eXtended Message and Presence Protocol, ) is the
federating instant-messaging protocol of the future. It is wildly used
all over the world by organisations, private individuals and everyone.

GNU social allows you to receive and distribute messages via XMPP using
this plugin. To get it running, you must also use an active XMPP account.

Installation
============
Add an addPlugin call to your config.php with your settings. Please read
the "Pre-requisites" section of what is required for this to work.

Example
-------
The example account "update@site.example" is hosted on a machine which
can be reached at the hostname "xmpp.site.example".

addPlugin('Xmpp', array(
'user' => 'update',
'server' => 'site.example',
'host' => 'xmpp.site.example',
'password' => '...',
));

Pre-requisites
==============

0. You may want to strongly consider setting up your own XMPP server.
We highly recommend the XMPP server "Prosody"
because it is actively developed and highly secure and efficient. It
is of course also free software under the MIT license. The following
three pages will help you get it running, even self-hosted at home:

0.1 https://prosody.im/doc/dns
0.2 https://prosody.im/doc/install
0.3 https://prosody.im/doc/configure

1. You must register an XMPP user ID (JID) which is used to send and
receive messages. Call it something like "update@site.example" or
similar to hint at what the account is made for. You may register
the account on any public server (jabber.org, jit.si, etc...) if
you cannot run one yourself.

GNU social will not register anything for you, this must be done
manually, preferrably using an XMPP client like Swift, Empathy,
Jitsi or maybe even the commandline on your own server. With
prosody, that'd be (perhaps prepended with 'sudo'):

prosodyctl adduser update@site.example

2. Configure your site's XMPP variables, as described below in the
Settings section below.

3. Learn to use the GNU social daemons for processing notice queues,
background checks and other processes which would be too slow to
perform on an active site. Using XMPP requires the "imdaemon" to
run, since a long-running XMPP connection is somewhat necessary.


Settings
========

Required
--------
user User part of the jid (like 'update')
server Host part of the jid (like 'site.example')
password The account's password. (your secret string)

Optional
--------
resource JID resource. Default: 'gnusocial'
encryption TLS server? Default: true
host Hostname for XMPP server? Default: same as server
port XMPP server port. Default: 5222
debug Log extra debug info. Default: false
public JIDs that should get the public feed (see "Public feed").

Since we do not currently support DNS SRV record lookup, please note
that you may have to enter an alternative 'host' parameter. This is
the case when update@site.example is not handled by the direct _address_
"site.example" but rather something like "xmpp.site.example".


Public feed
===========

You can send *all* messages from your social networking site to a
third-party service using XMPP. This can be useful for providing
search, indexing, bridging, or other cool services. Maybe a text
display next to your coffee machine at work.

To configure a downstream site to receive your public stream, add
their "JID" (Jabber ID) in the "public" array in your addPlugin call.
For example

addPlugin(array(
[...]
'public' => array('awesomebot@site.example'),

As the Pre-requisites section says, please only try to configure this
with daemons running properly in the background.