fix #1827

Document operator capabilities.

default.yaml

@@ -603,7 +603,12 @@ channels:
     # (0 or omit for no expiration):
     invite-expiration: 24h
 
-# operator classes
+# operator classes:
+# an operator has a single "class" (defining a privilege level), which can include
+# multiple "capabilities" (defining privileged actions they can take). all
+# currently available operator capabilities are associated with either the
+# 'chat-moderator' class (less privileged) or the 'server-admin' class (full
+# privileges) below: you can mix and match to create new classes.
 oper-classes:
     # chat moderator: can ban/unban users from the server, join channels,
     # fix mode issues and sort out vhosts.
@@ -613,15 +618,15 @@ oper-classes:
 
         # capability names
         capabilities:
-            - "kill"
-            - "ban"
-            - "nofakelag"
-            - "roleplay"
-            - "relaymsg"
-            - "vhosts"
-            - "sajoin"
-            - "samode"
-            - "snomasks"
+            - "kill"      # disconnect user sessions
+            - "ban"       # ban IPs, CIDRs, and NUH masks ("d-line" and "k-line")
+            - "nofakelag" # remove "fakelag" restrictions on rate of message sending
+            - "relaymsg"  # use RELAYMSG in any channel (see the 'relaymsg' config block)
+            - "vhosts"    # add and remove vhosts from users
+            - "sajoin"    # join arbitrary channels, including private channels
+            - "samode"    # modify arbitrary channel and user modes
+            - "snomasks"  # subscribe to arbitrary server notice masks
+            - "roleplay"  # use the (deprecated) roleplay commands in any channel
 
     # server admin: has full control of the ircd, including nickname and
     # channel registrations
@@ -634,12 +639,12 @@ oper-classes:
 
         # capability names
         capabilities:
-            - "rehash"
-            - "accreg"
-            - "chanreg"
-            - "history"
-            - "defcon"
-            - "massmessage"
+            - "rehash"       # rehash the server, i.e. reload the config at runtime
+            - "accreg"       # modify arbitrary account registrations
+            - "chanreg"      # modify arbitrary channel registrations
+            - "history"      # modify or delete history messages
+            - "defcon"       # use the DEFCON command (restrict server capabilities)
+            - "massmessage"  # message all users on the server
 
 # ircd operators
 opers:

docs/MANUAL.md

@@ -151,6 +151,8 @@ You'll need an [up-to-date distribution of the Go language for your OS and archi
 
 Many administrative actions on an IRC server are performed "in-band" as IRC commands sent from a client. The client in question must be an IRC operator ("oper", "ircop"). The easiest way to become an operator on your new Ergo instance is first to pick a strong, secure password, then "hash" it using the `ergo genpasswd` command (run `ergo genpasswd` from the command line, then enter your password twice), then copy the resulting hash into the `opers` section of your `ircd.yaml` file. Then you can become an operator by issuing the IRC command: `/oper admin mysecretpassword`.
 
+The operator defined in the default configuration file is named `admin` and has full administrative privileges on the server; see the `oper-classes` and `opers` blocks for information on how to define additional operators, or less privileged operators.
+
 
 ## Rehashing
 

traditional.yaml

@@ -576,7 +576,12 @@ channels:
     # (0 or omit for no expiration):
     invite-expiration: 24h
 
-# operator classes
+# operator classes:
+# an operator has a single "class" (defining a privilege level), which can include
+# multiple "capabilities" (defining privileged actions they can take). all
+# currently available operator capabilities are associated with either the
+# 'chat-moderator' class (less privileged) or the 'server-admin' class (full
+# privileges) below: you can mix and match to create new classes.
 oper-classes:
     # chat moderator: can ban/unban users from the server, join channels,
     # fix mode issues and sort out vhosts.
@@ -586,15 +591,15 @@ oper-classes:
 
         # capability names
         capabilities:
-            - "kill"
-            - "ban"
-            - "nofakelag"
-            - "roleplay"
-            - "relaymsg"
-            - "vhosts"
-            - "sajoin"
-            - "samode"
-            - "snomasks"
+            - "kill"      # disconnect user sessions
+            - "ban"       # ban IPs, CIDRs, and NUH masks ("d-line" and "k-line")
+            - "nofakelag" # remove "fakelag" restrictions on rate of message sending
+            - "relaymsg"  # use RELAYMSG in any channel (see the 'relaymsg' config block)
+            - "vhosts"    # add and remove vhosts from users
+            - "sajoin"    # join arbitrary channels, including private channels
+            - "samode"    # modify arbitrary channel and user modes
+            - "snomasks"  # subscribe to arbitrary server notice masks
+            - "roleplay"  # use the (deprecated) roleplay commands in any channel
 
     # server admin: has full control of the ircd, including nickname and
     # channel registrations
@@ -607,12 +612,12 @@ oper-classes:
 
         # capability names
         capabilities:
-            - "rehash"
-            - "accreg"
-            - "chanreg"
-            - "history"
-            - "defcon"
-            - "massmessage"
+            - "rehash"       # rehash the server, i.e. reload the config at runtime
+            - "accreg"       # modify arbitrary account registrations
+            - "chanreg"      # modify arbitrary channel registrations
+            - "history"      # modify or delete history messages
+            - "defcon"       # use the DEFCON command (restrict server capabilities)
+            - "massmessage"  # message all users on the server
 
 # ircd operators
 opers: