From bbb3c8d5160c0765ebfd131d3c97e7ac300fa967 Mon Sep 17 00:00:00 2001 From: Sasha Romijn Date: Thu, 11 Nov 2021 15:40:59 +0100 Subject: [PATCH] Add docs for #575 --- docs/admins/configuration.rst | 91 ++++++++++++++++++++++++++++----- docs/releases/4.1.0.rst | 2 +- docs/spelling_wordlist.txt | 3 ++ docs/users/database-changes.rst | 37 ++++++++++++-- 4 files changed, 113 insertions(+), 20 deletions(-) diff --git a/docs/admins/configuration.rst b/docs/admins/configuration.rst index 12317da2c..9db4e5b55 100644 --- a/docs/admins/configuration.rst +++ b/docs/admins/configuration.rst @@ -17,6 +17,7 @@ a key ``roa_source`` under a key ``rpki``. .. contents:: :backlinks: none :local: + :depth: 2 Example configuration file -------------------------- @@ -294,21 +295,21 @@ Email |br| `parent of newly created object(s).` -Authentication -~~~~~~~~~~~~~~ +Authentication and validation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ``auth.override_password``: a salted MD5 hash of the override password, which can be used to override any authorisation requirements for authoritative databases. |br| **Default**: not defined, no override password will be accepted. |br| **Change takes effect**: upon the next update attempt. -* ``auth.authenticate_related_mntners``: whether to check for - :ref:`related object maintainers ` when processing - updates. - |br| **Default**: true, check enabled - |br| **Change takes effect**: upon the next update attempt. * ``auth.gnupg_keyring``: the full path to the gnupg keyring. |br| **Default**: not defined, but required. |br| **Change takes effect**: after full IRRd restart. +* ``auth.authenticate_parents_route_creation``: whether to check for + :ref:`related object maintainers ` when users create + new `route(6)` objects. + |br| **Default**: true, check enabled + |br| **Change takes effect**: upon the next update attempt. .. danger:: @@ -317,6 +318,75 @@ Authentication changes. Therefore, the keyring referred to by ``auth.gnupg_keyring`` can not be simply reset, or PGP authentications may fail. +.. _conf-auth-set-creation: + +auth.set_creation +""""""""""""""""" +The ``auth.set_creation`` setting configures the requirements when creating new +RPSL set objects. These are `as-set`, `filter-set`, `peering-set`, `route-set` +and `rtr-set`. It is highly customisable, but therefore also more complex +than most other settings. + +There are two underlying settings: + +* ``prefix_required`` configures whether an ASN prefix is required in the name + of a set object. When enabled ``AS-EXAMPLE`` is invalid, while + ``AS65537:AS-EXAMPLE`` or ``AS65537:AS-EXAMPLE:AS-CUSTOMERS`` + are valid. +* ``autnum_authentication`` controls whether the user also needs to pass + authentication for the `aut-num` corresponding to the AS number used as the set + name prefix. For example, if the set name is ``AS65537:AS-EXAMPLE:AS-CUSTOMERS``, + this setting may require the creation to also pass authentication for the + `aut-num` AS65537. + The options are ``disabled``, ``opportunistic`` or ``required``. + When disabled, this check is skipped. For opportunistic, the check is used, but + passes if the aut-num does not exist. For required, the check is used and fails + if the aut-num does not exist. + +Note that even when ``autnum_authentication`` is set to ``required``, +if at the same time ``prefix_required`` is set to false, a set can be created +without a prefix or with one, per ``prefix_required``. +But if it has a prefix, there *must* be a corresponding +aut-num object for which authentication *must* pass, per ``autnum_authentication``. + +You can configure one default for all set classes under the key ``DEFAULT``, +and/or specific settings for specific classes using the class name as key. +An example:: + + irrd: + auth: + set_creation: + DEFAULT: + prefix_required: true + autnum_authentication: opportunistic + as-set: + prefix_required: true + autnum_authentication: required + rtr-set: + prefix_required: false + autnum_authentication: disabled + +This example means: + +* New ``as-set`` objects must include an ASN prefix in their name, an `aut-num` + corresponding that AS number must exist, and the user must pass authentication + for that `aut-num` object. +* New ``rtr-set`` objects are not required to include an ASN prefix in their + name, but this is permitted. The user never has to pass authentication for + the corresponding `aut-num` object, regardless of whether it exists. +* All other new set objects must include an ASN prefix in their name + and the user must pass authentication for the corresponding `aut-num` object, + if it exists. If the `aut-num` does not exist, the check passes. + +All checks are only applied when users create new set objects in authoritative +databases. Authoritative updates to existing objects, deletions, or objects from +mirrors are never affected. When looking for corresponding `aut-num` objects, +IRRd only looks in the same IRR source. + +|br| **Default**: TODO +|br| **Change takes effect**: upon the next update attempt. + + Access lists ~~~~~~~~~~~~ @@ -752,13 +822,6 @@ Compatibility See the :doc:`4.2.0 release notes ` for details. |br| **Default**: ``false``, operating normally. |br| **Change takes effect**: after SIGHUP, for all subsequent queries. -* ``compatibility.permit_non_hierarchical_as_set_name``: by default, - `as-set` objects created in authoritative databases are required to have a - hierarchical name, like ``AS65540:AS-CUSTOMERS``. For example, - ``AS-CUSTOMERS`` would not be allowed. If this setting is set to ``true``, - this name requirement does not apply, and ``AS-CUSTOMERS`` is permitted. - |br| **Default**: ``false``, hierarchical name required. - |br| **Change takes effect**: after SIGHUP, for all subsequent updates. * ``compatibility.ipv4_only_route_set_members``: if set to ``true``, ``!i`` queries will not return IPv6 prefixes. This option can be used for limited compatibility with IRRd version 2. Enabling this setting may have a diff --git a/docs/releases/4.1.0.rst b/docs/releases/4.1.0.rst index e981fa62c..502a06c04 100644 --- a/docs/releases/4.1.0.rst +++ b/docs/releases/4.1.0.rst @@ -96,7 +96,7 @@ Other changes for further details. * When users create `route(6)` objects in authoritative databases, IRRd also verifies authorisation from - :ref:`related object maintainers `. This behaviour + :ref:`related object maintainers `. This behaviour is enabled by default, but can be disabled with the ``auth.authenticate_related_mntners`` setting. * The ``!j`` command has changed, and now is exclusively used to check diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 47eb200a1..9a9bcadcb 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -1,5 +1,7 @@ ASes +aut CPython +customisable Escribano IPtables IPv @@ -46,6 +48,7 @@ nginx noreply nrtm ntt +num ov pidfile postgres diff --git a/docs/users/database-changes.rst b/docs/users/database-changes.rst index ba5705c2e..a7e683682 100644 --- a/docs/users/database-changes.rst +++ b/docs/users/database-changes.rst @@ -269,11 +269,13 @@ When you create a new `mntner`, a submission must pass authorisation for one of the auth methods of the new mntner. You can submit other objects that depend on the new `mntner` in the same submission. -.. _auth-related-mntners: +.. _auth-related-mntners-route: +Related maintainers in route objects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When you create new `route(6)` objects, authentication also needs to pass for the parent object. IRRd searches for the parent object in the following -order, only considering the first match: +order, only considering the first match, only looking in the same IRR source: * An `inet(6)num` that is an exact match to the new `route(6)`. * The smallest `inet(6)num` that is a less specific of the new `route(6)`. @@ -282,7 +284,32 @@ order, only considering the first match: If no objects match, there is no parent object, and there are no extra authentication requirements. This behaviour can be disabled by setting -``auth.authenticate_related_mntners`` to false. +``auth.authenticate_parents_route_creation`` to false. +These requirements do not apply when you change or delete existing objects. + +.. _auth-related-mntners-set: + +Related maintainers in set objects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +When you create new set objects, you may need to pass authentication for the +parent `aut-num` object. +RPSL set objects are `as-set`, `filter-set`, `peering-set`, `route-set` and +`rtr-set`. + +The details of this behaviour and the strictness of the checks are +:ref:`configured by the IRR operator `. This may +include a requirement to: + +* Include an ASN prefix in the name of your set, e.g. ``AS65537:AS-EXAMPLE`` + being valid, but ``AS-EXAMPLE`` being invalid. +* Pass authentication for the corresponding `aut-num`, e.g. AS65537 in the + last example, skipping this check if the `aut-num` does not exist. +* Pass authentication for the corresponding `aut-num`, e.g. AS65537 in the + last example, failing this check if the `aut-num` does not exist. + +These requirements do not apply when you change or delete existing objects. +When looking for corresponding `aut-num` objects, +IRRd only looks in the same IRR source. Object templates ---------------- @@ -323,12 +350,12 @@ This template shows: * The `member-of` attribute is a look-up key, meaning it can be used with ``-i`` queries. * The `member-of` attribute references to the `route-set` class. It is a - weak references, meaning the referred `route-set` does not have to exist, + weak reference, meaning the referred `route-set` does not have to exist, but is required to meet the syntax of a `route-set` name. The attribute is also optional, so it can be left out entirely. * The `admin-c` and `tech-c` attributes reference a `role` or `person`. This means they may refer to either object class, but must be a - reference to a valid, existing `person` or `role. This `person` or + reference to a valid, existing `person` or `role`. This `person` or `role` can be created as part of the same submission.