Mercurial > prosody-modules

annotate mod_easy_invite/README.markdown @ 4097:96838617695a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_invites: Update documentation
author Matthew Wild <mwild1@gmail.com>
date Fri, 11 Sep 2020 13:53:55 +0100
parents e77122025080
children d6710900019b
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 ---
e77122025080 mod_easy_invite: Add a touch of dependency info
Kim Alvefur <zash@zash.se>
parents: 3788
diff changeset
2 rockspec:
e77122025080 mod_easy_invite: Add a touch of dependency info
Kim Alvefur <zash@zash.se>
parents: 3788
diff changeset
3 dependencies:
e77122025080 mod_easy_invite: Add a touch of dependency info
Kim Alvefur <zash@zash.se>
parents: 3788
diff changeset
4 - mod_invites
e77122025080 mod_easy_invite: Add a touch of dependency info
Kim Alvefur <zash@zash.se>
parents: 3788
diff changeset
5 ---
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 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
8 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
9
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10 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
11 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
12
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13 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
14
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15 # Configuration
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 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
18 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
19 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
20
3787
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
21 | Name | Description | Default |
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
22 |--------------------------|-----------------------------------------------------------------------------------|---------|
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
23 | 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
24 | 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
25
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
26 ## 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
27 ``` {.lua}
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28 -- 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
29 allow_registration = true
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30 registration_invite_only = true
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 ```
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32
3787
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
33 ## Example: Open registration
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 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
36 an invite token.
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 ``` {.lua}
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
39 allow_registration = true
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
40 registration_invite_only = false
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
41 ```
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
42
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
43 ## Invite creation permissions
28deb30a5272 mod_easy_invite: Improve docs surrounding configuration options and defaults
Matthew Wild <mwild1@gmail.com>
parents: 3778
diff changeset
44
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 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
46 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
47
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48 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
49 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
50 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
51 on a different server.
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52
3778
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
53 # Usage
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
54
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
55 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
56
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
57 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
58
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
59 ```
3788
14028430638b mod_easy_invite: Change command name to 'generate' (from 'register')
Matthew Wild <mwild1@gmail.com>
parents: 3787
diff changeset
60 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
61 ```
7209f481bcfe mod_easy_invite: Add prosodyctl command to generate account invites
Matthew Wild <mwild1@gmail.com>
parents: 3777
diff changeset
62
3777
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63 # Compatibility
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64
26559776a87e mod_easy_invite: New module that implements XEP-0401/XEP-0379
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65 0.11 and later.