From c788a57b4eab5a7485614e897d69b0f0e5a0a635 Mon Sep 17 00:00:00 2001
From: Mike McLean <mikem@redhat.com>
Date: Jun 13 2019 17:43:14 +0000
Subject: clean up doc


---

diff --git a/docs/source/permissions.rst b/docs/source/permissions.rst
index e259e9e..f96597b 100644
--- a/docs/source/permissions.rst
+++ b/docs/source/permissions.rst
@@ -2,34 +2,50 @@
 Permission system
 =================
 
-Basic privileges for koji are handled by ``permissions``. These are granted
-and removed by ``admin`` user and allows other users to use different parts
-of koji. There are some default permissions, but new ones can be created by
-administrator and used in koji's :doc:`policies <defining_hub_policies>` or tag
-locks.
+Permissions are used by Koji to control access in a number of ways.
+Some permissions are built-in (e.g. ``admin``, ``repo``), but new ones can be
+created by administrators.
+
+The ``admin`` permission is special.
+It grants superuser access and can stand in for any other permission.
+
+Most of the built-in permissions control access to various hub calls.
+For example, the ``dist-repo`` permission allows access to create dist repos.
+
+Custom permissions can used as the required permission for a tag, or they can
+be referenced in :doc:`hub policies <defining_hub_policies>`.
+
 
 Permission management
 =====================
 
-Admin user can use following koji CLI commands:
+Granting or removing permissions requires the ``admin`` permission.
+A user with sufficient access can use the following koji CLI commands:
 
-  * ``koji grant-permission [--new] <permission> <user> [<user> ...]`` for
-    granting permission to one or more users. It can be also used to create
-    new permission class with ``--new``.
-  * ``koji revoke-permission <permission> <user> [<user> ...]`` for removing
-    such permission from users.
-  * ``koji list-permissions [--user <user>] [--mine]`` is self-descriptive.
+``koji grant-permission [--new] <permission> <user> [<user> ...]``\
+    Grants permission to one or more users. It can be also used to create
+    a new permission with the ``--new`` option.
 
-Default permissions
-===================
+``koji revoke-permission <permission> <user> [<user> ...]``
+    Removes the named permission from users.
+
+``koji list-permissions [--user <user>] [--mine]``
+    Lists permissions in the system.
+
+
+Built-in permissions
+====================
 
 Administration
 --------------
 
+The following permissions govern access to key administrative actions.
+
+
 ``admin``
-  Basic permission, which can be delegated to other users. This
-  is superadmin without any limitations, so grant with caution. Especially
-  services should use some limited form instead of this.
+  This is a superuser access without any limitations, so grant with caution.
+  Users with admin effectively have every other permission.
+  We recommend granting the smallest effective permission.
 
 ``host``
   Restricted permission for handling host-related management tasks.
@@ -40,15 +56,15 @@ Administration
 ``target``
   Permission for adding/deleting/editing targets
 
+
 Tasks
 -----
 
+The following permissions grant access to trigger specialized tasks.
+
 ``appliance``
   appliance tasks (``koji spin-appliance``)
 
-``build``
-  currently unused
-
 ``dist-repo``
   distRepo tasks (``koji dist-repo``)
 
@@ -58,14 +74,27 @@ Tasks
 ``livecd``
   livecd tasks (``koji spin-livecd``)
 
-``repo``
-  newRepo tasks (``koji regen-repo``)
+``livemedia``
+  livemedia tasks (``koji spin-livemedia``)
 
 ``regen-repo``
-  same as ``repo`` for now
+  This permission grants access to regenerate repos (i.e. to trigger
+  ``newRepo`` tasks).
+
+``win-admin``
+  The default ``vm`` policy requires this permission to trigger Windows builds.
+
 
 Data Import
 -----------
+
+The following import permissions allow a user to directly import build
+artifacts of different types.
+We recommend caution when granting these.
+In general, it is better to use the
+:doc:`content generator interface <content_generators>` rather than the direct
+import calls these govern.
+
 ``image-import``
   used for importing external maven artifacts
   (``koji import-archive --type maven``)
@@ -74,9 +103,28 @@ Data Import
   used for importing external maven artifacts
   (``koji import-archive --type maven``)
 
-``win-admin``
-  used in default policy for windows builds ('vm' channel)
-
 ``win-import``
   used for importing external maven artifacts
   (``koji import-archive --type win``)
+
+
+Other
+-----
+
+These remaining permissions don't fit into other categories.
+
+``build``
+  Defined in the database but currently unused
+
+``repo``
+  This special permission is only intended to be granted to the user that
+  ``kojira`` runs as.
+  It grants access to regenerate and expire repos, as well as flag them as
+  deleted or broken.
+  Do not grant this permission to normal users.
+  The ``regen-repo`` permission can be used to grant access for regeneration
+  only.
+
+``sign``
+  This permission grants access to add signatures to rpms and to write out
+  signed copies (``koji import-sig`` and ``koji write-signed-rpm``).