# HG changeset patch # User Kim Alvefur # Date 1440427436 -7200 # Node ID 29f3d6b7ad1621541544835a4f49f668bf063567 # Parent 12ac88940fe32e0ca1ef3fb336162d5eb4cb46a0 Import wiki pages diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_addressing/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_addressing/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,9 @@ +#summary XEP-0033: Extended Stanza Addressing +#labels Stage-Alpha + += Introduction = + +This module is a partial implementation of [http://xmpp.org/extensions/xep-0033.html XEP-0033: Extended Stanza Addressing]. + += TODO = +Query external servers for support. \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_adhoc/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_adhoc/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,59 @@ +#summary XEP-0050: Ad-Hoc Commands +#labels Stage-Beta, Deprecated + += Introduction = + +implementation of [http://xmpp.org/extensions/xep-0050.html XEP-0050: Ad-Hoc Commands], which allows clients to execute commands on the Prosody server. This plugin adds no commands itself, see the other `mod_adhoc_*` plugins for those. + +This module along with the other adhoc modules in prosody-modules are included in Prosody as of 0.8, making this plugin unnecessary for users of this version and later. + += Details = + +Will offer any adhoc command registered via 'module:add_item("adhoc", ....)'. + + + += Usage = + +First copy (or symlink) the directory "adhoc" which contains mod_adhoc to your plugins directory. +Load mod_adhoc and then any module which provides an adhoc command, such as +mod_adhoc_cmd_ping. + +If you want to build your own adhoc command, just register your adhoc command module with +module:add_item and a descriptor for your command. + +A descriptor can be created like this: +{{{ +local adhoc_new = module:require "adhoc".new; +local descriptor = adhoc_new("Name", "node", handler); +module:add_item ("adhoc", descriptor) +}}} + +A handler gets 2 parameters. A data table and a state. + +The data table has 4 fields: +||to||The to attribute of the stanza to be handled|| +||from||The from attribute of the stanza to be handled|| +||action||The action to be performed as specified in the stanza to be handled|| +||form||If the to be handled stanza contains a form this will contain the form element|| + +The handler should return two items. A data table and a state. +The state will be saved and passed to the handler on invocation for any adhoc stanza with the same sessionid. If a session has ended the state returned should be nil. + +The returned table can have the following fields: +||*Name*||*Explanation*||*Required?*|| +||status||Status of the command (One of: "completed", "canceled", "error")||yes|| +||error||A table with the fields "type", "condition" and "message"||when status is "error"|| +||info||Informational text for display to the user||no|| +||warn||A warning for the user||no|| +||actions||The actions avaiable to the client||no|| +||form||A dataform to be filled out by the user||no|| +||result||A dataform of type result to be presented to the user||no|| +||other||Any other XML to be included in the response to the user||no|| + +For a simple module and details have a look at mod_adhoc_cmd_ping. + += Compatibility = +||0.6||Most commands work|| +||0.7||Works|| +||0.8||Included in Prosody|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_adhoc_account_management/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_adhoc_account_management/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,33 @@ +#summary Personal account management command +#labels Stage-Alpha + += Introduction = + +This module adds an ad-hoc command that lets an user change their +password. This is useful for clients that don't have support for +[http://xmpp.org/extensions/xep-0077.html XEP-0077] style password +changing. In the future, it may provide other account management +commands. + += Configuration = + +{{{ +modules_enabled = { + -- other modules -- + "adhoc_account_management", + +} + +close_sessions_on_password_change = true +require_current_password = true +require_confirm_password = true +}}} + +|| *Option* || *Default* || *Description* || +|| close_sessions_on_password_change || true || Changing password invalidates other sessions the user may have || +|| require_current_password || true || Add a field for the current password || +|| require_confirm_password || true || Add a field for confirming the current password || + += Todo = + +Suggestions welcome, diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_adhoc_cmd_admin/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_adhoc_cmd_admin/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,32 @@ +#summary Administrative adhoc commands +#labels Stage-Beta, Deprecated + += Introduction = + +This module contains administrative commands. + +Supported commands are: + * Add User + * Delete User + * End User Session + * Change User Password + * Get User Password + * Get User Roster + * Get User Statistics + * Get List of Online Users + * Send Announcement to Online Users + * Shut Down Service + +The goal is to implement many/all commands described in XEP-0133. + += Usage = + +Load mod_adhoc_cmd_admin after [mod_adhoc], you can then use the provided adhoc commands from your XEP-0050 compliant client. + += Compatibility = +||0.7||Works|| +||0.8||Included in Prosody (in mod_admin_adhoc)|| + += TODO = + + * Add more commands diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_adhoc_cmd_modules/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_adhoc_cmd_modules/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,14 @@ +#summary Module management via ad-hoc commands +#labels Stage-Beta, Deprecated + += Introduction = + +This module adds support for Loading, Reloading and Unloading of modules. + + += Usage = +Load this module after [mod_adhoc]. It can then be used from any XEP-0050 compliant client. + += Compatibility = +||0.7||Works|| +||0.8||Included in Prosody (in mod_admin_adhoc)|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_adhoc_cmd_ping/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_adhoc_cmd_ping/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,13 @@ +#summary Adhoc command ping +#labels Stage-Beta, Deprecated + += Introduction = + +implements the adhoc command 'ping'. + += Usage = +Just load it after [mod_adhoc] and you can execute the adhoc command 'ping' with any adhoc command aware jabber client. + += Compatibility = +||0.7||Works|| +||0.8||Included in Prosody (in mod_ping)|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_adhoc_cmd_uptime/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_adhoc_cmd_uptime/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,15 @@ +#summary Adhoc command to show the uptime +#labels Stage-Beta, Deprecated + += Introduction = + +Implements an uptime adhoc command. + + += Usage = + +Load this module after [mod_adhoc]. + += Compatibility = +||0.7||Works|| +||0.8||Included in Prosody (in mod_uptime)|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_admin_message/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_admin_message/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,24 @@ +#summary IM-based administration console +#labels Stage-Beta + += Introduction = + +This module provides a console over XMPP. +All the commands of the mod_admin_telnet module are available from an XMPP client. + +Only the Prosody admins (see the _admins_ list in the Prosody configuration file) can use this console. + += Installation = + +Copy the mod_admin_message directory into a directory Prosody will check for plugins (cf. [http://prosody.im/doc/installing_modules Installing modules]) and set up a component: + +{{{ + Component "console@example.com" "admin_message" +}}} + +"console@example.com" is the identifier of the XMPP console. + += Compatibility = +||trunk||Works|| +||0.9||Works|| +||<= 0.8||Not supported|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_admin_web/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_admin_web/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,33 @@ +#summary Web administration interface +#labels Stage-Beta += Introduction = + +This module provides a basic web administration interface. +It currently gives you access to Ad-Hoc commands on any virtual host or component that you are set as an administrator for in the Prosody config file. It also provides a live list of all S2S and C2S connections. + += Installation = + + # Copy the admin_web directory into a directory Prosody will check for plugins. (cf. [http://prosody.im/doc/installing_modules Installing modules]) + # Execute the contained get_deps.sh script from within the admin_web directory. (Requires wget, tar, and a basic shell) + += Configuration Details = + +"admin_web" needs to be added to the modules_enabled table of the host you want to load this module on. + +By default the interface will then be reachable under `http://example.com:5280/admin`, or `https://example.com:5281/admin`. + +The module will automatically enable two other modules if they aren't already: mod_bosh (used to connect to the server from the web), and mod_admin_adhoc (which provides admin commands over XMPP). + +{{{ +VirtualHost "example.com" + modules_enabled = { + ..... + "admin_web"; + ..... + } +}}} + += Compatibility = +||trunk||Works|| +||0.9||Works|| +||<= 0.8||Not supported|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_archive/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_archive/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,52 @@ +#summary XEP-0136: Message Archiving +#labels Stage-Unsupported + +---- +This page is held here for reference only. mod_archive is no longer supported. + +Similar modules: + + * [mod_mam] + * [mod_mam_sql] + * [http://prosody.im/files/mod_log_messages.lua mod_log_messages] (mainly useful as a template for people making their own logging module) + +*Note:* If you are an administrator looking for a module just for centrally logging messages passing to/from users on your server, this probably isn't the module you are looking for (mod_archive is for user-managed archives). We'd really like to hear about your requirements to make a module more tailored to this kind of use-case though (especially how/where you would like the messages stored)... drop us an email at developers@prosody.im to let us know. + +---- + += Introduction = + +Currently many XMPP clients save the messages locally and it's not convenient or even possible to retrieve the historical messages, especially when one switches the clients a lot. + += Details = + +This module keeps an archive of incoming and outgoing messages for each user on the server, and allows the user to query and manage this archive using the XMPP extension described in [http://xmpp.org/extensions/xep-0136.html XEP-0136: Message Archiving]. + +*Note:* If you are an administrator looking for a module just for centrally logging messages passing to/from users on your server, this probably isn't the module you are looking for (mod_archive is for user-managed archives). We'd really like to hear about your requirements to make a module more tailored to this kind of use-case though (especially how/where you would like the messages stored)... drop us an email at developers@prosody.im to let us know. + += Usage = + +First copy the module to the prosody plugins directory. + +Then add "archive" to your modules_enabled list: +{{{ + modules_enabled = { + -- ... + "privacy", + "archive", + -- ... +}}} + += Configuration = +|| *Name* || *Description* || *Type* || *Default value* || +|| default_max || the maximum number of items to return when requesting collection list or archived messages || integer || 100 || +|| force_archiving || archive every message automatically, and do NOT consider the preferences || boolean || false || +|| auto_archiving_enabled || applied when no any preferences available || boolean || true || + + += Compatibility = +|| 0.7.0 || Works || + += TODO = + * consider '`exactmatch`' attribute when do JID matching. + * return a `` error when the client set the value of the '`save`' attribute to '`stream`'. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_archive_muc/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_archive_muc/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,38 @@ +#summary XEP-xxxx: Message Archive Management +#labels Stage-Alpha, Deprecated + += Introduction = + +Implementation of [http://matthewwild.co.uk/uploads/message-archive-management.html XEP-xxxx: Message Archive Management]. Like [mod_archive] but much simpler. + += Details = + +The server will have the ability to archive muc messages passing through. + += Usage = + +First copy the module to the prosody plugins directory. + +Then add "archive_muc" to your modules_enabled list: +{{{ + modules_enabled = { + -- ... + "privacy", + "archive_muc", + -- ... +}}} + += Configuration = + +|| *Name* || *Description* || *Type* || *Default value* || +|| auto_muc_archiving_enabled || applied when no any preferences available || boolean || true || + += Compatibility = +|| 0.7.0 || Works || + += TODO = +Test + + + + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_any/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_any/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,16 @@ +#summary Authentication module that accepts any username and password +#labels Type-Auth + += Introduction = + +This module accepts any username and password, which can be useful for testing. + += Configuration = + +{{{ +authentication = "any" +}}} + += Compatibility = + +Should work with 0.8 and above. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_ccert/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_ccert/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,29 @@ +#summary Client Certificate authentication module +#labels Stage-Alpha,Type-Auth + += Introduction = + +This module implements PKI-style client certificate authentication. +You will therefore need your own Certificate Authority. +How to set that up is beyond the current scope of this document. + += Configuration = + +{{{ + +authentication = "ccert" +certificate_match = "xmppaddr" -- or "email" + +c2s_ssl = { + capath = "/path/to/dir/with/your/ca" +} + +}}} + +`capath` should be pointed to a directory with your own CA certificate. You will need to run `c_rehash` in it. + += Compatibility = + +||trunk||Works|| +||0.9 and earlier||Doesn't work|| +||0.10 and later||Works|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_dovecot/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_dovecot/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,50 @@ +#summary Dovecot authentication module +#labels Stage-Alpha,Type-Auth + += Introduction = + +This is a Prosody authentication plugin which uses Dovecot as the backend. + += Configuration = + +As with all auth modules, there is no need to add this to modules_enabled. Simply add in the global section, or for the relevant hosts: + +{{{ + authentication = "dovecot" +}}} + +These options are used by mod_auth_dovecot: + +|| *Name* || *Description* || *Default value* || +|| dovecot_auth_socket || Path to the Dovecot auth socket || "/var/run/dovecot/auth-login" || +|| auth_append_host || If true, sends the bare JID as authzid. || false || + +The Dovecot user and group must have access to connect to this socket. You can create a new dedicated socket for Prosody too. Add the below to the _socket listen_ section of /etc/dovecot/dovecot.conf, and match the socket path in Prosody's dovecot_auth_socket setting. + +{{{ + socket listen { + ... + client { + path = /var/spool/prosody/private/auth-client + mode = 0660 + user = prosody + group = prosody + } +}}} + +Make sure the socket directories exist and are owned by the Prosody user. + +Note: Dovecot uses UNIX sockets by default. luasocket is compiled with UNIX socket on debian/ubuntu by default, but is not on many other platforms. +If you run into this issue, you would need to either recompile luasocket with UNIX socket support, or use Dovecot 2.x's TCP socket support. + +== TCP socket support for Dovecot 2.x == + +Dovecot 2.x includes TCP socket support. These are the relevant mod_auth_dovecot options: + +|| *Name* || *Description* || *Default value* || +|| dovecot_auth_host || Hostname to connect to. || "127.0.0.1" || +|| dovecot_auth_port || Port to connect to. || _(this value is required)_ || + += Compatibility = +||trunk||Works|| +||0.8||Works|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_external/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_external/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,85 @@ +#summary Authentication via external script/process +#labels Stage-Alpha,Type-Auth + += Introduction = + +Allow client authentication to be handled by an external script/process. + += Installation = + +mod_auth_external depends on a Lua module called [http://www.tset.de/lpty/ lpty]. You can install it on many platforms using [http://luarocks.org/ LuaRocks], for example: + +{{{ + sudo luarocks install lpty +}}} + +Note: Earlier versions of the module did not depend on lpty. While using the newer version is strongly recommended, you can find the [https://prosody-modules.googlecode.com/hg-history/50ee38e95e754bf1034d980364f93564028b2f34/mod_auth_external/mod_auth_external.lua older version here] if you need it (revision 50ee38e95e75 of the repository). + += Configuration = + +As with all auth modules, there is no need to add this to modules_enabled. Simply add in the global section, or for the relevant hosts: + +{{{ + authentication = "external" +}}} + +These options are specific to mod_auth_external: + +||external_auth_protocol||May be "generic" or "ejabberd" (the latter for compatibility with ejabberd external auth scripts. Default is "generic".|| +||external_auth_command||The command/script to execute.|| + +Two other options are also available, depending on whether the module is running in 'blocking' or 'non-blocking' mode: +||external_auth_timeout||blocking||The number of seconds to wait for a response from the auth process. Default is 5.|| +||external_auth_processes||non-blocking||The number of concurrent processes to spawn. Default is 1, increase to handle high connection rates efficiently.|| + +== Blocking vs non-blocking == + +Non-blocking mode is automatically activated when: + + * Running Prosody trunk ([http://prosody.im/nightly/ nightly] build 414+). + * [http://prosody.im/doc/libevent libevent] is enabled in the config, and LuaEvent is available. + * lpty (see installation above) is version 1.0.1 or later. + += Protocol = + +Prosody executes the given command/script, and sends it queries. + +Your auth script should simply read a line from standard input, and write the result to standard output. +It must do this in a loop, until there's nothing left to read. Prosody can keep sending more lines to the script, +with a command on each line. + +Each command is one line, and the response is expected to be a single line containing "0" for failure or "1" for success. +Your script must respond with "0" for anything it doesn't understand. + +There are three commands used at the moment: + +== auth == +Check if a user's password is valid. + +Example: {{{auth:username:example.com:abc123}}} + +Note: The password can contain colons. Make sure to handle that. + +== isuser == +Check if a user exists. + +Example: {{{isuser:username:example.com}}} + +== setpass == +Set a new password for the user. Implementing this is optional. + +Example: {{{setpass:username:example.com:abc123}}} + +Note: The password can contain colons. Make sure to handle that. + +== ejabberd compatibilty == +ejabberd implements a similar protocol. The main difference is that Prosody's protocol is line-based, while ejabberd's is length-prefixed. + +Add this to your config if you need to use an ejabberd auth script: +{{{ + external_auth_protocol = "ejabberd" +}}} + += Compatibility = +||0.8||Works|| +||0.9||Works|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_ha1/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_ha1/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,47 @@ +#summary Authentication module for 'HA1' hashed credentials in a text file, as used by reTurnServer +#labels Stage-Beta,Type-Auth + += Introduction = + +This module authenticates users against hashed credentials stored in a plain text file. The format is the same as that used by reTurnServer. + += Configuration = + +|| *Name* || *Default* || *Description* || +|| auth_ha1_file || auth.txt || Path to the authentication file|| + +Prosody reads the auth file at startup and on reload (e.g. SIGHUP). + += File Format = + +The file format is text, with one user per line. Each line is broken into four fields separated by colons (':'): + +{{{ +username:ha1:host:status +}}} + +|| *Field* || *Description* || +||username||The user's login name|| +||ha1||An MD5 hash of "username:host:password"|| +||host||The XMPP hostname|| +||status||The status of the account. Prosody expects this to be just the text "authorized"|| + +More info can be found [https://github.com/resiprocate/resiprocate/blob/master/reTurn/users.txt here]. + +== Example == + +{{{ +john:2a236a1a68765361c64da3b502d4e71c:example.com:authorized +mary:4ed7cf9cbe81e02dbfb814de6f84edf1:example.com:authorized +charlie:83002e42eb4515ec0070489339f2114c:example.org:authorized +}}} + +Constructing the hashes can be done manually using any MD5 utility, such as md5sum. For example the user 'john' has the password 'hunter2', and his hash can be calculated like this: + +{{{ +echo -n "john:example.com:hunter2" | md5sum - +}}} + += Compatibility = +||0.9||Works|| +||0.10||Works|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_imap/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_imap/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,18 @@ +#summary IMAP authentication module +#labels Stage-Alpha,Type-Auth + += Introduction = + +This is a Prosody authentication plugin which uses a generic IMAP server as the backend. + += Configuration = + +|| option || type || default || +|| imap_auth_host || string || localhost || +|| imap_auth_port || number || nil || +|| imap_auth_realm || string || Same as the sasl_realm option || +|| imap_auth_service_name || string || nil || +|| auth_append_host || boolean || false || +|| auth_imap_verify_certificate || boolean || true || +|| auth_imap_ssl || table || A SSL/TLS config || + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_internal_yubikey/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_internal_yubikey/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,62 @@ +#summary Two-factor authentication using Yubikeys +#labels Stage-Beta,Type-Auth + += Introduction = + +A [http://www.yubico.com/yubikey YubiKey] is a small USB one-time-password (OTP) generator. + +The idea behind one-time-passwords is that they can, well, only be used once. After authenticating with an OTP the only way to log in again is to calculate another one and use that. The only (practical) way to generate this is by inserting the (correct) Yubikey and pressing its button. Acting as a USB keyboard it then "types" the OTP into the password prompt of your XMPP client. + += Details = + +This self-contained module handles all the authentication of Yubikeys, it does not for example depend on the Yubico authentication service, or on any external system service such as PAM. + +When this module is enabled, only PLAIN authentication is enabled on the server (because Prosody needs to receive the full password from the client to decode it, not a hash), so connection encryption will automatically be enforced by Prosody. + +Even if the password is intercepted it is of little use to the attacker as it expires as soon as it is used. Additionally the data stored in Prosody's DB is not enough to authenticate as the user if stolen by the attacker. + +When this module is in use each user can either use normal password authentication, or instead have their account associated with a Yubikey - at which point only the key will work. + += Installation = + +Requires bitlib for Lua, and yubikey-lua from http://code.matthewwild.co.uk/yubikey-lua . When properly installed, the command `lua -lbit -lyubikey` should give you a Lua prompt with no errors. + += Configuration = + +== Associating keys == +Each Yubikey is configured with several pieces of information that Prosody needs to know. This information is shown in the Yubikey personalization tool (the _yubikey-personalization_ package in Debian/Ubuntu). + +To associate a Yubikey with a user, run the following prosodyctl command: +{{{ + prosodyctl mod_auth_internal_yubikey associate user@example.com +}}} + +This will run you through a series of questions about the information Prosody requires about the key configuration. + +*NOTE:* All keys used with the server (rather, with a given host) must all have a "public ID" (uid) of the same length. This length must be set in the Prosody config with the 'yubikey_prefix_length' option. + +Instead of entering the information interactively it is also possible to specify each option on the command-line (useful for automation) via --option="value". The valid options are: + +|| password || The user's password (may be blank) || +|| fixed || The public ID that the Yubikey prefixes to the OTP || +|| uid || The private ID that the Yubikey encrypts in the OTP || +|| key || The AES key that the Yubikey uses (may be blank if a global shared key is used, see below) || + +If a password is configured for the user (recommended) they must enter this into the password box immediately before the OTP. This password doesn't have to be incredibly long or secure, but it prevents the Yubikey being used for authentication if it is stolen and the password isn't known. + +== Configuring Prosody == + +To use this module for authentication, set in the config: +{{{ + authentication = "internal_yubikey" +}}} + +Module-specific options: + +|| yubikey_prefix_length || (*REQUIRED*) The length of the public ID prefixed to the OTPs || +|| yubikey_global_key || If all Yubikeys use the same AES key, you can specify it here. Pass --key="" to prosodyctl when associating keys. || + +If switching from a plaintext storage auth module then users without Yubikeys associated with their account can continue to use their existing passwords as normal, otherwise password resets are required. + += Compatibility = +||0.8|| Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_joomla/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_joomla/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,27 @@ +#summary Joomla authentication module +#labels Stage-Alpha,Type-Auth + += Introduction = + +This module allows you to authenticate against an Joomla database. + += Configuration = + +SQL connection paramaters are identical to those of [https://prosody.im/doc/modules/mod_storage_sql SQL storage] except for an additional 'prefix' parameter that defaults to 'jos_'. + +{{{ +authentication = "joomla" +sql = { -- See documentation for SQL storage + driver = "MySQL"; + database = "joomla"; + host = "localhost"; + username = "prosody"; + password = "secretpassword"; + + prefix = "jos_"; +} +}}} + += Compatibility = + +Prosody 0.8+ diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_ldap/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_ldap/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,51 @@ +#summary LDAP authentication module +#labels Stage-Alpha,Type-Auth + +_*Note:* A modified version of this module is available, but is not yet committed here. The plan is to merge them, for more info see [http://groups.google.com/group/prosody-dev/browse_thread/thread/282e876116ae4177/906121492495ad35#906121492495ad35 this thread]._ + += Introduction = + +This is a Prosody authentication plugin which uses LDAP as the backend. + += Dependecies = + +This module depends on [http://www.keplerproject.org/lualdap/ LuaLDAP] for connecting to an LDAP server. + += Configuration = + +Copy the module to the prosody modules/plugins directory. + +In Prosody's configuration file, under the desired host section, add: +{{{ + authentication = "ldap" + ldap_base = "ou=people,dc=example,dc=com" +}}} + +LDAP options are: +|| *Name* || *Description* || *Default value* || +|| ldap_server || Space-separated list of hostnames or IPs, optionally with port numbers (e.g. "localhost:8389") || "localhost" || +|| ldap_rootdn || The distinguished name to auth against || "" (anonymous) || +|| ldap_password || Password for rootdn || "" || +|| ldap_filter || Search filter, with $user and $host substituded for user- and hostname || "(uid=$user)" || +|| ldap_scope || Search scope. other values: "base" and "subtree" || "onelevel" || +|| ldap_tls || Enable TLS (StartTLS) to connect to LDAP (can be true or false). The non-standard 'LDAPS' protocol is not supported. || false || +|| ldap_base || LDAP base directory which stores user accounts || This is required || +|| ldap_mode || How passwords are validated. || "bind" || + +*Note:* lua-ldap reads from /etc/ldap/ldap.conf and other files like +~prosody/.ldaprc if they exist. Users wanting to use a particular TLS +root certificate can specify it in the normal way using TLS_CACERT in +the OpenLDAP config file. + += Modes = + +The "getpasswd" mode requires plain text access to passwords in LDAP and +feeds them into Prosodys authentication system. This enables more secure +authentication mechanisms but does not work for all deployments. + +The "bind" performs an LDAP bind, does not require plain text access to +passwords but limits you to the PLAIN authentication mechanism. + += Compatibility = + +|| 0.8 and above || should work || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_ldap2/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_ldap2/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,19 @@ +#summary Another take on LDAP authentication +#labels Type-Auth + += Introduction = + +See [mod_lib_ldap] for more information. + += Installation = + +You must install [mod_lib_ldap] to use this module. After that, you need only copy mod_auth_ldap2.lua to your Prosody installation's plugins directory. + += Configuration = + +In addition to the configuration that [mod_lib_ldap] itself requires, this plugin also requires the following fields in the ldap section: + + * user.filter + * admin (optional) + +See the README.md distributed with [mod_lib_ldap] for details. \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_pam/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_pam/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,26 @@ +#summary PAM authentication module +#labels Stage-Alpha,Type-Auth + += Introduction = + +This module makes Prosody authenticate users against PAM (Linux Pluggable Authentication Modules) + += Setup = + +Create a {{{/etc/pam.d/xmpp}}} with something like this: + +{{{ +auth [success=1 default=ignore] pam_unix.so obscure sha512 nodelay +auth requisite pam_deny.so +auth required pam_permit.so +}}} + +And switch authentication provider in the Prosody config: + +{{{ +authentication = "pam" +}}} + += Compatibility = + +Compatible with 0.9 and up diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_phpbb3/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_phpbb3/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,25 @@ +#summary PHPBB3 authentication module +#labels Stage-Alpha,Type-Auth + += Introduction = + +This module allows you to authenticate against an PHPBB3 database. + += Configuration = + +SQL connection paramaters are identical to those of [https://prosody.im/doc/modules/mod_storage_sql SQL storage]. + +{{{ +authentication = "phpbb3" +sql = { -- See documentation for SQL storage + driver = "MySQL"; + database = "phpbb3"; + host = "localhost"; + username = "prosody"; + password = "secretpassword"; +} +}}} + += Compatibility = + +Prosody 0.8+ diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_sql/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_sql/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,23 @@ +#summary SQL Database authentication module +#labels Type-Auth,Stage-Stable + += Introduction = + +Allow client authentication to be handled by an SQL database query. + +Unlike mod_storage_sql (which is supplied with Prosody) this module allows for custom schemas (though currently it is required to edit the source). + += Configuration = + +As with all auth modules, there is no need to add this to modules_enabled. Simply add in the global section, or for the relevant hosts: + +{{{ + authentication = "sql" +}}} + +This module reuses the database configuration of [http://prosody.im/doc/modules/mod_storage_sql mod_storage_sql] (the 'sql' option), which you can set even if you are not using SQL as Prosody's primary storage backend. + +The query is currently hardcoded in the module, so you will need to edit the module to change it. The default query is compatible with jabberd2 DB schema. + += Compatibility = +||0.8||Works|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auth_wordpress/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_wordpress/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,26 @@ +#summary Wordpress authentication module +#labels Stage-Alpha,Type-Auth + += Introduction = + +This module allows you to authenticate against an Wordpress database. + += Configuration = + +SQL connection paramaters are identical to those of [https://prosody.im/doc/modules/mod_storage_sql SQL storage]. + +{{{ +authentication = "wordpress" +wordpress_table_prefix = "wp_" -- default table prefix +sql = { -- See documentation for SQL storage + driver = "MySQL"; + database = "my_wordpress"; + host = "localhost"; + username = "prosody"; + password = "secretpassword"; +} +}}} + += Compatibility = + +Prosody 0.8+ diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auto_accept_subscriptions/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auto_accept_subscriptions/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,27 @@ +#summary Automatically accept incoming subscription requests on behalf of users +#labels Stage-Beta + += Introduction = + +In some environments where all users on the system have mutual trust in each other, it's sometimes fine to skip the usual authorization process to +add someone to your contact list and see their status. + +This module sets Prosody to automatically accept incoming subscription authorization requests, and add the contact to the user's contact list, without intervention from the user. + += Configuration = +Simply add the module to your modules_enabled list like any other module: + +{{{ + modules_enabled = { + ... + "auto_accept_subscriptions"; + ... + } +}}} + +This module has no further configuration. + += Compatibility = +||trunk||Works|| +||0.9||Works|| +||0.8||Works|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_auto_activate_hosts/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auto_activate_hosts/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,26 @@ +#summary Automatically activate/deactivate hosts on reload +#labels Stage-Beta + += Introduction = + +By default Prosody does not automatically activate/deactivate hosts when they are added to and removed from the configuration. + +This module will activate/deactivate hosts as necessary when the configuration is reloaded. + +This module was sponsored by [http://exa-networks.co.uk/ Exa Networks]. + += Configuration = +Add the module to your *global* modules_enabled list: + +{{{ + modules_enabled = { + ... + "auto_activate_hosts"; + ... + } +}}} + +There are no configuration options for this module. + += Compatibility = +|| 0.9 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_bidi/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_bidi/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,15 @@ +#summary XEP-0288: Bidirectional Server-to-Server Connections +#labels Stage-Alpha + += Introduction = + +This module implements [http://xmpp.org/extensions/xep-0288.html XEP-0288: Bidirectional Server-to-Server Connections]. It allows servers to use a single connection for sending stanzas to each other, instead of two connections (one for stanzas in each direction). + +Install and enable it like any other module. It has no configuration. + += Compatibility = + +||trunk||Works|| +||0.9||Works|| +||0.8||Works (use the 0.8 repo)|| + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_block_registrations/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_block_registrations/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,39 @@ +#summary Prevent registration of user accounts according to policies +#labels Stage-Beta + += Introduction = + +On a server with public registration it is usually desirable to prevent registration of certain "reserved" accounts, such as "admin". + +This plugin allows you to reserve individual usernames, or those matching certain patterns. It also allows you to ensure that usernames conform to a certain pattern. + += Configuration = + +Enable the module as any other: + +{{{ + modules_enabled = { + "block_registrations"; + } +}}} + +You can then set some options to configure your desired policy: + +|| *Option* || *Default* || *Description* || +|| block_registrations_users || { "admin" } || A list of reserved usernames || +|| block_registrations_matching || { } || A list of [http://www.lua.org/manual/5.1/manual.html#5.4.1 Lua patterns] matching reserved usernames (slower than block_registrations_users) || +|| block_registrations_allow || nil || A pattern that registered user accounts MUST match to be allowed || + +Some examples: + +{{{ + block_registrations_users = { "admin", "root", "xmpp" } + block_registrations_matching = { + "master$" -- matches anything ending with master: postmaster, hostmaster, webmaster, etc. + } + block_registrations_allow = "^[a-zA-Z0-9_-.]$" -- Allow only simple ASCII characters in usernames +}}} + += Compatibility = +|| 0.9 || Works || +|| 0.8 || Should work || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_blocking/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_blocking/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,34 @@ +#summary XEP-0191: Simple Communications Blocking support +#labels Stage-Alpha + += Introduction = + +Privacy lists are a widely implemented protocol for instructing your server on blocking communications with selected users and services. + +However experience has shown that the power and flexibility of the rule-based system that privacy lists allow is very often much more complex than the user needs, and that in most cases a simple block on all communications to or from a list of specified JIDs would suffice. + +Such a protocol would also allow much simpler user interface design than the current attempts at full privacy list interfaces. + += Details = + +Simple Communications Blocking was developed to solve the above issues, and allows the client to manage a simple list of blocked JIDs. This plugin implements support for that protocol in Prosody, however the actual blocking is still managed by mod_privacy, so it is *required* for that plugin to be loaded (this may change in future). + +An XEP-0191 implementation without dependency on mod_privacy is available in Prosody 0.10 as [https://prosody.im/doc/modules/mod_blocklist mod_blocklist]. + += Configuration = +Simply ensure that mod_privacy (or mod_privacy_lists in 0.10+) and mod_blocking are loaded in your modules_enabled list: + +{{{ + modules_enabled = { + -- ... + "privacy", -- or privacy_lists in Prosody 0.10+ + "blocking", + -- ... +}}} + += Compatibility = +||0.10||Works but will conflict with mod_blocklist|| +||0.9||Works|| +||0.8||Works|| +||0.7||Works|| +||0.6||Doesn't work|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_broadcast/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_broadcast/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,25 @@ +#summary Broadcast a message to online users +#labels Stage-Stable + += Introduction = + +This module largely duplicates the functionality of the standard mod_announce that is included with Prosody. It was developed for compatibility with some clients (e.g. iChat) that do not support ad-hoc commands or sending to JIDs with the format 'example.com/announce/online'. + +It may also be useful in other specific cases. + += Configuration = + +{{{ +Component "broadcast@example.com" "broadcast" +}}} + +By default, only server admins are allowed to post to this address. You can override this, by specifying the 'broadcast_senders' option: + +{{{ +Component "broadcast@example.com" "broadcast" + broadcast_senders = { "user1@example.com", "user2@example.com" } +}}} + += Compatibility = +||0.9||Works|| +||0.10||Works|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_c2s_conn_throttle/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_c2s_conn_throttle/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,22 @@ +#summary c2s connections throttling module +#labels Stage-Stable + += Introduction = + +This module allows to throttle those client connections which exceed a n*seconds limit. + += Usage = + +Copy the module folder into your prosody modules directory. +Place the module between your enabled modules either into the global or a vhost section. + +Optional configuration directives: + +cthrottler_logins_count = 3 -- number of login attempts allowed, default is 3 +cthrottler_time = 60 -- .. in number of seconds, default is 60 + + += Info = + + * 0.8, works + * 0.9, works diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_c2s_limit_sessions/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_c2s_limit_sessions/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,10 @@ +#summary Limit number of resources a user may connect + += Introduction = + +This module lets you limit number of resources a user may connect. + += Configuration = + +After installing and adding the module to `modules_enabled` you can specify a limit with `max_resources` wich defaults to 10. + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_candy/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_candy/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,20 @@ +#summary Serve Candy from prosody + += Introduction = +This is a very simple demo module showing how to serve a BOSH-using web app from prosody. + += Installation = + +[http://prosody.im/doc/installing_modules Install] and [http://prosody.im/doc/modules_enabled enable] the module just like any other. Note the included HTML file in the www_files directory, this directory needs to be in the same place as the module. + +You then need to download Candy and unpack it into the www_files directory, for example with curl: + +{{{ +curl -L http://github.com/candy-chat/candy/tarball/master | tar xzfv - --strip-components=1 +}}} + +After the module has been loaded, Candy will by default be reachable from `http://example.com:5280/candy/` + += Compatibility = +||trunk||Works|| +||0.9||Works|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_captcha_registration/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_captcha_registration/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,37 @@ +#summary provides captcha protection for registration form +#labels Stage-Beta + += Introduction = + +Prosody-captcha is a little modification of prosody's "mod_register.lua" module that provides captcha protection for registration form. + += Installation = +First of all you should build and install lua bindings for libgd — [https://github.com/ittner/lua-gd/ lua-gd]. + +Then clone repsository lua-captcha: + +*{{{ $ git clone https://github.com/mrDoctorWho/lua-captcha }}}* + +install it: + +*{{{ $ make install }}}* + += Configuration = + +After that you would configure prosody. This module requires from you 4 fields, you should add this into your VirtualHost entry. + +{{{ +captcha_config = { + dir = "/tmp"; -- Directory used to storage captcha images. Please make sure prosody user allowed to write there. + timeout = 60; -- Timeout when captcha will expire + web_path = "challenge"; -- Web path used to separate main prosody site from itself modules. + font = "/usr/lib/prosody/FiraSans-Regular.ttf" -- Font used for captcha text +} +}}} + +You can run script "install.lua" to install this or instead of that while prosody developers didn't accepted "dataforms" changes you should replace standard prosody "dataforms.lua" located in ubuntu in /usr/lib/prosody/util by another one from this repository. You should do the same thing with "mod_register.lua" located in ubuntu in /usr/lib/prosody/modules. + +After this all you can try to register on your server and see the captcha. + += TODO = + * Maybe use recaptcha instead of libgd. \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_carbons/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_carbons/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,37 @@ +#summary Message Carbons +#labels Stage-Beta + += Introduction = + +This module implements [http://xmpp.org/extensions/xep-0280.html XEP-0280: Message Carbons], +allowing users to maintain a shared and synchronized view of all +conversations across all their online clients and devices. + += Configuration = + +As with all modules, you enable it by adding it to the modules_enabled list. + +{{{ + modules_enabled = { + ... + "carbons"; + ... + } +}}} + +The module has no further configuration. + += Clients = +Clients that support XEP-0280: + * [http://gajim.org/ Gajim] (Desktop) + * [http://adium.im/ Adium (1.6)] (Desktop - OS X) + * [http://yaxim.org/ Yaxim] (Mobile - Android) + * [https://play.google.com/store/apps/details?id=eu.siacs.conversations Conversations] (Mobile - Android) + * [http://poezio.eu/en/ poezio] (Console) + + += Compatibility = +|| 0.8 || Works || +|| 0.9 || Works || +|| 0.10 || Included with prosody || +|| trunk || Included with prosody || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_checkcerts/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_checkcerts/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,26 @@ +#summary Certificate expiry reminder + += Introduction = + +This module periodically checks your certificate to see if it is about to +expire soon. The time before expiry is printed in the logs. About a +week before a certificate expires, reminder messages will be sent to +admins. + += Configuration = + +Simply add the module to the `modules_enabled` list. You can optionally +configure how long before expiry to start sending messages to admins. + +{{{ +modules_enabled = { + ... + "checkcerts" +} +checkcerts_notify = 7 -- ( in days ) +}}} + += Compatibility = + +Needs LuaSec 0.5+ + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_cleanup_http/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_cleanup_http/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,23 @@ +#summary http "spring cleans" module +#labels Stage-Beta, Deprecated + += Details = + +Auto cleans handlers and open unused http ports (only on server_select) for BOSH/HTTP modules. + += Usage = + +Copy both files into prosody's module directory and place 'em into your enabled modules into the configuration file's global section. + +Required parameters, example: +{{{ +local bosh_mod_name_ports_conf_var_reference = { { interface = { "127.0.0.1" }, port = 5280 } } +cleanup_http_modules = { ["bosh_mod_name"] = bosh_mod_name_ports_conf_var_reference, ["bosh_mod_name_unreferenced"] = { { interface = { "127.0.0.1" }, port = 5280 } } } +}}} + +You can either reference other local variables present in the configuration (see above, cleanup_http_modules needs to be placed after those in that case) or duplicate 'em (see bosh_mod_name_unreferenced). + += Compatibility = + + * 0.9/trunk works + * 0.8 works diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_client_certs/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_client_certs/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,70 @@ +#summary Client-side certificate management for Prosody +#labels Stage-Alpha + += Introduction = +[http://xmpp.org/extensions/xep-0257.html XEP-0257] specifies a protocol for clients to store and manage client side certificates. When a client presents a stored client side certificate during the TLS handshake, it can log in without supplying a password (using SASL EXTERNAL). This makes it possible to have multiple devices accessing an account, without any of them needing to know the password, and makes it easier to revoke access for a single device. + + += Details = + +Each user can add their own certificates. These do not need to be signed by a trusted CA, yet they do need to be valid at the time of logging in and they should include an subjectAltName with otherName "id-on-xmppAddr" with the JID of the user. + +== Generating your certificate == + + # To generate your own certificate with a "id-on-xmppAddr" attribute using the command line {{{openssl}}} tool, first create a file called {{{client.cnf}}} with contents: +{{{ +[req] +prompt = no +x509_extensions = v3_extensions +req_extensions = v3_extensions +distinguished_name = distinguished_name + +[v3_extensions] +extendedKeyUsage = clientAuth +keyUsage = digitalSignature,keyEncipherment +basicConstraints = CA:FALSE +subjectAltName = @subject_alternative_name + +[subject_alternative_name] +otherName.0 = 1.3.6.1.5.5.7.8.5;FORMAT:UTF8,UTF8:hamlet@shakespeare.lit + +[distinguished_name] +commonName = Your Name +emailAddress = hamlet@shakespeare.lit +}}} + # Replace the values for {{{otherName.0}}} and {{{commonName}}} and {{{emailAddress}}} with your own values. The JID in {{{otherName.0}}} can either be a full JID or a bare JID, in the former case, the client can only use the resource specified in the resource. There are many other fields you can add, however, for SASL EXTERNAL, they will have no meaning. You can add more JIDs as {{{otherName.1}}}, {{{otherName.2}}}, etc. + # Create a private key (as an example, a 4096 bits RSA key): +{{{ +openssl genrsa -out client.key 4096 +}}} + # Create the certificate request: +{{{ +openssl req -key client.key -new -out client.req -config client.cnf -extensions v3_extensions +}}} + # Sign it yourself: +{{{ +openssl x509 -req -days 365 -in client.req -signkey client.key -out client.crt -extfile client.cnf -extensions v3_extensions +}}} + The 365 means the certificate will be valid for a year starting now. + +The {{{client.key}}} *must* be kept secret, and is only needed by clients connecting using this certificate. The {{{client.crt}}} file contains the certificate that should be sent to the server using XEP-0257, and is also needed by clients connecting to the server. The {{{client.req}}} file is not needed anymore. + += Configuration = + +(None yet) + += Compatibility = + +||0.9||Works|| +||0.8||Untested. Probably doesn't.|| + += Clients = + +(None?) + += TODO = +Possible options to add to the configuration: + * Require certificates to be signed by a trusted CA. + * Do not require a id-on-xmppAddr + * Remove expired certs after a certain time + * Limit the number of certificates per user \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_compat_muc_admin/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_compat_muc_admin/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,16 @@ +#summary COMPAT Module for old clients using wrong namespaces in MUC's affiliation manipulations. +#labels Stage-Beta + += Details = + +Adds compatibility for old clients/libraries attempting to change affiliations and retrieve 'em sending the < http://jabber.org/protocol/muc#owner > xmlns instead of < http://jabber.org/protocol/muc#admin >. + += Usage = + +Copy the plugin into your prosody's modules directory. + +And add it between the enabled muc component's modules + += Compatibility = + + * 0.7-0.9.x diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_component_roundrobin/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_component_roundrobin/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,13 @@ +#summary Component round-robin load balancing module + += Introduction = + +This module enables multiple instances of external components to connect at the same time, and does round-robin load-balancing of incoming stanzas. + += Example = + +{{{ + Component "test.example.com" + modules_enabled = { "component_roundrobin" } + -- Other component options such as secrets here +}}} diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_conformance_restricted/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_conformance_restricted/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,11 @@ +#summary Send restricted XML for conformance testing + += Introduction = + +This module sends processing instructions, comments, DTDs and a +non predefined entity (defined by the DTD) to the requesting entity. + += Usage = + +Send "PI", "comment", "DTD" or "entity" to , while +directly connected to the Prosody instance. \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_couchdb/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_couchdb/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,25 @@ +#summary A CouchDB backend for Prosody +#labels Stage-Alpha,Type-Storage + +_*Note:* This module needs updating to the 0.8 storage module API._ + += Introduction = + +This is an experimental Prosody backend for CouchDB. + += Configuration = +In your config file, under the relevant host, add: +{{{ +datastore = "couchdb"; +couchdb_url = "http://127.0.0.1:5984/database-name"; +}}} + += Compatibility = + +This module was developed as a prototype during development of the storage provider API in Prosody 0.8. The final storage provider API is different, so this module needs updates to work. + += Quirks = + +This implementation is a work in progress. + + * The data stored in couchdb is limited to: account data, rosters, private XML and vCards \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_csi/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_csi/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,16 @@ +#summary Client State Indication support + += Introduction = + +This module implements Client State Indication, a way for mobile clients +to tell the server that they are sitting in someones pocket and would +rather not get some less urgent things pushed to it. + += Configuration = + +There is no configuration for this module, just add it to modules_enabled as normal. + += Compatibility = + +||0.9||Works|| + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_csi_compat/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_csi_compat/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,14 @@ +#summary Implement the google:queue protocol and map to mod_csi events + += Introduction = + +This module implements the google:queue protocol and maps it to [mod_csi] events. + += Configuration = + +There is no configuration for this module, just add it to modules_enabled as normal. + += Compatibility = + +||0.9||Works|| + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_data_access/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_data_access/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,67 @@ +#summary HTTP access to prosody’s storage mechanism + += Introduction = + +This module gives HTTP access to prosody’s storage mechanism. It uses normal HTTP verbs and [http://tools.ietf.org/html/rfc2617 Basic HTTP authentication], so you could call it RESTful if you like buzzwords. + += Syntax = + +To Fetch data, issue a normal GET request +{{{ + GET /data[//]/[/] HTTP/1.1 + Authorization: + + -- OR -- + + PUT|POST /data[//]/ HTTP/1.1 + Content-Type: text/x-lua | application/json + + +}}} + +These map to `datamanager.method(user, host, store, data)`, where choice of `method` and its parameters are explained below. + +== Verbs == + +||*Verb*||*Meaning* ||*datamanager method* || +||`GET` || Just fetch data || `load()` or `list_load()` || +||`PUT` || Replace all data in the store || `store() || +||`POST`|| Append item to the store || `list_append()` || + +Note: In a `GET` request, if `load()` returns `nil`, `list_load()` will be tried instead. + +== Fields == + +||*Field*||*Description*||*Default*|| +||`host`||Which virtual host to access||Required. If not set in the path, the domain-part of the authzid is used.|| +||`user`||Which users storage to access||Required. If not set in the path, uses the node part of the authzid.|| +||`store`||Which storage to access.||Required.|| +||`format`||Which format to serialize to. `json` and `lua` are supported. When uploading data, the `Content-Type` header is used.||`json`|| +||`data`||The actual data to upload in a `PUT` or `POST` request.||`nil`|| + +Note: Only admins can change data for users other than themselves. + +== Example usage == + +Here follows some example usage using `curl`. + +Get your account details: + +{{{ + curl http://prosody.local:5280/data/accounts -u user@example.com:secr1t + {"password":"secr1t"} +}}} + +Set someones account details: + +{{{ + curl -X PUT http://prosody.local:5280/data/example.com/user/accounts -u admin@host:r00tp4ssw0rd --header 'Content-Type: application/json' --data-binary '{"password":"changeme"}' +}}} + +== Client library == + +* https://metacpan.org/module/Prosody::Mod::Data::Access + +== TODO == + +* Use `Accept` header. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_default_bookmarks/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_default_bookmarks/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,31 @@ +#summary Default bookmarked chatrooms + += Introduction = + +This module allows you to add default bookmarks for users. It only kicks in when the user has no existing bookmarks, so users are free to add, change or remove them. + += Details = + +Most clients support storing a private list of room "bookmarks" on the server. When they log in, they fetch this list and join any that are marked as "autojoin". If this list is empty, as it would be for new users, this module would return the list supplied in the config. + += Configuration = + +Add "default_bookmarks" to your modules_enabled list: +{{{ + modules_enabled = { + -- ...other modules here... -- + "default_bookmarks"; + -- ...maybe some more here... -- + } +}}} + +Then add a list of the default rooms you want: + +{{{ +default_bookmarks = { + { jid = "room@conference.example.com", name = "The Room" }; + { jid = "another-room@conference.example.com", name = "The Other Room" }; + -- You can also use this compact syntax: + "yetanother@conference.example.com"; -- this will get "yetanother" as name +}; +}}} \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_default_vcard/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_default_vcard/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,16 @@ +#summary Automatically populate vcard based on account details +#labels Stage-Beta + += Introduction = + +It is possible for the user to supply more than just a username and password when creating an account using [https://prosody.im/doc/modules/mod_register mod_register]. This module automatically copies over that data to the user's vcard. + += Details = + +There is no configuration for this module, just add it to modules_enabled as normal. + +Note that running this on a public-facing server that prompts for email during registration will make the user's email address publicly visible in their vcard. + += Compatibility = + +|| 0.9 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_delegation/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_delegation/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,81 @@ +#summary XEP-0355 (Namespace Delegation) implementation +#labels Stage-Alpha + += Introduction = + +Namespace Delegation is an extension which allows server to delegate some features handling to an entity/component. +Typical use case is an external PEP service, but it can be used more generally when your prefered server lack one internal feature and you found an external component which can do it. + += Details = + +You can have all the details by reading the [http://xmpp.org/extensions/xep-0355.html XEP-0355]. Only the admin mode is implemented so far. + +If you use it with a component, you need to patch core/mod_component.lua to fire a new signal. To do it, copy the following patch in a, for example, /tmp/component.patch file: +{{{ +diff --git a/plugins/mod_component.lua b/plugins/mod_component.lua +--- a/plugins/mod_component.lua ++++ b/plugins/mod_component.lua +@@ -85,6 +85,7 @@ + session.type = "component"; + module:log("info", "External component successfully authenticated"); + session.send(st.stanza("handshake")); ++ module:fire_event("component-authenticated", { session = session }); + + return true; + end +}}} + +Then, at the root of prosody, enter: + +{{{patch -p1 < /tmp/component.patch}}} + += Usage = + +To use the module, like usual add *"delegation"* to your modules_enabled. Note that if you use it with a local component, you also need to activate the module in your component section: + +{{{ +modules_enabled = { + [...] + + "delegation"; +} + +[...] + +Component "youcomponent.yourdomain.tld" + component_secret = "yourpassword" + modules_enabled = {"delegation"} +}}} + +then specify delegated namespaces *in your host section* like that: + +{{{ +VirtualHost "yourdomain.tld" + + delegations = { + ["urn:xmpp:mam:0"] = { + filtering = {"node"}; + jid = "pubsub.yourdomain.tld"; + }, + ["http://jabber.org/protocol/pubsub"] = { + jid = "pubsub.yourdomain.tld"; + }, + } +}}} + +Here all MAM requests with a "node" attribute (i.e. all MAM pubsub request) will be delegated to pubsub.yourdomain.tld. Similarly, all pubsub request to the host (i.e. the PEP requests) will be delegated to pubsub.yourdomain.tld. + +*/!\ Be extra careful when you give a delegation to an entity/component, it's a powerful access, only do it if you absoly trust the component/entity, and you know where the software is coming from* + += Configuration = +The configuration is done with a table which map delegated namespace to namespace data. +Namespace data MUST have a *jid* (in the form *jid = "delegated@domain.tld"*) and MAY have an additional *filtering* array. If filtering is present, request with attributes in the array will be delegated, other will be treated normally (i.e. by Prosody). + +If your are not a developper, the delegated namespace(s)/attribute(s) are most probably specified with the external component/entity you want to use. + += Compatibility = +||dev||Need a patched core/mod_component.lua (see above)|| +||0.9||Need a patched core/mod_component.lua (see above)|| + += Note = +This module is often used with mod_privilege (c.f. XEP for more details) diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_disable_tls/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_disable_tls/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,19 @@ +#summary Disable TLS on certain client ports +#labels Stage-Beta + += Introduction = + +This module can be used to prevent Prosody from offering TLS on client ports that you specify. This can be useful to work around buggy clients when transport security is not required. + += Configuration = + +Load the module, and set `disable_tls_ports` to a list of ports: + +{{{ + disable_tls_ports = { 5322 } +}}} + +Don't forget to add any extra ports to c2s_ports, so that Prosody is actually listening for connections! + += Compatibility = +|| 0.9 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_discoitems/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_discoitems/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,32 @@ +#summary Manually override the list of service discovery items +#labels Stage-Beta + += Introduction = + +This Prosody plugin lets you manually override the service discovery items for a host. + += Usage = + +Simply add `"discoitems"` to your modules_enabled list. Then add the `disco_items` option to hosts for which you wish to override the default response. + +Note: mod_disco in Prosody 0.8+ supports the `disco_items` option; this plugin changes the behavior from appending items to replacing items + += Configuration = + +The `disco_items` option can be added to relevant hosts: + +{{{ +disco_items = { + {"proxy.eu.jabber.org", "Jabber.org SOCKS5 service"}; + {"conference.jabber.org", "The Jabber.org MUC"}; +} +}}} + +The format for individual items is `{JID, display-name}`. The display-name can be omitted: `{JID}`. + += Compatibility = +||0.8||Works|| +||0.7||Works|| +||0.6||Works|| +||0.5||Should work|| + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_dwd/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_dwd/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,22 @@ +#summary Dialback-without-Dialback + += Introduction = + +This module implements an optimization of the Dialback protocol, by +skipping the dialback step for servers presenting a valid certificate. + += Configuration = + +Simply add the module to the `modules_enabled` list. + +{{{ + modules_enabled = { + ... + "dwd"; + } +}}} + += Compatibility = +||0.10||Built into mod_dialback|| +||0.9 + LuaSec 0.5||Works|| +||0.8||Doesn't work|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_email_pass/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_email_pass/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,27 @@ +#labels Stage-Beta += Introduction = + +This module aims to help in the procedure of user password restoration. To start the restoration, the user must go to an URL provided by this module, fill the JID and email and submit the request. + +The module will generate a token valid for 24h and send an email with a specially crafted url to the vCard email address. If the user goes to this url, will be able to change his password. + += Usage = +Simply add "email_pass" to your modules_enabled list and copy files "*mod_email_pass.lua*" and "*vcard.lib.lua*" to prosody modules folder. +This module need to that *https_host* or *http_host* must be configured. This parameter is necessary to construct the URL that has been sended to the user. + +This module only send emails to the vCard user email address, then the user must set this address in order to be capable of do the restoration. + += Configuration = + +|| smtp_server || The Host/ip of your SMTP server || +|| smtp_port || Port used by your SMTP server. Default 25 || +|| smtp_ssl || Use of SMTP SSL legacy (No STARTTLS) || +|| smtp_user || Username used to do SMTP auth || +|| smtp_pass || Password used to do SMTP auth || +|| smtp_address || EMail address that will be apears as From in mails || +|| msg_subject || Subject used for messages/mails || +|| msg_body || Message send when password has been changed || +|| url_path || Path where the module will be visible. Default /resetpass/ || + += Compatibility = +||0.9||Works|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_filter_chatstates/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_filter_chatstates/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,18 @@ +#summary Drop chat states from messages to inactive sessions + += Introduction = + +Some mobile XMPP client developers consider +[http://xmpp.org/extensions/xep-0085.html Chat State Notifications] to be +a waste of power and bandwidth, especially when the user is not actively +looking at their device. This module will filter them out while the +session is considered inactive. It depends on `mod_csi` for deciding +when to begin and end filtering. + += Configuration = + +There is no configuration for this module, just add it to modules_enabled as normal. + += Compatibility = +||0.9||Works|| + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_firewall/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_firewall/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,232 @@ +#summary A rule-based stanza filtering module +#labels Stage-Alpha + +---- + +*Note:* mod_firewall is in its very early stages. This documentation is liable to change, and some described functionality may be missing, incomplete or contain bugs. Feedback is welcome in the comments section at the bottom of this page. + +---- + += Introduction = + +A firewall is an invaluable tool in the sysadmin's toolbox. However while low-level firewalls such as iptables and pf are incredibly good at what they do, they are generally not able to handle application-layer rules. + +The goal of mod_firewall is to provide similar services at the XMPP layer. Based on rule scripts it can efficiently block, bounce, drop, forward, copy, redirect stanzas and more! Furthermore all rules can be applied and updated dynamically at runtime without restarting the server. + += Details = + +mod_firewall loads one or more scripts, and compiles these to Lua code that reacts to stanzas flowing through Prosody. The firewall script syntax is unusual, but straightforward. + +A firewall script is dominated by rules. Each rule has two parts: conditions, and actions. When a stanza matches all of the conditions, all of the actions are executed in order. + +Here is a simple example to block stanzas from spammer@example.com: + +{{{ +FROM: spammer@example.com +DROP. +}}} + +FROM is a condition, and DROP is an action. This is about as simple as it gets. How about heading to the other extreme? Let's demonstrate something more complex that mod_firewall can do for you: + +{{{ +%ZONE myorganisation: staff.myorg.example, support.myorg.example + +ENTERING: myorganisation +KIND: message +TIME: 12am-9am, 5pm-12am, Saturday, Sunday +REPLY=Sorry, I am afraid our office is closed at the moment. If you need assistance, please call our 24-hour support line on 123-456-789. +}}} + +This rule will reply with a short message whenever someone tries to send a message to someone at any of the hosts defined in the 'myorganisation' outside of office hours. + +Firewall rules should be written to a {{{ruleset.pfw}}} file. Multiple such rule +files can be specified in the configuration using: + +{{{ +firewall_scripts = { "path/to/ruleset.pfw" } +}}} + +== Conditions == +All conditions must come before any action in a rule block. The condition name is followed by a colon (':'), and the value to test for. + +A condition can be preceded or followed by `NOT` to negate its match. For example: + +{{{ +NOT FROM: user@example.com +KIND NOT: message +}}} + +=== Zones === + +A 'zone' is one or more hosts or JIDs. It is possible to match when a stanza is entering or leaving a zone, while at the same time not matching traffic passing between JIDs in the same zone. + +Zones are defined at the top of a script with the following syntax (they are not part of a rule block): + +{{{ +%ZONE myzone: host1, host2, user@host3, foo.bar.example +}}} + +A host listed in a zone also matches all users on that host (but not subdomains). + +The following zone-matching conditions are supported: + +|| *Condition* || *Matches* || +|| `ENTERING` || When a stanza is entering the named zone || +|| `LEAVING` || When a stanza is leaving the named zone || + +=== Stanza matching === + +|| *Condition* || *Matches* || +|| `KIND` || The kind of stanza. May be 'message', 'presence' or 'iq' || +|| `TYPE` || The type of stanza. This varies depending on the kind of stanza. See 'Stanza types' below for more information. || +|| `PAYLOAD` || The stanza contains a child with the given namespace. Useful for determining the type of an iq request, or whether a message contains a certain extension. || +|| `INSPECT` || The node at the specified path exists or matches a given string. This allows you to look anywhere inside a stanza. See below for examples and more. || + +==== Stanza types ==== + +|| *Stanza* || *Valid types* || +|| iq || get, set, result, error || +|| presence || _available_, unavailable, probe, subscribe, subscribed, unsubscribe, unsubscribed, error || +|| message || normal, chat, groupchat, headline, error || + +*Note:* The type 'available' for presence does not actually appear in the protocol. Available presence is signalled by the omission of a type. Similarly, a message stanza with no type is equivalent to one of type 'normal'. mod_firewall handles these cases for you automatically. + +==== INSPECT ==== + +INSPECT takes a 'path' through the stanza to get a string (an attribute value or text content). An example is the best way to explain. Let's check that a user is not trying to register an account with the username 'admin'. This stanza comes from [http://xmpp.org/extensions/xep-0077.html#example-4 XEP-0077: In-band Registration]: + +{{{ + + + bill + Calliope + bard@shakespeare.lit + + +}}} + +{{{ +KIND: iq +TYPE: set +PAYLOAD: jabber:iq:register +INSPECT: {jabber:iq:register}query/username#=admin +BOUNCE=not-allowed The username 'admin' is reserved. +}}} + +That weird string deserves some explanation. It is a path, divided into segments by '/'. Each segment describes an element by its name, optionally prefixed by its namespace in curly braces ('{...}'). If the path ends with a '#' then the text content of the last element will be returned. If the path ends with '@name' then the value of the attribute 'name' will be returned. + +INSPECT is somewhat slower than the other stanza matching conditions. To minimise performance impact, always place it below other faster condition checks where possible (e.g. above we first checked KIND, TYPE and PAYLOAD matched before INSPECT). + +=== Sender/recipient matching === + +|| *Condition* || *Matches* || +|| `FROM` || The JID in the 'from' attribute matches the given JID || +|| `TO` || The JID in the 'to' attribute matches the given JID || + +These conditions both accept wildcards in the JID when the wildcard expression is enclosed in angle brackets ('<...>'). For example: + +{{{ +# All users at example.com +FROM: <*>@example.com +}}} +{{{ +# The user 'admin' on any subdomain of example.com +FROM: admin@<*.example.com> +}}} + +You can also use [http://www.lua.org/manual/5.1/manual.html#5.4.1 Lua's pattern matching] for more powerful matching abilities. Patterns are a lightweight regular-expression alternative. Simply contain the pattern in double angle brackets. The pattern is automatically anchored at the start and end (so it must match the entire portion of the JID). + +{{{ +# Match admin@example.com, and admin1@example.com, etc. +FROM: <>@example.com +}}} + +*Note:* It is important to know that 'example.com' is a valid JID on its own, and does *not* match 'user@example.com'. To perform domain whitelists or blacklists, use Zones. + +*Note:* Some chains execute before Prosody has performed any normalisation or validity checks on the to/from JIDs on an incoming stanza. It is not advisable to perform access control or similar rules on JIDs in these chains (see the chain documentation for more info). + +=== Time and date === +==== TIME ==== +Matches stanzas sent during certain time periods. +|| *Condition* || *Matches* || +|| TIME || When the current server local time is within one of the comma-separated time ranges given || + +{{{ +TIME: 10pm-6am, 14:00-15:00 +REPLY=Zzzz. +}}} + +==== DAY ==== +It is also possible to match only on certain days of the week. + +|| *Condition* || *Matches* || +|| DAY || When the current day matches one, or falls within a rage, in the given comma-separated list of days || + +Example: +{{{ +DAY: Sat-Sun, Wednesday +REPLY=Sorry, I'm out enjoying life! +}}} + + +=== Rate-limiting === +It is possible to selectively rate-limit stanzas, and use rules to decide what to do with stanzas when over the limit. + +First, you must define any rate limits that you are going to use in your script. Here we create a limiter called 'normal' that will allow 2 stanzas per second, and then we define a rule to bounce messages when over this limit. Note that the `RATE` definition is not part of a rule (multiple rules can share the same limiter). + +{{{ +%RATE normal: 2 (burst 3) + +KIND: message +LIMIT: normal +BOUNCE=policy-violation (Sending too fast!) +}}} + +The 'burst' parameter on the rate limit allows you to spread the limit check over a given time period. For example the definition shown above will allow the limit to be temporarily surpassed, as long as it is within the limit after 3 seconds. You will almost always want to specify a burst factor. + +Both the rate and the burst can be fractional values. For example a rate of 0.1 means only one event is allowed every 10 seconds. + +The LIMIT condition actually does two things; first it counts against the given limiter, and then it checks to see if the limiter over its limit yet. If it is, the condition matches, otherwise it will not. + +|| *Condition* || *Matches* || +|| `LIMIT` || When the named limit is 'used up'. Using this condition automatically counts against that limit. || + +*Note:* Reloading mod_firewall resets the current state of any limiters. + +== Actions == +Actions come after all conditions in a rule block. There must be at least one action, though conditions are optional. + +An action without parameters ends with a full-stop/period ('.'), and one with parameters uses an equals sign ('='): + +{{{ +# An action with no parameters: +DROP. + +# An action with a parameter: +REPLY=Hello, this is a reply. +}}} + +=== Route modification === +The most common actions modify the stanza's route in some way. Currently the first matching rule to do so will halt further processing of actions and rules (this may change in the future). + +|| *Action* || *Description* || +|| `PASS.` || Stop executing actions and rules on this stanza, and let it through this chain. || +|| `DROP.` || Stop executing actions and rules on this stanza, and discard it. || +|| `REDIRECT=jid` || Redirect the stanza to the given JID. || +|| `REPLY=text` || Reply to the stanza (assumed to be a message) with the given text. || +|| `BOUNCE.` || Bounce the stanza with the default error (usually service-unavailable) || +|| `BOUNCE=error` || Bounce the stanza with the given error (MUST be a defined XMPP stanza error, see [http://xmpp.org/rfcs/rfc6120.html#stanzas-error-conditions RFC6120]. || +|| `BOUNCE=error (text)` || As above, but include the supplied human-readable text with a description of the error || +|| `COPY=jid` || Make a copy of the stanza and send the copy to the specified JID. || + +=== Stanza modification === +These actions make it possible to modify the content and structure of a stanza. + +|| *Action* || *Description* || +|| `STRIP=name` || Remove any child elements with the given name in the default namespace || +|| `STRIP=name namespace` || Remove any child elements with the given name and the given namespace || +|| `INJECT=xml` || Inject the given XML into the stanza as a child element || + +=== Informational === +|| *Action* || *Description* || +|| `LOG=message` || Logs the given message to Prosody's log file. Optionally prefix it with a log level in square brackets, e.g. `[debug]`|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_flash_policy/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_flash_policy/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,30 @@ +#summary Adds support for flash socket policy +#labels Stage-Alpha + += Introduction = + +This Prosody plugin adds support for flash socket policies. When connecting with a flash client (from a webpage, not an exe) to prosody the flash client requests for an xml "file" on port 584 or the connecting port (5222 in the case of default xmpp). Responding on port 584 is tricky because it requires root priviliges to set up a socket on a port < 1024. + +This plugins filters the incomming data from the flash client. So when the client connects with prosody it immediately sends a xml request string ({{{\0}}}). Prosody responds with a flash cross-domain-policy. See http://www.adobe.com/devnet/flashplayer/articles/socket_policy_files.html for more information. + += Usage = + +Add "flash_policy" to your modules_enabled list. + += Configuration = + +|| crossdomain_file || Optional. The path to a file containing an cross-domain-policy in xml format. || +|| crossdomain_string || Optional. A cross-domain-policy as string. Should include the xml declaration. || + +Both configuration options are optional. If both are not specified a cross-domain-policy with "{{{}}}" is used as default. + += Compatibility = +||0.7||Works|| + += Caveats/Todos/Bugs = + + * The assumption is made that the first packet received will always +contain the policy request data, and all of it. This isn't robust +against fragmentation, but on the other hand I highly doubt you'll be +seeing that with such a small packet. + * Only tested by me on a single server :) \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_group_bookmarks/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_group_bookmarks/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,48 @@ +#summary mod_groups for chatrooms +#labels Stage-Beta + += Introduction = + +[http://prosody.im/doc/modules/mod_groups mod_groups] allows you to insert contacts into users' contact lists. Well mod_group_bookmarks allows you to insert chatrooms into the user's bookmarks. These are fetched by their client and automatically joined when the log in. + +In short, if you want to automatically join users to rooms when they sign in, this is the module you want. + += Details = + +Most clients support storing a private list of room "bookmarks" on the server. When they log in, they fetch this list and join any that are marked as "autojoin". Without affecting normal usage of the bookmarks store this module dynamically inserts custom rooms into users' bookmarks lists. + += Usage = + +Similar to [http://prosody.im/doc/modules/mod_groups mod_groups], you need to make a text file in this format: + +{{{ +[room@conferenceserver] +user1@example.com=User 1 +user2@example.com=User 2 + +[otherroom@conferenceserver] +user3@example.net=User 3 +}}} + +Add "group_bookmarks" to your modules_enabled list: +{{{ + modules_enabled = { + -- ...other modules here... -- + "group_bookmarks"; + -- ...maybe some more here... -- + } +}}} + += Configuration = +||group_bookmarks_file||The path to the text file you created (as above).|| + += Compatibility = +||0.8||Works|| +||0.7||Should work|| +||0.6||Should work|| + += Todo = + + * Support for injecting into ALL users bookmarks, without needing a list + * Allow turning off the autojoin flag + * Perhaps support a friendly name for the bookmark (currently uses the room address) \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_host_guard/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_host_guard/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,38 @@ +#summary Granular remote host blacklisting plugin +#labels Stage-Stable + += Details = + +As often it's undesiderable to employ only whitelisting logics in public environments, this module let's you more selectively +restrict access to your hosts (component or server host) either disallowing access completely (with optional exceptions) or +blacklisting certain sources. + += Usage = + +Copy the plugin into your prosody's modules directory. +And add it between your enabled modules into the global section (modules_enabled): + + * The plugin can work either by blocking all remote access (s2s) to a certain resource with optional exceptions (useful for components) + * Or by selectively blocking certain remote hosts through blacklisting (by using host_guard_selective and host_guard_blacklisting) + += Configuration = + +|| *Option name* || *Description* || +|| host_guard_blockall || A list of local hosts to protect from incoming s2s || +|| host_guard_blockall_exceptions || A list of remote hosts that are always allowed to access hosts listed in host_guard_blockall || +|| host_guard_selective || A list of local hosts to allow selective filtering (blacklist) of incoming s2s connections || +|| host_guard_blacklist || A blacklist of remote hosts that are not allowed to access hosts listed in host_guard_selective || + +== Example == + +host_guard_blockall = { "no_access.yourhost.com", "no_access2.yourhost.com" } -- insert here the local hosts where you want to forbid all remote traffic to. +host_guard_blockall_exceptions = { "i_can_access.no_access.yourhost.com" } -- optional exceptions for the above. +host_guard_selective = { "no_access_from_blsted.myhost.com", "no_access_from_blsted.mycomponent.com" } -- insert here the local hosts where you want to employ blacklisting. +host_guard_blacklist = { "remoterogueserver.com", "remoterogueserver2.com" } -- above option/mode mandates the use of a blacklist, you may blacklist remote servers here. + + +The above is updated when the server configuration is reloaded so that you don't need to restart the server. + += Compatibility = + + * Works with 0.8.x, successive versions and trunk. \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_http_dir_listing/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_http_dir_listing/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,31 @@ +#summary HTTP directory listing + += Introduction = + +This module generates directory listings when invoked by `mod_http_files`. +See [http://prosody.im/doc/modules/mod_http_files documentation on `mod_http_files`]. + += Configuration = + +The module itself doesn't have any configuration of its own, just enable the it along with `mod_http_files`. + +{{{ +modules_enabled = { + ... + + "http_files"; + "http_dir_listing"; +} + +http_dir_listing = true; +}}} + +The layout, CSS and icons in the `resources/` directory can be customized +or replaced. All resources are cached in memory when the module is +loaded and the images are inlined in the CSS. + += Compatibility = + +||trunk||Works|| +||0.9||Works|| +||0.8||Doesn't work|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_http_favicon/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_http_favicon/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,26 @@ +#summary HTTP favicon + += Introduction = + +This simple module serves a `favicon.ico` from prosodys HTTP server and +nothing else. + += Configuring = + +Simply load the module. The icon can be replaced by adding a `favicon` +option to the config. + +{{{ +modules_enabled = { + ... + "favicon"; +} + +favicon = "/path/to/my-favicon.ico" -- Override the built in one +}}} + += Compatibility = + +||trunk||Works|| +||0.9||Works|| +||0.8||Doesn't work|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_http_muc_log/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_http_muc_log/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,38 @@ +#summary Provides a web interface to stored chatroom logs +#labels Stage-Beta + += Introduction = + +This module provides a built-in web interface to view chatroom logs stored by [mod_mam_muc]. + += Installation = + +Just copy the folder muc_log_http as it is, into the modules folder of your Prosody installation. + += Configuration Details = + +You need to add muc_log_http to your global modules_enabled, and the configuration options similarly must be put into your global (server-wide) options section: + +{{{ + Component "conference.example.com" "muc" + modules_enabled = { + ..... + "mam_muc"; + "http_muc_log"; + ..... + } + storage = { + muc_log = "sql2"; -- for example + } +}}} + +The web interface would then be reachable at the address: +{{{ +http://conference.example.com:5280/muc_log/ +}}} + +See [http://prosody.im/doc/http the page about Prosodys HTTP server] for info about the address. + += Compatibility = + +Requires Prosody 0.10 or above and a storage backend with support for stanza archives. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_idlecompat/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_idlecompat/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,13 @@ +#summary XEP-0319 compatibility module +#labels Stage-Beta + += Introduction = + +This module adds [http://xmpp.org/extensions/xep-0319.html XEP-0319] idle tags to presence stanzas containing [http://xmpp.org/extensions/xep-0012.html XEP-0012: Last Activity] tags for idle indication (e.g. supported by libpurple clients). It works on outgoing and incoming presence stanzas. + +Install and enable it like any other module. It has no configuration. + += Compatibility = + +||trunk||Works|| +||0.9||Works|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_incidents_handling/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_incidents_handling/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,33 @@ +#summary Incidents Handling plugin +#labels Stage-Beta + += Introduction = + +This module implements [http://xmpp.org/extensions/xep-0268.html XEP-268]. + += Details = + +It will let you manage reports, inquiries, requests and responses through an Adhoc interface. +The following new adhoc admin commands will be available: + + * List Incidents -- List all available incidents and let's you reply requests. + * Send Incident Inquiry -- Inquiry a remote server about an incident. + * Send Incident Report -- Send an incident report to a remote server. + * Send Incident Request -- Send an incident request to a remote server. + +Each Adhoc form provides syntax instructions through `` elements (they may currently be stripped +by Prosody), although it's encouraged to read the [https://tools.ietf.org/html/rfc5070 IODEF specifications]. + += Usage = + +Copy the module folder into your prosody modules directory. +Place the module between your enabled modules either into the global or a vhost section. + +Optional configuration directives: + +incidents_expire_time = 86400 -- Expiral of "closed" incidents in seconds. + + += Info = + + * to be 0.9, works. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_ipcheck/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_ipcheck/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,12 @@ +#summary XEP-0279: Server IP Check +#labels Stage-Stable + += Introduction = + +Sometimes for various reasons a client might want to know its IP address as it appears to the server. This [http://xmpp.org/extensions/xep-0279.html simple XEP] allows the client to ask the server for the IP address it is connected from. + + += Compatibility = + +||0.7||Works|| +||0.6||Works|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_ircd/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_ircd/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,45 @@ +#summary IRC to XMPP interface to allow IRC clients to connect to chatrooms +#labels Stage-Alpha, Deprecated + +*NOTE: Consider this module currently more of a fun experiment than a serious project for use in production. Note the 'alpha' tag and have fun!* + += Introduction = + +Whether you like it or not, XMPP is the future, but that pesky IRC just won't go away :) + +With this module you can set up a special host on your server to allow connections from IRC clients and bots. They are able to join XMPP chatrooms on a specified conference server. + += Usage = +In your config file put something similar to the following: + +{{{ +Component "irc2muc.example.com" "ircd" + conference_server = "conference.example.com" -- required + listener_port = 7000 +}}} + +If you don't want your IRC users to have connectivity outside your server then there is no need for the hostnames you specify to be valid DNS entries. + += Warning = + +The plugin stability, and/or serving compatibility with most of the IRC clients is yet to be determined. + += Install = + +This release requires the [http://code.matthewwild.co.uk/verse/ Verse client library] as dependancy and [http://code.matthewwild.co.uk/squish/ Squish] to meld it with the plugin. + +Instructions (temporarily changed): + * Clone the Squish repo and/or download the latest tip from it (in that case you'll have to decompress the tip zip/tarball) + * In your Squish directory type make install + * Back into your mod_ircd directory call squish with --verse=./verse/verse.lua + * Move the mod_ircd.lua file to your prosody's plugins directory + += Compatibility = +||0.8||Works|| +||0.7||Uncertain|| +||0.6||Doesn't work|| + += Todo = + * Authentication + * SSL + * Many improvements to handling of IRC and XMPP diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_isolate_host/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_isolate_host/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,42 @@ +#summary Prevent communication between hosts +#labels Stage-Beta + += Introduction = + +In some environments it is desirable to isolate one or more hosts, and prevent communication with external, or even other internal domains. + +Loading mod_isolate_host on a host will prevent all communication with JIDs outside of the current domain, though it is possible to configure exceptions. + +*Note:* if you just want to prevent communication with external domains, this is possible without a plugin. See [http://prosody.im/doc/s2s#disabling Prosody: Disabling s2s] for more information. + +This module was sponsored by [http://exa-networks.co.uk/ Exa Networks]. + += Configuration = + +To isolate all hosts by default, add the module to your global modules_enabled: + +{{{ + modules_enabled = { + ... + "isolate_host"; + ... + } +}}} + +Alternatively you can isolate a single host by putting a modules_enabled line under the VirtualHost directive: + +{{{ + VirtualHost "example.com" + modules_enabled = { "isolate_host" } +}}} + +After enabling the module, you can add further options to add exceptions for the isolation: + +|| *Option* || *Description* || +|| isolate_except_domains || A list of domains to allow communication with. || +|| isolate_except_users || A list of user JIDs allowed to bypass the isolation and communicate with other domains. || + +*Note:* Admins of hosts are always allowed to communicate with other domains + += Compatibility = +|| 0.9 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_jid_prep/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_jid_prep/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,20 @@ +#summary Implement XEP-xxxx: JID prep for clients +#labels Stage-Alpha + += Introduction = + +This is a plugin that implements the JID prep protocol defined in http://xmpp.org/extensions/inbox/jidprep.html + += Details = + +JID prep requests can happen over XMPP using the protocol defined in the document linked above, or alternatively over HTTP. Simply request: + +{{{ +http://server:5280/jid_prep/USER@HOST +}}} + +The result will be the stringprepped JID, or a 400 Bad Request if the given JID is invalid. + += Compatibility = + +|| 0.9 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_json_streams/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_json_streams/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,38 @@ +#summary JSON Encodings for XMPP +#labels Stage-Beta + += Introduction = + +This plugin encodes XMPP as JSON. This is an implementation of [http://xmpp.org/extensions/xep-0295.html XEP-0295: JSON Encodings for XMPP]. + +Simply loading this module makes Prosody accept JSON on C2S streams (legacy XML clients are still supported). + +For BOSH, it requires mod_bosh be loaded, and JSON should be directed at the `/jsonstreams` HTTP path. + +JSON for S2S isn't supported due to the lack of a discovery mechanism, so we have left that disabled to stay compatible with legacy XML servers. + += Configuration = +Just add `"json_streams"` in your config's global `modules_enabled` list, for example: + +{{{ +modules_enabled = { + ... + "json_streams"; +} +}}} + += Strophe.js plugin = +We also developed a [http://prosody-modules.googlecode.com/hg/mod_json_streams/strophe.jsonstreams.js JSON streams plugin] for the popular [http://code.stanziq.com/strophe strophe.js] library. + +Just include it like this after including the strophe library, and your strophe-based client will be speaking JSON: +{{{ + +}}} +Be sure to set the HTTP path to `/jsonstreams`. No other changes are required. + += Compatibility = +||0.8||Works|| +||trunk||Works|| + += Quirks = + * This plugin does not currently work with Prosody's [http://prosody.im/doc/port_multiplexing port multiplexing] feature diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_lastlog/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_lastlog/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,37 @@ +#summary Log last login time +#labels Stage-Beta + += Introduction = + +Simple module that stores the timestamp of when a user logs in. + += Usage = + +As with all modules, copy it to your plugins directory and then add it to the modules_enabled list: + +{{{ + modules_enabled = { + -- ... + "lastlog", + -- ... + } +}}} + += Configuration = + +There are some options you can add to your config file: + +|| *Name* || *Values* || *Description* || +|| lastlog_ip_address || true/false || Log the IP address of the user? || +|| lastlog_stamp_offline || true/false || Add timestamp to offline presence? || + += Usage = + +You can check a user's last activity by running: + +{{{ + prosodyctl mod_lastlog username@example.com +}}} + += Compatibility = +|| 0.9 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_latex/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_latex/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,21 @@ +#summary Replace LaTeX markup in messages with embedded images +#labels Stage-Beta + += Introduction = + +This module intercepts messages between users and into chatrooms, and attaches a links to a rendered version of any [http://en.wikipedia.org/wiki/LaTeX LaTeX] in the message. This requires client support for [http://xmpp.org/extensions/xep-0071.html XHTML-IM], and fetching images via HTTP. + +This module was tested with the [http://gajim.org/ Gajim] client. + += Details = + +There is no configuration (yet). The module uses [http://www.mathtran.org/ MathTran] to render the LaTeX. + += Todo = + * Support for other rendering services (easy) + * Provide a built-in rendering service (e.g. mimetex) + * Send the images inline over XMPP (little client support at the moment) + += Compatibility = +|| 0.6 || Works || +|| 0.7 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_lib_ldap/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_lib_ldap/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,46 @@ +#summary Library module for LDAP + += Introduction = + +This module is used by other modules to access an LDAP server. It's pretty useless on its own; you should use it if you want to write your own LDAP-related module, or if you want to use one of mine ([mod_auth_ldap2], [mod_storage_ldap]). + += Installation = + +Simply copy ldap.lib.lua into your Prosody installation's plugins directory. + += Configuration = + +Configuration for this module (and all modules that use it) goes into the _ldap_ section of your prosody.cfg.lua file. Each plugin that uses it may add their own sections; this plugin relies on the following keys: + + * hostname - Where your LDAP server is located + * bind_dn - The DN to perform queries as + * bind_password - The password to use for queries + * use_tls - Whether or not TLS should be used to connect to the LDAP server + * user.usernamefield - The LDAP field that contains a user's username + * user.basedn - The base DN for user records + += API = + +== ldap.getconnection() == + +Returns an LDAP connection object corresponding to the configuration in prosody.cfg.lua. The connection object is a [http://www.keplerproject.org/lualdap/ LuaLDAP] connection. + +== ldap.getparams() == + +Returns the LDAP configuration provided in prosody.cfg.lua. Use this if you want to stick some configuration information for your module into the LDAP section in the configuration file. + +== ldap.bind(username, password) == + +Verifies that _username_ and _password_ bind ok. *NOTE*: This does not bind the current LDAP connection to the given username! + +== ldap.singlematch(query) == + +Used to fetch a single LDAP record given an LDAP query. A convenience function. + +== ldap.filter.combine_and(...) == + +Takes a list of LDAP filter expressions and returns a filter expression that results in the intersection of each given expression (it ANDs them together). + += More Information = + +For more information, please consult the README.md file under prosody-modules/mod_lib_ldap. \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_limits/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_limits/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,46 @@ +#summary Connection-level rate limiting +#labels Stage-Beta + += Introduction = + +On some servers, especially public ones, it is desired to make sure that everyone gets their fair share of system resources (and no more). + +mod_limits allows you to specify traffic bandwidth limits, preventing any single connection hogging the server's CPU, RAM and bandwidth. + += Details = + +mod_limits detects when a connection has exceeded its traffic allowance and temporarily ignores a connection. Due to the way TCP and the OS's network API works no data is lost, only slowed. + += Configuration = +Currently mod_limits is configured per connection type. The possible connection types are: + + * c2s + * s2sin + * s2sout + * component + +The limits are specified like so in the *global* section of your config (they cannot be per-host): + +{{{ + limits = { + c2s = { + rate = "3kb/s"; + burst = "2s"; + }; + s2sin = { + rate = "10kb/s"; + burst = "5s"; + }; + } +}}} + +All units are in terms of _bytes_, not _bits_, so that "kb/s" is interpreted as "kilobytes per second", where a kilobyte is 1000 bytes. + += Compatibility = +|| 0.9 || Works || +|| 0.8 || Doesn't work(`*`) || + +(`*`) This module can be made to work in 0.8 if you do two things: + + # Install [http://hg.prosody.im/0.9/raw-file/d46948d3018a/util/throttle.lua util.throttle] into your Prosody source's util/ directory. + # If you use libevent apply [http://prosody.im/patches/prosody08-mod-limits-fix.patch this patch] to net/server_event.lua. \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_log_auth/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_log_auth/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,38 @@ +#summary Log failed authentication attempts with their IP address +#labels Stage-Stable + += Introduction = + +Prosody doesn't write IP addresses to its log file by default for privacy reasons (unless debug logging is enabled). + +This module enables logging of the IP address in a failed authentication attempt so that those trying to break into accounts for example can be blocked. + += fail2ban configuration = + +fail2ban is a utility for monitoring log files and automatically blocking "bad" IP addresses at the firewall level. + +With this module enabled in Prosody you can use the following example configuration for fail2ban: + +{{{ +# /etc/fail2ban/filter.d/prosody-auth.conf +# Fail2Ban configuration file for prosody authentication +[Definition] +failregex = Failed authentication attempt \(not-authorized\) from IP: +ignoreregex = +}}} + +And at the appropriate place (usually the bottom) of /etc/fail2ban/jail.conf add these lines: + +{{{ +[prosody] +enabled = true +port = 5222 +filter = prosody-auth +logpath = /var/log/prosody/prosody*.log +maxretry = 6 +}}} + +== Compatibility == +|| trunk || Works || +|| 0.9 || Works || +|| 0.8 || Doesn't work || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_log_rate/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_log_rate/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,23 @@ +#summary Collect statistics on rate of log messages + += Introduction = + +If you ever wanted to collect statistics on the number of log messages, this is the module for you! + += Setup = + +After [https://prosody.im/doc/installing_modules installing the module] and adding it to modules_enabled as most other modules, you also need to add it to your logging config: + +{{{ +log = { + -- your other log sinks + info = "/var/log/prosody/prosody.log" + -- add this: + { to = "measure" } +}}} + +Then log messages will be counted by [https://prosody.im/doc/developers/core/statsmanager statsmanager]. + += Compatibility = + +Reqires Prosody 0.10 or above. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_mam/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_mam/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,61 @@ +#summary XEP-0313: Message Archive Management +#labels Stage-Beta + += Introduction = + +Implementation of [http://xmpp.org/extensions/xep-0313.html XEP-0313: Message Archive Management]. + += Details = + +This module will archive all messages that match the simple rules setup by the +user, and allow the user to access this archive. + += Usage = + +First copy the module to the prosody plugins directory. + +Then add "mam" to your modules_enabled list: +{{{ +modules_enabled = { + -- ... + "mam", + -- ... +} +}}} + += Storage backend = + +mod_mam uses the store "archive2". +See [https://prosody.im/doc/storage Prosodys data storage documentation] +for information on how to configure storage. + += Configuration = + +The MAM protocol includes a method of changing preferences regarding what +messages should be stored. This allows users to enable or disable +archiving by default, and set rules for specific contacts. This module +will log no messages by default, for privacy concerns. If you decide to +change this, you should inform your users. + +{{{ + default_archive_policy = false -- other options are true or "roster"; +}}} + +This controls what messages are archived if the user hasn't set a +matching rule, or another personal default. + + * `false` means to store no messages. This is the default. + * `"roster"` means to store messages to/from contacts in the users roster. + * `true` means is to store all messages. + +{{{ + max_archive_query_results = 20; +}}} + +This is the largest number of messages that are allowed to be retrieved in one request. + += Compatibility = +|| trunk || Works || +|| 0.10 || Works, requires a storage driver with archive support, eg mod_storage_sql2 in 0.10 || +|| 0.9 || Unsupported || +|| 0.8 || Does not work || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_mam_adhoc/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_mam_adhoc/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,25 @@ +#summary Ad-hoc interface to Message Archive Management Settings +#labels Stage-Alpha + += Introduction = + +This module complements mod_mam by allowing clients to change archiving preferences through an Ad-hoc command. + += Details = + +When enabled, an "Archive Settings" command should appear in the list of Ad-hoc commands available. This allows the user to change default policy (always, never, roster) and which JIDs to always store or never store. + += Usage = + +First copy the module to the prosody plugins directory. + +Then add "mam_adhoc" to your modules_enabled list: +{{{ + modules_enabled = { + -- ... + "mam", + "mam_adhoc", + -- ... + } +}}} + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_mam_archive/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_mam_archive/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,44 @@ +#summary XEP-0136: Message Archiving frontend for mod_mam +#labels Stage-Alpha + += Introduction = + +Implementation of [http://xmpp.org/extensions/xep-0136.html XEP-0136: Message Archiving] for [mod_mam]. + + += Details = + +See [mod_mam] for details. + += Usage = + +First configure mod_mam as specified in it's [mod_mam wiki]. Make sure it uses sql2 storage backend. + +Then add "mam_archive" to your modules_enabled list: +{{{ + modules_enabled = { + -- ... + "mam_archive", + -- ... + } +}}} + += Configuration = + +Because of the fact that [http://xmpp.org/extensions/xep-0136.html XEP-0136] defines a 'conversation' concept not present in [http://xmpp.org/extensions/xep-0313.html XEP-0313], we have to assume some periods of chat history as 'conversations'. + +Conversation interval defaults to one day, to provide for a convenient usage. + +{{{ +archive_conversation_interval = 86400; -- defined in seconds. One day by default +}}} + +That is the only reason SQL database is required as well. + += Compatibility = +|| 0.10 || Works || +|| 0.9 || Does not work || + +|| PostgreSQL || Tested || +|| MySQL || Not tested || +|| SQLite || Tested || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_mam_muc/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_mam_muc/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,52 @@ +#summary XEP-0313: Message Archive Management for MUC +#labels Stage-Alpha + += Introduction = + +This module logs the conversation of chatrooms running on the server to Prosody's archive storage. +To access them you will need a client with support for +[http://xmpp.org/extensions/xep-0313.html XEP-0313: Message Archive Management] +or a module such as [mod_http_muc_log]. + += Usage = + +First copy the module to the prosody plugins directory. + +Then add "mam_muc" to your modules_enabled list: +{{{ +Component "conference.example.org" "muc" +modules_enabled = { + "mam_muc", +} +storage = { + -- This makes mod_mam_muc use the sql2 storage backend (others will use internal) + -- which at the time of this writing is the only one supporting stanza archives + muc_log = "sql2"; +} +}}} + +See [https://prosody.im/doc/storage Prosodys data storage documentation] +for more info on how to configure storage for different plugins. + += Configuration = + +Logging needs to be enabled for each room in the room configuration dialog. + +{{{ + muc_log_by_default = true; -- Enable logging by default (can be disabled in room config) + + muc_log_all_rooms = false; -- set to true to force logging of all rooms + + -- This is the largest number of messages that are allowed to be retrieved in one MAM request. + max_archive_query_results = 20; + + -- This is the largest number of messages that are allowed to be retrieved when joining a room. + max_history_messages = 1000; +}}} + + += Compatibility = +|| trunk || Works || +|| 0.10 || Works || +|| 0.9 || Does not work || +|| 0.8 || Does not work || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_mam_sql/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_mam_sql/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,73 @@ +#summary XEP-0313: Message Archive Management using SQL +#labels Stage-Alpha, Deprecated + +*Note:* This module is unsupported and not up to date with the MAM specification + += Introduction = + +Implementation of (an older version of) [http://xmpp.org/extensions/xep-0313.html XEP-0313: Message Archive Management] backed by a SQL database. Like [mod_mam], but using SQL. + + += Details = + +See [mod_mam] for details. + += Usage = + +First copy the module to the prosody plugins directory. + +Then add "mam_sql" to your modules_enabled list: +{{{ + modules_enabled = { + -- ... + "mam_sql", + -- ... + } +}}} + +You should probably run the SQL to create the archive table/indexes: + +{{{ +CREATE TABLE `prosodyarchive` ( + `host` TEXT, + `user` TEXT, + `store` TEXT, + `id` INTEGER PRIMARY KEY AUTOINCREMENT, + `when` INTEGER, + `with` TEXT, + `resource` TEXT, + `stanza` TEXT +); +CREATE INDEX `hus` ON `prosodyarchive` (`host`, `user`, `store`); +CREATE INDEX `with` ON `prosodyarchive` (`with`); +CREATE INDEX `thetime` ON `prosodyarchive` (`when`); +}}} + +(*NOTE*: I ran the following SQL to initialize the table/indexes on MySQL): + +{{{ +CREATE TABLE prosodyarchive ( + `host` VARCHAR(1023) NOT NULL, + `user` VARCHAR(1023) NOT NULL, + `store` VARCHAR(1023) NOT NULL, + `id` INTEGER PRIMARY KEY AUTO_INCREMENT, + `when` INTEGER NOT NULL, + `with` VARCHAR(2047) NOT NULL, + `resource` VARCHAR(1023), + `stanza` TEXT NOT NULL +); +CREATE INDEX hus ON prosodyarchive (host, user, store); +CREATE INDEX `with` ON prosodyarchive (`with`); +CREATE INDEX thetime ON prosodyarchive (`when`); +}}} + +You may want to tweak the column sizes a bit; I did for my own purposes. + += Configuration = + +This module uses the same configuration settings that [mod_mam] does, in addition to the [http://prosody.im/doc/modules/mod_storage_sql SQL storage settings]. You may also name the SQL connection settings 'mam_sql' if you want. + += Compatibility = +|| 0.8 || ? || +|| 0.9 || Works || +|| trunk || Works || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_manifesto/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_manifesto/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,42 @@ +#summary Module for raising awareness about the Security Test Days + += Introduction = + +This module informs users about the XMPP Test day and whether their contacts are affected. For mor info about the test day, see https://stpeter.im/journal/1496.html + += Configuration = + +{{{ +manifesto_contact_encryption_warning = [[ + Your rant about security here +]] +admin_contact_address = "mailto:xmpp@example.com" +}}} + +`admin_contact_address` can be a JID or a `mailto:` URI. + +The default for `manifesto_contact_encryption_warning` is the following: + +{{{ +Hello there. + +This is a brief system message to let you know about some upcoming changes to the $HOST service. + +Some of your contacts are on other Jabber/XMPP services that do not support encryption. As part of an initiative to increase the security of the Jabber/XMPP network, this service ($HOST) will be participating in a series of tests to discover the impact of our planned changes, and you may lose the ability to communicate with some of your contacts. + +The test days will be on the following dates: January 4, February 22, March 22 and April 19. On these days we will require that all client and server connections are encrypted. Unless they enable encryption before that, you will be unable to communicate with your contacts that use these services: + +$SERVICES + +Your affected contacts are: + +$CONTACTS + +What can you do? You may tell your contacts to inform their service administrator about their lack of encryption. Your contacts may also switch to a more secure service. A list of public services can be found at https://xmpp.net/directory.php + +For more information about the Jabber/XMPP security initiative that we are participating in, please read the announcement at https://stpeter.im/journal/1496.html + +If you have any questions or concerns, you may contact us via $CONTACTVIA at $CONTACT +}}} + +Translations would be appreciated. There is currently a Swedish translation residing in a text file in the same directory as the module. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_measure_cpu/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_measure_cpu/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,6 @@ +#summary Measure CPU usage + += Description = + +This module measures CPU usage and reports using Prosody 0.10 APIs + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_measure_memory/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_measure_memory/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,6 @@ +#summary Measure memory usage + += Description = + +This module measures memory usage and reports using Prosody 0.10 APIs + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_message_logging/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_message_logging/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,19 @@ +#summary Log/archive all user messages +#labels Stage-Beta + += Introduction = + +Often service administrators need to log their users' messages for reasons such as auditing and compliance. This module simply logs user messages to simple text files, which can be easily searched, archived or removed on a regular basis. + += Usage = + +Simply load the module and it will start logging. Reloading Prosody (e.g. with a SIGHUP) will cause it to close any open logs (and re-open them if necessary). + += Configuration = + +|| *Option name* || *Description* || +|| message_logging_dir || The directory to save message logs in. Default is to create a 'message_logs' subdirectory inside the data directory. || + += Compatibility = + +|| 0.9 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_motd_sequential/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_motd_sequential/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,26 @@ +#summary Sequential MOTD messages +#labels Stage-Beta + += Introduction = + +mod_motd_sequential is a variant of +[https://prosody.im/doc/modules/mod_motd mod_motd] that lets you specify +a sequence of MOTD messages instead of a single static one. Each message +is only sent once and the module keeps track of who as seen which message. + += Configuration = + +{{{ + + modules_enabled = { + -- other modules + "motd_sequential"; + } + motd_sequential_messages = { + "Hello and welcome to our service!", -- First login + "Lorem ipsum dolor sit amet", -- Second time they login + -- Add more messages here. + } + +}}} + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_muc_ban_ip/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_muc_ban_ip/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,35 @@ +#summary Ban users from chatrooms by their IP address +#labels Stage-Alpha + += Introduction = + +One frequent complaint about XMPP chatrooms (MUCs) compared to IRC is the inability for a room admin to ban a user based on their IP address. This is because an XMPP user is not identified on the network by their IP address, only their JID. + +This means that it is possible to create a new account (usually quite easily), and rejoin the room that you were banned from. + +This module allows the *user's* server to enforce bans by IP address, which is very desirable for server admins who want to prevent their server being used for spamming and abusive behaviour. + += Details = + +An important point to note is that this module enforces the IP ban on the banned user's server, not on the MUC server. This means that: + + * The user's server MUST have this module loaded, however - + * The module works even when the MUC is on a different server to the user + * The MUC server does not need this module (it only needs to support the [http://xmpp.org/extensions/xep-0045.html#ban standard ban protocol]) + * The module works for effectively banning [http://prosody.im/doc/anonymous_logins anonymous users] + +Also note that IP bans are not saved permanently, and are reset upon a server restart. + += Configuration = + +There is no extra configuration for this module except for loading it. Remember... do not load it on the MUC host, simply add it to your global `modules_enabled` list, or under a specific host like: + +{{{ +VirtualHost "anon.example.com" + authentication = "anonymous" + modules_enabled = { "muc_ban_ip" } +}}} + += Compatibility = +|| 0.9 || Works || +|| 0.8 || Doesn't work || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_muc_config_restrict/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_muc_config_restrict/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,44 @@ +#summary Restrict MUC configuration options to server admins +#labels Stage-Alpha + += Introduction = + +Sometimes, especially on public services, you may want to allow people to create their own rooms, but prevent some options from being modified by normal users. + +For example, using this module you can prevent users from making rooms persistent, or making rooms publicly visible. + += Details = + +You need to supply a list of options that will be restricted to admins. Available options can vary, but the following table lists Prosody's built-in options (as defined in XEP-0045): + +|| *Name* || *Description* || +|| muc#roomconfig_roomname || The title/name of the room || +|| muc#roomconfig_roomdesc || The description of the room || +|| muc#roomconfig_persistentroom || Whether the room should remain when empty || +|| muc#roomconfig_publicroom || Whether the room is publicly visible || +|| muc#roomconfig_changesubject || Whether occupants can change the subject || +|| muc#roomconfig_whois || Control who can see occupant's real JIDs || +|| muc#roomconfig_roomsecret || The room password || +|| muc#roomconfig_moderatedroom || Whether the room is moderated || +|| muc#roomconfig_membersonly || Whether the room is members-only || +|| muc#roomconfig_historylength || The length of the room history || + +Some plugins may add other options to the room config (in Prosody 0.10+), for which you will need to consult their documentation for the full option name. + += Configuration = + +Enable the plugin on a MUC host (do not put it in your global modules_enabled list): + +{{{ + Component "conference.example.com" "muc" + modules_enabled = { "muc_config_restrict" } + muc_config_restricted = { + "muc#roomconfig_persistentroom"; -- Prevent non-admins from changing a room's persistence setting + "muc#roomconfig_membersonly"; -- Prevent non-admins from changing whether rooms are members-only + } +}}} + += Compatibility = +|| trunk || Works || +|| 0.9 || Doesn't work || +|| 0.8 || Doesn't work || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_muc_limits/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_muc_limits/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,50 @@ +#summary Impose rate-limits on a MUC +#labels Stage-Beta + += Introduction = + +This module allows you to control the maximum rate of 'events' in a MUC room. This makes it useful to prevent room floods (whether malicious or accidental). + += Details = + +This module limits the following events: + + * Room joins + * Nick changes + * Status changes + * Messages (including private messages) + +The limit is for the room as a whole, not individual occupants in the room. Users with an affiliation (members, admins and owners) are not limited. + += Configuration = + +Add the module to the MUC host (not the global modules_enabled): + +{{{ + Component "conference.example.com" "muc" + modules_enabled = { "muc_limits" } +}}} + +You can define (globally or per-MUC component) the following options: + +|| *Name* || *Default value* || *Description* || +|| muc_event_rate || 0.5 || The maximum number of events per second. || +|| muc_burst_factor || 6 || Allow temporary bursts of this multiple. || + +For more understanding of how these values are used, see the algorithm section below. + += Algorithm = + +A certain number of events are allowed per second, given by muc_event_rate. An event rate of 1 allows one event per second, and event rate of 3 allows three events per second, and 0.5 allows one event every two seconds, and so on. + +Obviously MUC conversations are not exactly steady streams of events. Sometimes multiple people will talk at once. This is handled by the muc_burst_factor option. + +A burst factor of 2 will allow 2 times as many events at once, for 2 seconds, before throttling will be triggered. A factor of 5, 5 times as many events for 5 seconds. + +When the limit is reached, an error response will be generated telling the user the MUC is overactive, and asking them to try again. + += Compatibility = +|| Trunk || Works || +|| 0.8 || Doesn't work`*` || + +`*` This module can be made to work in 0.8 (and _maybe_ previous versions) of Prosody by copying the new [http://hg.prosody.im/trunk/raw-file/fc8a22936b3c/util/throttle.lua util.throttle] into your Prosody source directory (into the util/ subdirectory). \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_muc_log/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_muc_log/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,34 @@ +#summary Log chatroom messages to disk +#labels Stage-Beta + += Introduction = + +This module logs the conversation of chatrooms running on the server to Prosody's data store. To view them you will need a module such as [mod_muc_log_http]. + += Details = + +mod_muc_log must be loaded individually for the components that need it. Assuming you have a MUC component already running on conference.example.org then you can add muc_log to it like so: + +{{{ +Component "conference.example.org" "muc" + modules_enabled = { + "muc_log"; + } +}}} + +Logging is not enabled by default. In 0.9+ logging can be enabled per room in the room config form. + +To enable logging in older versions, or to enable logging by default for all rooms, set + +{{{ +muc_log_by_default = true -- Log all rooms by default +}}} + + += Compatibility = +|| 0.6 || Works || +|| 0.7 || Works || +|| 0.8 || Works || +|| 0.9 || Works || + +*Note* that per-room configuration only works in 0.9+. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_muc_log_http/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_muc_log_http/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,46 @@ +#summary Provides a web interface to stored chatroom logs +#labels Stage-Beta + += Introduction = + +This module provides a built-in web interface to view chatroom logs stored by [mod_muc_log]. + += Installation = + +Just copy the folder muc_log_http as it is, into the modules folder of your Prosody installation. + += Configuration Details = + +Example configuration: + +{{{ + Component "conference.example.com" "muc" + modules_enabled = { + ..... + "muc_log"; + "muc_log_http"; + ..... + } + + muc_log_http = { -- These are the defaults + show_join = true; + show_presences = true; + show_status = true; + theme = "prosody"; + url_base = "muc_log"; + } +}}} + +*show_join* sets the default for showing joins or leaves. +*show_status* sets the default for showing status changes. + +The web interface would then be reachable at the address: +{{{ +http://conference.example.com:5280/muc_log/ +}}} + + += TODO = + * Log bans correctly + * Quota ~ per day ?! + * Testing testing :) diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_muc_restrict_rooms/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_muc_restrict_rooms/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,38 @@ +#summary Regexp based room restriction module + += Introduction = + +This module allows disabling room creation based on regexp patterns defined in configuration. + += Dependencies = + +This module depends on *muc/rooms* module. If *muc/rooms* is not loaded, this module won't work. + += How to load the module = + +Copy the module to the prosody modules/plugins directory. + +In Prosody's configuration file, under the desired MUC component definition, add: +{{{ + modules_enabled = { + ... + "mod_muc_restrict_rooms"; + ... + } +}}} + +*Note*: This module _shouldn't_ be loaded in the global *modules_enabled*, otherwise it won't work. + += Configuration = + +*mod_muc_restrict_rooms* has several variables which let you configure the patterns for room names you want to ban, establish exceptions for those patterns and even deciding whether admins can or not bypass the prohibition. + +|| *Name* || *Description* || *Example* || *Default value* || +|| muc_restrict_matching || Table in the key/value format (keys for patterns and values for reasons) that determines which rooms shouldn't be created. The key is a regexp and must be specified between quotation marks (see example). Room names will be evaluated always lowercase, so define your patterns taking this into consideration. Users that try to join any room that matches one of those rules will get an error telling them they cannot join. || muc_restrict_matching = { ["^admin"] = "Rooms that start with 'admin' are reserved for staff use only" } || {} || +|| muc_restrict_exceptions || String format table that contains exceptions to the above defined rules. Room names specified here will bypass the **muc_restrict_matching** restrictions and will be available for anyone || muc_restrict_exceptions = { "admins_are_good", "admins_rocks" } || {} || +|| muc_restrict_allow_admins || Boolean that determines whether users in the *admin* table are able to bypass any room restriction. If ser to _true_, they will be able to bypass those rules. || muc_restrict_allow_admins = true || false || + += Compatibility = + +|| 0.9 || Works || +|| 0.8 || Should work || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_munin/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_munin/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,10 @@ +#summary Implementation of the Munin node protocol +#labels Stage-Beta + += Summary = + +This module implements the Munin reporting protocol, allowing you to collect statistics directly from Prosody into Munin. + += Compatibility = + +Requires Prosody 0.10 or above diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_net_dovecotauth/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_net_dovecotauth/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,19 @@ += Introduction = + +mod_net_dovecotauth is a server implementation of the Dovecot +authentication protocol. It allows you to authenticate eg Postfix against +your Prosody installation. + +Due to missing support for virtal hosts in this protocol, only one host can be supported. + += Configuration = + +Install and add to modules_enabled like any other module. + +{{{ +dovecotauth_host = "example.com" -- Must be a defined VirtualHost +}}} + += Compatibility = + +Works with 0.9 diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_offline_email/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_offline_email/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,29 @@ +#summary Forward offline messages via email +#labels Stage-Beta + += Introduction = + +Quite often when I am out and about, I'm not able to connect to Jabber. It is usually much more likely I can access my email though (whether via the web, or a mobile client). + +For this reason I decided it would be extremely useful to have Jabber messages sent to me while I was offline forwarded to my email inbox. + += Usage = + +Simply add "offline_email" to your modules_enabled list. When any user receives a message while they are offline, it will automatically be forwarded via mail to the *same* address as their Jabber ID. e.g. user1@example.com's offline messages will be forwarded to user1@example.com's email inbox. + += Configuration = + +|| queue_offline_emails || The number of seconds to buffer messages for, before they are sent as an email. The default is to send each message as it arrives. || +|| smtp_server || Address of the SMTP server to send through. Default 'localhost' (recommended, see caveats below) || +|| smtp_username || If set, Prosody will authenticate with the SMTP server before sending (default is no authentication) || +|| smtp_password || The password for the above user (default is none) || +|| smtp_from || Address from which it will appear the emails came. Default is smtp_username@smtp_server, where smtp_username is replaced with 'xmpp' if not set || + += Compatibility = +||0.9||Works|| + += Caveats/Todos/Bugs = + + * Currently SMTP sending blocks the whole server. This should not be noticable if your mail server is on the same machine as Prosody. + * There is not (yet) any way to configure forwarding to an email address other than your JID (idea... use email address in vcard?) + * Enable/disable this feature per user? \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_onhold/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_onhold/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,16 @@ +#summary Module enabling "on-hold" functionality + += Introduction = + +Enable mod_onhold to allow temporarily placing messages from particular JIDs "on hold" -- i.e. store them, but do not deliver them until the hold status is taken away. + + += Details = + +Right now, it is configured through adding JIDs to a list in prosody.cfg.lua. Eventually, more dynamically configurable support will be added (i.e. with ad-hoc commands or some such thing). + +Simply enable mod_onhold in your list of modules, and then add a line: + +onhold_jids = { "someone@address.com", "someoneelse@address2.com" } + +Until those JIDs are removed, messages from those JIDs will not be delivered. Once they are removed and prosody is restarted, they will be delivered the next time the user to which they are directed logs on. \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_onions/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_onions/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,57 @@ +#summary s2s to Tor hidden services +#labels Stage-Alpha + += Introduction = + +This plugin allows Prosody to connect to other servers that are running as a Tor hidden service. Running Prosody on a hidden service works without this module, this module is only necessary to allow Prosody to federate to hidden XMPP servers. + +For general info about creating a hidden service, see https://www.torproject.org/docs/tor-hidden-service.html.en. + += Usage = +This module depends on the bit32 Lua library. + +To create a hidden service that can federate with other hidden XMPP servers, first add a hidden serivce to Tor. It should listen on port 5269 and optionally also on 5222 (if c2s connections to the hidden service should be allowed). + +Use the hostname that Tor gives with a virtualhost: + +{{{ +VirtualHost "555abcdefhijklmn.onion" + modules_enabled = { "onions" }; +}}} + += Configuration = +|| *Name* || *Description* || *Type* || *Default value* || +|| onions_socks5_host || the host to connect to for Tor's SOCKS5 proxy || string || "127.0.0.1" || +|| onions_socks5_port || the port to connect to for Tor's SOCKS5 proxy || integer || 9050 || +|| onions_only || forbid all connection attempts to non-onion servers || boolean || false || +|| onions_tor_all || pass all s2s connections through Tor || boolean || false || +|| onions_map || override the address for a host || table || {} || + +By setting {{{onions_map}}}, it is possible to override the address used to connect to a given host with the address of a hidden service. The configuration of {{{onions_map}}} works as follows: + +{{{ +onions_map = { + ["jabber.calyxinstitute.org"] = "ijeeynrc6x2uy5ob.onion"; +} +}}} + +or, to also specify a port: + +{{{ +onions_map = { + ["jabber.calyxinstitute.org"] = { host = "ijeeynrc6x2uy5ob.onion", port = 5269 }; +} +}}} + += Compatibility = +||0.8||Doesn't work|| +||0.9||Works|| + += Notes = + + * {{{onions_tor_all}}} does not look up SRV records first. Therefore it will fail for many servers. + * mod_onions currently does not support connecting to {{{.onion}}} entries in SRV records. + += Security considerations = + * Running a hidden service on a server together with a normal server might expose the hidden service. + * A hidden service that wants to remain hidden should either disallow s2s to non-hidden servers or pass all s2s traffic through Tor (setting either {{{onions_only}}} or {{{onions_tor_all}}}). \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_openid/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_openid/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,66 @@ +#summary Enables Prosody to act as an OpenID provider +#labels Stage-Alpha += Introduction = + +[http://openid.net/ OpenID] is an decentralized authentication mechanism for the Web. mod_openid turns Prosody into an OpenID _provider_, allowing users to use their Prosody credentials to authenticate with various third party websites. + += Caveats = + +mod_openid can best be described as a *proof-of-concept*, it has known deficiencies and should *not* be used in the wild as a legitimate OpenID provider. mod_openid was developed using the Prosody 0.4.x series, it has not been tested with the 0.5.x or later series. + += Details = + +OpenID works on the basis of a user proving to a third-party they wish to authenticate with, an OpenID _relaying party_, that they have claim or ownership over a URL, known as an OpenID _identifier_. mod_openid uses Prosody's built in HTTP server to provide every user with an OpenID identifier of the form `http://host.domain.tld[:port]/openid/user`, which would be the OpenID identifier of the user with a Jabber ID of `user@host.domain.tld`. + += Usage = + +Simply add "mod_openid" to your modules_enabled list. You may then use the OpenID identifier form as described above as your OpenID identifier. The port Prosody's HTTP server will listen on is currently set as 5280, meaning the full OpenID identifier of the user `romeo@montague.lit` would be `http://montague.lit:5280/openid/romeo`. + += Configuration = + +mod_openid has no configuration options as of this time. + += TODO = + +The following is a list of the pending tasks which would have to be done to make mod_openid fully featured. They are generally ranked in order of most importance with an estimated degree of difficulty. + + # Support Prosody 0.6.x series (_Medium_) + # Refactor code (_Medium_) + * The code is pretty messy at the moment, it should be refactored to be more easily understood. + # Disable use of "user@domain" OpenID identifier form (_Easy_) + * This is a vestigial feature from the early design, allowing explicit specification of the JID. However the JID can be inferred from the simpler OpenID identifier form. + # Use a cryptographically secure Pseudo Random Number Generator (PRNG) (_Medium_) + * This would likely be accomplished using luacrypto which provides a Lua binding to the OpenSSL PRNG. + # Make sure OpenID key-value pairs get signed in the right order (_Hard_) + * It is important that the OpenID key-value responses be signed in the proper order so that the signature can be properly verified by the receiving party. This may be complicated by the fact that the iterative ordering of keys in a Lua table is not guaranteed for non-integer keys. + # Do an actual match on the OpenID realm (_Medium_) + * The code currently always returns true for matches against an OpenID realm, posing a security risk. + # Don't use plain text authentication over HTTP (_Hard_) + * This would require some Javascript to perform a digest. + # Return meaningful error responses (_Medium_) + * Most error responses are an HTTP 404 File Not Found, obviously something more meaningful could be returned. + # Enable Association (_Hard_) + * Association is a feature of the OpenID specification which reduces the number of round-trips needed to perform authentication. + # Support HTTPS (_Medium_) + * With option to only allow authentication through HTTPS + # Enable OpenID 1.1 compatibility (_Medium_) + * mod_openid is designed from the OpenID 2.0 specification, which has an OpenID 1.1 compatibility mode. + # Check specification compliance (_Medium_) + * Walk through the code and make sure it complies with the OpenID specification. Comment code as necessary with the relevant sections in the specification. + +Once all these steps are done, mod_openid could be considered to have reached "beta" status and ready to real world use. The following are features that would be nice to have in a stable release: + + # Allow users to always trust realms (_Hard_) + # Allow users to remain logged in with a cookie (_Hard_) + # Enable simple registration using a user's vCard (_Medium_) + # More useful user identity page (_Hard_) + * Allow users to alter what realms they trust and what simple registration information gets sent to relaying parties by default. + # OpenID Bot (_Hard_) + * Offers all functionality of the user identity page management + # Better designed pages (Easy) + * Use semantic XHTML and CSS to allow for custom styling. + * Use the Prosody favicon. + += Useful Links = + * [http://openid.net/developers/specs/ OpenID Specifications] + * [http://en.wikipedia.org/wiki/OpenID OpenID on Wikipedia] \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_pastebin/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_pastebin/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,43 @@ +#summary Redirect long messages to built-in pastebin +#labels Stage-Stable + += Introduction = + +Pastebins are used very often in IM, especially in chat rooms. You have a long log or command output which you need to send to someone over IM, and don't want to fill their message window with it. Put it on a pastebin site, and give them the URL instead, simple. + +Not for everyone... no matter how hard you try, people will be unaware, or not care. They may also be too lazy to visit a pastebin. This is where mod_pastebin comes in! + += Details = + +When someone posts to a room a "large" (the actual limit is configurable) message, Prosody will intercept the message and convert it to a URL pointing to a built-in pastebin server. The URLs are randomly generated, so they can be considered for most purposes to be private, and cannot be discovered by people who are not in the room. + += Usage = + +To set up mod_pastebin for MUC rooms it *must* be explicitly loaded, as in the example below - it won't work when loaded globally, as that will only load it onto normal virtual hosts. + +For example: +{{{ +Component "conference.example.com" "muc" + modules_enabled = { "pastebin" } +}}} + +Pastes will be available by default at `http://:5280/pastebin/` by default. This can be changed with `pastebin_ports` (see below), or you can forward another external URL from your web server to Prosody, use `pastebin_url` to set that URL. + += Configuration = +||pastebin_ports||List of ports to run the HTTP server on, same format as mod_httpserver's http_ports|| +||pastebin_threshold||Maximum length (in characters) of a message that is allowed to skip the pastebin. (default 500 characters)|| +||pastebin_line_threshold||The maximum number of lines a message may have before it is sent to the pastebin. (default 4 lines)|| +||pastebin_trigger||A string of characters (e.g. "!paste ") which if detected at the start of a message, always sends the message to the pastebin, regardless of length. (default: not set)|| +||pastebin_url||Base URL to display for pastebin links, must end with / and redirect to Prosody's built-in HTTP server|| +||pastebin_expire_after||Number of hours after which to expire (remove) a paste, defaults to 24. Set to 0 to store pastes permanently on disk.|| + += Compatibility = +||0.9||Works, but pastebin_ports does not exist anymore, see the 0.9.0 release notes|| +||0.8||Works|| +||0.7||Works|| +||0.6||Works|| + += Todo = + + * Maximum paste length + * Web interface to submit pastes? diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_pep_vcard_avatar/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_pep_vcard_avatar/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,17 @@ +#summary Sync avatars between vCards and PEP +#labels Stage-Alpha + += Introduction = + +This module pushes the users nickname and avatar from vCards into PEP, or into vCards from PEP. This allows interop between older clients that use [http://xmpp.org/extensions/xep-0153.html XEP-0153: vCard-Based Avatars] to see the avatars of clients that use [http://xmpp.org/extensions/xep-0084.html XEP-0084: User Avatar] and vice versa. + += Configuration = + +Simply [https://prosody.im/doc/installing_modules#prosody-modules enable it like most other modules], no further configuration needed. + += Compatibility = + +|| trunk || Works || +|| 0.10 || Works || +|| 0.9 || Does not work || +|| 0.8 || Does not work || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_post_msg/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_post_msg/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,21 @@ +#summary Receives HTTP POST request, parses it and relays it into XMPP. + += Introduction = + +Sometimes it's useful to have different interfaces to access XMPP. + +This is example of sending message using HTTP POST to XMPP. For sure we need user auth information. + += Example usage = + +* curl http://example.com:5280/msg/user -u me@example.com:mypassword -H "Content-Type: text/plain" -d "Server@host has just crashed!" + +This would send a message to user@example.com from me@example.com + += Details = + +By Kim Alvefur + +Some code borrowed from mod_webpresence + + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_privacy_lists/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_privacy_lists/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,16 @@ +#summary Privacy lists (XEP-0016) support +#labels Stage-Beta + += Introduction = + +Privacy lists are a flexible method for blocking communications. + +Originally known as _mod`_`privacy_ and bundled with Prosody, this module is being phased out in favour of the newer simpler blocking (XEP-0191) protocol, implemented in mod_blocklist. + += Configuration = + +None. Each user can specify their privacy lists using their client (if it supports XEP-0016). + += Compatibility = +|| 0.9 || Works || +|| 0.10 || Works || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_private_adhoc/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_private_adhoc/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,10 @@ +#summary Retrieve private XML data via adhoc command + += Introduction = + +This is a very simple module which implements an adhoc commant toretrieves the users private XML data. + + += Details = + +Simple module which adds the adhoc command "Query private data" and will return the users private XML data (typically muc bookmarks,.. ). \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_privilege/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_privilege/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,93 @@ +#summary XEP-0356 (Privileged Entity) implementation +#labels Stage-Alpha + += Introduction = + +Privileged Entity is an extension which allows entity/component to have privileged access to server (set/get roster, send message on behalf of server, access presence informations). It can be used to build services independently of server (e.g.: PEP service). + += Details = + +You can have all the details by reading the [http://xmpp.org/extensions/xep-0356.html XEP-0356]. + +If you use it with a component, you need to patch core/mod_component.lua to fire a new signal. To do it, copy the following patch in a, for example, /tmp/component.patch file: +{{{ +diff --git a/plugins/mod_component.lua b/plugins/mod_component.lua +--- a/plugins/mod_component.lua ++++ b/plugins/mod_component.lua +@@ -85,6 +85,7 @@ + session.type = "component"; + module:log("info", "External component successfully authenticated"); + session.send(st.stanza("handshake")); ++ module:fire_event("component-authenticated", { session = session }); + + return true; + end +}}} + +Then, at the root of prosody, enter: + +{{{patch -p1 < /tmp/component.patch}}} + += Usage = + +To use the module, like usual add *"privilege"* to your modules_enabled. Note that if you use it with a local component, you also need to activate the module in your component section: + +{{{ +modules_enabled = { + [...] + + "privilege"; +} + +[...] + +Component "youcomponent.yourdomain.tld" + component_secret = "yourpassword" + modules_enabled = {"privilege"} +}}} + +then specify privileged entities *in your host section* like that: + +{{{ +VirtualHost "yourdomain.tld" + + privileged_entities = { + ["romeo@montaigu.lit"] = { + roster = "get"; + presence = "managed_entity"; + }, + ["juliet@capulet.lit"] = { + roster = "both"; + message = "outgoing"; + presence = "roster"; + }, + } +}}} + +Here _romeo@montaigu.lit_ can *get* roster of anybody on the host, and will *have presence for any user* of the host, while _juliet@capulet.lit_ can *get* and *set* a roster, *send messages* on the behalf of the server, and *access presence of anybody linked to the host* (not only people on the server, but also people in rosters of users of the server). + +*/!\ Be extra careful when you give a permission to an entity/component, it's a powerful access, only do it if you absoly trust the component/entity, and you know where the software is coming from* + += Configuration = +All the permissions give access to all accounts of the virtual host. +== roster == +||none _(default)_||No access to rosters|| +||get||Allow *read* access to rosters|| +||set||Allow *write* access to rosters|| +||both||Allow *read* and *write* access to rosters|| + +== message == +||none _(default)_||Can't send message from server|| +||outgoing||Allow to send message on behalf of server (from bare jids)|| + +== presence == +||none _(default)_||Do not have extra presence information|| +||managed_entity||Receive presence stanzas (except subscriptions) from host users|| +||roster||Receive all presence stanzas (except subsciptions) from host users and people in their rosters|| + += Compatibility = +||dev||Need a patched core/mod_component.lua (see above)|| +||0.9||Need a patched core/mod_component.lua (see above)|| + += Note = +This module is often used with mod_delegation (c.f. XEP for more details) diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_profile/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_profile/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,23 @@ +#summary Replacement for mod_vcard with vcard4 support and PEP integration + += Introduction = + +This module provides a replacement for mod_vcard. In addition to the ageing protocol defined by [http://xmpp.org/extensions/xep-0054.html XEP-0054], it also supports the [http://xmpp.org/extensions/xep-0292.html new vCard 4 based protocol] and integrates with [http://xmpp.org/extensions/xep-0163.html Personal Eventing Protocol]. The vCard 4, [http://xmpp.org/extensions/xep-0084.html User Avatar] and [http://xmpp.org/extensions/xep-0172.html User Nickname] PEP nodes are updated when the vCard is changed.. + += Configuration = + +{{{ +modules_enabled = { + -- "pep"; -- These two modules must be removed + -- "vcard"; + + "profile"; +} +}}} + + += Compatibility = + +Compatible with trunk after 2014-05-29. + +It depends on the new mod_pep_plus for PEP support. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_proxy65/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_proxy65/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,31 @@ +#summary XEP-0065: SOCKS5 Bytestreams file transfer proxy +#labels Stage-Beta, Deprecated + += Introduction = + +mod_proxy65 implements XEP-0065: SOCKS5 Bytestreams as a component. It allows the server to proxy file transfers between 2 clients that are behind NAT routers or firewalls, and otherwise wouldn't be able to transfer files. + += Details = +Once set up, depending on which client you are using the proxy may be automatically used, or the client may have to be configured. Consult your client's friendly documentation for more information :) + += Usage = +{{{ +Component "proxy.example.com" "proxy65" +}}} + += Configuration = +Although none are required, under the Component section mod_proxy65 understands several configuration options: + +||proxy65_interface||The server's interface (IP address) to bind (listen) on (default is "`*`", meaning all interfaces)|| +||proxy65_address||The advertised address of the proxy, which clients use to connect to (default is the same as the hostname of the component)|| +||proxy65_port||The port on the server to which clients should connect (default is port 5000)|| +||proxy65_acl||Access Control List, when specified all users will be denied access unless in the list. The list can contain domains, bare jids (normal) or full jids (including a resource). e.g. proxy65_acl = {"example.com", "theadmin@anotherdomain.com", "only@fromwork.de/AtWork"}|| + += Compatibility = +||0.7 and above||Officially included in Prosody|| +||0.6||Works|| +||0.5||Should work|| + += Todo = + * Optional support for UDP connections + * Statistics, bandwidth limits/monitoring diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_proxy65_whitelist/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_proxy65_whitelist/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,20 @@ +#summary Limit which file transfer users can use +#labels Stage-Alpha + += Introduction = + +This module attempts to restrict use of non-whitelisted XEP-0065 proxies. + += Configuration = + +Without any options, the module will restrict users to local [https://prosody.im/doc/modules/mod_proxy65 proxy65 components]. + +{{{ +-- additional proxies to allow +allowed_streamhosts = { "proxy.eu.jabber.org" } +}}} + +The module will add all local proxies to that list. To prevent it from doing that, set +{{{ +allow_local_streamhosts = false +}}} diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_pubsub_eventsource/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_pubsub_eventsource/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,39 @@ +#summary Subscribe to pubsub nodes using the HTML5 EventSource API +#labels Stage-Beta + += Introduction = + +[https://en.wikipedia.org/wiki/Server-sent_events Server-Sent Events] is a simple HTTP/line-based protocol supported in HTML5, making it easy to receive a stream of "events" in realtime using the Javascript [https://developer.mozilla.org/en-US/docs/Web/API/EventSource EventSource API]. + +EventSource is supported in [http://caniuse.com/#feat=eventsource most modern browsers], and for the remainder there are 'polyfill' compatibility layers such as [https://github.com/remy/polyfills/blob/master/EventSource.js EventSource.js] and [https://github.com/rwldrn/jquery.eventsource jquery.eventsource]. + += Details = + +Subscribing to a node from Javascript is easy: + +{{{ + var source = new EventSource('http://pubsub.example.org:5280/eventsource/mynode'); + source.onmessage = function (event) { + console.log(event.data); // Do whatever you want with the data here + }; +}}} + +== Cross-domain issues == +The same cross-domain restrictions apply to EventSource that apply to BOSH, and support for CORS is not clearly standardized yet. You may want to proxy connections through your web server for this reason. See [https://prosody.im/doc/setting_up_bosh#proxying_requests BOSH: Cross-domain issues] for more information. + += Configuration = +There is no special configuration for this module. Simply load it onto a pubsub component like so: + +{{{ + Component "pubsub.example.org" "pubsub" + modules_enabled = { "pubsub_eventsource" } +}}} + +As it uses HTTP to serve the event streams, you can use Prosody's standard [https://prosody.im/doc/http HTTP configuration options] to control how/where the streams are served. + +*Note about URLs:* It is important to get the event streams from the correct hostname (that of the pubsub host). An example stream URL is `http://pubsub.example.org:5280/eventsource/mynode`. If you need to access the streams using another hostname (e.g. `example.org`) you can use the `http_host` option under the Component, e.g. `http_host = "example.org"`. For more information see the [https://prosody.im/doc/http#virtual_hosts 'Virtual Hosts'] section of our HTTP documentation. + += Compatibility = +|| 0.9 || Works || +|| 0.8 || Doesn't work || +|| Trunk || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_pubsub_feeds/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_pubsub_feeds/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,31 @@ +#summary Subscribe to Atom and RSS feeds over pubsub + += Introduction = + +This module allows Prosody to fetch Atom and RSS feeds for you, and push new results to subscribers over XMPP. + +This module also implements a [http://pubsubhubbub.googlecode.com/svn/trunk/pubsubhubbub-core-0.3.html PubSubHubbub] subscriber, allowing updates be delivered without polling for supporting feed publishers. + += Configuration = + +This module must be loaded on a Prosody pubsub component. Add it to `modules_enabled` and configure like so: + +{{{ +Component "pubsub.example.com" "pubsub" + modules_enabled = { "pubsub_feeds" } + + feeds = { + planet_jabber = "http://planet.jabber.org/atom.xml"; + prosody_blog = "http://blog.prosody.im/feed/atom.xml"; + } +}}} + +This example creates two nodes, 'planet_jabber' and 'prosody_blog' that clients can subscribe to using [http://xmpp.org/extensions/xep-0060.html XEP-0060]. Results are in [http://atomenabled.org/ ATOM 1.0 format] for easy consumption. + +|| *Option* || *Description* || +|| feeds || A list of virtual nodes to create and their associated Atom or RSS URL. || +|| feed_pull_interval || Number of minutes between polling for new results (default 15) || +|| use_pubsubhubub || If PubSubHubbub should be enabled, true by default. || + += Compatibility = +|| 0.9 || Works || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_pubsub_github/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_pubsub_github/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,32 @@ +#summary Publish Github commits over pubsub +#labels Stage-Beta + += Introduction = + +This module accepts Github web hooks and publishes them to a local pubsub component for XMPP clients to subscribe to. + +Entries are pushed as Atom payloads. + += Configuration = + +Load the module on a pubsub component: + +{{{ +Component "pubsub.example.com" "pubsub" + modules_enabled = { "pubsub_github" } +}}} + +The module also takes the following config options: + +|| *Name* || *Default* || *Description* || +|| github_node || "github" || The pubsub node to publish commits on. || + +The URL for Github to post to would be either: + + * http://pubsub.example.com:5280/pubsub_github + * https://pubsub.example.com:5281/pubsub_github + +If your HTTP host doesn't match the pubsub component's address, you will need to inform Prosody. For more info see Prosody's [https://prosody.im/doc/http#virtual_hosts HTTP server documentation]. + += Compatibility = +|| 0.9 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_pubsub_hub/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_pubsub_hub/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,28 @@ +#summary PubSubHubbub service + += Introduction = + +This module implements a +[http://pubsubhubbub.googlecode.com/svn/trunk/pubsubhubbub-core-0.3.html PubSubHubbub] +(PuSH) hub, allowing PuSH clients to subscribe to local XMPP +[http://xmpp.org/extensions/xep-0060.html Publish-Subscribe] nodes stored by +[http://prosody.im/doc/modules/mod_pubsub mod_pubsub]. + += Configuration = + +{{{ +Component "pubsub.example.com" "pubsub" + + modules_enabled = { + "pubsub_hub"; + } + +}}} + +The hub is then available on {http://pubsub.example.com:5280/hub}. + += Compatibility = + +||trunk||Works|| +||0.9||Works|| +||0.8||Doesn't work|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_pubsub_mqtt/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_pubsub_mqtt/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,41 @@ +#summary MQTT interface to Prosody's pubsub +#labels Stage-Beta + += Introduction = + +[http://mqtt.org/ MQTT] is a lightweight binary pubsub protocol suited to embedded devices. This module provides a way for MQTT clients to connect to Prosody and publish or subscribe to local pubsub nodes. + += Details = + +MQTT has the concept of 'topics' (similar to XMPP's pubsub 'nodes'). mod_pubsub_mqtt maps pubsub nodes to MQTT topics of the form `HOST/NODE', e.g. `pubsub.example.org/mynode`. + +== Limitations == +The current implementation is quite basic, and in particular: + + * Authentication is not supported + * SSL/TLS is not supported + * Only QoS level 0 is supported + +== Payloads == +XMPP payloads are always XML, but MQTT does not define a payload format. Therefore mod_pubsub_mqtt will attempt to convert data of certain recognised payload types. Currently supported: + + * JSON (see [http://xmpp.org/extensions/xep-0335.html XEP-0335] for the format) + * Plain UTF-8 text (wrapped inside ``) + +All other XMPP payload types are sent to the client directly as XML. Data published by MQTT clients is currently never translated, and always treated as UTF-8 text. + += Configuration = + +There is no special configuration for this module. Simply load it on your pubsub host like so: + +{{{ +Component "pubsub.example.org" "pubsub" + modules_enabled = { "pubsub_mqtt" } +}}} + +You may also configure which port(s) mod_pubsub_mqtt listens on using Prosody's standard config directives, such as `mqtt_ports`. Network settings *must* be specified in the global section of the config file, not under any particular pubsub component. The default port is 1883 (MQTT's standard port number). + += Compatibility = +|| trunk || Works || +|| 0.9 || Works || +|| 0.8 || Doesn't work || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_pubsub_twitter/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_pubsub_twitter/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,30 @@ +#summary Subscribe to Twitter search queries over pubsub +#labels Stage-Alpha + += Introduction = + +Twitter has an open 'realtime' search API, but it requires polling (within their rate limits). This module allows Prosody to poll for you, and push new results to subscribers over XMPP. + += Configuration = + +This module must be loaded on a Prosody pubsub component. Add it to `modules_enabled` and configure like so: + +{{{ +Component "pubsub.example.com" "pubsub" + modules_enabled = { "pubsub_twitter" } + + twitter_searches = { + realtime = "xmpp OR realtime"; + prosody = "prosody xmpp"; + } +}}} + +This example creates two nodes, 'realtime' and 'prosody' that clients can subscribe to using [http://xmpp.org/extensions/xep-0060.html XEP-0060]. Results are in [http://atomenabled.org/ ATOM 1.0 format] for easy consumption. + +|| *Option* || *Description* || +|| twitter_searches || A list of virtual nodes to create and their associated Twitter search queries. || +|| twitter_pull_interval || Number of minutes between polling for new results (default 20) || +|| twitter_search_url || URL of the JSON search API, default: "http://search.twitter.com/search.json" || + += Compatibility = +|| 0.9 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_rawdebug/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_rawdebug/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,24 @@ +#summary Telnet command for raw stanza logging + += Summary = + +Sometimes it is useful to get the raw XML logs from clients for debugging purpouses, but some cliens don't expose this. This command lets you activate this on specific sessions. + += Usage = + +In the telnet console: + +{{{ +c2s:show() +| example.com +| user@example.com/bd0b8b19 [c2sb75e93d8] available(0) (encrypted) +| ... +| OK: Total: $n clients + + +rawdebug:enable"user@example.com/bd0b8b19" +> OK +}}} + +Then everything sent and received will be logged to debug levels. + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_register_json/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_register_json/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,63 @@ +#summary Token based JSON registration & verification servlet. +#labels Stage-Stable + += Introduction = + +This module let's you activate a httpserver interface to handle data from webforms with POST and Base64 encoded JSON. + += Implementation Details = + +Example Request format: + +{{{ +POST /your_register_base_url HTTP/1.1 +Host: yourserveraddress.com:yourchoosenport +Content-Type: application/encoded +Content-Transfer-Encoding: base64 + +eyJ1c2VybmFtZSI6InVzZXJuYW1lb2ZjaG9pY2UiLCJwYXNzd29yZCI6InRoZXVzZXJwYXNzd29yZCIsImlwIjoidGhlcmVtb3RlYWRkcm9mdGhldXNlciIsIm1haWwiOiJ1c2VybWFpbEB1c2VybWFpbGRvbWFpbi50bGQiLCJhdXRoX3Rva2VuIjoieW91cmF1dGh0b2tlbm9mY2hvaWNlIn0= +}}} + +Where the encoded content is this (example) JSON Array: + + +{"username":"usernameofchoice","password":"theuserpassword","ip":"theremoteaddroftheuser","mail":"usermail@usermaildomain.tld","auth_token":"yourauthtokenofchoice"} + + +Your form implementation needs to pass *all* parameters, the auth_token is needed to prevent misuses, if the request is successfull the server will answer with status code 200 and with the body of the response containing the token which your web app can send via e-mail to the user to complete the registration. + +Else, it will reply with the following http error codes: + + * 400 - if there's an error syntax; + * 401 - whenever an username is already pending registration or the auth token supplied is invalid; + * 403 - whenever registration is forbidden (blacklist, filtered mail etc.); + * 406 - if the username supplied fails nodeprepping; + * 409 - if the user already exists, or an user is associated already with the supplied e-mail; + * 503 - whenever a request is throttled. + +The verification URL path to direct the users to will be: */your-base-path-of-choice/verify/* - on your Prosody's http server. + +The module for now stores a hash of the user's mail address to help slow down duplicated registrations. + +It's strongly encouraged to have the web server communicate with the servlet via https. + += Usage = + +Copy the module folder and all its contents (register_json) into your prosody modules' directory. +Add the module your vhost of choice modules_enabled. + +Hint: pairing with mod_register_redirect is helpful, to allow server registrations only via your webform. + +Optional configuration directives: + +reg_servlet_base = "/base-path/" -- Base path of the plugin (default is register_account) +reg_servlet_secure = true -- Have the plugin only process requests on https (default is true) +reg_servlet_ttime = seconds -- Specifies the time (in seconds) between each request coming from the same remote address. +reg_servlet_bl = { "1.2.3.4", "4.3.2.1" } -- The ip addresses in this list will be blacklisted and will not be able to submit registrations. +reg_servlet_wl = { "1.2.3.4", "4.3.2.1" } -- The ip addresses in this list will be ignored by the throttling. +reg_servlet_filtered_mails = { ".*banneddomain.tld", ".*deamailprovider.tld" } -- allows filtering of mail addresses via Lua patterns. + + += Compatibility = + + * 0.9 \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_register_redirect/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_register_redirect/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,36 @@ +#summary XEP-077 IBR Registration Redirect. +#labels Stage-Stable + += Introduction = + +Registration Redirect as explained in the [http://xmpp.org/extensions/xep-0077.html#redirect IBR XEP]. + += Details = + +This module shows instructions on how to register to the server, should it be necessary to perform it through other means Out-Of-Band or not, and also let's registrations origining from ip addresses in the whitelist to go through normally. + += Usage = + +Copy the module file into your Prosody modules directory. + +The module will work "out of the box" as long as at least an admin entry is specified (see admins = {} option into prosody's documentation). +These are the optional parameters you can specify into your global server/hostname configuration: +{{{ +registration_whitelist = { "*your whitelisted web server ip address*" } +registrarion_url = "*your web registration page url*" +registration_text = "Your custom instructions banner here" +registration_oob = true (default) or false, in the case there's no applicable OOB method (e.g. the server admins needs to be contacted by phone) +}}} + +To not employ any whitelisting (i.e. registration is handled externally). +{{{ +no_registration_whitelist = true +}}} + += Compatibility = + + * 0.9 works + * 0.8 works + * 0.7 might not work + * 0.6 won't work + * 0.5 won't work diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_register_web/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_register_web/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,40 @@ +#summary A web interface to register user accounts +#labels Stage-Alpha + += Introduction = + +There are various reasons to prefer web registration instead of "in-band" account registration over XMPP. For example the lack of CAPTCHA support in clients and servers. + += Details = + +mod_register_web has Prosody serve a web page where users can sign up for an account. It implements reCaptcha to prevent automated sign-ups (from bots, etc.). + += Configuration = + +The module is served on Prosody's default HTTP ports at the path `/register_web`. More details on configuring HTTP modules in Prosody can be found in our [http://prosody.im/doc/http HTTP documentation]. + +To configure the CAPTCHA you need to supply a 'captcha_options' option: + +{{{ + captcha_options = { + recaptcha_private_key = "12345"; + recaptcha_public_key = "78901"; + } +}}} + +The keys for reCaptcha are available in your reCaptcha account, visit [http://recaptcha.net/ recaptcha.net] for more info. + +If no reCaptcha options are set, a simple built in captcha is used. + += Compatibility = +|| 0.9 || Works || +|| 0.8 || Doesn't work || + += Todo = + +Lots. The module is very basic at the moment. In particular I would like to see: + + * Customisation (CSS and/or HTML) + * Different CAPTCHA implementation support + * Collection of additional data, such as email address + * The module kept simple! \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_reload_modules/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_reload_modules/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,21 @@ +#summary Automatically reload modules with the config +#labels Stage-Stable + += Introduction = + +By default Prosody does not reload modules at runtime unless instructed to via one of its admin interfaces. However sometimes you want to easily reload a module to apply new settings when the config changes. + +mod_reload_modules will reload a set list of modules every time Prosody reloads its config (e.g. on SIGHUP). + += Configuration = + +Add "reload_modules" to modules_enabled. Then the list of modules to reload using the 'reload_modules' option in your config like so: + +{{{ + reload_modules = { "groups", "tls" } +}}} + +This would reload mod_groups and mod_tls whenever the config is reloaded. Note that on many systems this will be at least daily, due to logrotate. + += Compatibility = +|| 0.9 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_require_otr/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_require_otr/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,22 @@ +#summary Enforce a policy for OTR-encrypted messages +#labels Stage-Stable + += Introduction = + +[https://otr.cypherpunks.ca/ OTR, "Off The Record"], encryption allows clients to encrypt messages such that the server cannot read/modify them. + +This module allows the server admin to require that all messages are OTR-encrypted. + += Configuration = + +Just enable the module by adding it to your global `modules_enabled`, or if you only want to load it on a single host you can load it only for one host like this: + +{{{ +VirtualHost "example.com" + modules_enabled = { "require_otr" } +}}} + +=== Compatibility === +||0.10||Works|| +||0.9||Works|| +||0.8||Works|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_roster_allinall/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_roster_allinall/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,13 @@ += Introduction = + +This module is similar in purpouse to mod_groups, for when you want all users on the server to be in each others roster. + += Details = + +Upon login, this module will add all currently logged in users to the logging in users roster. + += Configuration = + +Just add it to the modules_enabled, after that there is no further configuration. + + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_roster_command/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_roster_command/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,51 @@ +#summary Manage rosters through prosodyctl +#labels Stage-Beta + += Introduction = + +This module allows you to perform various actions on user rosters via prosodyctl. + += Details = + +After putting this module in your modules directory you can use it via prosodyctl like this: + +{{{ + prosodyctl mod_roster_command COMMAND [OPTIONS...] +}}} + +*Note:* Do not add mod_roster_command to your Prosody config file. This is unnecessary because it will automatically be loaded by prosodyctl when you use it. + +== Commands == + +{{{ + subscribe user@host contact@host +}}} + +Subscribes the user to the contact's presence. That is, the user will see when the contact is online (but the contact won't see the user). + +{{{ + subscribe_both user@host contact@host +}}} +The same as the 'subscribe' command, but performs the subscription in both directions, so that both the contact and user will always see each other online. + +{{{ + unsubscribe user@host contact@host +}}} + +Removes a subscription to the contact's presence. + +{{{ + unsubscribe_both user@host contact@host +}}} + +Same as unsubscribe, but also revokes a contact's subscription to the user's presence. + +{{{ + rename user@host contact@host [name] [group] +}}} + +Sets or updates a name for a contact in the user's roster, and moves the contact to the given group, if specified. + += Compatibility = +|| 0.9 || Works || +|| 0.8 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_s2s_auth_compat/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_s2s_auth_compat/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,5 @@ +#summary Workaround for servers doing EXTERNAL without proper stream headers + += Introduction = + +This module is a workaround for servers that try to do s2s authentication with certificates and SASL EXTERNAL, but do not send correct stream headers. Notably Openfire versions since 3.7 or 3.8. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_s2s_auth_dane/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_s2s_auth_dane/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,60 @@ +#summary S2S authentication using DANE +#labels Stage-Alpha,Type-S2SAuth + += Introduction = + +This module implements DANE as described in +[http://tools.ietf.org/html/draft-miller-xmpp-dnssec-prooftype Using DNS Security Extensions (DNSSEC) and DNS-based Authentication of Named Entities (DANE) as a Prooftype for XMPP Domain Name Associations]. + += Dependencies = + +This module requires a DNSSEC aware DNS resolver. Prosodys internal DNS +module does not support DNSSEC. Therefore, to use this module, a +replacement is needed, such as [https://www.zash.se/luaunbound.html this one]. + +More installation instructions can be found at [https://www.zash.se/prosody-dane.html Prosody with DANE]. + += Configuration = + +After [https://prosody.im/doc/installing_modules installing the module], just add it to `modules_enabled`; + +{{{ +modules_enabled = { + ... + "s2s_auth_dane"; +} +}}} + += DNS Setup = + +In order for other services to verify your site using using this plugin, +you need to publish TLSA records (and they need to have this plugin). +Here's an example using "DANE-EE Cert SHA2-256" for a host named +xmpp.example.com serving the domain example.com. + +{{{ +$ORIGIN example.com. +; Your standard SRV record +_xmpp-server._tcp.example.com IN SRV 0 0 5269 xmpp.example.com. +; IPv4 and IPv6 addresses +xmpp.example.com. IN A 192.0.2.68 +xmpp.example.com. IN AAAA 2001:0db8:0000:0000:4441:4e45:544c:5341 + +; The DANE TLSA records. These three are equivalent, you would use only one of them. +; First, using symbolic names: +_5269._tcp.xmpp.example.com. 300 IN TLSA DANE-EE Cert SHA2-256 E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855 +; Using numbers: +_5269._tcp.xmpp.example.com. 300 IN TLSA 3 0 1 E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855 +; Raw binary format, should work even with very old DNS tools: +_5269._tcp.xmpp.example.com. 300 IN TYPE52 \# 35 030001E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855 +}}} + +[http://www.internetsociety.org/deploy360/dnssec/tools/ List of DNSSEC and DANE tools] + += Further reading = + +* [http://tools.ietf.org/html/draft-ietf-dane-ops DANE TLSA implementation and operational guidance] + += Compatibility = + +Requires 0.9 or above. \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_s2s_auth_fingerprint/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_s2s_auth_fingerprint/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,37 @@ +#summary Fingerprint based s2s authentication +#labels Stage-Alpha, Type-S2SAuth + += Introduction = + +This module allows you to manually pin certificate fingerprints of remote servers. + += Details = + +Servers not listed in the configuration are not affected. + += Configuration = + +After installing and enabling this module, you can put fingerprints of remote servers in your config like this: + +{{{ +s2s_auth_fingerprint_digest = "sha1" -- This is the default. Other options are "sha256" and "sha512" +s2s_trusted_fingerprints = { + ["jabber.org"] = "11:C2:3D:87:3F:95:F8:13:F8:CA:81:33:71:36:A7:00:E0:01:95:ED"; + ["matthewwild.co.uk"] = { + "FD:7F:B2:B9:4C:C4:CB:E2:E7:48:FB:0D:98:11:C7:D8:4D:2A:62:AA"; + "CF:F3:EC:43:A9:D5:D1:4D:D4:57:09:55:52:BC:5D:73:06:1A:A1:A0"; + }; +} + +-- If you don't want to fall back to dialback, you can list the domains s2s_secure_domains too +s2s_secure_domains = { + "jabber.org"; +} +}}} + += Compatibility = + +||trunk||Works|| +||0.9||Works|| +||0.8||Doesn't work|| + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_s2s_auth_monkeysphere/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_s2s_auth_monkeysphere/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,15 @@ +#summary Monkeysphere certificate checking for s2s +#labels Stage-Alpha, Type-S2SAuth + += Introduction = + +[http://web.monkeysphere.info/ Monkeysphere] is a project aiming to introduce PGP's web of trust to protocols such as SSH and TLS (which XMPP uses). + += Details = + +This module is currently just a prototype, it has numerous issues and is *not* suitable for production use. + += Compatibility = +|| trunk || Works || +|| 0.10 || Works || +|| 0.9 || Works || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_s2s_blackwhitelist/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_s2s_blackwhitelist/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,45 @@ +#summary Module for setting blacklist and whitelist on new server to server connections +#labels Deprecated + += Introduction = + +This module adds the functionality of blacklist and whitelist for new server to server connections (federation). + + += Details = + +If the configuration is changed then you can use console to issue "config:reload()" and this plugin will automatically reload the black/whitelists. + +You can either choose whitelist or blacklist functionality (both can't co-exist). + +Note: If a host with existing connections is blacklisted then this module will not tear down existing connection since that was created when the connection agreement was valid. You will need to use "s2s:close" command on console to manually close those connections. + += Configuration = + +First define whether you need blacklist or whitelist, + +{{{ +s2s_enable_blackwhitelist = "whitelist" -- enable whitelist. use blacklist to use blacklists +}}} + +Now create populate an array of domains in those lists + +For whitelist, + +{{{ +s2s_whitelist = { "abc.net", "gmail.com", "xyz.net" } +}}} + +For blacklist, + +{{{ +s2s_blacklist = { "gmail.com", "xyz.com" } +}}} + +You can change configuration at runtime but need to use console plugin to reload configuration via "config:reload" command. + += Compatibility = + +|| 0.9 || Doesn't work || +|| 0.8 || Unknown || +|| 0.7 || tested to work with dialbacks || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_s2s_idle_timeout/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_s2s_idle_timeout/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,18 @@ +#summary Close idle server-to-server connections +#labels Stage-Stable + += Introduction = + +Some people find it preferable to close server-to-server connections after they have been silent for a while. + + += Configuration = +...is trivial. The default timeout is 300 seconds (5 minutes). To change this simply put in the config: + +{{{ + s2s_idle_timeout = 60 -- or any other number of seconds +}}} + += Compatibility = +|| 0.6 || Works || +|| 0.7 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_s2s_log_certs/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_s2s_log_certs/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,32 @@ +#summary Log certificate status and fingerprint of remote servers + += Introduction = + +This module produces info level log messages with the certificate status +and fingerprint every time an s2s connection is established. It can also +optionally store this in persistant storage. + +*info* jabber.org has a trusted valid certificate with SHA1: 11:C2:3D:87:3F:95:F8:13:F8:CA:81:33:71:36:A7:00:E0:01:95:ED + +Fingerprints could then be added to [mod_s2s_auth_fingerprint]. + += Configuration = + +Add the module to the `modules_enabled` list. + +{{{ +modules_enabled = { + ... + "s2s_log_certs"; +} +}}} + +If you want to keep track of how many times, and when a certificate is seen add + +{{{s2s_log_certs_persist = true}}} + += Compatibility = + +||trunk||Works|| +||0.9||Works|| +||0.8||Doesn't work|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_s2s_never_encrypt_blacklist/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_s2s_never_encrypt_blacklist/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,26 @@ +#summary Stops prosody from including starttls into available features for specified remote servers. +#labels Stage-Beta + += Details = + +Let's you stop Prosody from sending feature to choppy/buggy servers which therefore would fail to re-negotiate and use a secure stream. (e.g. [http://issues.igniterealtime.org/browse/OF-405 OpenFire 3.7.0]) + += Usage = + +Copy the plugin into your prosody's modules directory. + +And add it between your enabled modules into the global section (modules_enabled). + +Then list each host as follow: +{{{ +tls_s2s_blacklist = { "host1.tld", "host2.tld", "host3.tld" } +}}} + +In the unfortunate case of OpenFire... you can add the Server's ip address directly as it may not send proper rfc6121 requests. +{{{ +tls_s2s_blacklist_ip = { "a.a.a.a", "b.b.b.b", "c.c.c.c" } +}}} + += Compatibility = + +It's supposed to work with 0.7-0.8.x \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_s2s_reload_newcomponent/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_s2s_reload_newcomponent/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,20 @@ +#summary Module to automatically load new components when config:reload is done in console + += Introduction = + +Currently, module:reload command in console doesn't load new components. This module will automatically load the new components (if any) when the config:reload command is run in the console. + + += Details = + +In order to use the plugin, simply load the plugin by adding "s2s_reload_newcomponent" to the modules enabled list. The plugin requires configuration to be reloaded via console plugin's config:reload() command. + +Now, add a new component in the prosody configuration and then run config:reload() command in the console plugin. The new component should become active in prosody at this point and can be used. + += Dependency = + +Needs console plugin to reload configuration. + += Compatibility = + +|| 0.7 || works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_saslname/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_saslname/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,15 @@ +#summary XEP-0233: Domain-Based Service Names in XMPP SASL Negotiation +#labels Stage-Alpha,Type-Auth + += Introduction = + +This module implements [http://xmpp.org/extensions/xep-0233.html XEP-0233: Domain-Based Service Names in XMPP SASL Negotiation]. + += Configuration = +{{{ +sasl_hostname = "auth42.us.example.com" +}}} + += Compatibility = + +Prosody 0.7+ diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_seclabels/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_seclabels/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,62 @@ +#summary Security Labels +#labels Stage-Alpha + += Introduction = + +This module implements [http://xmpp.org/extensions/xep-0258.htmla XEP-0258: Security Labels in XMPP]. + += Configuration = + +As with all modules, you enable it by adding it to the modules_enabled list. + +{{{ + modules_enabled = { + ... + "seclabels"; + ... + } +}}} + +These options exist: + +|| *Name* || *Description* || *Default* || +|| security_catalog_name || Catalouge name || "Default" || +|| security_catalog_desc || Catalouge description || "My labels" || + +You can then add your labels in a table called security_labels. They can be both orderd and unorderd, but ordered comes first. + +{{{ + security_labels = { + { -- This label will come first + name = "Public", + label = true, -- This is a label, but without the actual label. + default = true -- This is the default label. + }, + { + name = "Private", + label = "PRIVATE", + color = "white", + bgcolor = "blue" + }, + Sensitive = { -- A Sub-selector + SECRET = { -- The index is used as name + label = true + }, + TOPSECRET = { -- The order of this and the above is not guaranteed. + color = "red", + bgcolor = "black", + } + } + } +}}} + + +Each label can have the following properties: + +|| *Name* || *Description* || *Default* || +|| name || The name of the label. Used for selector. || Required. || +|| label || The actual label, ie {{{}}} || Required, can be boolean for a empty label, or a string. || +|| display || The text shown as display marking. || Defaults to the name || +|| color, bgcolor || The fore- and background color of the display marking || None || +|| default || Boolean, true for the default. Only one may be default. || false || + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_secure_interfaces/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_secure_interfaces/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,32 @@ +#summary Mark some network interfaces (e.g. loopback/LAN) as always secure +#labels Stage-Beta + += Introduction = + +Sometimes you might run clients without encryption on the same machine or LAN as Prosody - and you want Prosody to treat them as secure (e.g. allowing plaintext authentication) even though they are not encrypted. + +This module allows you to tell Prosody which of the current server's interfaces (IP addresses) that you consider to be on secure networks. + + += Configuration = + +Configuration is simple, just load the module like any other by adding it to your modules_enabled list: + +{{{ + modules_enabled = { + ... + "secure_interfaces"; + ... + } +}}} + +Then set the list of secure interfaces (just make sure it is set in the global section of your config file, and *not* under a VirtualHost or Component): + +{{{ + secure_interfaces = { "127.0.0.1", "::1", "192.168.1.54" } +}}} + += Compatibility = +|| 0.9 || Works || +|| 0.8 || Unknown || +|| trunk || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_server_contact_info/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_server_contact_info/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,25 @@ +#summary Contact Addresses for XMPP Services +#labels Stage-Alpha + += Introduction = + +This module implements [http://xmpp.org/extensions/xep-0157.html XEP-0157: Contact Addresses for XMPP Services]. + += Configuration = + +{{{ +contact_info = { + abuse = { "mailto:abuse@shakespeare.lit", "xmpp:abuse@shakespeare.lit" }; + admin = { "mailto:admin@shakespeare.lit", "xmpp:admin@shakespeare.lit" }; + feedback = { "http://shakespeare.lit/feedback.php", "mailto:feedback@shakespeare.lit", "xmpp:feedback@shakespeare.lit" }; + sales = "xmpp:bard@shakespeare.lit"; + security = "xmpp:security@shakespeare.lit"; + support = { "http://shakespeare.lit/support.php", "xmpp:support@shakespeare.lit" }; +}; +}}} + +The default is based on the `admins` config variable. + += Compatibility = + +||trunk||Works|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_server_status/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_server_status/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,26 @@ +#summary Server status plugin +#labels Stage-Stable + += Introduction = + +This module fetches the current status of configured hosts and/or stanza statistics from [http://code.google.com/p/prosody-modules/wiki/mod_stanza_counter# mod_stanza_counter]. +And outputs it in either XML or JSON format. + += Usage = + +Copy the file into prosody's module directory and place it into your global's enabled modules. + +Configuration example: +{{{ +server_status_basepath = "/server-info/" +server_status_show_hosts = { "iwanttoshowifthishostisonline.com", "iwanttoshowifthishostisonline2.com" } +server_status_show_comps = { "muc.iwanttoshowifthishostisonline.com", "transport.iwanttoshowifthishostisonline.com" } +server_status_json = true +}}} + +By default the plugin's output is in XML, setting server_status_json to "true" will turn it into JSON instead. +if mod_stanza_counter isn't loaded the plugin will require at least either server_status_show_hosts or server_status_show_comps to be set. + += Info = + + * This is only compatible with 0.9 for older versions please look at the 0.8-diverge branch. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_sift/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_sift/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,20 @@ +#summary XEP-0273: Stanza Interception and Filtering Technology +#labels Stage-Alpha + += Introduction = + +SIFT is a technology to allow clients to filter incoming traffic on the server. This helps save bandwidth, etc. + += Compatibility = + +||0.7||Works|| + += Quirks = + +This implementation is a work in progress. + + * Stanzas to full JIDs get sifted correctly + * Stanzas to bare JIDs are currently allowed/disallowed for all resources as a whole, and not for individual resources + * Presence is only sent to available resources, and probes are not sent for unavailable reasources + * This module currently does not interact with offline messages (filtered messages are dropped with an error reply) + * Not tested with privacy lists diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_smacks/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_smacks/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,31 @@ +#summary XEP-0198: Reliability and fast reconnects for XMPP +#labels Stage-Beta + += Introduction = + +By default XMPP is as reliable as your network is. Unfortunately in some cases that is not very reliable - in some network conditions disconnects can be frequent and message loss can occur. + +To overcome this, XMPP has an optional extension (XEP-0198: Stream Management) which, when supported by both the client and server, can allow a client to resume a disconnected session, and prevent message loss. + += Details = + +When using XEP-0198 both the client and the server keep a queue of the most recently sent stanzas - this is cleared when the other end acknowledges they have received the stanzas. If the client disconnects, instead of marking the user offline the server pretends the client is still online for a short (configurable) period of time. If the client reconnects within this period, any stanzas in the queue that the client did not receive are re-sent. + +If the client fails to reconnect before the timeout then it is marked offline as normal, and any stanzas in the queue are returned to the sender as a "recipient-unavailable" error. + += Configuration = + +|| *Option* || *Default* || *Description* || +|| smacks_hibernation_time || 300 (5 minutes) || The number of seconds a disconnected session should stay alive for (to allow reconnect) || + += Compatibility = +||0.9||Works|| +||0.8||Works, use version [http://prosody-modules.googlecode.com/hg-history/7693724881b3f3cdafa35763f00dd040d02313bf/mod_smacks/mod_smacks.lua 7693724881b3]|| + += Clients = +Clients that support XEP-0198: + * Gajim + * Swift (but not resumption, as of version 2.0 and alphas of 3.0) + * Psi (in an unreleased branch) + * Yaxim + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_sms_clickatell/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_sms_clickatell/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,37 @@ +#summary XMPP to SMS gateway using the Clickatell API +#labels Stage-Alpha + += Introduction = + +This module provides and SMS gateway component which uses the Clickatell HTTP API to deliver text messages. See clickatell.com for details on their services. Note that at present, this is entirely one way: replies will either go nowhere or as sms to the source number you specify. + += Configuration = + +In prosody.cfg.lua: + +{{{ +Component "sms.example.com" "sms_clickatell" + sms_message_prefix = "some text" +}}} + +The sms_message_prefix is a piece of text you want prefixing to all messages sent through the gateway. For example, I use the prefix "{{{[Via XMPP]}}} " to indicate to recipients that I've sent the message via the internet rather than the mobile network. Since my primary use case for this component is to be able to send messages to people only reachable via mobile when I myself only have internet access and no mobile reception, this option allows me to give a hint to my recipients that any reply they send may not reach me in a timely manner. + += Usage = + +Once you've installed and configured, you should be able to use service discovery in your XMPP client to find the component service. Once found, you need to register with the service, supplying your Clickatell username, password, API ID, and a source number for your text messages. + +The source number is the mobile number you want messages to 'originate' from i.e. where your recipients see messages coming from. The number should be in international format without leading plus sign, or you can use some other format if clickatell supports it. + +To send text messages to a target number, you need to add a contact in the form of {{{[number]@sms.example.com}}}, where {{{[number]}}} is the mobile number of the recipient, in international format without leading plus sign, and sms.example.com is the name for the component you configured above. For example: + +447999000001@sms.yourdomain.com + +You should then be able to send messages to this contact which get sent as text messages to the number by the component. + += Compatibility = + +||0.7||Works|| + += Todo = + + * Refactor to create a framework for multiple sms gateway back ends, and split Clickatell specific code in to its own back end \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_srvinjection/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_srvinjection/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,45 @@ +#summary Manually specify SRV records +#labels Stage-Beta + += Introduction = +This Prosody plugin lets you manually override SRV records used for a remote host. + += Usage = +Simply add `"srvinjection"` to your `modules_enabled` list to enable. Then add the `srvinjection` option to the global section. + += Configuration = +The `srvinjection` option can be used as follows: + +{{{ +srvinjection = { + ["example.com"] = {"localhost", 5000}; + ["jabber.org"] = {"localhost", 5001}; +}; +}}} + +The format for individual items is `["remote-hostname"] = {"srv-hostname", srv-port};`. + +The special remote hostname `"*"` can be used as a wildcard: +{{{ + srvinjection = { ["*"] = {"xmpp-server.l.google.com", 5269} } -- Use Google's XMPP server for all hostnames +}}} + += Reloading = +The module can be reloaded via the telnet console. Edit the config file to make any updates. + +You can reload the configuration from disk: +{{{ +config:reload() +}}} +And then reload the module to apply the configuration changes: +{{{ +module:reload("srvinjection", "*") +}}} + += Compatibility = +||0.8||Works|| +||0.7||Works|| +||0.6||Works|| + += How it works = +The module replaces the `lookup` function of the `net.adns` module with its own. The original is set back when the module is unloaded. \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_stanza_counter/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_stanza_counter/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,25 @@ +#summary Simple incoming and outgoing stanza counter +#labels Stage-Stable + += Introduction = + +This module counts incoming and outgoing stanzas from when the instance started, +and makes the data available to other modules by creating a global prosody. object + += Details = + +The counter module is "stanza_counter", the example output module is stanza_counter_http. + += Usage = + +Copy both files into prosody's module directory and place 'em into your enabled modules (stanza_counter_http requires to be loaded into the global section!) + +Config for stanza_counter_http: + +stanza_counter_basepath = "/counter-path-custom/" + + += Info = + + * As of now to count components stanzas, it needs to be manually loaded (inserted into modules_enabled of the components' sections) on these. + * This version isn't compatible with previous versions of prosody (looks at 0.8-diverge branch for olders). diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_storage_gdbm/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_storage_gdbm/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,19 @@ +#summary Lua-GDBM storage +#labels Stage-Beta,Type-Storage,ArchiveStorage + += Introduction = + +This is a storage module using GNU DBM as backend. +It supports archives. + += Dependencies = + +[http://webserver2.tecgraf.puc-rio.br/~lhf/ftp/lua/#lgdbm lgdbm] is required to access gdbm databases. + += Details = + +Refer to [https://prosody.im/doc/storage Prosodys data storage documentation]. + += Compatibility = + +|| >=0.9 || Should work || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_storage_ldap/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_storage_ldap/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,22 @@ +#summary LDAP storage for rosters, groups, and vcards +#labels Type-Storage + += Introduction = + +See [mod_lib_ldap] for more information. + += Installation = + +You must install [mod_lib_ldap] to use this module. After that, you need only copy mod_storage_ldap.lua and ldap/vcard.lib.lua to your Prosody installation's plugins directory. Make sure vcard.lib.lua is installed under plugins/ldap/. + += Configuration = + +In addition to the configuration that [mod_lib_ldap] itself requires, this plugin also requires the following fields in the ldap section: + + * user.namefield + * groups.memberfield + * groups.namefield + * groups.basedn + * vcard_format (optional) + +See the README.md distributed with [mod_lib_ldap] for details. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_storage_lmdb/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_storage_lmdb/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,18 @@ +#summary Lightning Memory-Mapped Database storage +#labels Stage-Beta,Type-Storage + += Introduction = + +This is a storage module using OpenLDAP Lightning Memory-Mapped Database as backend. + += Dependencies = + +[https://github.com/shmul/lightningdbm lightningdbm] is required to access LMDB databases. + += Details = + +Refer to [https://prosody.im/doc/storage Prosodys data storage documentation]. + += Compatibility = + +|| >=0.9 || Should work || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_storage_memory/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_storage_memory/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,13 @@ +#summary Simple memory-only storage module +#labels Stage-Beta,Type-Storage,ArchiveStorage + += Introduction = + +This module acts as a normal storage module for Prosody, but saves all data in memory only. All data is lost when the server stops. This makes it useful for testing, or certain specialized applications. + += Details = + +Because the accounts store will always begin empty, it is mostly useful combined with an authentication plugin which doesn't use Prosody's storage API, or with [mod_auth_any], or you can create user accounts manually each time the server starts. + += Compatibility = +|| 0.9 || Works || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_storage_mongodb/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_storage_mongodb/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,30 @@ +#summary MongoDB Storage Module +#labels Type-Storage,Stage-Alpha + += Introduction = + +This is a storage backend that uses MongoDB. +Depends on [https://github.com/mwild1/luamongo luamongo bindings] + +This module is not under active development and has a number of issues related to limitations in MongoDB. It is not suitable for production use. + += Configuration = + +Copy the module to the prosody modules/plugins directory. + +In Prosody's configuration file, set: +{{{ + storage = "mongodb" +}}} + +MongoDB options are: +|| *Name* || *Description* || +|| server || hostname:port || +|| dbname || the database to use || +|| username || your username for the given database || +|| password || your password for the given database (either raw or pre-digested) || +|| is_digest || whether the password field has been pre-digested || + += Compatibility = + +|| trunk || Untested, but should work || \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_storage_muc_log/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_storage_muc_log/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,28 @@ +#summary Storage module using mod_muc_log data with new stanza archive API +#labels Stage-Alpha,ArchiveStorage + += Introduction = + +[mod_muc_log] provided logging of chatrooms running on the server to Prosody's data store. This module gives access to this data using the 0.10+ stanza archive API, allowing legacy log data to be used with [mod_mam_muc] and [mod_http_muc_log]. + += Details = + +Replace mod_muc_log (and mod_muc_log_http) in your config with + +{{{ +Component "conference.example.org" "muc" + modules_enabled = { + -- "muc_log"; -- functionality replaced by mod_mam_muc + mod_storage_muc_log + "mam_muc"; -- Does logging to storage backend configured below + + -- "muc_log_http"; -- Replaced by the mod_http_muc_log + "http_muc_log"; + } + storage = { + muc_log = "muc_log"; + } +}}} + += Compatibility = + +Requires Prosody 0.10 or above. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_storage_xmlarchive/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_storage_xmlarchive/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,17 @@ +#summary XML archive storage +#labels Stage-Beta,Type-Storage,ArchiveStorage + += Introduction = + +This module implements stanza archives using files, similar to the default "internal" storage. + += Details = + +Refer to [https://prosody.im/doc/storage Prosodys data storage documentation]. + +Note that this module does not implement the "keyval" storage method and +can't be used by anything other than archives, eg MAM and MUC logs. + += Compatibility = + +|| >=0.10 || Should work || diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_strict_https/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_strict_https/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,24 @@ +#summary HTTP Strict Transport Security + += Introduction = + +This module implements [https://tools.ietf.org/html/rfc6797 HTTP Strict Transport Security] +and responds to all non-HTTPS requests with a `301 Moved Permanently` redirect to the HTTPS +equivalent of the path. + += Configuration = + +Add the module to the `modules_enabled` list and optionally configure the specific header sent. + +{{{ + modules_enabled = { + ... + "strict_https"; + } + hsts_header = "max-age=31556952" +}}} + += Compatibility = +||trunk||Works|| +||0.9||Works|| +||0.8||Doesn't work|| diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_support_contact/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_support_contact/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,24 @@ +#summary Add a support contact to new registrations +#labels Stage-Stable + += Introduction = + +This Prosody plugin adds a default contact to newly registered accounts. + += Usage = + +Simply add "support_contact" to your modules_enabled list. When a new account is created, the new roster would be initialized to include a support contact. + += Configuration = + +|| support_contact || The bare JID of the support contact. The default is support@hostname, where hostname is the host the new user's account is on. || +|| support_contact_nick || Nickname of the support contact. The default is "Support". || +|| support_contact_group || The roster group in the support contact's roster in which to add the new user. || + += Compatibility = +||0.7||Works|| +||0.6||Works|| + += Caveats/Todos/Bugs = + + * This only works for accounts created via in-band registration. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_swedishchef/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_swedishchef/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,28 @@ +#summary Silly little module to convert your conversations to "swedish" +#labels Stage-Beta + += Introduction = + +This module does some conversions on message bodys passed through it causing +them to look like our beloved swedish chef had typed them. + + += Details = + +To load this on a MUC component do + +{{{ +Component "funconference.example.com" "muc" + modules_enabled = { "swedishchef" } + swedishchef_trigger = "!chef"; -- optional, converts only when the message starts with "!chef" +}}} + +In theory this also works for whole servers, but that is untested and not recommended ;) + += Compatibility = +||0.6||Works|| +||0.5||Works|| + += Todo = + + * Possibly add xhtml-im (XEP-0071) support \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_tcpproxy/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_tcpproxy/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,47 @@ +#summary TCP-over-XMPP :) +#labels Stage-Beta + += Introduction = + +It happens occasionally that I would like to use the XMPP server as a generic proxy for connecting to another service. It is especially awkward in some environments, and impossible in (for example) Javascript inside a web browser. + + += Details = + +Using mod_tcpproxy an XMPP client (including those using BOSH) can initiate a pipe to a given TCP/IP address and port. This implementation uses the [http://xmpp.org/extensions/xep-0047.html In-Band Bytestreams] XEP, simply extended with 2 new attributes in a new namespace, host and port. + +An example Javascript client can be found in the web/ directory of mod_tcpproxy in the repository. + += Configuration = +Just add tcpproxy as a component, for example: + +{{{Component "tcp.example.com" "tcpproxy"}}} + += Protocol = + +A new stream is opened like this: + +{{{ + + + +}}} + +The stanza attribute (currently) MUST be 'message', and a block-size, if given, is (currently) ignored. + +In response to this stanza you will receive a result upon connection success, or an error if the connection failed. You can then send to the connection by sending message stanzas as described in the IBB XEP. Incoming data will likewise be delivered as messages. + += Compatibility = +||0.7||Works|| +||0.6||Doesn't work|| + += Todo = + * ACLs (restrict to certain JIDs, and/or certain target hosts/ports) + * Honour block-size (undecided) + * Support iq stanzas for data transmission + * Signal to start SSL/TLS on a connection \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_telnet_tlsinfo/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_telnet_tlsinfo/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,53 @@ +#summary Telnet command for showing TLS info + += Introduction = + +This module adds two commands to the telnet console, `c2s:showtls()` and +`s2s:showtls()`. These commands shows TLS parameters, such as ciphers and key +agreement protocols, of all c2s or s2s connections. + += Configuration = + +Just add the module to the `modules_enabled` list. There is no other configuration. + +{{{ + modules_enabled = { + ... + "telnet_tlsinfo"; + } +}}} + += Usage = + +Simply type `c2s:showtls()` to show client connections or `s2s:showtls()` +for server-to-server connections. These commands can also take a JID for +limiting output to matching users or servers. + +{{{ +s2s:showtls("prosody.im") +| example.com -> prosody.im +| protocol: TLSv1.1 +| cipher: DHE-RSA-AES256-SHA +| encryption: AES(256) +| algbits: 256 +| bits: 256 +| authentication: RSA +| key: DH +| mac: SHA1 +| export: false +}}} + +|| *Field* || *Description* || +|| protocol || The protocol used. *Note*: With older LuaSec, this is the protocol that added the used cipher || +|| cipher || The OpenSSL cipher string for the currently used cipher || +|| encryption || Encryption algorithm used || +|| bits, algbits || Secret bits involved in the cipher || +|| authentication || The authentication algoritm used || +|| mac || Message authentication algorithm used || +|| key || Key exchange mechanism used. || +|| export || Whethere an export cipher is used || + += Compatibility = + +||0.9 with LuaSec 0.5||Works|| + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_throttle_presence/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_throttle_presence/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,17 @@ +#summary Limit presence stanzas to save traffic +#labels Stage-Beta + += Introduction = + +For most people 'presence' (status changes) of contacts make up most of the traffic received by their client. However much of the time it is not essential to have highly accurate presence information. + +This module automatically cuts down on presence traffic when clients indicate they are inactive (using the [mod_csi CSI protocol]. + +This is extremely valuable for mobile clients that wish to save battery power while in the background. + += Configuration = + +Just load the module (e.g. in modules_enabled). There are no configuration options. + += Compatibility = +||0.9||Works|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_twitter/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_twitter/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,32 @@ +#summary Simple example of working component and HTTP polling. +#labels Stage-Alpha + += Introduction = + +Twitter has simple API to use, so I tried to deal with it via Prosody. +I didn't manage to finish this module, but it is nice example of component that accepts registrations, unregistrations, does HTTP polling and so on. +Maybe someone will finnish this idea. + += Details = + +It does require some non-prosody Lua libraries: LuaJSON + + += Configuration = + +At the moment no configuration needed, but you can configure some variables inside code. + += TODO = + + * Send latest tweets to XMPP user + * Reply user's messages to Twitter + * OAuth support + * User configuration (forms) + * discuss about using cjson + * [!!!!] rewrite to be compatible with 0.9+ + * drop? (since it is mod_twitter in spectrum) + += Compatibility = +||trunk||Currently Not Works|| +||0.9||Currently Not Works|| +||0.8||Works|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_uptime_presence/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_uptime_presence/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,9 @@ +#summary Report server uptime in presence + += Introduction = + +This module simply responds to a presence probe sent to the server with a +presence staza containing a timestamp from when the server started. + +This is imagined as an alternative to the XEP-0012 "Last Activity" +protocol that can seem a bit overloaded. diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_vjud/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_vjud/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,47 @@ +#summary XEP-0055: Jabber Search +#labels Stage-Alpha + += Introduction = + +Basic implementation of [http://xmpp.org/extensions/xep-0055.html XEP-0055: Jabber Search]. + += Details = + +This module has two modes. One mode requires users to opt-in to be +searchable, then allows users to search the list of those users. The +second mode allows search accross all users. + += Usage = + +First copy the module to the prosody plugins directory. + +Then add "vjud" to your modules_enabled list: +{{{ + modules_enabled = { + -- ... + "vjud", + -- ... + } +}}} + + +Alternatively, you can load it as a component: + +{{{ + Component "search.example.com" "vjud" +}}} + +(Some old clients require this) + += Configuration = + +|| Option || Default || Description || +|| vjud_mode || "opt-in" || Defines how the module behaves || + += Compatibility = +|| 0.8 || Works, but only the opt-in mode || +|| 0.9 || Works || +|| trunk || Works || + +Note that the version for 0.8 and 0.9 are slightly different. + diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_watchuntrusted/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_watchuntrusted/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,30 @@ +#summary Warn admins about outgoing s2s connections that are refused due to invalid or untrusted certificates +#labels Stage-Alpha + += Introduction = + +Similar to mod_watchregistrations, this module warns admins when an s2s connection fails due for encryption or trust reasons. + +The certificate shows the SHA1 hash, so it can easily be used together with mod_s2s_auth_fingerprint. + += Configuration = + +{{{ +modules_enabled = { + -- other modules -- + "watchuntrusted", + +} + +untrusted_fail_watchers = { "admin@example.lit" } +untrusted_fail_notification = "Establishing a secure connection from $from_host to $to_host failed. Certificate hash: $sha1. $errors" +}}} + +|| *Option* || *Default* || *Description* || +|| untrusted_fail_watchers || All admins || The users to send the message to || +|| untrusted_fail_notification || "Establishing a secure connection from $from_host to $to_host failed. Certificate hash: $sha1. $errors" || The message to send, $from_host, $to_host, $sha1 and $errors are replaced || + + += Compatibility = + +||trunk||Works|| \ No newline at end of file diff -r 12ac88940fe3 -r 29f3d6b7ad16 mod_webpresence/README.wiki --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_webpresence/README.wiki Mon Aug 24 16:43:56 2015 +0200 @@ -0,0 +1,43 @@ +#summary Display your online status in web pages +#labels Stage-Stable + += Introduction = + +Quite often you may want to publish your Jabber status to your blog or website. mod_webpresence allows you to do exactly this. + += Details = + +This module uses Prosody's built-in HTTP server (it does not depend on mod_httpserver). It supplies a status icon representative of a user's online state. + += Installation = + +Simply copy mod_webpresence.lua to your modules directory, the image files are embedded within it. Then add "webpresence" to your modules_enabled list. + += Usage = + +Once loaded you can embed the icon into a page using a simple `` tag, as follows: + +{{{}}} + +Alternatively, it can be used to get status name as plaint text, status message as plain text or html-code for embedding on web-pages. + +To get status name in plain text you can use something like that link: {{{http://prosody.example.com:5280/status/john.smith/text}}} + +To get status message as plain text you can use something like following link: {{{http://prosody.example.com:5280/status/john.smith/message}}} + +To get html code, containig status name, status image and status message (if set): +{{{http://prosody.example.com:5280/status/john.smith/html}}} + +All other += Compatibility = +||0.9||Works|| +||0.8||Works|| +||0.7||Works|| +||0.6||Works|| + += Todo = + + * JSON? + * Display PEP information (maybe a new plugin?) + * More (free) iconsets + * Internal/external image generator (GD, ImageMagick) \ No newline at end of file