Members and access

Running a community takes two kinds of control:

• The configuration file decides the rules: whether the server is open or protected, the password, whether invitations are allowed, and the bootstrap secret for the first administrator. A reload applies changes, except to the bootstrap secret, which waits for a restart.
• Administrators in the app handle everything day to day: rooms, invitations, roles and removing people. The server's operator can do the same from the command line.

The first administrator

A new community has no administrator. There are two ways to get one:

• a bootstrap secret: a one-time secret you put in the configuration and then enter in the app;
• an administrator invitation: a link you create on the command line and open in the app. On a protected server this is simplest, because your device joins and becomes administrator in one step. See With an invitation.

To use a bootstrap secret:

1. Add a secret to the configuration and restart the server:

   [access]
   bootstrap_secret = "correct-horse-battery-staple"

   Use something long and random, such as the output of openssl rand -base64 24.

2. Connect to the server in Moin.

3. Open the community's More actions menu (⋯) in the connections list and choose Claim community.

4. Enter the secret and choose Claim administrator role.

The first successful claim makes that device the administrator and closes bootstrap for good: the secret never works again, even after a restart or a change to it. You can remove it from the configuration afterwards.

Some things to know:

• Claim before inviting others. Anyone who has the secret and can connect can claim. moin-server admin status shows Bootstrap open until someone does.
• Claim while you can connect. On a protected server, your device has to get in first, with the password or an invitation. Claiming while the server is still open, then protecting it, works too. Claiming makes your device a member, so it keeps its access.
• Wrong secrets count toward a limit. Claims are limited to eight attempts every ten seconds across the whole server.
• Keeping the secret out of the file. bootstrap_secret_env names an environment variable to read it from instead. Use one or the other. A secret is 1 to 1024 bytes.

With an invitation

On a protected server with invites_enabled = true, create a single-use administrator invitation:

moin-server admin --config moin-server.toml invites create --role admin --max-claims 1 --expires-in 1d

Open the printed link in Moin on the device that should be the administrator. It joins the community as an administrator. This needs no bootstrap secret, and the two don't affect each other. See Invitations with a role.

From the command line instead

If you can run commands on the server, you don't need a secret. Connect from your device, find it in moin-server admin status by its nickname, and give it the role:

moin-server admin --config moin-server.toml roles set <device-id> admin

A member's menu in the app shows the last eight characters of their device ID, which tells apart devices with the same nickname.

Bootstrap is closed while the community has an administrator. If nobody ever claimed it with the secret and the last administrator loses the role, it opens again.

Recovering a lost administrator

If the only administrator loses their device, the operator can make a new one with roles set at any time, or send a new administrator invitation to their new device. Once a secret has been claimed, bootstrap never reopens, so the command line is the way back.

Managing from the app

Once connected, administrators and moderators find their tools here. A member's menu is there for someone in any room, so you can moderate a room without joining it:

Where	What
The community's More actions menu → Create room	Create a room, with an optional member limit.
A room's More actions menu → Edit room, Delete room	Rename a room, change its limit, or delete it. Deleting moves everyone in it out.
The community's More actions menu → Share community	Share the community link on a phone or copy it on desktop. If invitations are enabled, you can create a limited invitation link.
The community's More actions menu → Community administration	Everyone with a role, the invitations and whether each is still usable, and revoking them.
A member's menu in a room → Role	Make someone a member, moderator or administrator. Not on phones, where roles are changed in Community administration.
A member's menu in a room → Move to, Remove from room	Move someone to another room, or out of the room, without removing them. Both of you need a current version of Moin.
A member's menu in a room → Kick	Remove someone's device from the community.

Each person only sees what their role allows; see Roles. Room controls appear only with rooms = "managed".

A few things need the operator's command line: giving a role to someone who isn't in a room with an administrator, removing a device that's offline or in another room, and adding a device without a password or invitation.

Open or protected

Open is the default. Anyone who has the server's ID, hostname or a link can join.

Protected lets in only devices that are members. A device becomes a member by entering the server's password, by opening an invitation link, by being given a role, or by being added by the operator. After that it's remembered and joins without asking again.

[access]
mode = "protected"
invites_enabled = true
password_env = "MOIN_COORDINATOR_PASSWORD"

Passwords and invitations are independent. Turn on either, both, or neither: with neither, only devices that are already members can join, and the operator adds new ones with moin-server admin devices add.

Devices that joined while the server was open aren't members, unless they have a role. When the server becomes protected, the others need to join again.

Passwords

Set the password through an environment variable, so it stays out of the configuration file:

[access]
mode = "protected"
password_env = "MOIN_COORDINATOR_PASSWORD"

The server refuses to start if that variable isn't set. password = "…" in the file works too, but not both at once. A password is 1 to 1024 bytes.

When someone adds a protected server, the app asks for the password. It's entered once per device and never saved on it. Share community gives out the community link but never the password; send that separately. On a phone, the link opens in the share sheet. If invitations are also enabled, choose Share link in the dialog.

Changing or removing the password only affects devices joining from then on. Everyone who joined with the old password stays a member.

Invitations

With invites_enabled = true, administrators and moderators can create invitation links:

• in the app, with Share community → Create invite link, lasting 1 hour, 24 hours, 7 days or forever, for 1, 5, 10 or unlimited devices;
• on the command line, with any expiry and number of uses: moin-server admin invites create --expires-in 3d --max-claims 5.

Each link is shown once. Opening it in Moin makes the device a member. Only the first join from each device counts as a use.

On iPhone or Android, creating an invitation opens the share sheet. The dialog also lets you share or copy that link again before closing it. If sharing fails, Retry uses the same invitation.

An invitation lets its holder into the whole community, not a particular room. Expiring or revoking it only affects devices that haven't used it yet. Revoke invitations in Community administration, or with moin-server admin invites revoke.

Invitations with a role

The operator can create an invitation that also gives a role, with moin-server admin invites create --role admin or --role moderator. A device that joins with it becomes a member and gets the role at once.

• Only the command line creates them, and only on a protected server.
• A device that's already a member gets the role too, if it's higher than the one it has, and uses the invitation up. One that already has that role or a higher one doesn't use it, and keeps its role. Moin says which happened when the link is opened.
• Community administration lists them like any other invitation; moin-server admin invites list shows their role.
• Anyone with the link gets the role, so use --max-claims 1 and a short expiry, and revoke it if it goes astray.

Roles

Members without a role can join rooms and talk. Two roles add more:

	Administrator	Moderator
Create and revoke invitations	yes	yes
Remove members without a role	yes	yes
Remove members with a role	yes	no
Create, rename and delete rooms	yes	no
Move members between rooms	yes	yes
Give and take away roles	yes	no

Roles work in open and protected mode alike, and show as badges next to members' names. The last administrator can't be demoted or removed from inside the app. The operator, whoever can run moin-server admin on the server, is above every role and isn't bound by that rule.

Removing someone

Removing a device takes away its membership and role and disconnects it. In the app, Kick in a member's menu works for members of any room, not only yours. If the person joined with an invitation that could still be used, Kick revokes it too, and the app tells you. The operator can remove any device with moin-server admin devices revoke <device-id>, which leaves invitations alone.

Removing a device isn't a ban. What stops it coming back depends on the mode:

• Open: nothing. The device can reconnect straight away.
• Protected with invitations: kick the device, then revoke any other invitations the person might still have.
• Protected with a password: remove the device, then change the password and reload. Everyone else stays a member.

Guessing protection

Join attempts from devices that aren't members yet are limited to eight every ten seconds across the whole server, and so are attempts to claim administrator with the bootstrap secret. Past that, the app is told to wait and try again.