Mercurial > prosody-modules

comparison mod_pastebin/README.md @ 5972:51b6a10b50d2

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