annotate mod_pastebin/README.markdown @ 5853:97c9b76867ca

mod_log_ringbuffer: Detach event handlers on logging reload (thanks Menel) Otherwise the global event handlers accumulate, one added each time logging is reoladed, and each invocation of the signal or event triggers one dump of each created ringbuffer.
author Kim Alvefur <zash@zash.se>
date Sun, 03 Mar 2024 11:23:40 +0100
parents 4bba01ce2f98
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
2 labels:
4315
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
3 - Stage-Stable
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
4 summary: Redirect long messages to built-in pastebin
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
5 ---
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
4315
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
7 # Introduction
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
9 Pastebins are used very often in IM, especially in chat rooms. You have
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
10 a long log or command output which you need to send to someone over IM,
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
11 and don't want to fill their message window with it. Put it on a
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
12 pastebin site, and give them the URL instead, simple.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
14 Not for everyone... no matter how hard you try, people will be unaware,
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
15 or not care. They may also be too lazy to visit a pastebin. This is
4315
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
16 where mod_pastebin comes in!
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17
4315
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
18 # Details
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
20 When someone posts to a room a "large" (the actual limit is
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
21 configurable) message, Prosody will intercept the message and convert it
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
22 to a URL pointing to a built-in pastebin server. The URLs are randomly
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
23 generated, so they can be considered for most purposes to be private,
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
24 and cannot be discovered by people who are not in the room.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25
4315
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
26 # Usage
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27
4315
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
28 To set up mod_pastebin for MUC rooms it **must** be explicitly loaded,
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
29 as in the example below - it won't work when loaded globally, as that
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
30 will only load it onto normal virtual hosts.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32 For example:
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
33
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
34 Component "conference.example.com" "muc"
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
35 modules_enabled = { "pastebin" }
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
37 Pastes will be available by default at
1834
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
38 `http://<your-prosody>:5280/pastebin/` by default.
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
39
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
40 In Prosody 0.9 and later this can be changed with [HTTP
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
41 settings](https://prosody.im/doc/http).
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
42
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
43 In 0.8 and older this can be changed with `pastebin_ports` (see below),
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
44 or you can forward another external URL from your web server to Prosody,
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
45 use `pastebin_url` to set that URL.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
46
4316
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
47 # Discovery
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
48
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
49 The line and character tresholds are advertised in
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
50 [service discovery][xep-0030] like this:
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
51
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
52 ``` {.xml}
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
53 <iq id="791d37e8-86d8-45df-adc2-9bcb17c45cb7" type="result" xml:lang="en" from="prosody@conference.prosody.im">
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
54 <query xmlns="http://jabber.org/protocol/disco#info">
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
55 <identity type="text" name="Prosŏdy IM Chatroom" category="conference"/>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
56 <feature var="http://jabber.org/protocol/muc"/>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
57 <feature var="https://modules.prosody.im/mod_pastebin"/>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
58 <x xmlns="jabber:x:data" type="result">
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
59 <field type="hidden" var="FORM_TYPE">
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
60 <value>http://jabber.org/protocol/muc#roominfo</value>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
61 </field>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
62 <field label="Title" type="text-single" var="muc#roomconfig_roomname">
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
63 <value>Prosŏdy IM Chatroom</value>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
64 </field>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
65 <!-- etc... -->
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
66 <field type="text-single" var="{https://modules.prosody.im/mod_pastebin}max_lines">
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
67 <value>12</value>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
68 </field>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
69 <field type="text-single" var="{https://modules.prosody.im/mod_pastebin}max_characters">
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
70 <value>1584</value>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
71 </field>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
72 </x>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
73 </query>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
74 </iq>
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
75 ```
4bba01ce2f98 mod_pastebin: Document tresholds inclusion in disco#info
Kim Alvefur <zash@zash.se>
parents: 4315
diff changeset
76
4315
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
77 # Configuration
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
78
4315
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
79 Option Description
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
80 ------------------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
81 pastebin_threshold Maximum length (in characters) of a message that is allowed to skip the pastebin. (default 500 characters)
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
82 pastebin_line_threshold The maximum number of lines a message may have before it is sent to the pastebin. (default 4 lines)
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
83 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)
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
84 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.
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
85 pastebin_ports List of ports to run the HTTP server on, same format as mod_httpserver's http_ports[^1]
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
86 pastebin_url Base URL to display for pastebin links, must end with / and redirect to Prosody's built-in HTTP server[^2]
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
87
4315
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
88 # Compatibility
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
89
4315
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
90 ------ -------
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
91 0.11 Works
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
92 0.10 Works
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
93 0.9 Works
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
94 0.8 Works
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
95 ------ -------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
96
4315
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
97 # Todo
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
98
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
99 - Maximum paste length
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
100 - Web interface to submit pastes?
1834
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
101
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
102 [^1]: As of Prosody 0.9, `pastebin_ports` is replaced by `http_ports`,
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
103 see [Prosody HTTP server documentation](https://prosody.im/doc/http)
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
104
7bb2f149f8ec mod_pastebin/README: Try to clarify the config differences in 0.9+
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
105 [^2]: See also
4315
87e250409998 mod_pastebin: Normalize markdown
Kim Alvefur <zash@zash.se>
parents: 3484
diff changeset
106 [http_external_url](https://prosody.im/doc/http#external_url)