Package: collective.xmpp.core
Introductioncollective.xmpp.coreis a fork/merge ofjarn.xmpp.twistedandjarn.xmpp.coreboth written by Yiorgis Gozadinos (@ggozad).It removes the PubSub and Messaging features from thejarn.xmpp.coreand is intended to instead serve
only as a base on which Plone add-ons with XMPP-enabled features can depend.Currently it provides the following features:Extensions to thewokkelpackage by implementing parts of the following XMPP extensions:XEP-0071XHTML-IM.XEP-0144Roster Item Exchange.XEP-0060Publish-Subscribe.XEP-0248PubSub Collection Nodes.XEP-0133Service Administration.ATwistedreactor that runs side-by-side with the Zope instance.Utilities that provide XMPP clients of two sorts, adeferredclient that initially connects, executes a task and disconnects as soon as it is done, as well as a normal client that remains connected and can respond to XMPP events.An XMPP component base class for writing custom components.Integration of plone user accounts with XMPP accounts and authentication.InstallationBefore setting up the package you need to have a working XMPP server and access to the administration account on the server. The package has only been tested with ejabberd version 2.1.5 and above which is recommended. In any case the following XMPP extensions need to be supported by the server you are going to use:XEP-0144Roster Item Exchange.XEP-0133Service Administration.XEP-0124Bidirectional-streams Over Synchronous HTTP (BOSH)XEP-0206XMPP over BOSHBuildoutA sample buildout you can use as a starting point can be found atcollective.xmpp.buildout.Setting up ejabberd (>=2.1.5)Automatic configurationUse the recipe provided incollective.xmpp.buildout(in which case you
will need to have erlang installed, erlang-nox on Debian) or download theejabberdinstaller.A minimal configuration for ejabberd can be generated for convenience by theejabberd.cfgpart ofcollective.xmpp.buildout. You will need to copy thetemplatesdirectory and modify the recipe configuration accordingly:[ejabberd.cfg]
recipe = collective.recipe.template
input = templates/ejabberd.cfg.in
output = ${buildout:directory}/etc/ejabberd.cfg
xmppdomain = localhost
admin_userid = admin
collaboration_allowed_subnet = 0,0,0,0
collaboration_port = 5347
component_password = secretwherexmppdomainis the domain (or virtual host) running on your XMPP server andadmin_useridis the id the the administrator account that Plone is going to use to interact with the server. The rest of the options are  used bycollective.xmpp.collaborationfor the collaborative editing component connecting to the XMPP server. Here,collaboration_allowed_subnetspecifies from which IPs the XMPP server is going to accept connections and should match the IPs your Plone instances are going to be using. Leaving it to0,0,0,0will allow all IPs,127,0,0,1will allow onlylocalhost. Finallycollaboration_portis the port to which the collaboration component is going to connect to andcomponent_passwordis the shared password between the component and the XMPP server.Manual configurationIf you already run an XMPP server here are some hints on how to set it up:We assume that your xmpp domain islocalhost. There should exist an administrator accountadmin@localhost. In addition if you intend to run some of the tests in any of thecollective.xmpp.*packages you will need to be running an additional XMPP node onlocalhostif you use some other domain for production. You can safely remove any references tolocalhostif you are not interested in doing that.Make sure you have enabled thehttp_bindmodule, as this is what the javascript clients will use to connect. You should have  something like this in your ejabberd.cfg:{5280, ejabberd_http, [
     http_bind,
     web_admin
     ]}In order to test and run custom XMPP components (for instance the collaborative editing component provided bycollective.xmpp.collaboration) you will need to allow them to connect. This means you should have something similar to this configuration:{5347, ejabberd_service, [
          {access, all},
          {shaper_rule, fast},
          {ip, {127, 0, 0, 1}},
          {hosts,
           ["collaboration.localhost"],
           [{password, "secret"}]
          }
         ]},The rest of the standard options should be fine.Administrator accountIf you have not done so during installation you might need to create manually the administrator account. In the ejabberd folder execute:./bin/ejabberdctl register admin localhost your_passwordTest that you can access your ejabberd by logging to the admin interface (typicallyhttp://localhost:5280/admin). You should also be able to access thehttp-bindinterface athttp://localhost:5280/http-bind.Setting up your front-end proxyOn the client-side every authenticated user will be connected to your jabber server through an emulated bidirectional stream through HTTP. To allow for this you need a proxy in front of Plone that will be redirecting the XMPP stream to your XMPP server. It is possible to do without one using the inferior solution of Flash plugins but this is not going to be supported.Assuming you run your webserver as a proxy at port8080for the domainlocalhost, Zope listens on8081, there exists a Plone site with idPloneand your ejabberd has thehttp_bindconfigured for port5280, yournginxorapacheconfiguration will look as follows:Nginxhttp {
    server {
        listen       8080;
        server_name  localhost;
        location ~ ^/http-bind/ {
            proxy_pass http://localhost:5280;
        }
        location / {
            proxy_pass http://localhost:8081/VirtualHostBase/http/localhost:8080/Plone/VirtualHostRoot/;
        }
    }
}Apache<VirtualHost *:8080>
    ServerName localhost
    RewriteEngine On
    RewriteRule ^/http-bind(.*) http://localhost:5280/http-bind$1 [P,L]
    RewriteRule ^/(.*) http://localhost:8081/VirtualHostBase/http/%{HTTP_HOST}:8080/Plone/VirtualHostRoot/$1 [P,L]
