File

mod_cloud_notify: Update Readme diff --git a/mod_cloud_notify/README.md b/mod_cloud_notify/README.md --- a/mod_cloud_notify/README.md +++ b/mod_cloud_notify/README.md @@ -1,109 +1,106 @@ ---- -labels: -- 'Stage-Beta' -summary: 'XEP-0357: Cloud push notifications' ---- +# Introduction -Introduction -============ +This module enables support for sending "push notifications" to clients +that need it, typically those running on certain mobile devices. -This module enables support for sending "push notifications" to clients that -need it, typically those running on certain mobile devices. +As well as this module, your client must support push notifications (the +apps that need it generally do, of course) and the app developer's push +gateway must be reachable from your Prosody server (this happens over a +normal XMPP server-to-server 's2s' connection). -As well as this module, your client must support push notifications (the apps -that need it generally do, of course) and the app developer's push gateway -must be reachable from your Prosody server (this happens over a normal XMPP -server-to-server 's2s' connection). - -Details -======= +# Details Some platforms, notably Apple's iOS and many versions of Android, impose -limits that prevent applications from running or accessing the network in the -background. This makes it difficult or impossible for an XMPP application to -remain reliably connected to a server to receive messages. - -In order for messaging and other apps to receive notifications, the OS vendors -run proprietary servers that their OS maintains a permanent connection to in -the background. Then they provide APIs to application developers that allow -sending notifications to specific devices via those servers. +limits that prevent applications from running or accessing the network +in the background. This makes it difficult or impossible for an XMPP +application to remain reliably connected to a server to receive +messages. -When you connect to your server with an app that requires push notifications, -it will use this module to set up a "push registration". When you receive -a message but your device is not connected to the server, this module will -generate a notification and send it to the push gateway operated by your -application's developers). Their gateway will then connect to your device's -OS vendor and ask them to forward the notification to your device. When your -device receives the notification, it will display it or wake up the app so it -can connect to XMPP and receive any pending messages. +In order for messaging and other apps to receive notifications, the OS +vendors run proprietary servers that their OS maintains a permanent +connection to in the background. Then they provide APIs to application +developers that allow sending notifications to specific devices via +those servers. -This protocol is described for developers in [XEP-0357: Push Notifications]. +When you connect to your server with an app that requires push +notifications, it will use this module to set up a "push registration". +When you receive a message but your device is not connected to the +server, this module will generate a notification and send it to the push +gateway operated by your application's developers). Their gateway will +then connect to your device's OS vendor and ask them to forward the +notification to your device. When your device receives the notification, +it will display it or wake up the app so it can connect to XMPP and +receive any pending messages. -For this module to work reliably, you must have [mod_smacks], [mod_mam] and -[mod_carbons] also enabled on your server. +This protocol is described for developers in \[XEP-0357: Push +Notifications\]. + +For this module to work reliably, you must have \[mod_smacks\], +\[mod_mam\] and \[mod_carbons\] also enabled on your server. -Some clients, notably Siskin and Snikket iOS need some additional extensions -that are not currently defined in a standard XEP. To support these clients, -see [mod_cloud_notify_extensions]. +Some clients, notably Siskin and Snikket iOS need some additional +extensions that are not currently defined in a standard XEP. To support +these clients, see \[mod_cloud_notify_extensions\]. -Configuration -============= +# Configuration - Option Default Description - ------------------------------------ ----------------- ------------------------------------------------------------------------------------------------------------------- - `push_notification_important_body` `New Message!` The body text to use when the stanza is important (see above), no message body is sent if this is empty - `push_max_errors` `16` How much persistent push errors are tolerated before notifications for the identifier in question are disabled - `push_max_devices` `5` The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached) - `push_max_hibernation_timeout` `259200` (72h) Number of seconds to extend the smacks timeout if no push was triggered yet (default: 72 hours) - `push_notification_with_body` (\*) `false` Whether or not to send the real message body to remote pubsub node. Without end-to-end encryption, enabling this may expose your message contents to your client developers and OS vendor. Not recommended. - `push_notification_with_sender` (\*) `false` Whether or not to send the real message sender to remote pubsub node. Enabling this may expose your contacts to your client developers and OS vendor. Not recommended. + Option Default Description + -------------------------------------- ---------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + `push_notification_important_body` `New Message!` The body text to use when the stanza is important (see above), no message body is sent if this is empty + `push_max_errors` `16` How much persistent push errors are tolerated before notifications for the identifier in question are disabled + `push_max_devices` `5` The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached) + `push_max_hibernation_timeout` `259200` (72h) Number of seconds to extend the smacks timeout if no push was triggered yet (default: 72 hours) + `push_notification_with_body` (\*) `false` Whether or not to send the real message body to remote pubsub node. Without end-to-end encryption, enabling this may expose your message contents to your client developers and OS vendor. Not recommended. + `push_notification_with_sender` (\*) `false` Whether or not to send the real message sender to remote pubsub node. Enabling this may expose your contacts to your client developers and OS vendor. Not recommended. -(\*) There are privacy implications for enabling these options. +(\*) There are privacy implications for enabling these options.[^1] -Internal design notes -===================== +# Internal design notes -App servers are notified about offline messages, messages stored by [mod_mam] -or messages waiting in the smacks queue. -The business rules outlined [here](//mail.jabber.org/pipermail/standards/2016-February/030925.html) are all honored[^2]. +App servers are notified about offline messages, messages stored by +\[mod_mam\] or messages waiting in the smacks queue. The business rules +outlined +[here](//mail.jabber.org/pipermail/standards/2016-February/030925.html) +are all honored[^2]. -To cooperate with [mod_smacks] this module consumes some events: -`smacks-ack-delayed`, `smacks-hibernation-start` and `smacks-hibernation-end`. -These events allow this module to send out notifications for messages received -while the session is hibernated by [mod_smacks] or even when smacks -acknowledgements for messages are delayed by a certain amount of seconds -configurable with the [mod_smacks] setting `smacks_max_ack_delay`. +To cooperate with \[mod_smacks\] this module consumes some events: +`smacks-ack-delayed`, `smacks-hibernation-start` and +`smacks-hibernation-end`. These events allow this module to send out +notifications for messages received while the session is hibernated by +\[mod_smacks\] or even when smacks acknowledgements for messages are +delayed by a certain amount of seconds configurable with the +\[mod_smacks\] setting `smacks_max_ack_delay`. -The `smacks_max_ack_delay` setting allows to send out notifications to clients -which aren't already in smacks hibernation state (because the read timeout or -connection close didn't already happen) but also aren't responding to acknowledgement -request in a timely manner. This setting thus allows conversations to be smoother -under such circumstances. +The `smacks_max_ack_delay` setting allows to send out notifications to +clients which aren't already in smacks hibernation state (because the +read timeout or connection close didn't already happen) but also aren't +responding to acknowledgement request in a timely manner. This setting +thus allows conversations to be smoother under such circumstances. -The new event `cloud-notify-ping` can be used by any module to send out a cloud -notification to either all registered endpoints for the given user or only the endpoints -given in the event data. +The new event `cloud-notify-ping` can be used by any module to send out +a cloud notification to either all registered endpoints for the given +user or only the endpoints given in the event data. -The config setting `push_notification_important_body` can be used to specify an alternative -body text to send to the remote pubsub node if the stanza is encrypted or has a body. -This way the real contents of the message aren't revealed to the push appserver but it -can still see that the push is important. -This is used by Chatsecure on iOS to send out high priority pushes in those cases for example. +The config setting `push_notification_important_body` can be used to +specify an alternative body text to send to the remote pubsub node if +the stanza is encrypted or has a body. This way the real contents of the +message aren't revealed to the push appserver but it can still see that +the push is important. This is used by Chatsecure on iOS to send out +high priority pushes in those cases for example. -Compatibility -============= - -**Note:** This module should be used with Lua 5.2 and higher. Using it with -Lua 5.1 may cause push notifications to not be sent to some clients. +# Compatibility ------- ----------------------------------------------------------------------------- - trunk Works - 0.12 Works - 0.11 Works - 0.10 Works - 0.9 Support dropped, use last supported version [675726ab06d3](//hg.prosody.im/prosody-modules/raw-file/675726ab06d3/mod_cloud_notify/mod_cloud_notify.lua) ------- ----------------------------------------------------------------------------- +**Note:** This module should be used with Lua 5.2 and higher. Using it +with Lua 5.1 may cause push notifications to not be sent to some +clients. + ------- ----------------------------------------------------------------- + trunk Works as of 25-06-13 + 13 Works + 0.12 Works + ------- ----------------------------------------------------------------- -[^1]: The service which is expected to forward notifications to something like Google Cloud Messaging or Apple Notification Service -[^2]: [business_rules.markdown](//hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.markdown) +[^1]: The service which is expected to forward notifications to + something like Google Cloud Messaging or Apple Notification Service + +[^2]: [business_rules.md](//hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.md)

