Mercurial > prosody-modules

annotate mod_easy_invite/README.markdown @ 4082:6cdbca89b8be

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_easy_invite: Minor refactoring to begin merging additional changes from Snikket
author Matthew Wild <mwild1@gmail.com>
date Mon, 07 Sep 2020 12:50:36 +0100
parents 14028430638b
children e77122025080
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 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
3 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
4
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 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
6 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
7
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 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
9
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10 # Configuration
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12 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
13 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
14 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
15
3787
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
16 | Name | Description | Default |
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
17 |--------------------------|-----------------------------------------------------------------------------------|---------|
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
18 | 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
19 | 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
20
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
21 ## 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
22 ``` {.lua}
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 -- 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
24 allow_registration = true
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25 registration_invite_only = true
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 ```
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27
3787
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
28 ## Example: Open registration
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
29
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
30 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
31 an invite token.
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
32
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
33 ``` {.lua}
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
34 allow_registration = true
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
35 registration_invite_only = false
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
36 ```
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
37
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
38 ## Invite creation permissions
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
39
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40 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
41 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
42
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 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
44 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
45 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
46 on a different server.
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47
3778
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
48 # Usage
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
49
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
50 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
51
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
52 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
53
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
54 ```
3788
14028430638b mod_easy_invite: Change command name to 'generate' (from 'register')
Matthew Wild <mwild1@gmail.com>
parents: 3787
diff changeset
55 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
56 ```
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
57
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 # Compatibility
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60 0.11 and later.