README

   1 XMPP (eXtended Message and Presence Protocol, <http://xmpp.org/>) is the
   2 federating instant-messaging protocol of the future. It is wildly used
   3 all over the world by organisations, private individuals and everyone.
   4
   5 GNU social allows you to receive and distribute messages via XMPP using
   6 this plugin. To get it running, you must also use an active XMPP account.
   7
   8 Installation
   9 ============
  10 Add an addPlugin call to your config.php with your settings. Please read
  11 the "Pre-requisites" section of what is required for this to work.
  12
  13 Example
  14 -------
  15 The example account "update@site.example" is hosted on a machine which
  16 can be reached at the hostname "xmpp.site.example".
  17
  18 addPlugin('Xmpp', array(
  19     'user'      => 'update',
  20     'server'    => 'site.example',
  21     'host'      => 'xmpp.site.example',
  22     'password'  => '...',
  23 ));
  24
  25 Pre-requisites
  26 ==============
  27
  28 0. You may want to strongly consider setting up your own XMPP server.
  29    We highly recommend the XMPP server "Prosody" <https://prosody.im/>
  30    because it is actively developed and highly secure and efficient. It
  31    is of course also free software under the MIT license. The following
  32    three pages will help you get it running, even self-hosted at home:
  33
  34       0.1 https://prosody.im/doc/dns
  35       0.2 https://prosody.im/doc/install
  36       0.3 https://prosody.im/doc/configure
  37
  38 1. You must register an XMPP user ID (JID) which is used to send and
  39    receive messages. Call it something like "update@site.example" or
  40    similar to hint at what the account is made for. You may register
  41    the account on any public server (jabber.org, jit.si, etc...) if
  42    you cannot run one yourself.
  43
  44    GNU social will not register anything for you, this must be done
  45    manually, preferrably using an XMPP client like Swift, Empathy,
  46    Jitsi or maybe even the commandline on your own server. With
  47    prosody, that'd be (perhaps prepended with 'sudo'):
  48
  49       prosodyctl adduser update@site.example
  50
  51 2. Configure your site's XMPP variables, as described below in the
  52    Settings section below.
  53
  54 3. Learn to use the GNU social daemons for processing notice queues,
  55    background checks and other processes which would be too slow to
  56    perform on an active site. Using XMPP requires the "imdaemon" to
  57    run, since a long-running XMPP connection is somewhat necessary.
  58
  59 A design goal of GNU Social is that the basic Web functionality should
  60 work on even the most restrictive commercial hosting services.
  61 However, additional functionality, such as receiving messages by XMPP,
  62 require that you be able to run long-running processes on your account.
  63
  64 Settings
  65 ========
  66
  67 Required
  68 --------
  69 user        User part of the jid (like 'update')
  70 server      Host part of the jid (like 'site.example')
  71 password    The account's password. (your secret string)
  72
  73 Optional
  74 --------
  75 resource    JID resource. Default: 'gnusocial'
  76 encryption  TLS server? Default: true
  77 host        Hostname for XMPP server? Default: same as server
  78 port        XMPP server port. Default: 5222
  79 debug       Log extra debug info. Default: false
  80 public      JIDs that should get the public feed (see "Public feed").
  81
  82 Since we do not currently support DNS SRV record lookup, please note
  83 that you may have to enter an alternative 'host' parameter. This is
  84 the case when update@site.example is not handled by the direct _address_
  85 "site.example" but rather something like "xmpp.site.example".
  86
  87
  88 Public feed
  89 ===========
  90
  91 You can send *all* messages from your social networking site to a
  92 third-party service using XMPP. This can be useful for providing
  93 search, indexing, bridging, or other cool services. Maybe a text
  94 display next to your coffee machine at work.
  95
  96 To configure a downstream site to receive your public stream, add
  97 their "JID" (Jabber ID) in the "public" array in your addPlugin call.
  98 For example
  99
 100 addPlugin(array(
 101     [...]
 102     'public' => array('awesomebot@site.example'),
 103
 104 As the Pre-requisites section says, please only try to configure this
 105 with daemons running properly in the background.