# LDAP plugin suite for Prosody

The LDAP plugin suite includes an authentication plugin (mod\_auth\_ldap2) and storage plugin
(mod\_storage\_ldap) to query against an LDAP server.  It also provides a plugin library (mod\_lib\_ldap)
for accessing an LDAP server to make writing other LDAP-based plugins easier in the future.

# LDAP Authentication

**NOTE**: LDAP authentication currently only works with plaintext auth (as opposed to DIGEST-MD5 or SCRAM)
If this isn't ok with you, don't use it!  (Or better yet, fix it =) )

With that note in mind, if you need to allow (XMPP) clients to connect to your server without TLS and
want to use this module, you need to set 'allow\_unencrypted\_plain\_auth' to true in your
configuration.  You probably don't actually want to do this, though.

To enable LDAP authentication, set 'authentication' to 'ldap2' in your configuration file.
See also http://prosody.im/doc/authentication.

# LDAP Storage

LDAP storage is currently read-only, and it only supports rosters and vCards.

To enable LDAP storage, set 'storage' to 'ldap' in your configuration file.
See also http://prosody.im/doc/storage.

# LDAP Configuration

All of the LDAP-specific configuration for the plugin set goes into an 'ldap' section
in the configuration.  You must set the 'hostname' field in the 'ldap' section to
your LDAP server's location (a custom port is also accepted, so I guess it's not strictly
a hostname).  The 'bind\_dn' and 'bind\_password' are optional if you want to bind as
a specific DN.  There should be an example configuration included with this README, so
feel free to consult that.

