From cb3d8636680320efb998ac303fe55e775ae75b97 Mon Sep 17 00:00:00 2001 From: Mikael Nordfeldth Date: Tue, 11 Mar 2014 00:05:28 +0100 Subject: [PATCH] Updated and moved XMPP documentation into plugin. --- INSTALL | 53 ------------------- plugins/Xmpp/README | 120 ++++++++++++++++++++++++++++++++------------ 2 files changed, 89 insertions(+), 84 deletions(-) diff --git a/INSTALL b/INSTALL index 20817f3009..64f4a817cc 100644 --- a/INSTALL +++ b/INSTALL @@ -310,59 +310,6 @@ that if your mail server is on a different computer from your email server, you'll need to have a full installation of StatusNet, a working config.php, and access to the StatusNet database from the mail server. -XMPP ----- - -XMPP (eXtended Message and Presence Protocol, ) is the -instant-messenger protocol that drives Jabber and GTalk IM. You can -distribute messages via XMPP using the system below; however, you -need to run the XMPP incoming daemon to allow incoming messages as -well. - -1. You may want to strongly consider setting up your own XMPP server. - Ejabberd, OpenFire, and JabberD are all Open Source servers. - Jabber, Inc. provides a high-performance commercial server. - -2. You must register a Jabber ID (JID) with your new server. It helps - to choose a name like "update@example.com" or "notice" or something - similar. Alternately, your "update JID" can be registered on a - publicly-available XMPP service, like jabber.org or GTalk. - - StatusNet will not register the JID with your chosen XMPP server; - you need to do this manually, with an XMPP client like Gajim, - Telepathy, or Pidgin.im. - -3. Configure your site's XMPP variables, as described below in the - configuration section. - -On a default installation, your site can broadcast messages using -XMPP. Users won't be able to post messages using XMPP unless you've -got the XMPP daemon running. See 'Queues and daemons' below for how -to set that up. Also, once you have a sizable number of users, sending -a lot of SMS, OStatus, and XMPP messages whenever someone posts a message -can really slow down your site; it may cause posting to timeout. - -NOTE: stream_select(), a crucial function for network programming, is -broken on PHP 5.2.x less than 5.2.6 on amd64-based servers. We don't -work around this bug in StatusNet; current recommendation is to move -off of amd64 to another server. - -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. - -To configure a downstream site to receive your public stream, add -their "JID" (Jabber ID) to your config.php as follows: - - $config['xmpp']['public'][] = 'downstream@example.net'; - -(Don't miss those square brackets at the end.) Note that your XMPP -broadcasting must be configured as mentioned above. Although you can -send out messages at "Web time", high-volume sites should strongly -consider setting up queues and daemons. Queues and daemons ------------------ diff --git a/plugins/Xmpp/README b/plugins/Xmpp/README index a8ec7da73a..2dbba8372a 100644 --- a/plugins/Xmpp/README +++ b/plugins/Xmpp/README @@ -1,43 +1,101 @@ -The XMPP plugin allows users to send and receive notices over the -XMPP/Jabber/GTalk network. +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 "addPlugin('xmpp', - array('setting'=>'value', 'setting2'=>'value2', ...);" -to the bottom of your config.php +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. -The daemon included with this plugin must be running. It will be -started by the plugin along with their other daemons when you run -scripts/startdaemons.sh. See the section "Queues and daemons" in -INSTALL for more about queuing and daemons. +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 ======== -user*: user part of the jid -server*: server part of the jid -resource (gnusocial): resource part of the jid -port (5222): port on which to connect to the server -encryption (true): use encryption on the connection -host (same as server): host to connect to. Usually, you won't set this. -debug (false): log extra debug info (e.g. sent/recv XMPP stanzas) -public: list of jid's that should get the public feed (firehose) -* required -default values are in (parenthesis) +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) -Note that setting 'host' is required if the XMPP service is configured -with DNS SRV records, since XMPPHP does currently not support SRV -lookups. +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". -Example -======= -addPlugin('xmpp', array( - 'user'=>'update', - 'resource'=>'social', - 'server'=>'identi.ca', - 'password'=>'...', - 'public'=>array('bob@aol.com', 'sue@google.com') -)); +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.