.. _entities-roles:

Roles
=====
A Role represents the permissions :ref:`entities-users` or :ref:`entities-groups`
have to view, manipulate, update and delete domains from the user-facing web interface.

A Role consists of a (list of) :ref:`Server(s) <entities-servers>` and Zones
that Users and Groups with this Role have access to, as well as a list of Permissions.

Configuring access to zones
---------------------------
.. note::
  Domain names must be specified with a trailing dot!

Zones can be specified as either complete domainnames, or wildcards::

  example.com.

This will give the user with this role access to ``example.com``, but not to subdomains.

::

  *.example.org.

This will give the user with this role access to all domains ending with ``.example.org``, excluding ``example.org`` itself.

::

  *

This wildcard gives the user access to all domains on all the Servers it can access.

A Zone that does not match in any of the Roles applied to a User is not shown in the web interface for the user.

Having access does not mean the User is allowed to manipulate the domains,
these permissions can be set in the role.

Allowing access to certain records (RRSets)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 1.1.0

When a :ref:`Role <entities-roles>` has access to a zone, it might
be that it only requires access to a subset of records.
The "website" role, for instance, could only require access to the
A and AAAA records for the domain itself and the 'www'-variant.
In a similar vain, the "mail-admin" roles could only require access to the MX records of a domain.

The syntax to limit the RRSets a Role can access within the Zones it has access to, is similar to the one used for domains.
This syntax is ``domainname/rrtype(s)``, one per line.
For example::

  example.com./A,AAAA
  www.example.com./A,AAAA

Allows this role access to the A and AAAA records for example.com and www.example.com, but nothing more.
When a Role requires access to all MX records of all Zones it can access, the following can be used::

  */MX

RRSets that do not match are not shown in the web interface and can not be created by the role.
When checking the RRSet permissions, when one of the permissions allows the access, it is allowed.

By default, a Role has access to all RRSets in the Zones it can access::

  *

RRSet permission interactions with other permissions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When a Role also has the :ref:`"Restore version" <permissions-restore-version>` permission,
the RRSet permission is **not** checked when restoring.

When the Role has :ref:`"Readonly" <permissions-readonly>` permissions, only the allowed
RRSets are shown. Editing, deleting or adding is still disallowed.

Permissions
-----------
Apart from what Zones and RRSets a Role can see, ZoneControl allows configuration
of **what** can be done with these zones and records.

The following permissions exists for each Role:

.. _permissions-readonly:

Readonly
^^^^^^^^
This permission allows users to only view the Zone contents but not edit them in any way.

Add zones
^^^^^^^^^
This permission allows users to add Zones to the :ref:`entities-servers` they have access to.
When a User attempts to add a Zone, the name of the Zone has to match the domain name(s) in this role.

Delete zones
^^^^^^^^^^^^
Deleting Zones from and Authoritiative Server can lead to unreachability of a domain, depending on the exact DNS infrastructure setup.
This is why this is a special permission.

Change settings
^^^^^^^^^^^^^^^
This permission allows users to edit settings for a Zone. e.g. to change a Zone from Master to Slave, setting AXFR ACLs, Notification settings etcetera.

Change DNSSEC
^^^^^^^^^^^^^
This permission allows the user to enable DNSSEC on a Zone.

.. _permissions-restore-version:

Restore version
^^^^^^^^^^^^^^^
When a user has this permission, it can revert the whole zone to a previous version, discarding all changes to the Zone since that version.

All permissions
^^^^^^^^^^^^^^^
Gives all the above (apart from Readonly) permissions to users with this Role.

.. _permissions-advanced-dnssec:

Advanced DNSSEC
^^^^^^^^^^^^^^^
This permission allows the user to access the "Advanced" tab for zones. Here,
single keys can be created, uploaded, removed, or set (in)active.

Users and Groups with multiple Roles
------------------------------------
Users and Groups can have more than one role assigned. When this is the case,
the most 'open' permission is used.

For instance, when a user has 2 roles configured like this::

  role1:
    Access to Zones:
      - example.com.
    RRSets:
      - */A,AAAA
    Permissions: (None specified)

  role2:
    Access to Zones:
      - example.com.
    RRSets:
      - *
    Permissions:
      - Read Only

The user can see all records in example.com, but can only edit the A and AAAA records
in the zone.
