introduce 'host' permission + docs

Fixes: https://pagure.io/koji/issue/1453

docs/source/index.rst

@@ -22,6 +22,7 @@ Contents
     :maxdepth: 2
 
     HOWTO
+    permissions
     defining_hub_policies
     external_repo_server_bootstrap
     image_build

docs/source/permissions.rst

@@ -0,0 +1,76 @@
+=================
+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.
+
+Permission management
+=====================
+
+Admin user can use 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.
+
+Default permissions
+===================
+
+Administration
+--------------
+
+``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.
+
+``host``
+  Restricted permission for handling host-related management tasks.
+
+Tasks
+-----
+
+``appliance``
+  appliance tasks (``koji spin-appliance``)
+
+``build``
+  currently unused
+
+``dist-repo``
+  distRepo tasks (``koji dist-repo``)
+
+``image``
+  image tasks (``koji image-build``)
+
+``livecd``
+  livecd tasks (``koji spin-livecd``)
+
+``repo``
+  newRepo tasks (``koji regen-repo``)
+
+``regen-repo``
+  same as ``repo`` for now
+
+Data
+----
+``image-import``
+  used for importing external maven artifacts
+  (``koji import-archive --type maven``)
+
+``maven-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``)

hub/kojihub.py

@@ -2108,7 +2108,7 @@ def readTagGroups(tag, event=None, inherit=True, incl_pkgs=True, incl_reqs=True,
         return [x for x in groups if not x['blocked']]
 
 def set_host_enabled(hostname, enabled=True):
-    context.session.assertPerm('admin')
+    context.session.assertPerm('host')
     host = get_host(hostname)
     if not host:
         raise koji.GenericError('host does not exist: %s' % hostname)
@@ -2128,7 +2128,7 @@ def add_host_to_channel(hostname, channel_name, create=False):
 
     Channel must already exist unless create option is specified
     """
-    context.session.assertPerm('admin')
+    context.session.assertPerm('host')
     host = get_host(hostname)
     if host == None:
         raise koji.GenericError('host does not exist: %s' % hostname)
@@ -2146,7 +2146,7 @@ def add_host_to_channel(hostname, channel_name, create=False):
     insert.execute()
 
 def remove_host_from_channel(hostname, channel_name):
-    context.session.assertPerm('admin')
+    context.session.assertPerm('host')
     host = get_host(hostname)
     if host == None:
         raise koji.GenericError('host does not exist: %s' % hostname)
@@ -4782,7 +4782,7 @@ def edit_host(hostInfo, **kw):
 
     Returns True if changes are made to the database, False otherwise.
     """
-    context.session.assertPerm('admin')
+    context.session.assertPerm('host')
 
     host = get_host(hostInfo, strict=True)
 
@@ -8848,7 +8848,7 @@ class RootExports(object):
     '''Contains functions that are made available via XMLRPC'''
 
     def restartHosts(self, priority=5, options=None):
-        context.session.assertPerm('admin')
+        context.session.assertPerm('host')
         if options is None:
             args = []
         else:
@@ -10987,7 +10987,7 @@ class RootExports(object):
         If krb_principal is not given then that field will be generated
         from the HostPrincipalFormat setting (if available).
         """
-        context.session.assertPerm('admin')
+        context.session.assertPerm('host')
         # validate arches
         arches = " ".join(arches)
         arches = koji.parse_arches(arches, strict=True)

tests/test_hub/test_add_host.py

@@ -65,7 +65,7 @@ class TestAddHost(unittest.TestCase):
         r = self.exports.addHost('hostname', ['i386', 'x86_64'])
         self.assertEqual(r, 12)
 
-        self.context.session.assertPerm.assert_called_once_with('admin')
+        self.context.session.assertPerm.assert_called_once_with('host')
         kojihub.get_host.assert_called_once_with('hostname')
         self.context.session.createUser.assert_called_once_with('hostname',
                 usertype=koji.USERTYPES['HOST'], krb_principal='-hostname-')