view INSTALL @ 393:728b08c0d000

storage (pgsql): fixed storage of multiple items
author Goffi <>
date Fri, 15 Feb 2019 22:06:19 +0100
parents e93a9fd329d9
line wrap: on
line source


- Python 2.7.x
- Twisted >= 15.2.0:
   - Twisted Core
   - Twisted Words
- Wokkel >= 0.7.1 (
- A XMPP server that supports the component protocol (XEP-0114),
  and, to enable the micro-blogging feature, Namespace Delegation (XEP-0355)
  and privileged entity (XEP-0356) are needed.
  We recommend using Prosody with mod_privilege and mod_delegation modules.
- SàT backend ( is currently needed for MAM and RSM handling

For the PostgreSQL backend, the following is also required:

- PostgreSQL >= 9.5 (including development files for psycopg2)
- psycopg2


sat_pubsub uses setuptools for package building and installing.
To build from the source run:

  python build

Then, to install run the following, possibly as root:

  python install

See the setuptools documentation for further information on changing
installation locations.


sat_pubsub uses Twisted's twistd command for running its services.

Idavoll, on which sat_pubsub is based, provides two types of storage for the backend:
a memory-based storage facility, which is volatile, and a persistent storage facility
using PostgreSQL. For now, sat_pubsub only uses the persistent storage facility.

For using the PostgreSQL backend, create a database (for example named pubsub):

  sudo -u postgres createuser -d -P `whoami`
  createdb pubsub
  psql pubsub < sat_pubsub/db/pubsub.sql

Your XMPP server must also be configured to accept component connections and,
to enable the micro-blogging feature, privileged entity and namespace delegation.
See below for details.

Running sat_pubsub

The minimal example for running sat_pubsub is:

  twistd sat_pubsub

This will start the service and run it in the background. It generates a
file that holds the PID of the service and a log file twistd.log.
The twistd utility has a fair number of options that might be useful, and
can be viewed with:

  twistd --help

When the service starts, it will connect to the XMPP server at the local
machine using the component protocol, and assumes the JID 'pubsub'. This
assumes a couple of defaults which can be overridden by passing parameters to
the twistd plugin. You can get an overview of the parameters and their defaults

  twistd sat_pubsub --help

In particular, the following parameters will be of interest:

 --jid: The Jabber ID the component will assume.
 --rport: the port number of the XMPP server to connect to
 --secret: the secret used to authenticate with the XMPP server.

For example:

  twistd sat_pubsub --jid=sat-pubsub.<your_xmpp_domain> --secret=<password>

You may also want to provide the --verbose flag to see the traffic flow,
for example to debug the configuration. Below some specifics for the
Prosody XMPP server implementation.

Running sat_pubsub with Prosody

To enable the micro-blogging feature with Prosody XMPP server, you need
the mod_delegation and privileged_entity plugins.
Check if the mod_delegation and mod_privilege plugins are already
in your Prosody installation:

  cd prosody/plugins
  ls mod_delegation.lua
  ls mod_privilege.lua

If you can't see it, download them from


Edit the prosody.cfg.lua file to add this module:

  modules_enabled = {

In your VirtualHost, add this lines:

VirtualHost "<your_xmpp_domain>"
  privileged_entities = {
    ["sat-pubsub.<your_xmpp_domain>"] = {
      roster = "get";
      message = "outgoing";
  delegations = {
    ["urn:xmpp:mam:1"] = {
      filtering = {"node"};
      jid = "sat-pubsub.<your_xmpp_domain>";
    [""] = {
      jid = "sat-pubsub.<your_xmpp_domain>";

Also add these two lines at the end of the file, adapting them to your XMPP server
domain (virtual host) and selecting a password of your choice:

  Component "sat-pubsub.<your_xmpp_domain>"
          component_secret = "<password>"
		  modules_enabled = {"delegation", "privilege"}

For a more complete installation and configuration of Prosody to be used with
sat_pubsub, please report yourself to the Salut à Toi wiki: