Mercurial > prosody-modules

annotate mod_easy_invite/README.markdown @ 5787:e79f9dec35c0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_c2s_conn_throttle: Reduce log level from error->info Our general policy is that "error" should never be triggerable by remote entities, and that it is always about something that requires admin intervention. This satisfies neither condition. The "warn" level can be used for unexpected events/behaviour triggered by remote entities, and this could qualify. However I don't think failed auth attempts are unexpected enough. I selected "info" because it is what is also used for other notable session lifecycle events.
author Matthew Wild <mwild1@gmail.com>
date Thu, 07 Dec 2023 15:46:50 +0000
parents d3d2e9e7e8b7
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4090
e77122025080 mod_easy_invite: Add a touch of dependency info
Kim Alvefur <zash@zash.se>
parents: 3788
diff changeset
1 ---
4098
d6710900019b mod_easy_invite: Add deprecation note and tag
Matthew Wild <mwild1@gmail.com>
parents: 4090
diff changeset
2 labels:
d6710900019b mod_easy_invite: Add deprecation note and tag
Matthew Wild <mwild1@gmail.com>
parents: 4090
diff changeset
3 - 'Stage-Deprecated'
d6710900019b mod_easy_invite: Add deprecation note and tag
Matthew Wild <mwild1@gmail.com>
parents: 4090
diff changeset
4 summary: 'Invite management module for Prosody (deprecated)'
4090
e77122025080 mod_easy_invite: Add a touch of dependency info
Kim Alvefur <zash@zash.se>
parents: 3788
diff changeset
5 rockspec:
e77122025080 mod_easy_invite: Add a touch of dependency info
Kim Alvefur <zash@zash.se>
parents: 3788
diff changeset
6 dependencies:
e77122025080 mod_easy_invite: Add a touch of dependency info
Kim Alvefur <zash@zash.se>
parents: 3788
diff changeset
7 - mod_invites
e77122025080 mod_easy_invite: Add a touch of dependency info
Kim Alvefur <zash@zash.se>
parents: 3788
diff changeset
8 ---
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9
4150
d3d2e9e7e8b7 mod_easy_invite: Highlight deprecation notice
Kim Alvefur <zash@zash.se>
parents: 4098
diff changeset
10 ::: {.alert .alert-warning}
4098
d6710900019b mod_easy_invite: Add deprecation note and tag
Matthew Wild <mwild1@gmail.com>
parents: 4090
diff changeset
11 **NOTE:** This module has been deprecated. Its functionality has been
d6710900019b mod_easy_invite: Add deprecation note and tag
Matthew Wild <mwild1@gmail.com>
parents: 4090
diff changeset
12 moved to other modules, see the mod_invites documentation for details.
4150
d3d2e9e7e8b7 mod_easy_invite: Highlight deprecation notice
Kim Alvefur <zash@zash.se>
parents: 4098
diff changeset
13 :::
4098
d6710900019b mod_easy_invite: Add deprecation note and tag
Matthew Wild <mwild1@gmail.com>
parents: 4090
diff changeset
14
d6710900019b mod_easy_invite: Add deprecation note and tag
Matthew Wild <mwild1@gmail.com>
parents: 4090
diff changeset
15
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 This module allows admins and users to create invitations suitable for sharing
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 to potential new users/contacts.
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 User invitations can be created through the "New Invite" ad-hoc command. An overview
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 of the semantics and protocol can be found at [modernxmpp.org/client/invites](https://docs.modernxmpp.org/client/invites/).
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22 This module depends on mod_invites to actually create and store the invitation tokens.
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 # Configuration
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 To allow users to join your server through invitations, you must
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27 enable mod_register_ibr and set allow_registration = true, and then
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28 also set `registration_invite_only = true` to restrict registration.
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29
3787
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
30 | Name | Description | Default |
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
31 |--------------------------|-----------------------------------------------------------------------------------|---------|
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
32 | registration_invite_only | Whether registration attempts without an invite token should be blocked | true |
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
33 | allow_user_invites | Whether existing users should be allowed to invite new users to register accounts | true |
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
34
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
35 ## Example: Invite-only registration
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 ``` {.lua}
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 -- To allow invitation through a token, mod_register
3787
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
38 allow_registration = true
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 registration_invite_only = true
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40 ```
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41
3787
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
42 ## Example: Open registration
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
43
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
44 This setup allows completely open registration, even without
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
45 an invite token.
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
46
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
47 ``` {.lua}
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
48 allow_registration = true
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
49 registration_invite_only = false
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
50 ```
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
51
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
52 ## Invite creation permissions
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
53
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 To allow existing users of your server to send invitation links that
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55 allow new people to join your server, you can set `allow_user_invites = true`.
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 If you do not wish users to invite other users to create accounts on your
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 server, set `allow_user_invites = false`. They will still be able to send
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 contact invites, but new contacts will be required to register an account
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60 on a different server.
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61
3778
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
62 # Usage
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
63
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
64 Users can use the "New Invite" ad-hoc command through their client.
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
65
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
66 Admins can create registration links using prosodyctl, e.g.
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
67
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
68 ```
3788
14028430638b mod_easy_invite: Change command name to 'generate' (from 'register')
Matthew Wild <mwild1@gmail.com>
parents: 3787
diff changeset
69 prosodyctl mod_easy_invite example.com generate
3778
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
70 ```
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
71
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72 # Compatibility
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74 0.11 and later.