user accounting

parsav comes with sophisticated user management tools. you can manage users either from the command line (if you have shell and database access on the host), or using the web UI. both methods will be described in depth here.

core concepts

in parsav, users are a subset of actors, entities that post content on the fediverse. users are the actors that a given parsav instance publishes. some aspects of parsav administration apply to all actors, meaning that remote actors as well as local users are subject to them; others apply only only to users. in the database, users are distinguished only from other actors in that they are marked as belonging to the local instance.

every actor has several properties, most of which are fairly standard social media concepts. the first of these is the handle, the username that uniquely identifies a user on an instance and on the fediverse. due to technical limitations in the design of activitypub, handles cannot be changed, and are indelibly associated with a specific account. (as parsav is also intended to have a non-federating mode, and perhaps a mode to federate only with other parsav instances, it should be possible for non-federating instances to allow handle changes at some point.) the second is the nym, or "display name" in twitter parlance, a string that the user can set and change at will to identify himself, and which is displayed before the handle on posts. and of course, a user can give herself a bio, a block of markdown-formatted text that is displayed on her profile. neither the display name nor the bio can be changed by administrators.

actors can also have an epithet, a secondary title which is displayed in emphasized fashion after the handle and nym. how you use epithets is entirely up to you; you might use them to indicate specific staff roles ("founder", "admin", "moderator" or so on), or to attach humorous labels to well-known users as a mark of respect (or disrespect). the key thing about the epithet is that it can be set only by administrators (specifically, users with the herald power), so bearing an epithet indicates some kind of status recognized by the operator of the instance. (at some point it may also be made possible to change the color of a user's epithet as well, but for now they all display alike.) epithets can also be assigned to members of a chatroom by chatroom staff, but these are scoped to the chatroom and do not display outside of it (nor can they be modified by instance administrators). epithets can be set from the command line with the parsav actor <xid> bestow <epithet> command.

finally, every actor can be assigned a rank. this determines their level of authority on the server. when users are given powers, they can only exercise these powers over actors without rank or with lower ranks than their own; for instance, users of rank 2 can affect actors of rank 3 and 4, but not rank 1. rank 1 is special, being the highest possible rank, in that rank 1 users can affect other rank 1 users — this exception is to prevent the situation where a root user forgets their password and nobody else can reset it. however, the best practice is still to reserve rank 1 for the server owner and use lower ranks for all other users. it is important to note that all actors, not just local users, can be given ranks; while remote users cannot exercise power locally, they can be exempted from the power of lower-ranking administrators. rank can be set with the parsav actor <xid> rank <number> command; degrade will remove an actor's rank

local users have additional properties, a set of powers that governs their ability to use the instance. some of these powers relate only to normal use (logging in, posting, editing one's posts, and so on), and are given to all users by default. others grant power over other users, such as elevate, demote, and discipline (see "powers" for a list). administrative powers can be exercised only over users of lower rank; users without rank cannot make any use of most administrative powers (though herald can be granted to allow a user to change his own epithet). local users also have a "quota" (defaulting to 1000) that governs how many posts they can publish each day. if you run a restricted instance that requires invitations to join, users are also assigned a certain number of those invitations, and once they run out this count must be increased by an administrator before they can invite more users.

creating administrative accounts

when you first install parsav and initialize its database, there will be no user accounts (unless you're using postgresql and unmanaged authentication) and user self-registration will not be allowed. in order to begin using your new instance, you will need to create yourself a user with which to administrate it. in order to do this, you will need to use the parsav utility you used to initialize the database in the first place. (note that depending on your configuration, you may need to run parsav as the same user the parsavd process runs as for it to be able to connect to the database.)

initial account creation is handled with the parsav mkroot <handle> command, where <handle> is the handle of your new user. issuing this command will create a new account with the given name, grant all powers to that account, assign it to rank 1, and generate a password you can use to log in. you can run this command multiple times and create multiple root users if you want, but note that these users have absolute power over the instance, including other root users! in most cases, there should be a single root account beloning to the instance owner, with lower-ranking accounts given out to moderators and other staff. (see "core concepts")

mkroot is purely a convenience function, and is almost identical to the effect of the commands user <handle> create, actor <xid> rank 1, user <handle> grant all, user <handle> auth pw new, and conf set master <handle> issued in sequence. the only difference is that mkroot also bestows a silly title on the new account.

creating user accounts

the command parsav user is used to manage local user accounts, and you can create a new standard user with the command parsav user <handle> create. for example, a user named @eve could be created with parsav user eve create. this user will have no rank, default rights, default settings, and will not be able to log in.

you can enable the user to log in by creating a credential for them. for instance, to issue @eve a password, you could use the command parsav user eve auth pw new or pw reset. (the difference between the two is that reset deletes existing credentials of that type, whereas new creates a new credential without disabling any others). this will generate a temporary password that @eve can use to log in.

you can also create new users through the HTTP interface. log in to your administrative account, navigate to the configuration screen, and click "users" in the menu. (see "emergency recovery" if you don't have this option in your menu.) unfold the "new user" interface, and enter a handle for the new account; it will be created and you will be taken to a page where you can set its properties and create authentication tokens. note that administrators cannot edit other users' display names or bios; these are exclusively the prerogative of the user herself.

nota bene: if you want to give an account to another user, creating an invitation link is generally the best way of doing it, rather than manually adding a new account.

powers

the abilities a user can exercise on a server are governed by their powers, a set of flags administrators can set on their accounts.

these powers are intended for ordinary users, and default to on:

• login: the user can log in to the instance. revoking this power is equivalent to banning the user.
• visible: the user and his posts can be seen by other users without navigating directly to his profile page
• post: the user can publish new posts
• shout: the user is visible on the local timeline
• propagate: the user's posts federate
• artifact: the user can upload artifacts and attach them to posts. users without this power can still add artifacts uploaded by others to their account, but cannot upload their own.
• account: the user can configure their own account and profile
• edit: the user can edit her own posts
• snitch: the user can submit reports asking for moderator action

these powers are intended for staff, and default to off:

• herald: the user can change the epithets of lower-ranking actors, grant them badges, or revoke their badges. note that badges can also be restricted such that only heralds of a certain rank can grant or revoke them.
• crier: the user can promote content to the instance page (and thus the archives). note that by default only one post can be promoted per crier per day, though this can be changed (see server configuration).
• elevate: the user can increase the rank of lower-ranking actors up to one rank below his own, and can grant powers that he already possesses.
• demote: the user can decrease the rank of lower-ranking actors or strip them of rank entirely, and can revoke powers that she too possesses.
• censor: the user can eliminate undesirable content, remove posts from the instance page, and respond to badthink reports, whether by dismissing the report, by suppressing (but not deleting) the post in question, or by referring the matter upwards to someone with the discipline power. on smaller instances, moderators should probably hold this power and the discipline power simultaneously; on larger ones, it may be best to separate the two.
• discipline: the user can place sanctions on lower-ranking actors and cancel pending invites. sanctions are (usually temporary) punishments that strip certain abilities (or suspend certain conversations), and are intended as a less extreme, more flexible means of dealing with toxic behavior. most moderators should possess this power rather than elevate or demote, as sanctions leave a paper trail and can be summarily vacated by users of equal or higher rank with the vacate power. discipline also grants various other disciplinary abilities, such as issuing demerits, which can result in various penalties
• vacate: the user can rehabilitate disciplined actors, vacating sanctions, voiding demerits, and issuing temporary reprieves from restrictions.
• purge: the user can completely destroy lower-ranking accounts and all associated content, removing them entirely from the instance. best to keep this one for yourself.
• invite: the user can issue invites and create accounts without depleting their invite supply, even if they have none at all. users with both the invite and elevate powers can grant invites to others.
• cred: the user can add, change, and remove the credentials of lower-ranking users (think password resets).
• config: grants access to technical and security-related server settings, like bind or domain. be aware that changes made by users with this power affect all users, regardless of rank, and may affect how certain other powers function.
• rebrand: grants access to server settings that affect the appearance and livery of the site, like the ui-accent setting, the instance name, or the content of the instance page.

powers can be granted and revoked through the online interface, in the users section. they can also be controlled using the command line tool, with the commands parsav user <handle> grant <power>… and revoke <power>… (all can be used instead of a list of powers to grant or strip all powers simultaneously)

recommendations

on smaller servers, it is highly recommended that the config, rebrand, purge, elevate, and demote powers all rest with a single user. other administrators and moderators should be given censor, discipline, vacate, and possibly invite and herald depending on your intentions for the site. you should be the only rank-1 user, and other staff should be given rank 2. rank 3 might be useful to limit the damage new staff can do during a "probation period." herald and crier are useful powers to combine, as they create a "moderator" with powers related mostly to promotion of users and their work.

on larger servers, it may be necessary to have more levels of administrative abstraction, or even to increase the maximum number of ranks from its default of 10. in this case, certain exceptional powers such as rebrand and purge should still remain exclusively with the founder, but it may be necessary to (carefully!) apportion out access to powers like elevate and demote. it may also be desirable to have a broader class of less-trusted moderators who can take minimally destructive measures on their own (say, censor and herald) to filter through the bulk of reports, with a smaller corps of highly trusted commissars who have powers like discipline and vacate to handle the small number of reports that censors believe deserve their attention.

in both cases, it's very, very important to keep in mind that 99% of community management is social. parsav tries to provide you with effective tools for when use of force becomes unavoidable, but most of the time a good community leader can accomplish his goals with words alone (remember, IRC has none of this fancy shit, and they manage just fine most of the time!). apart from those relatively rare cases where you are faced with true bad-faith actors (in which cases immediate brutality is the only solution), a community can be handled effectively with just with judicious use of symbolic measures like rank, badges, and epithets. a gentle indication that a high-status user disapproves of her conduct is often all it takes to convince a lower-status user who truly cares about her community to shape up. all the power in the world won't give you a drop of authority, and if you're new to running communities, you may be surprised how much authority you can endow other members with without giving them anything besides maybe a fancy title (though even that is just a convenience) so long as the people in your community like, trust, and respect you.

and if your users don't respect you, you might as well pack up right now.

emergencies

shit happens. sometimes this shit results in getting locked out of your own instance. if so, don't panic quite yet. as long as you can get shell access to the host to run the parsav utility, you can resolve the situation. (note that parsavd does not need to be running to use commands that control the database, and for some backends such as sqlite parsavd may need to be shut down first.)

locked out

if you are locked out of your administrator account, the fix is simple, as long as you can modify the underlying database: the parsav utility does not use instance credentials, but rather directly modifies the DB and sends IPC signals through the kernel. if you're locked out because you've forgotten your password or all your credentials have been deleted somehow, just issue yourself a new temporary password like you would for any other user, with the parsav user <handle> auth pw reset command.

missing privileges

if you've been stripped of the login privilege by a bug or a rogue admin, you can restore it with parsav user <handle> grant login, and it may be worthwhile to issue a revoke demote to keep that rogue admin from immediately locking you out again. keep in mind that this won't affect sanctions that have been issued against your account; see below for these.

sanctions

users with the discipline privilege cannot change user powers outright, but can issue sanctions that temporarily limit these powers in various ways, for instance preventing a user from posting for a few hours until they've cooled down. users with discipline can only affect users of lower rank unless they're rank 1, in which case they can affect all users. if you've fallen afoul of one of these users and need to get your instance back, you'll need to vacate all the sanctions against your account. this can be done with the parsav actor <xid> sanction all vacate command. alternately, you can list individual sanctions with sanction, and then delete them individually with sanction <sid> vacate.

lost account

if your account has been completely deleted, rather than just suspended, things are decidedly more serious. everything associated with your account — posts, media, circles, relationships, all of it — is gone, irreversibly, unless you have a database backup around somewhere. (the purge power is so named because it is serious business, to be treated as the equivalent of a concealed carry permit — you should give it out to other users only out of specific justified need in exceptional circumstances, and revoke it proactively when it is no longer absolutely necessary, rather than as punishment for misuse. hopefully you have now learned this lesson.)