DISPATCH-990: Document name pattern match feature in old book. Rename and touch up configuration settings to make docs read better.
Project: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/commit/63a56d60 Tree: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/tree/63a56d60 Diff: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/diff/63a56d60 Branch: refs/heads/master Commit: 63a56d6052e747a0043df621a67805989de5d255 Parents: 8712cab Author: Chuck Rolke <[email protected]> Authored: Tue May 15 10:43:44 2018 -0400 Committer: Chuck Rolke <[email protected]> Committed: Tue May 15 10:43:44 2018 -0400 ---------------------------------------------------------------------- doc/book/policy.adoc | 59 ++++++++++++++++++++ python/qpid_dispatch/management/qdrouter.json | 4 +- .../qpid_dispatch_internal/management/config.py | 2 +- src/policy.c | 6 +- tests/system_tests_policy.py | 2 +- 5 files changed, 66 insertions(+), 7 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/63a56d60/doc/book/policy.adoc ---------------------------------------------------------------------- diff --git a/doc/book/policy.adoc b/doc/book/policy.adoc index c2be257..888611c 100644 --- a/doc/book/policy.adoc +++ b/doc/book/policy.adoc @@ -90,6 +90,64 @@ xref:example2[Example 2] illustrates how the default vhost feature can be used to apply a single vhost policy set of restrictions to any number of vhost connections. +=== Vhost Patterns + +Policy vhost names may be interpreted as literal host names or +as host name patterns. Vhost name patterns are a convenience +for letting a single policy rule cover a wide range of vhosts. + +Host name patterns consist of a series of host and domain name +labels and one or more tokens all concatenated with periods or dots. +A token can be one of the following: + +[options="header"] +|==== +| Token character | Match rule +| asterisk * | matches a single hostname label +| hash # | matches zero or more hostname labels +|==== + +Some simple examples show how given policy name patterns match +incoming connection vhost names. + +[options="header"] +|==== +| Policy pattern | Connection vhost | Policy match +| *.example.com | example.com | no +| *.example.com | www.example.com | yes +| *.example.com | srv2.www.example.com | no +| #.example.com | example.com | yes +| #.example.com | www.example.com | yes +| #.example.com | a.b.c.d.example.com | yes +| #.example.com | bighost.com | no +| www.*.test.example.com | www.test.example.com | no +| www.*.test.example.com | www.a.test.example.com | yes +| www.*.test.example.com | www.a.b.c.test.example.com | no +| www.#.test.example.com | www.test.example.com | yes +| www.#.test.example.com | www.a.test.example.com | yes +| www.#.test.example.com | www.a.b.c.test.example.com | yes +|==== + +Pattern matching applies the following precedence rules. + +[options="header"] +|==== +| Policy pattern | Precedence +| exact match | high +| asterisk * | medium +| hash # | low +|==== + +Policy vhost name patterns are optimised before they are used +in connection vhost name matching. As a result of this +optimisation the names stored for pattern match lookups are +not necessarily the same as the patterns specified in the +vhost policy hostname. The policy agent disallows vhost +name patterns that reduce to the same pattern as an existing name +pattern. For instance, name pattern _pass:[#.#.#.#.com]_ is reduced to _pass:[#.com]_. +Attempts to create a vhost name pattern whose optimised +name conflicts with an existing optimised name will be denied. + == Policy Schema Policy configuration is specified in two schema objects. @@ -123,6 +181,7 @@ created as needed. | enableVhostPolicy | false | Enable vhost policy connection denial, and resource limit enforcement. | policyDir | "" | Absolute path to a directory that holds vhost definition .json files. All vhost definitions in all .json files in this directory are processed. | defaultVhost | "$default" | Vhost rule set name to use for connections with a vhost that is otherwise not defined. Default vhost processing may be disabled either by erasing the definition of _defaultVhost_ or by not defining a _vhost_ object named _$default_. +| enableVhostNamePatterns | false | Enable vhost name patterns. When false vhost hostnames are treated as literal strings. When true vhost hostnames are treated as match patterns. |==== === Vhost Policy http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/63a56d60/python/qpid_dispatch/management/qdrouter.json ---------------------------------------------------------------------- diff --git a/python/qpid_dispatch/management/qdrouter.json b/python/qpid_dispatch/management/qdrouter.json index ee8a943..42f501f 100644 --- a/python/qpid_dispatch/management/qdrouter.json +++ b/python/qpid_dispatch/management/qdrouter.json @@ -1678,10 +1678,10 @@ "required": false, "create": true }, - "useVhostNamePatterns": { + "enableVhostNamePatterns": { "type": "boolean", "default": false, - "description": "Use Vhost name patterns.", + "description": "Enable vhost name patterns. When false vhost hostnames are treated as literal strings. When true vhost hostnames are treated as match patterns.", "required": false, "create": true }, http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/63a56d60/python/qpid_dispatch_internal/management/config.py ---------------------------------------------------------------------- diff --git a/python/qpid_dispatch_internal/management/config.py b/python/qpid_dispatch_internal/management/config.py index aad6bd2..82814b5 100644 --- a/python/qpid_dispatch_internal/management/config.py +++ b/python/qpid_dispatch_internal/management/config.py @@ -178,7 +178,7 @@ def configure_dispatch(dispatch, lib_handle, filename): # Configure policy and policy manager before vhosts policyDir = config.by_type('policy')[0]['policyDir'] policyDefaultVhost = config.by_type('policy')[0]['defaultVhost'] - useHostnamePatterns = config.by_type('policy')[0]['useVhostNamePatterns'] + useHostnamePatterns = config.by_type('policy')[0]['enableVhostNamePatterns'] for a in config.by_type("policy"): configure(a) agent.policy.set_default_vhost(policyDefaultVhost) http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/63a56d60/src/policy.c ---------------------------------------------------------------------- diff --git a/src/policy.c b/src/policy.c index 9c99c88..697ec1b 100644 --- a/src/policy.c +++ b/src/policy.c @@ -67,7 +67,7 @@ struct qd_policy_t { int max_connection_limit; char *policyDir; bool enableVhostPolicy; - bool useVhostNamePatterns; + bool enableVhostNamePatterns; // live statistics int connections_processed; int connections_denied; @@ -115,7 +115,7 @@ qd_error_t qd_entity_configure_policy(qd_policy_t *policy, qd_entity_t *entity) policy->policyDir = qd_entity_opt_string(entity, "policyDir", 0); CHECK(); policy->enableVhostPolicy = qd_entity_opt_bool(entity, "enableVhostPolicy", false); CHECK(); - policy->useVhostNamePatterns = qd_entity_opt_bool(entity, "useVhostNamePatterns", false); CHECK(); + policy->enableVhostNamePatterns = qd_entity_opt_bool(entity, "enableVhostNamePatterns", false); CHECK(); qd_log(policy->log_source, QD_LOG_INFO, "Policy configured maxConnections: %d, " "policyDir: '%s'," @@ -124,7 +124,7 @@ qd_error_t qd_entity_configure_policy(qd_policy_t *policy, qd_entity_t *entity) policy->max_connection_limit, policy->policyDir, (policy->enableVhostPolicy ? "true" : "false"), - (policy->useVhostNamePatterns ? "true" : "false")); + (policy->enableVhostNamePatterns ? "true" : "false")); return QD_ERROR_NONE; error: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/63a56d60/tests/system_tests_policy.py ---------------------------------------------------------------------- diff --git a/tests/system_tests_policy.py b/tests/system_tests_policy.py index e2f2797..92555d0 100644 --- a/tests/system_tests_policy.py +++ b/tests/system_tests_policy.py @@ -758,7 +758,7 @@ class PolicyHostamePatternTest(TestCase): config = Qdrouterd.Config([ ('router', {'mode': 'standalone', 'id': 'QDR.Policy8'}), ('listener', {'port': listen_port}), - ('policy', {'maxConnections': 2, 'policyDir': policy_config_path, 'enableVhostPolicy': 'true', 'useVhostNamePatterns': 'true'}) + ('policy', {'maxConnections': 2, 'policyDir': policy_config_path, 'enableVhostPolicy': 'true', 'enableVhostNamePatterns': 'true'}) ]) cls.router = cls.tester.qdrouterd('PolicyVhostNamePatternTest', config, wait=True) --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
