From 04f4489427b1beb398d5bd8152a816ca3de4274b Mon Sep 17 00:00:00 2001 From: Badlop Date: Thu, 11 Aug 2022 13:25:02 +0200 Subject: [PATCH] Convert modules README.txt to markdown syntax --- ejabberd_observer_cli/README.md | 3 +- mod_cron/README.md | 2 +- mod_default_contacts/README.md | 42 +++++ mod_default_contacts/README.txt | 40 ----- mod_default_rooms/README.md | 40 +++++ mod_default_rooms/README.txt | 38 ----- mod_deny_omemo/README.md | 45 ++++++ mod_deny_omemo/README.txt | 43 ----- mod_filter/{README.txt => README.md} | 50 +++--- mod_grafite/README.md | 32 ++-- mod_log_chat/README.md | 11 ++ mod_log_chat/README.txt | 11 -- mod_logsession/{README.txt => README.md} | 62 ++++---- mod_logxml/README.md | 87 +++++++++++ mod_logxml/README.txt | 86 ---------- mod_message_log/README.md | 41 +++++ mod_message_log/README.txt | 34 ---- mod_muc_log_http/README.md | 39 +++++ mod_muc_log_http/README.txt | 42 ----- mod_post_log/{README.txt => README.md} | 16 +- mod_pottymouth/{README.txt => README.md} | 51 ++++-- mod_rest/{README.txt => README.md} | 115 ++++++++------ mod_s2s_log/README.md | 13 ++ mod_s2s_log/README.txt | 12 -- mod_shcommands/README.md | 69 ++++++++ mod_shcommands/README.txt | 68 -------- mod_spam_filter/{README.txt => README.md} | 54 ++++--- mod_statsdx/README.md | 92 +++++++++++ mod_statsdx/README.txt | 87 ----------- mod_webpresence/{README.txt => README.md} | 182 ++++++++++++---------- 30 files changed, 804 insertions(+), 703 deletions(-) create mode 100644 mod_default_contacts/README.md delete mode 100644 mod_default_contacts/README.txt create mode 100644 mod_default_rooms/README.md delete mode 100644 mod_default_rooms/README.txt create mode 100644 mod_deny_omemo/README.md delete mode 100644 mod_deny_omemo/README.txt rename mod_filter/{README.txt => README.md} (87%) create mode 100644 mod_log_chat/README.md delete mode 100644 mod_log_chat/README.txt rename mod_logsession/{README.txt => README.md} (56%) create mode 100644 mod_logxml/README.md delete mode 100644 mod_logxml/README.txt create mode 100644 mod_message_log/README.md delete mode 100644 mod_message_log/README.txt create mode 100644 mod_muc_log_http/README.md delete mode 100644 mod_muc_log_http/README.txt rename mod_post_log/{README.txt => README.md} (60%) rename mod_pottymouth/{README.txt => README.md} (60%) rename mod_rest/{README.txt => README.md} (79%) create mode 100644 mod_s2s_log/README.md delete mode 100644 mod_s2s_log/README.txt create mode 100644 mod_shcommands/README.md delete mode 100644 mod_shcommands/README.txt rename mod_spam_filter/{README.txt => README.md} (71%) create mode 100644 mod_statsdx/README.md delete mode 100644 mod_statsdx/README.txt rename mod_webpresence/{README.txt => README.md} (65%) diff --git a/ejabberd_observer_cli/README.md b/ejabberd_observer_cli/README.md index 8d72329..8353ed4 100644 --- a/ejabberd_observer_cli/README.md +++ b/ejabberd_observer_cli/README.md @@ -1,4 +1,5 @@ -# ejabberd observer_cli plugins +ejabberd observer_cli plugins +============================= [observer_cli][oc] is an erlang tool to visualize Erlang node statistics on the command line. diff --git a/mod_cron/README.md b/mod_cron/README.md index 7d78745..5993e05 100644 --- a/mod_cron/README.md +++ b/mod_cron/README.md @@ -8,7 +8,7 @@ mod_cron - Execute scheduled tasks This module allows advanced ejabberd administrators to schedule tasks for periodic and automatic execution. This module is a similar concept than the -*nix's cron program. +Unix's cron program. Each time a scheduled task finishes its execution, a message is printed in the ejabberd log file. diff --git a/mod_default_contacts/README.md b/mod_default_contacts/README.md new file mode 100644 index 0000000..0746154 --- /dev/null +++ b/mod_default_contacts/README.md @@ -0,0 +1,42 @@ +mod_default_contacts - Add roster contact(s) on registration +============================================================ + +* Author: Holger Weiss + + +Description +----------- + +This module allows for specifying one or more contacts that should be +added to the user's roster automatically on successful registration (via +`mod_register`, or, for example, `ejabberdctl register`). Note that no +presence subscription is performed, and the rosters of the contacts aren't +modified. + + +Configuration +------------- + +In order to use this module, add a configuration snippet such as the +following: + +```yaml +modules: + # [...] + mod_default_contacts: + contacts: + - + name: "Bob Virding" + jid: "bob@example.com" + - + name: "Alice Armstrong" + jid: "alice@example.com" +``` + +The configurable `mod_default_contacts` options are: + +- `contacts` (default: `[]`) + + The list of contact JIDs that should be auto-added to the user's roster + on account registration. Each list item must specify the `jid:` and + optionally the `name:` of the contact. diff --git a/mod_default_contacts/README.txt b/mod_default_contacts/README.txt deleted file mode 100644 index c92949c..0000000 --- a/mod_default_contacts/README.txt +++ /dev/null @@ -1,40 +0,0 @@ - - mod_default_contacts - Add roster contact(s) on registration - - Author: Holger Weiss - - - DESCRIPTION - ----------- - -This module allows for specifying one or more contacts that should be -added to the user's roster automatically on successful registration (via -"mod_register", or, for example, "ejabberdctl register"). Note that no -presence subscription is performed, and the rosters of the contacts aren't -modified. - - - CONFIGURATION - ------------- - -In order to use this module, add a configuration snippet such as the -following: - - modules: - # [...] - mod_default_contacts: - contacts: - - - name: "Bob Virding" - jid: "bob@example.com" - - - name: "Alice Armstrong" - jid: "alice@example.com" - -The configurable mod_default_contacts options are: - -- contacts (default: []) - - The list of contact JIDs that should be auto-added to the user's roster - on account registration. Each list item must specify the 'jid:' and - optionally the 'name:' of the contact. diff --git a/mod_default_rooms/README.md b/mod_default_rooms/README.md new file mode 100644 index 0000000..e42fd36 --- /dev/null +++ b/mod_default_rooms/README.md @@ -0,0 +1,40 @@ +mod_default_rooms - Add MUC bookmark(s) on registration +======================================================= + +* Author: Holger Weiss + + +Description +----------- + +This module allows for specifying one or more rooms that should be +bookmarked automatically on successful user registration (via +`mod_register`, or, for example, `ejabberdctl register`). + + +Configuration +------------- + +In order to use this module, add a configuration snippet such as the +following: + +```yaml +modules: + # [...] + mod_default_rooms: + rooms: + - "foo@conference.example.net" + - "bar@conference.example.org" +``` + +The configurable `mod_default_rooms` options are: + +- `rooms` (default: `[]`) + + The list of rooms users that should be auto-bookmarked on account + registration. + +- `auto_join` (default: `true`) + + This option specifies wether the auto-join flag should be set for the + bookmarks created on registration. diff --git a/mod_default_rooms/README.txt b/mod_default_rooms/README.txt deleted file mode 100644 index 0250e23..0000000 --- a/mod_default_rooms/README.txt +++ /dev/null @@ -1,38 +0,0 @@ - - mod_default_rooms - Add MUC bookmark(s) on registration - - Author: Holger Weiss - - - DESCRIPTION - ----------- - -This module allows for specifying one or more rooms that should be -bookmarked automatically on successful user registration (via -"mod_register", or, for example, "ejabberdctl register"). - - - CONFIGURATION - ------------- - -In order to use this module, add a configuration snippet such as the -following: - - modules: - # [...] - mod_default_rooms: - rooms: - - "foo@conference.example.net" - - "bar@conference.example.org" - -The configurable mod_default_rooms options are: - -- rooms (default: []) - - The list of rooms users that should be auto-bookmarked on account - registration. - -- auto_join (default: true) - - This option specifies wether the auto-join flag should be set for the - bookmarks created on registration. diff --git a/mod_deny_omemo/README.md b/mod_deny_omemo/README.md new file mode 100644 index 0000000..d746062 --- /dev/null +++ b/mod_deny_omemo/README.md @@ -0,0 +1,45 @@ +mod_deny_omemo - Prevent OMEMO sessions from being established +============================================================== + +* Author: Holger Weiss + + +Description +----------- + +Unless the configured access rule (called `omemo` by default) returns +`allow`, this module prevents OMEMO sessions from being established. +Requests to query the devicelist from other users are rejected. Requests +to publish a devicelist are also rejected, and all OMEMO nodes referenced +in that devicelist are removed. Incoming devicelist updates are silently +dropped. OMEMO-encrypted messages are bounced with an error message. + + +Configuration +------------- + +In order to use this module, add configuration snippets such as the +following: + +```yaml +access_rules: + # [...] + omemo: + - deny: + - user: "alice@example.com" + - user: "bob@example.com" + - allow # Permit OMEMO except for the JIDs above. + +modules: + # [...] + mod_deny_omemo: {} +``` + +The configurable `mod_deny_omemo` options are: + +- `access` (default: `omemo`) + + This option defines the access rule to control who will be able to + establish OMEMO sessions. The default value is `omemo`. Establishing + OMEMO sessions is only permitted if an access rule of that name exists + and returns `allow`. diff --git a/mod_deny_omemo/README.txt b/mod_deny_omemo/README.txt deleted file mode 100644 index 037db0b..0000000 --- a/mod_deny_omemo/README.txt +++ /dev/null @@ -1,43 +0,0 @@ - - mod_deny_omemo - Prevent OMEMO sessions from being established - - Author: Holger Weiss - - - DESCRIPTION - ----------- - -Unless the configured access rule (called 'omemo' by default) returns -'allow', this module prevents OMEMO sessions from being established. -Requests to query the devicelist from other users are rejected. Requests -to publish a devicelist are also rejected, and all OMEMO nodes referenced -in that devicelist are removed. Incoming devicelist updates are silently -dropped. OMEMO-encrypted messages are bounced with an error message. - - - CONFIGURATION - ------------- - -In order to use this module, add configuration snippets such as the -following: - - access_rules: - # [...] - omemo: - - deny: - - user: "alice@example.com" - - user: "bob@example.com" - - allow # Permit OMEMO except for the JIDs above. - - modules: - # [...] - mod_deny_omemo: {} - -The configurable mod_deny_omemo options are: - -- access (default: 'omemo') - - This option defines the access rule to control who will be able to - establish OMEMO sessions. The default value is 'omemo'. Establishing - OMEMO sessions is only permitted if an access rule of that name exists - and returns 'allow'. diff --git a/mod_filter/README.txt b/mod_filter/README.md similarity index 87% rename from mod_filter/README.txt rename to mod_filter/README.md index bfbbebb..f97a52c 100644 --- a/mod_filter/README.txt +++ b/mod_filter/README.md @@ -1,26 +1,25 @@ +mod_filter - Flexible Filtering by Server Policy +================================================ - mod_filter - Flexible Filtering by Server Policy - - Author: Magnus Henoch - Copyright (C) 2005 Magnus Henoch - +* Author: Magnus Henoch +* Copyright (C) 2005 Magnus Henoch This module allows the admin to specify packet filtering rules using ACL and ACCESS. - - EJABBERD PATCH - ============== +ejabberd Patch +-------------- Since ejabberd 19.08, it is necessary to apply a small patch to ejabberd -source code in order to use complex access_rules configurations, like the +source code in order to use complex `access_rules` configurations, like the ones shown in examples 1, 2, 3, 4... So, apply this patch your ejabberd source code. As you can see, it only adds a line. Then recompile ejabberd, reinstall and restart it: +```diff diff --git a/src/acl.erl b/src/acl.erl index d13c05601..c2a72fd9f 100644 --- a/src/acl.erl @@ -33,20 +32,24 @@ index d13c05601..c2a72fd9f 100644 deny => access_validator()}, []))). --- +-- +``` - CONFIGURATION - ============= +Configuration +------------- To use this module, follow the general build instructions. You can modify the default module configuration file like this: To enable the module: +```yaml modules: mod_filter: {} +``` And you must also add the default access rules: +```yaml access_rules: mod_filter: - allow: all @@ -56,15 +59,17 @@ access_rules: - allow: all mod_filter_iq: - allow: all +``` The configuration of rules is done using ejabberd's ACL and ACCESS, so you should also study the corresponding section on ejabberd guide. You can find here several examples that may help you to understand how it works. - EXAMPLE 1 - ========= +Example 1 +--------- +```yaml access_rules: mod_filter_presence: - allow: all @@ -85,15 +90,17 @@ access_rules: restrict_foreign: - allow: admin - deny: all +``` - EXAMPLE 2 - ========= +Example 2 +--------- -On this example, the users of a private vhost (example3.org) can only chat with themselves, +On this example, the users of a private vhost (`example3.org`) can only chat with themselves, so that particular vhost will have no connection to the exterior. The other vhosts on the server are completely unrestricted. The administrators are also unrestricted. +```yaml ## This ejabberd server has three virtual hosts hosts: - "localhost" @@ -131,15 +138,16 @@ access_rules: - allow: admin - deny: ex3server - allow: all +``` - EXAMPLE 4 - ========= - +Example 4 +--------- This server has two virtual hosts, one with anonymous users. The anonymous users cannot send or receive presence stanzas from outside their vhost. +```yaml hosts: - "localhost" - "anon.localhost.org" @@ -167,4 +175,4 @@ access_rules: - allow: all mod_filter_iq: - allow: all - +``` diff --git a/mod_grafite/README.md b/mod_grafite/README.md index 6153198..4db5c7d 100644 --- a/mod_grafite/README.md +++ b/mod_grafite/README.md @@ -1,35 +1,31 @@ - mod_grafite - Gathers statistics and publishes via statsd/grafite -author: Thiago Rocha Camargo (rochacamargothiago@gmail.com) +================================================================= - mod_grafite - ============== +* Author: Thiago Rocha Camargo (rochacamargothiago@gmail.com) Gathers statistics and publishes via statsd/grafite - CONFIGURE - --------- -Enable the module in ejabberd.yml for example with a basic configuration: -modules: - mod_grafite: - statsdhost: "carbonr.xmpp.com.br" - statsdport: 8125 +Configuration +------------- Configurable options: - statsdhost: Host of the statsd server - statsdport: Port of the statsd server +- `statsdhost`: Host of the statsd server +- `statsdport`: Port of the statsd server - EXAMPLE CONFIGURATION - --------------------- +Example Configuration +--------------------- + +```yaml modules: mod_grafite: statsdhost: "carbonr.xmpp.com.br" statsdport: 8125 +``` - FEATURE REQUESTS - ---------------- + +Feature Requests +--------------- - Add support for configurable Hooks - diff --git a/mod_log_chat/README.md b/mod_log_chat/README.md new file mode 100644 index 0000000..df5c437 --- /dev/null +++ b/mod_log_chat/README.md @@ -0,0 +1,11 @@ +mod_log_chat +============ + +`mod_log_chat` is an ejabberd module aimed at logging chat messages in +text files. `mod_log_chat` creates one file per couple of chatters and +per day (it doesn't log muc messages, use `mod_muc_log` for this). + +It can store messages in plain text or HTML format. + +Be sure that the directories where you want to create your log +files exists and are writable by you ejabberd user. diff --git a/mod_log_chat/README.txt b/mod_log_chat/README.txt deleted file mode 100644 index 1d09130..0000000 --- a/mod_log_chat/README.txt +++ /dev/null @@ -1,11 +0,0 @@ -mod_log_chat -============ - -mod_log_chat is an ejabberd module aimed at logging chat messages in -text files. mod_log_chat creates one file per couple of chatters and -per day (it doesn't log muc messages, use mod_muc_log for this). - -It can store messages in plain text or HTML format. - -Be sure that the directories where you want to create your log -files exists and are writable by you ejabberd user. diff --git a/mod_logsession/README.txt b/mod_logsession/README.md similarity index 56% rename from mod_logsession/README.txt rename to mod_logsession/README.md index 5d9359d..7db0e4e 100644 --- a/mod_logsession/README.txt +++ b/mod_logsession/README.md @@ -1,13 +1,13 @@ +mod_logsession - Log session connections to file +================================================ - mod_logsession - Log session connections to file - - Requirements: ejabberd 19.08 or higher - Homepage: http://www.ejabberd.im/mod_logsession - Author: Badlop +* Requirements: ejabberd 19.08 or higher +* Homepage: http://www.ejabberd.im/mod_logsession +* Author: Badlop - DESCRIPTION - ----------- +Description +----------- This module is intended to log in a text file the session connections. Right now it only logs the forbidden connection attempts and the @@ -17,54 +17,62 @@ Each vhost is logged in a different file. Note: to log the failed authentication attempts, you need to patch ejabberd. - CONFIGURABLE PARAMETERS - ----------------------- +Configuration +------------- -sessionlog: - Define the name of log files, or set to 'auto'. - The keyword @HOST@ is substituted with the name of the vhost. - If set to 'auto', it will store in the ejabberd log path - with the filename "session_@HOST@.log" - Default value: auto +- `sessionlog` + + Define the name of log files, or set to `auto`. + The keyword `@HOST@` is substituted with the name of the vhost. + If set to `auto`, it will store in the ejabberd log path + with the filename `"session_@HOST@.log"` + Default value: `auto` - EXAMPLE CONFIGURATION - --------------------- +Example Configuration +--------------------- +```yaml modules: ... mod_logsession: sessionlog: "/var/log/ejabberd/session_@HOST@.log" ... +``` With that configuration, if the server has three vhosts: "localhost", "example.org" and "example.net", then the forbidden accesses will be logged in the files: - /var/log/ejabberd/session_localhost.log - /var/log/ejabberd/session_example.org.log - /var/log/ejabberd/session_example.net.log +``` +/var/log/ejabberd/session_localhost.log +/var/log/ejabberd/session_example.org.log +/var/log/ejabberd/session_example.net.log +``` - FORMAT OF LOG - ------------- +Log Format +---------- The content of the file is the date and time of the attempted login and the JID of the denied user. For example: +``` 2008-01-08 12:20:50 Forbidden session for tron@localhost/teeest 2008-01-08 12:36:01 Forbidden session for baduser@localhost/aaa22 2010-04-02 17:21:37 Failed authentication for someuser@localhost from 127.0.0.1 port 58973 2010-04-02 17:25:20 Failed authentication for badlop@localhost from 127.0.0.1 port 45842 +``` - REOPEN LOG FILES - ---------------- +Reopen Log Files +---------------- This module provides an ejabberd command to reopen the log file of a host where the module is enabled. Example usage: - ejabberdctl reopen-seslog localhost - ejabberdctl reopen-seslog jabber.example.org - +``` +ejabberdctl reopen-seslog localhost +ejabberdctl reopen-seslog jabber.example.org +``` diff --git a/mod_logxml/README.md b/mod_logxml/README.md new file mode 100644 index 0000000..6dd273f --- /dev/null +++ b/mod_logxml/README.md @@ -0,0 +1,87 @@ +mod_logxml - Log XMPP packets to XML file +========================================= + +* Homepage: http://www.ejabberd.im/mod_logxml +* Author: Badlop +* Requires: ejabberd 19.08 or higher + + +Description +----------- + +This module sniffs all the XMPP traffic send and received by ejabberd, +both internally and externally transmitted. It logs the XMPP packets +to a XML formatted file. It's posible to filter transmitted packets +by orientation, stanza and direction. It's possible to configure the +file rotation rules and intervals. + +This module reuses code from `mod_log_forensic`, `mod_stats2file`, `mod_muc_log`. + + +Configuration +------------- + +- `stanza`: + Log packets only when stanza matches. + Default value: `[iq, message, presence, other]` +- `direction`: + Log packets only when direction matches. + Default value: `[internal, vhosts, external]` +- `orientation`: + Log packets only when orientation matches. + Default value: `[send, revc]` +- `logdir`: + Base filename, including absolute path. + If set to `auto`, it uses the ejabberd log path. + Default value: `auto` +- `show_ip`: + If the IP address of the local user should be logged to file. + Default value: `false` +- `rotate_days`: + Rotate logs every X days. + Put 0 to disable this limit. + Default value: `1` +- `rotate_megs`: + Rotate when the logfile size is higher than this, in megabytes. + Put 0 to disable this limit. + Default value: `10` +- `rotate_kpackets`: + Rotate every *1000 XMPP packets logged. + Put `0` to disable this limit. + Default value: `10` +- `check_rotate_kpackets`: + Check rotation every `*1000` packets. + Default value: `1` + + +Example Configuration +--------------------- + +In `ejabberd.yml`, in the modules section, add the module. For example: + +```yaml +modules: + mod_logxml: + stanza: + - iq + - other + direction: + - external + orientation: + - send + - recv + logdir: "/tmp/logs/" + show_ip: false + rotate_days: 1 + rotate_megs: 100 + rotate_kpackets: 0 + check_rotate_kpackets: 1 +``` + +XML Format +---------- + +XMPP packets are enclosed in ``, with attributes: +- `or`: orientation of the packet, either `send` or `recv` +- `ljid`: local JID of the sender or receiver, depending on the orientation +- `ts`: timestamp when the packet was logged diff --git a/mod_logxml/README.txt b/mod_logxml/README.txt deleted file mode 100644 index d7f8c15..0000000 --- a/mod_logxml/README.txt +++ /dev/null @@ -1,86 +0,0 @@ - - mod_logxml - Log XMPP packets to XML file - - Homepage: http://www.ejabberd.im/mod_logxml - Author: Badlop - Requires: ejabberd 19.08 or higher - - - DESCRIPTION - ----------- - -This module sniffs all the XMPP traffic send and received by ejabberd, -both internally and externally transmitted. It logs the XMPP packets -to a XML formatted file. It's posible to filter transmitted packets -by orientation, stanza and direction. It's possible to configure the -file rotation rules and intervals. - -This module reuses code from mod_log_forensic, mod_stats2file, mod_muc_log - - - CONFIGURATION - ------------- - -stanza: - Log packets only when stanza matches - Default value: [iq, message, presence, other] -direction: - Log packets only when direction matches - Default value: [internal, vhosts, external] -orientation: - Log packets only when orientation matches - Default value: [send, revc] -logdir: - Base filename, including absolute path - If set to 'auto', it uses the ejabberd log path. - Default value: auto -show_ip: - If the IP address of the local user should be logged to file. - Default value: false -rotate_days: - Rotate logs every X days - Put 0 to disable this limit. - Default value: 1 -rotate_megs: - Rotate when the logfile size is higher than this, in megabytes. - Put 0 to disable this limit. - Default value: 10 -rotate_kpackets: - Rotate every *1000 XMPP packets logged - Put 0 to disable this limit. - Default value: 10 -check_rotate_kpackets: - Check rotation every *1000 packets - Default value: 1 - - - EXAMPLE CONFIGURATION - --------------------- - -In ejabberd.yml, in the modules section, add the module. For example: - -modules: - mod_logxml: - stanza: - - iq - - other - direction: - - external - orientation: - - send - - recv - logdir: "/tmp/logs/" - show_ip: false - rotate_days: 1 - rotate_megs: 100 - rotate_kpackets: 0 - check_rotate_kpackets: 1 - - - FORMAT OF XML - ------------- - -XMPP packets are enclosed in , with attributes: - or: orientation of the packet, either 'send' or 'recv' - ljid: local JID of the sender or receiver, depending on the orientation - ts: timestamp when the packet was logged diff --git a/mod_message_log/README.md b/mod_message_log/README.md new file mode 100644 index 0000000..59afe7e --- /dev/null +++ b/mod_message_log/README.md @@ -0,0 +1,41 @@ +mod_message_log - Log one line per message transmission +======================================================= + +* Author: Holger Weiss + + +Description +----------- + +This module writes a line for each sent or received message to a log file. +Each line mentions the sender's JID and the recipient's JID, and also the +message type (e.g., `"normal"`, `"chat"`, or `"groupchat"`). Carbon copies are +marked as such. The log lines look similar to this one: + +``` +2014-05-25 11:55:04 [outgoing, normal] dan@example.com/Foo -> eve@example.net/Bar +``` + +After log rotation, you can execute the following command in order to tell +`mod_message_log` to reopen the log file: + +``` +ejabberdctl reopen_log +``` + + +Configuration +------------- + +In order to use this module, add the following lines to the modules section +of your ejabberd.yml file: + +``` +modules: + mod_message_log: + filename: "/path/to/ejabberd-message.log" +``` + +If the filename option is set to `auto`, it will be set to +the default ejabberd log path, with the file name `"message.log"`. +The filename option takes as default value `auto`. diff --git a/mod_message_log/README.txt b/mod_message_log/README.txt deleted file mode 100644 index 0122f29..0000000 --- a/mod_message_log/README.txt +++ /dev/null @@ -1,34 +0,0 @@ - - mod_message_log - Log one line per message transmission - - Author: Holger Weiss - - - DESCRIPTION - ----------- - -This module writes a line for each sent or received message to a log file. -Each line mentions the sender's JID and the recipient's JID, and also the -message type (e.g., "normal", "chat", or "groupchat"). Carbon copies are -marked as such. The log lines look similar to this one: - - 2014-05-25 11:55:04 [outgoing, normal] dan@example.com/Foo -> eve@example.net/Bar - -After log rotation, you can execute the following command in order to tell -mod_message_log to reopen the log file: - - ejabberdctl reopen_log - - - CONFIGURATION - ------------- - -In order to use this module, add the following lines to the modules section -of your ejabberd.yml file: - - mod_message_log: - filename: "/path/to/ejabberd-message.log" - -If the filename option is set to 'auto', it will be set to -the default ejabberd log path, with the file name "message.log". -The filename option takes as default value 'auto'. diff --git a/mod_muc_log_http/README.md b/mod_muc_log_http/README.md new file mode 100644 index 0000000..caf8d72 --- /dev/null +++ b/mod_muc_log_http/README.md @@ -0,0 +1,39 @@ +mod_muc_log_http - Serve MUC logs on the web +============================================ + +* Requires: ejabberd 19.08 or higher +* Homepage: http://ejabberd.im/mod_muc_log_http +* Author: Badlop + + +Description +----------- + +This module serves the directory containing MUC logs already +configured on `mod_muc_log`. So, there's no need to setup a web server +to allow your users to view the MUC logs. It is a small modification +of `mod_http_fileserver`, customized for log serving. + + +Configuration +------------- + +Sample ejabberd.yml options. The directory to serve is already defined +on `mod_muc_log`. + +```yaml +listen: + - + port: 5282 + module: ejabberd_http + request_handlers: + /muclogs: mod_muc_log_http + +modules: + mod_muc_log: + outdir: "/tmp/muclogs" + mod_muc_log_http: {} +``` + +With that example configuration, open your web browser at: +`http://server:5282/muclogs/` diff --git a/mod_muc_log_http/README.txt b/mod_muc_log_http/README.txt deleted file mode 100644 index 7b9684b..0000000 --- a/mod_muc_log_http/README.txt +++ /dev/null @@ -1,42 +0,0 @@ - - - mod_muc_log_http - Serve MUC logs on the web - - Requires: ejabberd 19.08 or higher - Homepage: http://ejabberd.im/mod_muc_log_http - Author: Badlop - - - DESCRIPTION - =========== - -This module serves the directory containing MUC logs already -configured on mod_muc_log. So, there's no need to setup a web server -to allow your users to view the MUC logs. It is a small modification -of mod_http_fileserver, customized for log serving. - - - CONFIGURATION - ============= - -Sample ejabberd.yml options. The directory to serve is already defined -on mod_muc_log. - -listen: - - - port: 5282 - module: ejabberd_http - request_handlers: - /muclogs: mod_muc_log_http - -modules: - mod_muc_log: - outdir: "/tmp/muclogs" - mod_muc_log_http: {} - - - USAGE - ===== - -With the example options, open your web browser at: -http://server:5282/muclogs/ diff --git a/mod_post_log/README.txt b/mod_post_log/README.md similarity index 60% rename from mod_post_log/README.txt rename to mod_post_log/README.md index 8b00038..4ff6d33 100644 --- a/mod_post_log/README.txt +++ b/mod_post_log/README.md @@ -1,15 +1,16 @@ -# mod_post_log - Logs messages to an HTTP API +mod_post_log - Logs messages to an HTTP API +=========================================== -*Homepage*: https://github.com/processone/ejabberd-contrib/tree/master/mod_post_log -*Author*: Tim Stewart, Mojo Lingo LLC -*Requirements*: ejabberd 14.07 or later +* Author: Tim Stewart, Mojo Lingo LLC +* Requirements: ejabberd 14.07 or later This module implements logging of all messages sent (chat and groupchat) via an HTTP API. -## CONFIGURATION +Configuration +------------- -Add the module to your ejabberd.yml, in the modules section: +Add the module to your `ejabberd.yml`, in the modules section: ```yaml modules: @@ -19,7 +20,8 @@ modules: ... ``` -## API example +API Example +----------- ``` POST /messages HTTP/1.0 diff --git a/mod_pottymouth/README.txt b/mod_pottymouth/README.md similarity index 60% rename from mod_pottymouth/README.txt rename to mod_pottymouth/README.md index ad25367..16a15b7 100644 --- a/mod_pottymouth/README.txt +++ b/mod_pottymouth/README.md @@ -1,23 +1,36 @@ -The 'mod_pottymouth' ejabberd module aims to fill the void left by 'mod_shit' -which has disappeared from the net. It allows individual whole words of a -message to be filtered against a blacklist. It allows multiple blacklists +mod_pottymouth - Filter bad words in messages +============================================= + +* Author: Tom Quackenbush + + +This module allows individual whole words of a message to be filtered against a blacklist. + +It allows multiple blacklists sharded by language. The internal bloomfilter can support arbitrary blacklist sizes. Using a large list (say, 87M terms) will slow down the initial server boot time (to about 15 minutes respectively), but once loaded lookups are very speedy. -Configuration file is ~/.ejabberd-modules/mod_pottymouth/conf/mod_pottymouth.yml +`mod_pottymouth` aims to fill the void left by `mod_shit` +which has disappeared from the net. + +Configuration +------------- + +```yaml modules: - mod_pottymouth: - blacklists: - default: /home/your_user/blacklist_en.txt - en: /home/your_user/blacklist_en.txt - cn: /home/your_user/blacklist_cn.txt - fr: /home/your_user/blacklist_fr.txt - charmaps: - default: /etc/ejabberd/modules/mod_pottymouth/charmap_en.txt - en: /etc/ejabberd/modules/mod_pottymouth/charmap_en.txt + mod_pottymouth: + blacklists: + default: /home/your_user/blacklist_en.txt + en: /home/your_user/blacklist_en.txt + cn: /home/your_user/blacklist_cn.txt + fr: /home/your_user/blacklist_fr.txt + charmaps: + default: /etc/ejabberd/modules/mod_pottymouth/charmap_en.txt + en: /etc/ejabberd/modules/mod_pottymouth/charmap_en.txt +``` For each language (en,cn,fr,...whatever) provide a full path to a backlist file. The blacklist file is a plain text file with blacklisted words listed one per @@ -28,10 +41,11 @@ to specify simple substitutions that will be made on the fly so you don't need to include those permutations in the blacklist. This keeps the blacklist small and reduces server startup time. For example, if you included the word: 'xyza' in the blacklist, adding the following substitutions in the charmap -would filter permutations such as 'XYZA', 'xYz4', or 'Xyz@' automatically. +would filter permutations such as `XYZA`, `xYz4`, or `Xyz@` automatically. -charmap format: +Charmap format: +``` [ {"X", "x"}, {"Y", "y"}, @@ -39,18 +53,21 @@ charmap format: {"@", "a"}, {"4", "a"} ]. +``` -Gotchas: +Gotchas +------- The language will be looked up by whatever value is passed in the xml:lang attribute of the xml message. So, any xml:lang value to be supported will need -a corresponding entry/blacklist in the config file. If xml:lang is missing, +a corresponding entry/blacklist in the config file. If `xml:lang` is missing, the 'default' entry in config will be used. For xml:lang attribute docs, see: http://wiki.xmpp.org/web/Programming_XMPP_Clients#Sending_a_message Blacklist helper +---------------- Thinking of a bunch of swear words and all the permutations can be tough. We made a helper script to take a bare wordlist and generate permutations given a diff --git a/mod_rest/README.txt b/mod_rest/README.md similarity index 79% rename from mod_rest/README.txt rename to mod_rest/README.md index 244d1dc..62d13ec 100644 --- a/mod_rest/README.txt +++ b/mod_rest/README.md @@ -1,10 +1,9 @@ +mod_rest - HTTP interface to POST stanzas into ejabberd +======================================================= - mod_rest - HTTP interface to POST stanzas into ejabberd - - Requires: ejabberd 19.08 or higher - Author: Nolan Eakins - Copyright (C) 2008 Nolan Eakins - +* Requires: ejabberd 19.08 or higher +* Author: Nolan Eakins +* Copyright (C) 2008 Nolan Eakins This is an ejabberd module that adds an HTTP handler that allows HTTP @@ -15,48 +14,55 @@ stanza. This module can also be used as a frontend to execute ejabberd commands. - CONFIGURATION - ============= +Configuration +------------- You can modify the default module configuration file like this: To enable the module: +```yaml modules: mod_rest: allowed_ips: - "127.0.0.1" +``` To enable the HTTP request handler in the listen section: +```yaml listen: - port: 5285 module: ejabberd_http request_handlers: /rest: mod_rest +``` With that configuration, you can send HTTP POST requests to the URL: - http://localhost:5285/rest +`http://localhost:5285/rest` Configurable options: - allowed_ips: IP addresses that can use the rest service. +- `allowed_ips`: IP addresses that can use the rest service. Notice that the IP address is checked after the connection is established. If you want to restrict the IP address that listens connections, and only allow a certain IP to be able to connect to the port, then the - option allowed_ips is not useful to you: you better define the + option `allowed_ips` is not useful to you: you better define the listening IP address in the ejabberd listeners (see the ejabberd Guide). - allowed_destinations: Allowed destination Jabber ID addresses in the stanza. +- `allowed_destinations`: Allowed destination Jabber ID addresses in the stanza. - allowed_stanza_types: Allowed stanza types of the posted stanza. +- `allowed_stanza_types`: Allowed stanza types of the posted stanza. - access_commands: Access restrictions to execute ejabberd commands. - This option is similar to the option ejabberdctl_access_commands that +- `access_commands`: Access restrictions to execute ejabberd commands. + This option is similar to the option `ejabberdctl_access_commands` that is documented in the ejabberd Guide. There is more information about AccessCommands in the ejabberd Guide. -Complex example configuration: +Example Configuration +--------------------- + +```yaml acl: restuser: user: @@ -84,31 +90,32 @@ modules: - restaccess: - registered_users - connected_users +``` This module gives many power to perform tasks in ejabberd, -such power in bad hands can harm your server, so you should +such power in bad hands can harm your server, so you should restrict the IP address that can connect to the service using: -a firewall, allowed_ips option, or the listener IP option. +a firewall, `allowed_ips option`, or the listener IP option. In ejabberd 2.0.x versions, it is important that the value indicated in Content-Length matches exactly the size of the content. - EXAMPLE REST CALL - ================= +Example ReST Call +----------------- When the module receives this: -------- +``` POST /rest HTTP/1.1 Host: localhost Content-Length: 85 World -------- +``` ejabberd.log shows those messages: -------- +``` =INFO REPORT==== 2-Mar-2009::11:46:05 === I(<0.484.0>:ejabberd_listener:201) : (#Port<0.3661>) Accepted connection {{127,0,0,1},55945} -> {{127,0,0,1},5285} @@ -122,29 +129,34 @@ to nolan@localhost: {xmlelement,"message", [{"to","nolan@localhost"},{"from","localhost/rest"}], [{xmlelement,"body",[],[{xmlcdata,<<"World">>}]}]} -------- +``` If the user nolan@localhost exists, he will receive this message: -------- +``` World -------- +``` Instead of an XMPP stanza, you can provide an ejabberd command to execute: +``` registered_users localhost +``` -If you configure access_commands in mod_rest, you need to provide information +If you configure `access_commands` in `mod_rest`, you need to provide information about a local Jabber account with enough privileges according to your option: +``` --auth robot localhost pass0011 registered_users localhost +``` - EXAMPLE CALL WITH LYNX - ====================== +Example Call With Lynx +---------------------- This example shows how to send a POST using Lynx: +``` $ lynx http://localhost:5285/rest/ -mime_header -post_data World --- @@ -154,13 +166,15 @@ Content-Type: text/html; charset=utf-8 Content-Length: 2 Ok +``` - EXAMPLE CALL WITH WGET - ====================== +Example Call With Wget +---------------------- This example shows how to send a POST using Wget: +``` $ wget http://localhost:5285/rest/ --server-response --post-data 'World' --2009-03-02 12:01:42-- http://localhost:5285/rest/ @@ -177,39 +191,46 @@ Saving to: `index.html' 100%[======================================>] 2 --.-K/s in 0s 2009-03-02 12:01:42 (285 KB/s) - `index.html' saved [2/2] - +``` The content of the index.html is simply: +``` Ok +``` -Please notice that mod_rest and wget don't work correctly over HTTPS. +Please notice that `mod_rest` and wget don't work correctly over HTTPS. - EXAMPLE AUTH COMMAND WITH WGET - ============================== +Example Auth Command With Wget +------------------------------ To execute an ejabberd command, simply provide its name and arguments as in ejabberdctl: +``` wget http://localhost:5285/rest/ --server-response --post-data 'registered_users localhost' +``` -If you configure access_commands option, you must provide the credentials like this: +If you configure `access_commands` option, you must provide the credentials like this: +``` wget http://localhost:5285/rest/ --server-response --post-data '--auth user1 localhost thepass registered_users localhost' +``` - EXAMPLE COMMAND WITH CURL - ============================== +Example Call With Curl +---------------------- -Example call with Curl: +``` curl -X POST -i http://localhost:5285/rest/ -d 'create_room testroom muc.localhost localhost' HTTP/1.1 200 OK Content-Type: text/html; charset=utf-8 Content-Length: 1 +``` - EXAMPLE CALL WITH PYTHON - ======================== +Example Call With Python +------------------------ This example Python code first calls to send a stanza, and then calls to execute a command: -------- +```python import urllib2 server_url = 'http://localhost:5285/rest/' @@ -223,14 +244,14 @@ call = 'registered_users localhost' resp = urllib2.urlopen(server_url, call) result = resp.read() print result -------- +``` - EXAMPLE CALL WITH PHP - ===================== +Example Call With PHP +--------------------- This example PHP code implements a call to execute a command (thanks to Qu1cksand): -------- +```php -------- +``` diff --git a/mod_s2s_log/README.md b/mod_s2s_log/README.md new file mode 100644 index 0000000..c700148 --- /dev/null +++ b/mod_s2s_log/README.md @@ -0,0 +1,13 @@ +mod_s2s_log - Log all s2s connections in a file +=============================================== + + +This module can be used to keep track of other XMPP servers your server has +been connected with. + +You can use it by adding the following lines `ejabberd.yml`: +```yaml +modules: + mod_s2s_log: + filename: "/path/to/s2s.log" +``` diff --git a/mod_s2s_log/README.txt b/mod_s2s_log/README.txt deleted file mode 100644 index b7bc129..0000000 --- a/mod_s2s_log/README.txt +++ /dev/null @@ -1,12 +0,0 @@ - - mod_s2s_log - ----------- - - -This module can be use to keep a track of other XMPP servers your server has -been connected with. - -You can use it by adding the following line in the modules section of -ejabberd.yml: - mod_s2s_log: - filename: "/path/to/s2s.log" diff --git a/mod_shcommands/README.md b/mod_shcommands/README.md new file mode 100644 index 0000000..2736954 --- /dev/null +++ b/mod_shcommands/README.md @@ -0,0 +1,69 @@ +mod_shcommands - Execute shell commands +======================================= + +* Requires: ejabberd 19.08 or higher +* Author: Badlop +* http://ejabberd.im/mod_shcommands + + + ***************** + + W A R N I N G + + ***************** + + + USE THIS MODULE AT YOUR OWN RISK + + This module allows ejabberd administrators + to remotely execute shell commands + which could compromise both + the ejabberd server and the whole machine. + + + ***************** + + W A R N I N G + + ***************** + + + + +Description +----------- + +This module provides the ejabberd server administrator a method to remotely +execute shell commands in the ejabberd server. + +It provides a page in the ejabberd Web Admin. +Only the administrators of the whole server can access this page. + +Three types of commands are possible: +* ejabberd_ctl: makes a call to ejabberd_ctl +* erlang shell: executes an erlang command +* system shell: executes a command on the system shell +The result of the execution will be shown. + +In the system shell, only non-interactive commands will work correctly, +for example this will work: +``` +ps -all +``` +Don't use commands that start an interactive mode: +* DON'T TRY THIS: top +* DON'T TRY THIS: vim readme.txt + +This module does not check if the commands are dangerous or problematic, +so this module is only recommended for experienced ejabberd and Erlang/OTP +administrators. + + +Basic Configuration +------------------- + +Add the module to your `ejabberd.yml`, on the modules section: +``` +modules: + mod_shcommands: {} +``` diff --git a/mod_shcommands/README.txt b/mod_shcommands/README.txt deleted file mode 100644 index c1589d1..0000000 --- a/mod_shcommands/README.txt +++ /dev/null @@ -1,68 +0,0 @@ - - mod_shcommands - Execute shell commands - - Requires: ejabberd 19.08 or higher - Author: Badlop - http://ejabberd.im/mod_shcommands - - - - - ***************** - - W A R N I N G - - ***************** - - - USE THIS MODULE AT YOUR OWN RISK - - This module allows ejabberd administrators - to remotely execute shell commands - which could compromise both - the ejabberd server and the whole machine. - - - ***************** - - W A R N I N G - - ***************** - - - - - DESCRIPTION - =========== - -This module provides the ejabberd server administrator a method to remotely -execute shell commands in the ejabberd server. - -It provides a page in the ejabberd Web Admin. -Only the administrators of the whole server can access this page. - -Three types of commands are possible: - * ejabberd_ctl: makes a call to ejabberd_ctl - * erlang shell: executes an erlang command - * system shell: executes a command on the system shell -The result of the execution will be shown. - -In the system shell, only non-interactive commands will work correctly, -for example this will work: - ps -all -Don't use commands that start an interactive mode: - DON'T TRY THIS: top - DON'T TRY THIS: vim readme.txt - -This module does not check if the commands are dangerous or problematic, -so this module is only recommended for experienced ejabberd and Erlang/OTP -administrators. - - - - BASIC CONFIGURATION - =================== - -Add the module to your ejabberd.yml, on the modules section: -modules: - mod_shcommands: {} diff --git a/mod_spam_filter/README.txt b/mod_spam_filter/README.md similarity index 71% rename from mod_spam_filter/README.txt rename to mod_spam_filter/README.md index c159ba9..744a22c 100644 --- a/mod_spam_filter/README.txt +++ b/mod_spam_filter/README.md @@ -1,46 +1,48 @@ +mod_spam_filter - Filter spam messages based on JID/content +=========================================================== - mod_spam_filter - Filter spam messages based on JID/content - - Author: Holger Weiss +* Author: Holger Weiss - DESCRIPTION - ----------- +Description +----------- This module allows for filtering spam messages and subscription requests received from remote servers based on lists of known spammer JIDs and/or URLs mentioned in spam messages. Traffic classified as spam is rejected -with an error (and an [info] message is logged) unless the sender is +with an error (and an `[info]` message is logged) unless the sender is subscribed to the recipient's presence. An access rule can be specified to control which recipients are subject to spam filtering. - CONFIGURATION - ------------- +Configuration +------------- In order to use this module, add a configuration snippet such as the following: - modules: - # [...] - mod_spam_filter: - spam_jids_file: "/etc/ejabberd/spam-filter/jids.txt" - spam_urls_file: "/etc/ejabberd/spam-filter/urls.txt" +```yaml +modules: + # [...] + mod_spam_filter: + spam_jids_file: "/etc/ejabberd/spam-filter/jids.txt" + spam_urls_file: "/etc/ejabberd/spam-filter/urls.txt" +``` -The configurable mod_spam_filter options are: +The configurable `mod_spam_filter` options are: -- spam_dump_file (default: none) +- `spam_dump_file` (default: `none`) This option specifies the path to a file that messages classified as spam will be written to. The messages are dumped in raw XML format, and - a tag with the current timestamp is added. The @HOST@ keyword + a `` tag with the current timestamp is added. The `@HOST@` keyword will be substituted with the name of the virtual host. Note that this module doesn't limit the file size, so if you use this option, make sure to monitor disk file usage and to rotate the file if necessary. After - rotation, the command "ejabberdctl reopen-log" can be called to let the + rotation, the command `ejabberdctl reopen-log` can be called to let the module reopen the spam dump file. -- spam_jids_file (default: none) +- `spam_jids_file` (default: `none`) This option specifies the path to a plain text file containing a list of known spammer JIDs, one JID per line. Messages and subscription @@ -50,7 +52,7 @@ The configurable mod_spam_filter options are: future traffic originating from that JID will also be classified as spam. -- spam_urls_file (default: none) +- `spam_urls_file` (default: `none`) This option specifies the path to a plain text file containing a list of URLs known to be mentioned in spam message bodies. Messages containing @@ -58,31 +60,33 @@ The configurable mod_spam_filter options are: Furthermore, the sender's JID will be cached, so that future traffic originating from that JID will be classified as spam as well. -- access_spam (default: none) +- `access_spam` (default: `none`) This option defines the access rule to control who will be subject to - spam filtering. If the rule returns 'allow' for a given recipient, spam + spam filtering. If the rule returns `allow` for a given recipient, spam messages aren't rejected for that recipient. By default, all recipients are subject to spam filtering. -- cache_size (default: 10000) +- `cache_size` (default: `10000`) This option specifies the maximum number of JIDs that will be cached due to sending spam URLs (see above). If that limit is exceeded, the least recently used entries are removed from the cache. Setting this option - to 0 disables the caching feature. Note that separate caches are used + to `0` disables the caching feature. Note that separate caches are used for each virtual host, and that the caches aren't distributed across cluster nodes. - ejabberd COMMANDS - ----------------- +ejabberd Commands +----------------- This module provides ejabberdctl/API calls to reread the spam JID/URL files, to print the JID cache contents, and to remove entries from that cache. See: +``` $ ejabberdctl help reload-spam-filter-files $ ejabberdctl help get-spam-filter-cache $ ejabberdctl help expire-spam-filter-cache $ ejabberdctl help drop-from-spam-filter-cache +``` diff --git a/mod_statsdx/README.md b/mod_statsdx/README.md new file mode 100644 index 0000000..0480505 --- /dev/null +++ b/mod_statsdx/README.md @@ -0,0 +1,92 @@ +mod_statsdx - Calculates and gathers statistics actively +======================================================== + +* Requires: ejabberd 19.08 or higher +* Homepage: http://www.ejabberd.im/mod_statsdx +* Author: Badlop + + +Measures several statistics. It provides a new section in ejabberd +Web Admin and two ejabberd commands to view the information. + + +Configuration +------------- + +Enable the module in ejabberd.yml for example with a basic configuration: +```yaml +modules: + mod_statsdx: {} +``` + +Configurable options: +- `hooks`: + + Set to `true` to enable hooks and related statistics. + This option by default `false` because it is expected to + consume many resources in very populated servers. + If set to `traffic`, it will also keep counters of traffic stanzas. + + +Example Configuration +--------------------- + +```yaml +modules: + mod_statsdx: + hooks: true +``` + + +Feature Requests +---------------- + + - fix the problem with plain/ssl/tlsusers, it crashes ejabberd + - traffic: send bytes per second, received bps + - connections to a transport + - traffic: send presence per second, received mps + - Number of SASL c2s connections + - improve to work in distributed server + + +mod_stats2file +============== + +Generates files with all kind of statistics + +This module writes a file with all kind of statistics every few minutes. +Available output formats are html (example), +text file with descriptions and raw text file (for MRTG, RRDTool...). + + +Configuration +------------- + +This module requires `mod_statsdx`. + +Enable the module in `ejabberd.yml` for example with a basic configuration: +```yaml +modules: + mod_stats2file: {} +``` + +Configurable options: +- `interval`: Time between updates, in minutes (default: `5`) +- `type`: Type of output. Allowed values: `html`, `txt`, `dat` (default: `html`) +- `basefilename`: Base filename including absolute path (default: `"/tmp/ejasta"`) +- `split`: If split the statistics in several files (default: `false`) +- `hosts`: List of virtual hosts that will be checked. By default `all` + + +Example Configuration +--------------------- + +```yaml +modules: + mod_stats2file: + interval: 60 + type: txt + split: true + basefilename: "/var/www/stats" + hosts: ["localhost", "server3.com"] +``` diff --git a/mod_statsdx/README.txt b/mod_statsdx/README.txt deleted file mode 100644 index 9f5aa4e..0000000 --- a/mod_statsdx/README.txt +++ /dev/null @@ -1,87 +0,0 @@ - - mod_statsdx - Calculates and gathers statistics actively - - Requires: ejabberd 19.08 or higher - Homepage: http://www.ejabberd.im/mod_statsdx - Author: Badlop - - - mod_statsdx - ============== - -Measures several statistics. It provides a new section in ejabberd -Web Admin and two ejabberd commands to view the information. - - - CONFIGURE - --------- - -Enable the module in ejabberd.yml for example with a basic configuration: -modules: - mod_statsdx: {} - -Configurable options: - hooks: Set to 'true' to enable hooks and related statistics. - This option by default 'false' because it is expected to - consume many resources in very populated servers. - If set to 'traffic', it will also keep counters of traffic stanzas. - - - EXAMPLE CONFIGURATION - --------------------- - -modules: - mod_statsdx: - hooks: true - - - FEATURE REQUESTS - ---------------- - - - fix the problem with plain/ssl/tlsusers, it crashes ejabberd - - traffic: send bytes per second, received bps - - connections to a transport - - traffic: send presence per second, received mps - - Number of SASL c2s connections - - improve to work in distributed server - - - - mod_stats2file - ============== - - Generates files with all kind of statistics - -This module writes a file with all kind of statistics every few minutes. -Available output formats are html (example), -text file with descriptions and raw text file (for MRTG, RRDTool...). - - - CONFIGURE - --------- - -This module requires mod_statsdx. - -Enable the module in ejabberd.yml for example with a basic configuration: -modules: - mod_stats2file: {} - -Configurable options: - interval: Time between updates, in minutes (default: 5) - type: Type of output. Allowed values: html, txt, dat (default: html) - basefilename: Base filename including absolute path (default: "/tmp/ejasta") - split: If split the statistics in several files (default: false) - hosts: List of virtual hosts that will be checked. By default all - - - EXAMPLE CONFIGURATION - --------------------- - -modules: - mod_stats2file: - interval: 60 - type: txt - split: true - basefilename: "/var/www/stats" - hosts: ["localhost", "server3.com"] - diff --git a/mod_webpresence/README.txt b/mod_webpresence/README.md similarity index 65% rename from mod_webpresence/README.txt rename to mod_webpresence/README.md index cb259a7..8d72ab7 100644 --- a/mod_webpresence/README.txt +++ b/mod_webpresence/README.md @@ -1,16 +1,17 @@ - mod_webpresence - Presence on the Web +mod_webpresence - Presence on the Web +===================================== - Requires: ejabberd 19.08 or higher - Authors: Igor Goryachev, Badlop, runcom - http://www.ejabberd.im/mod_webpresence +* Requires: ejabberd 19.08 or higher +* Authors: Igor Goryachev, Badlop, runcom +* http://www.ejabberd.im/mod_webpresence - DESCRIPTION - ----------- +Description +----------- This module allows any local user of the ejabberd server to publish his presence information in the web. -This module is the succesor of Igor Goryachev's mod_presence. +This module is the succesor of Igor Goryachev's `mod_presence`. Allowed output methods are * Icons (various themes available) @@ -21,20 +22,20 @@ Allowed output methods are No web server, database, additional libraries or programs are required. - - INSTALL - ------- +Install +------- 1. Compile the module - * On Windows: build.bat - * On other systems: ./build.sh + * On Windows: `build.bat` + * On other systems: `./build.sh` -2. Copy ebin/mod_webpresence.beam to your ejabberd ebin directory. +2. Copy `ebin/mod_webpresence.beam` to your ejabberd `ebin` directory. -3. Copy the directory data/pixmaps to a directory you prefer. +3. Copy the directory `data/pixmaps` to a directory you prefer. -4. Edit ejabberd.yml and add the HTTP and module definitions: +4. Edit `ejabberd.yml` and add the HTTP and module definitions: +```yaml listen: - port: 5280 @@ -46,70 +47,82 @@ listen: modules: mod_webpresence: pixmaps_path: "/path/to/pixmaps" +``` 5. Restart ejabberd. If problems appear, remember to always look first the ejabberd log files -ejabberd.log and sasl.log since they may provide some valuable information. +`ejabberd.log` and `sasl.log` since they may provide some valuable information. - CONFIGURABLE PARAMETERS - ----------------------- +Configuration +------------- + +- `host` -host Define the hostname of the service. - You can use the keyword @HOST@. - Default value: "webpresence.@HOST@" -access: + You can use the keyword `@HOST@`. + Default value: `"webpresence.@HOST@"` + +- `access` + Specify who can register in the webpresence service. - Don't bother to specify 'all' because this module can only show presence of + Don't bother to specify `all` because this module can only show presence of local users. - Default value: local -pixmaps_path: + Default value: `local` + +- `pixmaps_path` + Take special care with commas and dots: if this module does not seem to work correctly, the problem may be that the configuration file has syntax errors. Remember to put the correct path to the pixmaps directory, and make sure the user than runs ejabberd has read access to that directory. - Default value: "./pixmaps" -baseurl: + Default value: `"./pixmaps"` + +- `baseurl` + This informational option is used only when sending a message to the user and when building the JavaScript code. It is the base part of the URL of the webpresence HTTP content. - You can use the keyword @HOST@. - If the option is not specified, it takes as default value: http://host:52080/presence/ + You can use the keyword `@HOST@`. + If the option is not specified, it takes as default value: `http://host:52080/presence/` - AUTOMATIC ENABLE - ---------------- +Automatic Enable +---------------- If you want certain Jabber accounts to be automatically accepted, without requiring the user to register in the service, you can user ACL+ACCESS. -The ACCESSNAME 'webpresence_auto' is available for that purpose. +The ACCESSNAME `webpresence_auto` is available for that purpose. -In that case, all the output methods are enabled, the icon theme is -'jsf-jabber-text' and RandomID is disabled. +In that case, all the output methods are enabled, the icon theme is +`jsf-jabber-text` and RandomID is disabled. The default behaviour is to not have automatic webpresence: - access: - webpresence_auto: - all: deny +```yaml +access: + webpresence_auto: + all: deny +``` For example, if you want all the local users to be automatically enabled in the service: - access: - webpresence_auto: - local: allow +```yaml +access: + webpresence_auto: + local: allow +``` -Note that this ACCESS rule is only checked if the user is not registered. +Note that this ACCESS rule is only checked if the user is not registered. So, if the user registers and disables all output methods, his registration prevails over your setup. If you want to ensure the users do not register and disable output methods, you can use the Access configurable parameter. - EXAMPLE CONFIGURATION - --------------------- +Example Configuration +--------------------- - Example 1 - --------- +## Example 1 +```yaml listen: - port: 5280 @@ -120,11 +133,11 @@ listen: modules: mod_webpresence: pixmaps_path: "/path/to/pixmaps" +``` +## Example 2 - Example 2 - --------- - +```yaml listen: - port: 80 @@ -138,14 +151,14 @@ modules: access: local pixmaps_path: "/path/to/pixmaps" baseurl: "http://www.example.org/status/" +``` - - USAGE - ----- +Usage +----- The web-presence feature by default is switched off for every user. If -user wants to use it, he should register on service webpresence.example.org, -which is accessible from Service Discovery. +user wants to use it, he should register on service `webpresence.example.org`, +which is accessible from Service Discovery. There are several switches for web-presence: * Jabber ID: publish the presence in URIs that use the user's Jabber ID. * Random ID: publish the presence in URIs that use a Random ID. @@ -155,51 +168,60 @@ There are several switches for web-presence: Login to an account on your ejabberd server using a powerful Jabber client. Open the Service Discovery on your Jabber client, and you should see -a new service called "webpresence.example.org". -Try to register on it. A formulary appears allowing the user to +a new service called `webpresence.example.org`. +Try to register on it. A formulary appears allowing the user to allow image publishing, and XML publishing. -Once you enabled some of those options, +Once you enabled some of those options, on a web browser open the corresponding URI: * for XML output: - http://example.org:5280/presence/jid///xml/ + `http://example.org:5280/presence/jid///xml/` * for image output: - http://example.org:5280/presence/jid///image/ + `http://example.org:5280/presence/jid///image/` * for image output with theme: - http://example.org:5280/presence/jid///image/theme// + `http://example.org:5280/presence/jid///image/theme//` * for avatar output: - http://example.org:5280/presence/jid///avatar/ + `http://example.org:5280/presence/jid///avatar/` -If you want to show the image or text outputs of a specific resource, add /res/ +If you want to show the image or text outputs of a specific resource, add `/res/` to the URI: - http://example.org:5280/presence/jid///text/res/ - http://example.org:5280/presence/jid///image/res/ - http://example.org:5280/presence/jid///image/theme//res/ +``` +http://example.org:5280/presence/jid///text/res/ +http://example.org:5280/presence/jid///image/res/ +http://example.org:5280/presence/jid///image/theme//res/ +``` For output types image and avatar, you can append any string to a valid URI. For example, you can use this URI: - http://example.org:5280/presence/jid///image/theme//myimage.jpeg -The response is exactly the same than the regular image/theme// +``` +http://example.org:5280/presence/jid///image/theme//myimage.jpeg +``` +The response is exactly the same than the regular `image/theme//` If you don't want to reveal your Jabber ID, you can enable Random ID URI. After the registration the user gets a message with his a pseudo-random ID. The URI can be formed this way: - http://example.org:5280/presence/rid//image/ +``` +http://example.org:5280/presence/rid//image/ +``` If the user forgets his Random ID, he can get another message by just registering again, there is no need to change the values. If the user wants to get a new Random ID, he must disable Random ID in the registration form, and later enable Random ID again. A new Random ID will be generated for him. - EXAMPLE PHP CODE - ---------------- +Example PHP Code +---------------- This PHP script generates HTML code. Thanks to Tobias Markmann and NoAlWin. It assumes that the URI of the presence is: - http://example.org:5280/presence/jid/tom/example.org +``` +http://example.org:5280/presence/jid/tom/example.org +``` +```php load('http://example.org:5280/presence/jid/tom/example.org/xml'); @@ -229,23 +251,27 @@ It assumes that the URI of the presence is: } echo "

"; } -?> +?> +``` - - JAVASCRIPT CALLBACK - ------------------- +JavaScript Callback +------------------- The JavaScript output supports cross-site AJAX calls. Basically, it allows to tack on a callback parameter to presence requests like so: - http://example.org:5280/presence/jid///js?cb=doStuff +``` +http://example.org:5280/presence/jid///js?cb=doStuff +``` Which then gets fed back in the result as: - var jabber_resources = [...]; doStuff(); +``` +var jabber_resources = [...]; doStuff(); +``` The motivation for this is to work around browser restrictions in -cross-site scripting. You can use it by adding a new