</VirtualHost>Setting up your Plone instancesYour instances will need to maintain a connection to the administrator account of your XMPP server. This is accomplished throughTwistedand you will need to run a Twisted reactor on each of them. To do so include this in your instance section of your buildout:zcml-additional =
  <configure xmlns="http://namespaces.zope.org/zope">
    <include package="collective.xmpp.core" file="reactor.zcml" />
  </configure>Moreover, if your Plone buildout is not using plone.dexterity and you want to avoid this dependency being brought just add the bellow line to your CFG file:[versions]
Products.UserAndGroupSelectionWidget = 2.0.4Again, it will help you to have a look at the sample buildout provided incollective.xmpp.buildout.Setting up a new Plone siteStart ejabberd (if you used the recipe to build ejabberd,bin/ejabberdwill do the job).Start the Nginx frontend.bin/frontend startStart your zope instance.Access Zope directly athttp://localhost:8081/manageand create a new Plone site withcollective.xmpp.core.Go to the Plone control panel and click on theXMPP Integrationlink underPlone Configuration.  Make sure the XMPP settings reflect your installation.Restart your Plone instance.Upon the first request the administrator will log to his account. You should see things happening in the logs and if there are any errors something might be wrong with your installation.When you create a new Plone user, they will automatically be registered on the XMPP server. Your existing users can also be registered by going back to theXMPP Integrationconfiglet in the control panel, and then clicking on theUser Registrationtab. Keep an eye on your instance.log traceback in the console to make sure there aren’t any errors. You can see the registered users by going to the XMPP admin interface at localhost:5280/admin.Making sure things work ;)This is a complex infrastructure so it can be hard to know what goes wrong sometimes. Do not despair, here are a few things to try:Make sure your ejabberd is running. Connect to it normal client as the admin user.Verify that http-binding is setup properly on ejabberd. Visitinghttp://localhost:5280/http-bindshould tell you it’s working.Verify that XMPP requests will get properly through your proxy. Visitinghttp://localhost:8080/http-bind/should give you the same result as above.When you start your Zope instance in foreground you can verify the Twisted reactor is running fine:2011-09-01 14:37:38 INFO collective.xmpp.core Starting Twisted reactor...
2011-09-01 14:37:38 INFO collective.xmpp.core Twisted reactor started
2011-09-01 14:37:38 INFO Zope Ready to handle requestsAfter the first request to the site, you should also see in the logs:2011-09-01 14:45:48 INFO collective.xmpp.core XMPP admin client has authenticated succesfully.If your Plone user was succesfully registered on the XMPP server, logging-in to the Plone site with a user should also authenticate him with the XMPP server. This is indicated in the logs by:2011-09-01 14:45:50 INFO collective.xmpp.core Pre-binded ggozad@localhost/auto-QravOoyEeEExperimentingUsageAdd a few users.Login as one of them, and in a different browser as some other. Use the frontend to access the site, if you used the settings above this should behttp://localhost:8080.All actions are performed through the viewlet on the top right:Online userswill display the users currently logged in. Clicking it will give you the list of users. You can message them directly or look at their personal feed.Try posting an entry to your feed. Links will be transformed automatically. As soon as you submit other logged-in users will receive a notification in real-time. Using a recent browser that supports geolocation will allow you also share your location at the time of the post.Try commenting on a feed post.By clicking on the “Following” user action you can select which users you want to follow, or follow them all.You can see all posts by clicking onSite feedon the viewlet.SecurityIncluded is an implementation of an authenticating client over BOSH according toXEP-0206. This practically means that the javascript client never needs to know the password of the XMPP user. Instead, the user is authenticated directly between the XMPP server and the Plone instance. A pair of secret tokens are exchanged, valid for a short time (~2 minutes). It is this pair that is given to the javascript client and not the password.When a Plone user is registered on the XMPP server, a random password is generated and stored in the ZODB in a persistent utility.If you do not need to access the XMPP accounts outside of the Plone instance you can additionally hide the entire XMPP service behind a firewall and only allow connections to it from the Plone instances. This in combination with HTTPS should be enough for the paranoid among us.TestingSome of the included tests are functional tests that require a XMPP server running onlocalhostas well as an administrator account setup up on this server with JIDadmin@localhostand passwordadmin. If you wish to run those you have to specify alevel2 on your testrunner, i.e.:./bin/test -a 2 -s collective.xmpp.coreYou’ll also have to configure ejabberd to listen on port 5347 for external
components.The minimum requirement would be to add the following entry to thelistenkeyword::{listen,
    [
    % Add only the line below
    {{5347, {0,0,0,0} }, ejabberd_service, []}
    ]
}Tips for production deploymentDon’t cache @@xmpp-loader:Make sure the${site_url}/@@xmpp-loaderURL isn’t cached. This view
returns an authentication token which has to be different each time you
reload your page.If you cache this, the token won’t change and you won’t be able to communicate
with the XMPP server.CreditsThanks goes Yiorgis Gozadinos (@ggozad) for writing jarn.xmpp.core and being the first to integrate XMPP into Plone.Changelog0.3 (2013-06-28)Feature: Remove password from storage if jabber server returns not-authorized
in order to try to create the user again as this error comes up when the
password is still present but the jabber server doesn’t have the user anymore
[ichim-david]Feature: Log response from the jabber server when trying to bind client and
it fails
[ichim-david]Bugfix: Could not get portrait data for users with custom profile pictures.
[jcbrand]Feature: Add a new controlpanel option to update all user’s vCards.
[jcbrand]Bugfix: When pre-binding, fetch admin user’s password from IXMPPSettings.
[jcbrand]0.2 (2013-03-20)Feature: Include the user’s portrait in their vCard.
[jcbrand]Feature: Update the user’s vCard when they change their personal preferences.
[jcbrand]Bugfix: Last user’s roster suggestions ignored by XMPP server.
[jcbrand]0.1 (2013-03-15)Released. [jcbrand]0.1b8 (2013-03-09)Bugfix. All xmpp passwords were cleared when deregistering a subset of users.
[jcbrand]0.1b7 (2013-03-05)Previous release was broken. Didn’t include ZCML files.
[jcbrand]0.1b6 (2013-03-04)Fixed rst issues when read by pypi which combines readme.rst and history.txt
[ichim-david]0.1b5 (2013-03-04)Feature: “Completely wipe password storage” action is now traced under zope log.
[alecghica]Bugfix: ‘ComponentLookupError’ error when adding a local user.
[alecghica]Feature: added error image and ‘Unable to communicate with chat server’ message
when unable to bind the user to jabber server
[alecghica]Feature: Add a VCard when registering a user on the XMPP server.
[jcbrand]Feature: Make manual user registration idempotent (ignore already registered
users).
[jcbrand]Users are no longer registered upon creation. They must either be registered
manually, or upon next logged in visit.
[jcbrand]0.1b4 (2013-02-02)Bugfix for “Deregister All” in @@xmpp-user-setup page. Site root was not set
in callback method.
[jcbrand]0.1b3 (2013-01-17)Add option to completely clear the XMPP password utility.
[jcbrand]Add upgrade step to make sure the registry is reloaded so that the
“auto-register on login” entry is added.
[jcbrand]Bugfix. Always get the XMPP virtual host from the registry.
[jcbrand]Bugfix. When auto-subscribing, LDAP users’ fullnames weren’t being shown.
[jcbrand]0.1b2 (2013-01-17)Add a configuration setting to turn auto-register on login on. It’s disabled
by default.
[jcbrand]0.1b1 (2013-01-16)Feature: if not already registered, Plone users get
registered on jabber server on login
[alecghica]Bugfix: no need to refresh browser for users registered
on login, they are binded on the fly
[alecghica]Bugfix: “Deregister ALL Users” function, credentials were
left un-deleted under IXMPPPasswordStorage resulting in
various errors when registering/deregistering users
[alecghica]Bugfix: fixed subscribing when a new plone user is added
[alecghica]Bugfix: users were only being auto-subscribed to
other users added in that current session
[alecghica]Bugfix: new users are now auto-subscribed only
to existing XMPP users
[alecghica]0.1a8 (2012-12-13)Bugfix. Check for GS profile version in dbconfig.py to avoid the instance not
starting without having run the GS upgrade step.
[jcbrand]0.1a7 (2012-12-13)Documentation updated with Apache config example.
[alecghica]Cleaned up dependencies that already ship with Plone
[alecghica]Made Products.UserAndGroupSelectionWidget package optional.
Products.UserAndGroupSelectionWidget will be imported only
if package version is greater then 2.0.4 as it brings dependencies
like plone.dexterity witch conflict with other packages found in
the current Plone release.
[alecghica]Fixed register users form to work for the case when
Products.UserAndGroupSelectionWidget is not installed/used
[alecghica]Added info on how to make plone.dexterity optional
[alecghica]Explicitly store XMPP server’s hostname instead of only using the XMPP
domain. Also store the port number instead of only using the default.
[jcbrand]Allow the configuration of the registry settings via buildout. See
dbconfig.py
[jcbrand]0.1a6 (2012-11-22)Added Spanish translation.
[macagua]Added improvements about i18n support.
[macagua]Bugfix. Prevent getAllMemberIds from returning duplicates.
[jcbrand]0.1a5 (2012-11-19)Fixed RST formatting bugs.
[jcbrand]0.1a4 (2012-11-19)Documentation updated
[jcbrand]Fixed HISTORY.txt markup
[alecghica]Fixed version used for Products.UserAndGroupSelectionWidget to >2.04
as earlier version will crash due to API changes
[alecghica]Bugfix. Password utility forgets user passwords when a user is registered.
[jcbrand]0.1a3 (2012-11-09)Bugfix for RuntimeError that might occur when upgrading from 0.1a1 to 0.1a2
[jcbrand]0.1a2 (2012-11-09)Add control panel configlet for configuration and registering XMPP users.
[jcbrand]Add support for PAS plugins (such as LDAP).
[jcbrand]0.1a1 (2012-10-18)Forked from jarn.xmpp.core 0.34
[jcbrand]Merged in jarn.xmpp.twisted 0.1
[jcbrand]Removed all PubSub and Messaging related features.
[jcbrand]Add browserlayer and check for it when handling events.
[jcbrand]Fixed the @@setup-xmpp script to only register the next user once the previous one
has finished.
[jcbrand]