## The user section

The user section must contain the following keys:

  * basedn - The base DN against which to base your LDAP queries for users.
  * filter - An LDAP filter expression that matches users.
  * usernamefield - The name of the attribute in an LDAP entry that contains the username.
  * namefield - The name of the attribute in an LDAP entry that contains the user's real name.

## The groups section

The LDAP plugin suite has support for grouping (ala mod\_groups), which can be enabled via the groups
section in the ldap section of the configuration file.  Currently, you must have at least one group.
The groups section must contain the following keys:

  * basedn - The base DN against which to base your LDAP queries for groups.
  * memberfield - The name of the attribute in an LDAP entry that contains a list of a group's members. The contents of this field
                  must match usernamefield in the user section.
  * namefield - The name of the attribute in an LDAP entry that contains the group's name.

The groups section must contain at least one entry in its array section.  Each entry must be a table, with the following keys:

  * name - The name of the group that will be presented in the roster.
  * $namefield (whatever namefield is set to is the name) - An attribute pair to match this group against.
  * admin (optional) - whether or not this group's members are admins.

## The vcard\_format section

The vcard\_format section is used to generate a vCard given an LDAP entry.  See http://xmpp.org/extensions/xep-0054.html for
more information.  The JABBERID field is automatically populated.

The key/value pairs in this table fall into three categories:

### Simple pairs

Some values in the vcard\_format table are simple key-value pairs, where the key corresponds to a vCard
entry, and the value corresponds to the attribute name in the LDAP entry for the user.  The fields that
be configured this way are:

  * displayname - corresponds to FN
  * nickname - corresponds to NICKNAME
  * birthday - corresponds to BDAY
  * mailer - corresponds to MAILER
  * timezone - corresponds to TZ
  * title - corresponds to TITLE
  * role - corresponds to ROLE
  * note - corresponds to NOTE
  * rev - corresponds to REV
  * sortstring - corresponds to SORT-STRING
  * uid - corresponds to UID
  * url - corresponds to URL
  * description - corresponds to DESC

### Single-level fields

These pairs have a table as their values, and the table itself has a series of key value pairs that are translated
similarly to simple pairs.  The fields that are configured this way are:

  * name - corresponds to N
    * family - corresponds to FAMILY
    * given - corresponds toGIVEN
    * middle - corresponds toMIDDLE
    * prefix - corresponds toPREFIX
    * suffix - corresponds toSUFFIX
  * photo - corresponds to PHOTO
    * type - corresponds to TYPE
    * binval - corresponds to BINVAL
    * extval - corresponds to EXTVAL
  * geo - corresponds to GEO
    * lat - corresponds to LAT
    * lon - corresponds to LON
  * logo - corresponds to LOGO
    * type - corresponds to TYPE
    * binval - corresponds to BINVAL
    * extval - corresponds to EXTVAL
  * org - corresponds to ORG
    * orgname - corresponds to ORGNAME
    * orgunit - corresponds to ORGUNIT
  * sound - corresponds to SOUND
    * phonetic - corresponds to PHONETIC
    * binval - corresponds to BINVAL
    * extval - corresponds to EXTVAL
  * key - corresponds to KEY
    * type - corresponds to TYPE
    * cred - corresponds to CRED

### Multi-level fields

These pairs have a table as their values, and each table itself has tables as its values.  The nested tables have
the same key-value pairs you're used to, the only difference being that values may have a boolean as their type, which
converts them into an empty XML tag.  I recommend looking at the example configuration for clarification.

  * address - ADR
  * telephone - TEL
  * email - EMAIL

For example, to get something like this in your vCard:

    <TEL>
      <WORK />
      <VOICE />
      <NUMBER>555-555-5555</NUMBER>
    </TEL>

Your configuration for `telephone` will probably look something like this:

    telephone = {
      work = {
        voice = true,
        number = 'telephoneNumber',
      },
    }

### Unsupported vCard fields

  * LABEL
  * AGENT
  * CATEGORIES
  * PRODID
  * CLASS

### Example Configuration

You can find an example configuration in the dev directory underneath the
directory that this file is located in.

# Missing Features

This set of plugins is missing a few features, some of which are really just ideas:

  * Implement non-plaintext authentication.
  * Use proper LDAP binding (LuaLDAP must be patched with http://prosody.im/patches/lualdap.patch, though)
  * Non-hardcoded LDAP groups (derive groups from LDAP queries)
  * LDAP-based MUCs (like a private MUC per group, or something)
  * This suite of plugins was developed with a POSIX-style setup in mind; YMMV. Patches to work with other setups are welcome!
  * Add ability for users to change their vCard/passwords/etc from within Prosody