259 lines
8.3 KiB
ReStructuredText
259 lines
8.3 KiB
ReStructuredText
=====================
|
|
Defining Hub Policies
|
|
=====================
|
|
|
|
Defining a policy on the hub allows you fine control over certain activities
|
|
in the system. At present, policy allows you to control:
|
|
* tag/untag/move operations
|
|
* allowing builds from srpm
|
|
* allowing builds from expired repos
|
|
* managing the package list for a tag
|
|
* managing which channel a task goes to
|
|
|
|
In the future, we expect to add more policy hooks for controlling more aspects
|
|
of the system.
|
|
|
|
Policy configuration is optional. If you don't define one, then by default:
|
|
* tag/untag/move operations are governed by tag locks/permissions
|
|
* builds from srpm are only allowed for admins
|
|
* builds from expired repos are only allowed for admins
|
|
* only admins may modify package lists
|
|
* tasks go to the default channel
|
|
|
|
Configuration
|
|
=============
|
|
|
|
The hub policy is configured in the ``hub.conf`` file, which is an ini-style
|
|
configuration file. Policies are defined in the section named ``[policy]``.
|
|
Each ``name = value`` pair defines the policy of that name. With multiple line
|
|
policies, successive lines should be indented so that the parser treats them
|
|
as part of the whole.
|
|
|
|
Consider the following simple (and strict) example:
|
|
|
|
::
|
|
|
|
[policy]
|
|
tag =
|
|
has_perm admin :: allow
|
|
tag *-candidate :: allow
|
|
all :: deny
|
|
|
|
This policy section defines a single policy (named 'tag'). The policy is a
|
|
series of rules, one per line. The rule lines must be indented. Each rule is
|
|
a test and an action, separated by a double colon. The valid actions for
|
|
current policies are 'allow' and 'deny'. There are many tests available,
|
|
though not all of them are applicable for all policies. Each test is specified
|
|
by giving the name of the test followed by any arguments the test accepts.
|
|
|
|
Each rule in the policy is checked until a match is found. Upon finding a
|
|
match, the action is applied. Our example above limits non-admins to tags
|
|
ending in -candidate.
|
|
|
|
Getting a bit more complicated
|
|
The example above is very simple. The policy syntax also supports compound
|
|
tests, negated tests, and nested tests. Consider the following example:
|
|
|
|
::
|
|
|
|
[policy]
|
|
tag =
|
|
buildtag *epel* :: {
|
|
tag *epel* !! deny
|
|
}
|
|
tag *-updates :: {
|
|
operation move :: {
|
|
fromtag *-updates-candidate :: allow
|
|
fromtag *-updates-testing :: allow
|
|
all :: deny
|
|
}
|
|
operation tag && hastag *-updates-candidate *-updates-testing :: deny
|
|
}
|
|
all :: allow
|
|
|
|
This policy sets up some rules concerning tags ending in -updates and tags
|
|
containing epel, but is otherwise permissive.
|
|
|
|
The first nested rule limits builds built from a tag matching ``epel`` to only
|
|
such tags. Note the use of !! instead of :: negates the test.
|
|
|
|
For tags matching ``*-updates``, a particular work-flow is enforced. Moving is
|
|
only allowed if the move is coming from a tag matching ``*-updates-candidate``
|
|
or ``*-updates-testing``. Conversely, a basic tag operation (not a move) is
|
|
denied if the build also has such a tag (the policy requires a move instead).
|
|
|
|
General format
|
|
==============
|
|
The general form of a basic policy line is one of the following
|
|
|
|
::
|
|
|
|
test [params] [&& test [params] ...] :: action-if-true
|
|
test [params] [&& test [params] ...] !! action-if-false
|
|
|
|
And for nested rules:
|
|
|
|
::
|
|
|
|
test [params] [&& ...] [::|!!] {
|
|
test [params] [&& ...] [::|!!] action
|
|
test [params] [&& ...] [::|!!] {
|
|
...
|
|
}
|
|
}
|
|
|
|
Note that each closing brace must be on a line by itself.
|
|
Using ``!!`` instead of ``::`` negates the entire test.
|
|
Tests can only be joined with &&, the syntax does not support ``||``.
|
|
|
|
Available policies
|
|
==================
|
|
The system currently looks for the following policies
|
|
|
|
* tag : checked during tag/untag/move operations
|
|
* build_from_srpm : checked when a build from srpm (not an SCM reference) is
|
|
requested.
|
|
* build_from_repo_id : checked when a build from a specified repo id is
|
|
requested
|
|
* package_list : checked when the package list for a tag is modified
|
|
* channel : consulted when a task is created
|
|
|
|
These policies are set by assigning a rule set to the given name in the policy
|
|
section.
|
|
|
|
Note that the use of tag policies does not bypass tag locks or permissions
|
|
|
|
Note that an admin can bypass the tag policy by using ``--force``.
|
|
|
|
Actions
|
|
=======
|
|
|
|
Most of the policies are simply allow/deny policies. They have two possible
|
|
actions: ``allow`` or ``deny``.
|
|
|
|
The channel policy is used to determine the channel for a task. It supports
|
|
the following actions:
|
|
|
|
``use <channel>``
|
|
* use the given channel
|
|
|
|
``req``
|
|
* use the requested channel
|
|
* generally this means the default, though some calls allow the client to
|
|
request a channel
|
|
|
|
``parent``
|
|
* use the parent's channel
|
|
* only valid for child tasks
|
|
* recommend using the ``is_child_task`` test to be sure
|
|
|
|
Available tests
|
|
===============
|
|
``true``
|
|
* always true. no arguments
|
|
|
|
``all``
|
|
* an alias of true
|
|
|
|
``false``
|
|
* always false. no arguments
|
|
|
|
``none``
|
|
* an alias of false
|
|
|
|
``operation``
|
|
* for tag operations, the operation is one of: tag, untag, move. This test
|
|
checks its arguments against the name of the operation and returns true if
|
|
there is a match. Accepts glob patterns.
|
|
* only applicable to the tag policy
|
|
|
|
``package``
|
|
* Matches its arguments against the package name. Accepts glob patterns.
|
|
|
|
``tag``
|
|
* matches its arguments against the tag name. Accepts glob patterns.
|
|
* for move operations, the tag name tested is the destination tag (see
|
|
fromtag)
|
|
* for untag operations, the tag name is null and this test will always be
|
|
false (see fromtag)
|
|
* for the build_from_* policies, tests the destination tag for the build
|
|
(which will be null is --skip-tag is used)
|
|
|
|
``fromtag``
|
|
* matches against the tag name that a build is leaving. Accepts glob
|
|
patterns
|
|
* for tag operations, the tag name is null and this test will always be
|
|
false
|
|
* for move operations, the tag name test is the one that the build is
|
|
moving from
|
|
* for untag operations, tests the tag the build is being removed from
|
|
* only applicable to the tag policy
|
|
|
|
``hastag``
|
|
* checks the current tags for the build in question against the arguments.
|
|
|
|
``buildtag``
|
|
|
|
* checks the build tag name against the arguments
|
|
* for the build_from_* policies the build tag is determined by the build
|
|
target requested
|
|
* for the tag policies, determines the build tag from the build data,
|
|
which will by null for imported builds
|
|
|
|
``skip_tag``
|
|
* checks to see if the --skip-tag option was used
|
|
* only applicable to the build_from_* policies
|
|
|
|
``imported``
|
|
* checks to see if the build in question was imported
|
|
* takes no arguments
|
|
* true if any of the component rpms in the build lacks buildroot data
|
|
* only applicable to the tag policy
|
|
|
|
``is_build_owner``
|
|
* Check if requesting user owns the build (not the same as package
|
|
ownership)
|
|
* take no arguments
|
|
|
|
``user_in_group``
|
|
* matches the users groups against the arguments
|
|
* true if user is in /any/ matching group
|
|
|
|
``has_perm``
|
|
* matches the user's permissions against the arguments
|
|
* true is user has /any/ matching permission
|
|
|
|
``source``
|
|
* test the build source against the arguments
|
|
* for the build_from_* policies, this is the source specified for the build
|
|
* for the tag policy, this comes from the task corresponding to the build
|
|
(and will be null for imported builds)
|
|
|
|
``policy``
|
|
* takes a single argument, which is the name of another policy to check
|
|
* checks the named policy. true if the resulting action is one of: yes,
|
|
true, allow
|
|
* additional policies are defined in the [policy] section, just like the
|
|
others
|
|
|
|
``is_new_package``
|
|
* true if the package being added is new to the system
|
|
* intended for use with the package_list policy
|
|
|
|
``is_child_task``
|
|
* true if the task is a child task
|
|
* for use with the channel policy
|
|
|
|
``method``
|
|
* matches the task method name agaist glob pattern(s)
|
|
* true if the method name matches any of the patterns
|
|
* for use with the channel policy
|
|
|
|
``user``
|
|
* checks the username against glob patterns
|
|
* true if any pattern matches
|
|
* the user matched is the user performing the action
|
|
|
|
``match``
|
|
* matches a field in the data against glob patterns
|
|
* true if any pattern matches
|