diff --git a/doc/.tx/config b/doc/.tx/config index 81bc05858c5..65eedbc82e8 100644 --- a/doc/.tx/config +++ b/doc/.tx/config @@ -1922,34 +1922,34 @@ file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/ source_file = _build/locale/pot/developer-guide/plugins/example-plugins/basic-authorization/working-with-http-headers.en.pot source_lang = en -[apache-traffic-server-6x.developer-guide--plugins--example-plugins--blacklist--accessing-the-transaction-being-processed_en] -file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/blacklist/accessing-the-transaction-being-processed.en.po -source_file = _build/locale/pot/developer-guide/plugins/example-plugins/blacklist/accessing-the-transaction-being-processed.en.pot +[apache-traffic-server-6x.developer-guide--plugins--example-plugins--denylist--accessing-the-transaction-being-processed_en] +file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/denylist/accessing-the-transaction-being-processed.en.po +source_file = _build/locale/pot/developer-guide/plugins/example-plugins/denylist/accessing-the-transaction-being-processed.en.pot source_lang = en -[apache-traffic-server-6x.developer-guide--plugins--example-plugins--blacklist--index_en] -file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/blacklist/index.en.po -source_file = _build/locale/pot/developer-guide/plugins/example-plugins/blacklist/index.en.pot +[apache-traffic-server-6x.developer-guide--plugins--example-plugins--denylist--index_en] +file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/denylist/index.en.po +source_file = _build/locale/pot/developer-guide/plugins/example-plugins/denylist/index.en.pot source_lang = en -[apache-traffic-server-6x.developer-guide--plugins--example-plugins--blacklist--setting-a-global-hook_en] -file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/blacklist/setting-a-global-hook.en.po -source_file = _build/locale/pot/developer-guide/plugins/example-plugins/blacklist/setting-a-global-hook.en.pot +[apache-traffic-server-6x.developer-guide--plugins--example-plugins--denylist--setting-a-global-hook_en] +file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/denylist/setting-a-global-hook.en.po +source_file = _build/locale/pot/developer-guide/plugins/example-plugins/denylist/setting-a-global-hook.en.pot source_lang = en -[apache-traffic-server-6x.developer-guide--plugins--example-plugins--blacklist--setting-up-a-transaction-hook_en] -file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/blacklist/setting-up-a-transaction-hook.en.po -source_file = _build/locale/pot/developer-guide/plugins/example-plugins/blacklist/setting-up-a-transaction-hook.en.pot +[apache-traffic-server-6x.developer-guide--plugins--example-plugins--denylist--setting-up-a-transaction-hook_en] +file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/denylist/setting-up-a-transaction-hook.en.po +source_file = _build/locale/pot/developer-guide/plugins/example-plugins/denylist/setting-up-a-transaction-hook.en.pot source_lang = en -[apache-traffic-server-6x.developer-guide--plugins--example-plugins--blacklist--source-code_en] -file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/blacklist/source-code.en.po -source_file = _build/locale/pot/developer-guide/plugins/example-plugins/blacklist/source-code.en.pot +[apache-traffic-server-6x.developer-guide--plugins--example-plugins--denylist--source-code_en] +file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/denylist/source-code.en.po +source_file = _build/locale/pot/developer-guide/plugins/example-plugins/denylist/source-code.en.pot source_lang = en -[apache-traffic-server-6x.developer-guide--plugins--example-plugins--blacklist--working-with-http-header-functions_en] -file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/blacklist/working-with-http-header-functions.en.po -source_file = _build/locale/pot/developer-guide/plugins/example-plugins/blacklist/working-with-http-header-functions.en.pot +[apache-traffic-server-6x.developer-guide--plugins--example-plugins--denylist--working-with-http-header-functions_en] +file_filter = locale//LC_MESSAGES/developer-guide/plugins/example-plugins/denylist/working-with-http-header-functions.en.po +source_file = _build/locale/pot/developer-guide/plugins/example-plugins/denylist/working-with-http-header-functions.en.pot source_lang = en [apache-traffic-server-6x.developer-guide--plugins--example-plugins--query-remap--example-query-remap_en] diff --git a/doc/admin-guide/configuration/proxy-protocol.en.rst b/doc/admin-guide/configuration/proxy-protocol.en.rst index cc924062a31..8df27d1eed0 100644 --- a/doc/admin-guide/configuration/proxy-protocol.en.rst +++ b/doc/admin-guide/configuration/proxy-protocol.en.rst @@ -44,12 +44,12 @@ Proxy Protocol on a port. Once enabled, all incoming requests must be prefaced with the PROXY v1 header. Any request not preface by this header will be dropped. -As a security measure, an optional whitelist of trusted IP addresses may be +As a security measure, an optional list of trusted IP addresses may be configured with :ts:cv:`proxy.config.http.proxy_protocol_allowlist`. .. important:: - If the whitelist is configured, requests will only be accepted from these + If the allowlist is configured, requests will only be accepted from these IP addresses and must be prefaced with the PROXY v1 header. See :ts:cv:`proxy.config.http.insert_forwarded` for configuration information. diff --git a/doc/admin-guide/plugins/cachekey.en.rst b/doc/admin-guide/plugins/cachekey.en.rst index 8ca153d10c3..406256f5cf1 100644 --- a/doc/admin-guide/plugins/cachekey.en.rst +++ b/doc/admin-guide/plugins/cachekey.en.rst @@ -122,8 +122,8 @@ Cache key structure and related plugin parameters * ``User-Agent`` classification * ``--ua-allowlist=:`` (default: empty string) - loads a regex patterns list from a file ````, the patterns are matched against the ``User-Agent`` header and if matched ```` is added it to the key. - * ``--ua-blocklist=:`` (default: empty string) - loads a regex patterns list from a file ````, the patterns are matched against the ``User-Agent`` header and if **not** matched ```` is added it to the key. - * Multiple ``--ua-allowlist`` and ``--ua-blocklist`` can be used and the result will be defined by their order in the plugin configuration. + * ``--ua-denylist=:`` (default: empty string) - loads a regex patterns list from a file ````, the patterns are matched against the ``User-Agent`` header and if **not** matched ```` is added it to the key. + * Multiple ``--ua-allowlist`` and ``--ua-denylist`` can be used and the result will be defined by their order in the plugin configuration. * ``User-Agent`` regex capturing and replacement * ``--ua-capture=`` (default: empty string) - if specified and not empty then strings are captured from the ``User-Agent`` header based on ```` (see below) and are added to the `cache key`. * If any ``User-Agent`` classification and regex capturing and replacement plugin parameters are used together they are added to the `cache key` in the order shown in the diagram. @@ -179,10 +179,10 @@ Cache key structure and related plugin parameters ^^^^^^^^^^^^^^^ * If no query related plugin parameters are used, the query string is included in the `cache key`. -* ``--exclude-params`` (default: empty list) - comma-separated list of query params to be black-listed in the `cache key`. If the list is empty then no black-list is applied (no query parameters will be excluded from the `cache key`). The exclude list overrides the include list. -* ``--include-params`` (default: empty list) - comma-separated list of query params to be white-listed in the `cache key`. If the list is empty then no white-list is applied (all query parameters will be included in the `cache key`). -* ``--include-match-params`` (default: empty list) - regular expression matching query parameter names which will be white-listed in the `cache key`. -* ``--exclude-match-params`` (default: empty list) - regular expression matching query parameter names which will be black-listed in the `cache key`. +* ``--exclude-params`` (default: empty list) - comma-separated list of query params to be excluded in the `cache key`. If the list is empty then no exlusions are applied (no query parameters will be excluded from the `cache key`). The exclude list overrides the include list. +* ``--include-params`` (default: empty list) - comma-separated list of query params to be allow-listed in the `cache key`. If the list is empty then no allow-list is applied (all query parameters will be included in the `cache key`). +* ``--include-match-params`` (default: empty list) - regular expression matching query parameter names which will be allowed in the `cache key`. +* ``--exclude-match-params`` (default: empty list) - regular expression matching query parameter names which will be excluded in the `cache key`. * ``--remove-all-params`` (boolean:``true|false``, ``0|1``, ``yes|no``, default: ``false``) - if equals ``true`` then all query parameters are removed (the whole query string) and all other URI query parameter related settings (if used) will have no effect. * ``--sort-params`` (boolean:``true|false``, ``0|1``, ``yes|no``, default: ``false``) - if equals ``true`` then all query parameters are sorted in an increasing case-sensitive order @@ -377,7 +377,7 @@ The following will make sure only query parameters ``a`` and ``c`` will be used If the URI has the following query string ``c=1&a=1&b=2&x=1&k=1&u=1&y=1`` the `cache key` will use ``c=1&a=1`` -White-list + black-list certain parameters using multiple parameters in the same remap rule. +Include and exclude certain parameters using multiple parameters in the same remap rule. """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" If the plugin is used with the following plugin parameters in the remap rule: :: @@ -390,7 +390,7 @@ If the plugin is used with the following plugin parameters in the remap rule: :: and if the URI has the following query string ``c=1&a=1&b=2&x=1&k=1&u=1&y=1`` the `cache key` will use ``c=1&b=1`` -White-list + black-list certain parameters using multiple parameters in the same remap rule and regular expressions (PCRE). +Include and exclude certain parameters using multiple parameters in the same remap rule and regular expressions (PCRE). """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" If the plugin is used with the following plugin parameters in the remap rule: :: @@ -570,7 +570,7 @@ If the plugin is used with the following plugin parameter:: then ``Mozilla/5.0_AppleWebKit/537.75.14`` will be used when constructing the key. -User-Agent white-list classifier +User-Agent allow-list classifier """""""""""""""""""""""""""""""" If the plugin is used with the following plugin parameter:: @@ -585,12 +585,12 @@ and if ``browser_agents.config`` contains: :: then ``browser`` will be used when constructing the key. -User-Agent black-list classifier +User-Agent deny-list classifier """""""""""""""""""""""""""""""" If the plugin is used with the following plugin parameter:: @plugin=cachekey.so \ - @pparam=--ua-blacklist=browser:tool_agents.config + @pparam=--ua-denylist=browser:tool_agents.config and if ``tool_agents.config`` contains: :: diff --git a/doc/admin-guide/plugins/stats_over_http.en.rst b/doc/admin-guide/plugins/stats_over_http.en.rst index bcea100c1ac..d09a4a0b878 100644 --- a/doc/admin-guide/plugins/stats_over_http.en.rst +++ b/doc/admin-guide/plugins/stats_over_http.en.rst @@ -88,16 +88,16 @@ This sets the path value for stats .. option:: allow_ip= -A comma separated white list of ipv4 addresses allowed to access the endpoint +A comma separated list of IPv4 addresses allowed to access the endpoint .. option:: allow_ip6= -A comma separated white list of ipv6 addresses allowed to access the endpoint +A comma separated list of IPv6 addresses allowed to access the endpoint Output Format ============= -By default stats_over_http.so will output all the stats in json format. However +By default stats_over_http.so will output all the stats in JSON format. However if you wish to have it in CSV format you can do so by passing an ``Accept`` header: .. option:: Accept: text/csv diff --git a/doc/developer-guide/api/functions/TSAPI.en.rst b/doc/developer-guide/api/functions/TSAPI.en.rst index b47d0ec1136..e8c06fd4cc5 100644 --- a/doc/developer-guide/api/functions/TSAPI.en.rst +++ b/doc/developer-guide/api/functions/TSAPI.en.rst @@ -59,11 +59,11 @@ type. Possible uses for plugins include the following: -* HTTP processing plugins can filter, blacklist, authorize users or transform content. +* HTTP processing plugins can filter, denylist, authorize users or transform content. * Protocol plugins can enable Traffic Server to proxy-cache new protocol content. -* A blacklisting plugin denies attempts to access web sites that are off-limits. +* A denylisting plugin denies attempts to access web sites that are off-limits. * Append transform plugins add data to HTTP response content. diff --git a/doc/developer-guide/introduction/index.en.rst b/doc/developer-guide/introduction/index.en.rst index 19c43814efb..0cfdc140db2 100644 --- a/doc/developer-guide/introduction/index.en.rst +++ b/doc/developer-guide/introduction/index.en.rst @@ -53,7 +53,7 @@ Below is a section-by-section breakdown of this guide: How to compile and load plugins. Walks through a simple "hello world" example; explains how to initialize and register plugins. Basic structures that all plugins use: events, continuations, and how to hook on to |TS| - processes. Detailed explication of a sample blacklisting plugin. + processes. Detailed explication of a sample denylisting plugin. :ref:`developer-plugins-examples-query-remap` This chapter demonstrates on a practical example how you can @@ -61,7 +61,7 @@ Below is a section-by-section breakdown of this guide: :ref:`developer-plugins-header-based-examples` Detailed explanation about writing plugins that work on HTTP - headers; discusses sample blacklisting and basic authorization + headers; discusses sample denylisting and basic authorization plugins. :ref:`developer-plugins-http-transformations` diff --git a/doc/developer-guide/plugins/example-plugins/blacklist/accessing-the-transaction-being-processed.en.rst b/doc/developer-guide/plugins/example-plugins/denylist/accessing-the-transaction-being-processed.en.rst similarity index 91% rename from doc/developer-guide/plugins/example-plugins/blacklist/accessing-the-transaction-being-processed.en.rst rename to doc/developer-guide/plugins/example-plugins/denylist/accessing-the-transaction-being-processed.en.rst index 46d2a54a41d..9742418be6f 100644 --- a/doc/developer-guide/plugins/example-plugins/blacklist/accessing-the-transaction-being-processed.en.rst +++ b/doc/developer-guide/plugins/example-plugins/denylist/accessing-the-transaction-being-processed.en.rst @@ -17,7 +17,7 @@ .. include:: ../../../../common.defs -.. _developer-plugins-blacklist-access-process-txn: +.. _developer-plugins-denylist-access-process-txn: Accessing the Transaction Being Processed ***************************************** @@ -38,12 +38,12 @@ The key here is that if the event is an HTTP transaction event, then the data passed to the continuation's handler is of type ``TSHttpTxn`` (a data type that represents HTTP transactions). Your plugin can then do things with the transaction. Here's how it looks in the code for the -Blacklist plugin's handler: +Denylist plugin's handler: .. code-block:: c static int - blacklist_plugin (TSCont contp, TSEvent event, void *edata) + denylist_plugin (TSCont contp, TSEvent event, void *edata) { TSHttpTxn txnp = (TSHttpTxn) edata; switch (event) { @@ -60,5 +60,5 @@ Blacklist plugin's handler: } For example: when the origin server DNS lookup event is sent, -``blacklist_plugin`` can call ``handle_dns``\ and pass ``txnp`` as an +``denylist_plugin`` can call ``handle_dns``\ and pass ``txnp`` as an argument. diff --git a/doc/developer-guide/plugins/example-plugins/blacklist/index.en.rst b/doc/developer-guide/plugins/example-plugins/denylist/index.en.rst similarity index 75% rename from doc/developer-guide/plugins/example-plugins/blacklist/index.en.rst rename to doc/developer-guide/plugins/example-plugins/denylist/index.en.rst index b88c3f288fc..e45ed39f100 100644 --- a/doc/developer-guide/plugins/example-plugins/blacklist/index.en.rst +++ b/doc/developer-guide/plugins/example-plugins/denylist/index.en.rst @@ -17,21 +17,21 @@ .. include:: ../../../../common.defs -.. _developer-plugins-examples-blacklist: +.. _developer-plugins-examples-denylist: -Blacklist Plugin +Denylist Plugin **************** -The sample blacklisting plugin included in the Traffic Server SDK is -``blacklist_1.c``. This plugin checks every incoming HTTP client request -against a list of blacklisted web sites. If the client requests a -blacklisted site, then the plugin returns an ``Access forbidden`` +The sample denylisting plugin included in the Traffic Server SDK is +``denylist_1.c``. This plugin checks every incoming HTTP client request +against a list of listed web sites. If the client requests a +listed site, then the plugin returns an ``Access forbidden`` message to the client. -The flow of HTTP processing with the blacklist plugin is illustrated in -the figure titled :ref:`BlackListPlugin`. +The flow of HTTP processing with the denylist plugin is illustrated in +the figure titled :ref:`DenyListPlugin`. This example also contains a simple configuration management interface. -It can read a list of blacklisted sites from a file (``blacklist.txt``) +It can read a list of sites from a file (``denylist.txt``) that can be updated by a Traffic Server administrator. When the configuration file is updated, Traffic Server sends an event to the plugin that wakes it up to do some work. @@ -52,7 +52,7 @@ Traffic Server has a multi-threaded design, race conditions can occur if several threads try to access the same continuation's data. Here is how the static parent continuation is created in -``blacklist_1.c``: +``denylist_1.c``: .. code-block:: c @@ -62,20 +62,20 @@ Here is how the static parent continuation is created in // ... TSCont contp; - contp = TSContCreate (blacklist_plugin, NULL); + contp = TSContCreate (denylist_plugin, NULL); // ... } -The handler function for the plugin is ``blacklist_plugin``, and the +The handler function for the plugin is ``denylist_plugin``, and the mutex is null. The continuation handler function's job is to handle the -events that are sent to it; accordingly, the ``blacklist_plugin`` +events that are sent to it; accordingly, the ``denylist_plugin`` routine consists of a switch statement that covers each of the events that might be sent to it: .. code-block:: c static int - blacklist_plugin (TSCont contp, TSEvent event, void *edata) + denylist_plugin (TSCont contp, TSEvent event, void *edata) { TSHttpTxn txnp = (TSHttpTxn) edata; switch (event) { @@ -86,7 +86,7 @@ that might be sent to it: handle_response (txnp); return 0; default: - TSDebug ("blacklist_plugin", "This event was unexpected: %d", ); + TSDebug ("denylist_plugin", "This event was unexpected: %d", ); break; } return 0; @@ -94,10 +94,10 @@ that might be sent to it: When you write handler functions, you have to anticipate any events that might be sent to the handler by hooks or by other functions. In the -Blacklist plugin, ``TS_EVENT_OS_DNS`` is sent because of the global hook +Denylist plugin, ``TS_EVENT_OS_DNS`` is sent because of the global hook established in ``TSPluginInit``, ``TS_EVENT_HTTP_SEND_RESPONSE_HDR`` is sent because the plugin contains a transaction hook -(see :ref:`developer-plugins-examples-blacklist-txn-hook`). +(see :ref:`developer-plugins-examples-denylist-txn-hook`). It is good practice to have a default case in your switch statements. .. toctree:: diff --git a/doc/developer-guide/plugins/example-plugins/blacklist/setting-a-global-hook.en.rst b/doc/developer-guide/plugins/example-plugins/denylist/setting-a-global-hook.en.rst similarity index 86% rename from doc/developer-guide/plugins/example-plugins/blacklist/setting-a-global-hook.en.rst rename to doc/developer-guide/plugins/example-plugins/denylist/setting-a-global-hook.en.rst index e471b1c5d2d..d095dcd2b19 100644 --- a/doc/developer-guide/plugins/example-plugins/blacklist/setting-a-global-hook.en.rst +++ b/doc/developer-guide/plugins/example-plugins/denylist/setting-a-global-hook.en.rst @@ -23,7 +23,7 @@ Setting a Global Hook Global hooks are always added in ``TSPluginInit`` using ``TSHttpHookAdd``. The two arguments of ``TSHttpHookAdd`` are the hook ID and the continuation to call when processing the event corresponding -to the hook. In ``blacklist_1.c``, the global hook is added as follows: +to the hook. In ``denylist_1.c``, the global hook is added as follows: .. code-block:: c @@ -32,7 +32,7 @@ to the hook. In ``blacklist_1.c``, the global hook is added as follows: Above, ``TS_HTTP_OS_DNS_HOOK`` is the ID for the origin server DNS lookup hook and ``contp`` is the parent continuation created earlier. -This means that the Blacklist plugin is called at every origin server -DNS lookup. When it is called, the handler functio ``blacklist_plugin`` +This means that the Denylist plugin is called at every origin server +DNS lookup. When it is called, the handler functio ``denylist_plugin`` receives ``TS_EVENT_HTTP_OS_DNS`` and calls ``handle_dns`` to see if the request is forbidden. diff --git a/doc/developer-guide/plugins/example-plugins/blacklist/setting-up-a-transaction-hook.en.rst b/doc/developer-guide/plugins/example-plugins/denylist/setting-up-a-transaction-hook.en.rst similarity index 82% rename from doc/developer-guide/plugins/example-plugins/blacklist/setting-up-a-transaction-hook.en.rst rename to doc/developer-guide/plugins/example-plugins/denylist/setting-up-a-transaction-hook.en.rst index 7f89d31c054..10ad8511d34 100644 --- a/doc/developer-guide/plugins/example-plugins/blacklist/setting-up-a-transaction-hook.en.rst +++ b/doc/developer-guide/plugins/example-plugins/denylist/setting-up-a-transaction-hook.en.rst @@ -17,16 +17,16 @@ .. include:: ../../../../common.defs -.. _developer-plugins-examples-blacklist-txn-hook: +.. _developer-plugins-examples-denylist-txn-hook: Setting Up a Transaction Hook ***************************** -The Blacklist plugin sends "access forbidden" messages to clients if -their requests are directed to blacklisted hosts. Therefore, the plugin +The Denylist plugin sends "access forbidden" messages to clients if +their requests are directed to listed hosts. Therefore, the plugin needs a transaction hook so it will be called back when Traffic Server's HTTP state machine reaches the "send response header" event. In the -Blacklist plugin's ``handle_dns`` routine, the transaction hook is added +Denylist plugin's ``handle_dns`` routine, the transaction hook is added as follows: .. code-block:: c @@ -34,7 +34,7 @@ as follows: TSMutexLock (sites_mutex); for (i = 0; i < nsites; i++) { if (strncmp (host, sites[i], host_length) == 0) { - printf ("blacklisting site: %s\n", sites[i]); + printf ("denylisting site: %s\n", sites[i]); TSHttpTxnHookAdd (txnp, TS_HTTP_SEND_RESPONSE_HDR_HOOK, contp); @@ -50,10 +50,10 @@ as follows: TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE); This code fragment shows some interesting features. The plugin is -comparing the requested site to the list of blacklisted sites. While the -plugin is using the blacklist, it must acquire the mutex lock for the -blacklist to prevent configuration changes in the middle of a -blacklisting operation. If the requested site is blacklisted, then the +comparing the requested site to the list of listed sites. While the +plugin is using the denylist, it must acquire the mutex lock for the +denylist to prevent configuration changes in the middle of a +denylisting operation. If the requested site is listed, then the following things happen: #. A transaction hook is added with ``TSHttpTxnHookAdd``; the plugin is @@ -66,7 +66,7 @@ following things happen: ``TS_EVENT_HTTP_ERROR`` as its event argument. Reenabling with an error event tells the HTTP state machine to stop the transaction and jump to the "send response header" state. Notice that if the - requested site is not blacklisted, then the transaction is reenabled + requested site is not listed, then the transaction is reenabled with the ``TS_EVENT_HTTP_CONTINUE`` event. #. The string and ``TSMLoc`` data stored in the marshal buffer ``bufp`` is diff --git a/doc/developer-guide/plugins/example-plugins/blacklist/source-code.en.rst b/doc/developer-guide/plugins/example-plugins/denylist/source-code.en.rst similarity index 72% rename from doc/developer-guide/plugins/example-plugins/blacklist/source-code.en.rst rename to doc/developer-guide/plugins/example-plugins/denylist/source-code.en.rst index 0be18042423..b6c828de348 100644 --- a/doc/developer-guide/plugins/example-plugins/blacklist/source-code.en.rst +++ b/doc/developer-guide/plugins/example-plugins/denylist/source-code.en.rst @@ -17,20 +17,20 @@ .. include:: ../../../../common.defs -.. _developer-plugins-examples-blacklist-code: +.. _developer-plugins-examples-denylist-code: Sample Source Code ****************** -.. _blacklist-1.c: +.. _denylist-1.c: -blacklist_1.c +denylist_1.c ------------- -The sample blacklisting plugin included in the Traffic Server SDK is -``blacklist_1.c``. This plugin checks every incoming HTTP client request -against a list of blacklisted web sites. If the client requests a -blacklisted site, then the plugin returns an ``Access forbidden`` +The sample denylisting plugin included in the Traffic Server SDK is +``denylist_1.c``. This plugin checks every incoming HTTP client request +against a list of web sites. If the client requests a +listed site, then the plugin returns an ``Access forbidden`` message to the client. This plugin illustrates: @@ -43,5 +43,5 @@ This plugin illustrates: - How to use the plugin configuration management interface -.. literalinclude:: ../../../../../example/plugins/c-api/blacklist_1/blacklist_1.c +.. literalinclude:: ../../../../../example/plugins/c-api/denylist_1/denylist_1.c :language: c diff --git a/doc/developer-guide/plugins/example-plugins/blacklist/working-with-http-header-functions.en.rst b/doc/developer-guide/plugins/example-plugins/denylist/working-with-http-header-functions.en.rst similarity index 86% rename from doc/developer-guide/plugins/example-plugins/blacklist/working-with-http-header-functions.en.rst rename to doc/developer-guide/plugins/example-plugins/denylist/working-with-http-header-functions.en.rst index 5d394606306..baa678f1da5 100644 --- a/doc/developer-guide/plugins/example-plugins/blacklist/working-with-http-header-functions.en.rst +++ b/doc/developer-guide/plugins/example-plugins/denylist/working-with-http-header-functions.en.rst @@ -17,12 +17,12 @@ .. include:: ../../../../common.defs -.. _developer-plugins-examples-blacklist-http-header-functions: +.. _developer-plugins-examples-denylist-http-header-functions: Working with HTTP Header Functions ********************************** -The Blacklist plugin examines the host header in every client +The Denylist plugin examines the host header in every client transaction. This is done in the ``handle_dns`` routine, using ``TSHttpTxnClientReqGet``, ``TSHttpHdrUrlGet``, and ``TSUrlHostGet``. @@ -39,19 +39,19 @@ transaction. This is done in the ``handle_dns`` routine, using int host_length; if (TSHttpTxnClientReqGet(txnp, &bufp, &hdr_loc) != TS_SUCCESS) { - TSError("[blacklist] Couldn't retrieve client request header"); + TSError("[denylist] Couldn't retrieve client request header"); goto done; } if (TSHttpHdrUrlGet(bufp, hdr_loc, &url_loc) != TS_SUCCESS) { - TSError("[blacklist] Couldn't retrieve request url"); + TSError("[denylist] Couldn't retrieve request url"); TSHandleMLocRelease(bufp, TS_NULL_MLOC, hdr_loc); goto done; } host = TSUrlHostGet(bufp, url_loc, &host_length); if (!host) { - TSError("[blacklist] couldn't retrieve request hostname"); + TSError("[denylist] couldn't retrieve request hostname"); TSHandleMLocRelease(bufp, hdr_loc, url_loc); TSHandleMLocRelease(bufp, TS_NULL_MLOC, hdr_loc); goto done; diff --git a/doc/developer-guide/plugins/example-plugins/index.en.rst b/doc/developer-guide/plugins/example-plugins/index.en.rst index 7da4a35ee69..f9b740d3201 100644 --- a/doc/developer-guide/plugins/example-plugins/index.en.rst +++ b/doc/developer-guide/plugins/example-plugins/index.en.rst @@ -26,7 +26,7 @@ Example Plugins :maxdepth: 2 basic-authorization/index.en - blacklist/index.en + denylist/index.en query_remap/index.en tls_bridge.en @@ -47,7 +47,7 @@ understand the following topics: - Working with HTTP header functions -The two sample plugins discussed in this chapter are ``blacklist_1.c`` +The two sample plugins discussed in this chapter are ``denylist_1.c`` and ``basic_auth.c``. To build and install the example plugins use :: ./configure --enable-example-plugins diff --git a/doc/developer-guide/plugins/getting-started/index.en.rst b/doc/developer-guide/plugins/getting-started/index.en.rst index b4a482feddf..f300673e0cc 100644 --- a/doc/developer-guide/plugins/getting-started/index.en.rst +++ b/doc/developer-guide/plugins/getting-started/index.en.rst @@ -93,7 +93,7 @@ Possible Uses for Plugins Possible uses for plugins include the following: -- HTTP processing: plugins can filter, blacklist, authorize users, +- HTTP processing: plugins can filter, deny access, authorize users, transform content - Protocol support: plugins can enable Traffic Server to proxy-cache @@ -101,7 +101,7 @@ Possible uses for plugins include the following: Some examples of plugins include: -- **Blacklisting plugin**: denies attempts to access web sites that are +- **Denylisting plugin**: denies attempts to access web sites that are off-limits. - **Append transform plugin**: adds text to HTTP response content. @@ -151,9 +151,9 @@ You can find basic examples for many plugins in the SDK sample code: - ``basic_auth.c`` performs basic HTTP proxy authorization. -- ``blacklist_1.c`` reads blacklisted servers from a configuration file +- ``denylist_1.c`` reads a list of servers from a configuration file and denies client access to these servers. This plugin is explained - in :ref:`developer-plugins-examples-blacklist`. + in :ref:`developer-plugins-examples-denylist`. Plugin Loading -------------- diff --git a/doc/developer-guide/plugins/hooks-and-transactions/adding-hooks.en.rst b/doc/developer-guide/plugins/hooks-and-transactions/adding-hooks.en.rst index e6174314723..aca6268bd57 100644 --- a/doc/developer-guide/plugins/hooks-and-transactions/adding-hooks.en.rst +++ b/doc/developer-guide/plugins/hooks-and-transactions/adding-hooks.en.rst @@ -33,7 +33,7 @@ There are several ways to add hooks to your plugin. - **Transaction hooks** Transaction hooks can be used to call plugins back for a specific HTTP transaction. You cannot add transaction hooks in ``TSPluginInit``; you first need a handle to a transaction. - See :ref:`developer-plugins-blacklist-access-process-txn`. + See :ref:`developer-plugins-denylist-access-process-txn`. - **Transformation hooks** Transformation hooks are a special case of transaction hooks. See @@ -80,7 +80,7 @@ values for ``TSHttpHookID`` are: Called immediately after the HTTP state machine has completed a DNS lookup of the origin server. The HTTP state machine will know the origin server's IP address at this point, which is useful for - performing both authentication and blacklisting. Corresponds to the + performing both authentication and denylisting. Corresponds to the event ``TS_EVENT_HTTP_OS_DNS``. ``TS_HTTP_POST_REMAP_HOOK`` diff --git a/doc/developer-guide/plugins/http-headers/trafficserver-http-header-system.en.rst b/doc/developer-guide/plugins/http-headers/trafficserver-http-header-system.en.rst index 6af66bcc633..938f24c850a 100644 --- a/doc/developer-guide/plugins/http-headers/trafficserver-http-header-system.en.rst +++ b/doc/developer-guide/plugins/http-headers/trafficserver-http-header-system.en.rst @@ -42,7 +42,7 @@ passed into the common ``str*()`` routines Values returned from a marshall buffer can be ``NULL``, which means the field or object requested does not exist. -For example (from the ``blacklist_1`` sample) +For example (from the ``denylist_1`` sample) .. code-block:: c diff --git a/doc/developer-guide/plugins/introduction.en.rst b/doc/developer-guide/plugins/introduction.en.rst index 58aaf32860d..1a17043fdf5 100644 --- a/doc/developer-guide/plugins/introduction.en.rst +++ b/doc/developer-guide/plugins/introduction.en.rst @@ -173,7 +173,7 @@ them into activity. A plugin may consist of just one static continuation that is called whenever certain events happen. Examples of such plugins include -``blacklist_1.c``, ``basic_auth.c``, and ``redirect_1.c``. +``denylist_1.c``, ``basic_auth.c``, and ``redirect_1.c``. Alternatively, a plugin might dynamically create other continuations as needed. Transform plugins are built in this manner: a static parent continuation checks all transactions to see if any are transformable; @@ -266,35 +266,35 @@ reflects the Traffic Server state that was *just completed*. For example, the "OS DNS lookup" hook wakes up a plugin right *after* the origin server DNS lookup. For a plugin that requires the IP address of the requested origin server, this hook is the right one to use. The -Blacklist plugin works in this manner, as shown in the :ref:`BlackListPlugin` +Denylist plugin works in this manner, as shown in the :ref:`DenyListPlugin` diagram below. -**Blacklist Plugin** +**Denylist Plugin** -.. _BlackListPlugin: +.. _DenyListPlugin: -.. figure:: /static/images/sdk/blacklist75.jpg - :alt: Blacklist Plugin +.. figure:: /static/images/sdk/denylist.jpg + :alt: Denylist Plugin - Blacklist Plugin + Denylist Plugin -Traffic Server calls the Blacklist plugin right after the origin server +Traffic Server calls the Denylist plugin right after the origin server DNS lookup. The plugin checks the requested host against a list of -blacklisted servers; if the request is allowed, then the transaction -proceeds. If the host is forbidden, then the Blacklist plugin sends the +denylisted servers; if the request is allowed, then the transaction +proceeds. If the host is forbidden, then the Denylist plugin sends the transaction into an error state. When the HTTP state machine gets to the -"send reply header" state, it then calls the Blacklist plugin to provide +"send reply header" state, it then calls the Denylist plugin to provide the error message that's sent to the client. Types of Hooks ^^^^^^^^^^^^^^ -The Blacklist plugin's hook to the origin server DNS lookup state is a *global +The Denylist plugin's hook to the origin server DNS lookup state is a *global hook*, meaning that the plugin is called every time there's an HTTP transaction with a DNS lookup event. The plugin's hook to the send reply header state is a *transaction hook*, meaning that this hook is only invoked for specified -transactions (in the :ref:`developer-plugins-examples-blacklist` example, it's -only used for requests to blacklisted servers). Several examples of setting up +transactions (in the :ref:`developer-plugins-examples-denylist` example, it's +only used for requests to denylisted servers). Several examples of setting up hooks are provided in :ref:`developer-plugins-header-based-examples` and :ref:`developer-plugins-http-transformations`. diff --git a/doc/developer-guide/plugins/mutexes.en.rst b/doc/developer-guide/plugins/mutexes.en.rst index 6c63c0d053a..ae59e41ea98 100644 --- a/doc/developer-guide/plugins/mutexes.en.rst +++ b/doc/developer-guide/plugins/mutexes.en.rst @@ -71,12 +71,12 @@ by other continuations). Locking Global Data =================== -The :ref:`blacklist-1.c` sample plugin implements a mutex that locks global -data. The blacklist plugin reads its blacklisted sites from a +The :ref:`denylist-1.c` sample plugin implements a mutex that locks global +data. The denylist plugin reads sites to be denied from a configuration file; file read operations are protected by a mutex -created in :c:func:`TSPluginInit`. The :ref:`blacklist-1.c` code uses +created in :c:func:`TSPluginInit`. The :ref:`denylist-1.c` code uses :c:func:`TSMutexLockTry` instead of :c:func:`TSMutexLock`. For more detailed -information, see the :ref:`blacklist-1.c` code; +information, see the :ref:`denylist-1.c` code; start by looking at the :c:func:`TSPluginInit` function. General guidelines for locking shared data are as follows: @@ -368,7 +368,7 @@ continuation created in ``txn_handler``: TSCont newCont; .... newCont = TSContCreate (newCont_handler, NULL); - //It's not necessary to create a new mutex for newCont. + // It's not necessary to create a new mutex for newCont. ... diff --git a/doc/developer-guide/plugins/plugin-management/logging-api.en.rst b/doc/developer-guide/plugins/plugin-management/logging-api.en.rst index 0ce902b2985..013d39e6f81 100644 --- a/doc/developer-guide/plugins/plugin-management/logging-api.en.rst +++ b/doc/developer-guide/plugins/plugin-management/logging-api.en.rst @@ -58,8 +58,8 @@ The logging API enables you to: :c:func:`TSTextLogObjectDestroy` The steps below show how the logging API is used in the -``blacklist_1.c`` sample plugin. For the complete source code, see the -:ref:`developer-plugins-examples-blacklist-code` section. +``denylist_1.c`` sample plugin. For the complete source code, see the +:ref:`developer-plugins-examples-denylist-code` section. #. A new log file is defined as a global variable. @@ -71,10 +71,10 @@ The steps below show how the logging API is used in the .. code-block:: c - TSReturnCode error = TSTextLogObjectCreate("blacklist", + TSReturnCode error = TSTextLogObjectCreate("denylist", TS_LOG_MODE_ADD_TIMESTAMP, &log); - The new log is named ``blacklist.log``. Each entry written to the log + The new log is named ``denylist.log``. Each entry written to the log will have a timestamp. The ``NULL`` argument specifies that the new log does not have a log header. The error argument stores the result of the log creation; if the log is created successfully, then an @@ -86,11 +86,11 @@ The steps below show how the logging API is used in the .. code-block:: c if (error != TS_SUCCESS) { - printf("Blacklist plugin: error %d while creating log\n", error); + printf("denylist plugin: error %d while creating log\n", error); } -#. The :ref:`developer-plugins-examples-blacklist` matches the host portion of - the URL (in each client request) with a list of blacklisted sites (stored in +#. The :ref:`developer-plugins-examples-denylist` matches the host portion of + the URL (in each client request) with a list of denylisted sites (stored in the array ``sites[]``): .. code-block:: c @@ -101,23 +101,23 @@ The steps below show how the logging API is used in the } } - If the host matches one of the blacklisted - sites (such as ``sites[i]``), then the plugin writes a blacklist - entry to ``blacklist.log``: + If the host matches one of the denylisted + sites (such as ``sites[i]``), then the plugin writes a denylist + entry to ``denylist.log``: .. code-block:: c - if (log) { TSTextLogObjectWrite(log, "blacklisting site: %s", + if (log) { TSTextLogObjectWrite(log, "denylisting site: %s", sites[i]); The format of the log entry is as follows: :: - blacklisting site: sites[i] + denylisting site: sites[i] The log is not flushed or - destroyed in the ``blacklist_1`` plugin - it lives for the life of + destroyed in the ``denylist_1`` plugin - it lives for the life of the plugin. diff --git a/doc/static/images/sdk/blacklist75.jpg b/doc/static/images/sdk/denylist.jpg similarity index 77% rename from doc/static/images/sdk/blacklist75.jpg rename to doc/static/images/sdk/denylist.jpg index 880c32cb356..c2a990ea328 100644 Binary files a/doc/static/images/sdk/blacklist75.jpg and b/doc/static/images/sdk/denylist.jpg differ diff --git a/example/plugins/c-api/Makefile.am b/example/plugins/c-api/Makefile.am index 97abebb64b1..81a89b3a26b 100644 --- a/example/plugins/c-api/Makefile.am +++ b/example/plugins/c-api/Makefile.am @@ -26,13 +26,13 @@ example_Plugins = \ add_header.la \ append_transform.la \ basic_auth.la \ - blocklist_0.la \ - blocklist_1.la \ bnull_transform.la \ cert_update.la \ request_buffer.la \ cache_scan.la \ client_context_dump.la \ + denylist_0.la \ + denylist_1.la \ file_1.la \ hello.la \ intercept.la \ @@ -71,8 +71,8 @@ endif add_header_la_SOURCES = add_header/add_header.c append_transform_la_SOURCES = append_transform/append_transform.c basic_auth_la_SOURCES = basic_auth/basic_auth.c -blocklist_0_la_SOURCES = blocklist_0/blocklist_0.c -blocklist_1_la_SOURCES = blocklist_1/blocklist_1.c +denylist_0_la_SOURCES = denylist_0/denylist_0.c +denylist_1_la_SOURCES = denylist_1/denylist_1.c bnull_transform_la_SOURCES = bnull_transform/bnull_transform.c cert_update_la_SOURCES = cert_update/cert_update.cc request_buffer_la_SOURCES = request_buffer/request_buffer.c diff --git a/example/plugins/c-api/blocklist_1/readme.txt b/example/plugins/c-api/blocklist_1/readme.txt deleted file mode 100644 index 0402434c681..00000000000 --- a/example/plugins/c-api/blocklist_1/readme.txt +++ /dev/null @@ -1,17 +0,0 @@ -How to run the blocklist plugin -=============================== - -1. Modify blocklist.cgi to specify the location of perl and traffic server. -2. Copy blocklist.cgi, blocklist_1.so, PoweredByInktomi.gif to the directory - specified by the variable proxy.config.plugin.plugin_dir. -3. Modify plugin.config to load the blocklist plugin. - - - -About the blocklist plugin -========================== - -The blocklist plugin allows Traffic Server to compare all incoming request -origin servers with a blocklisted set of web servers. If the requested origin -server is blocklisted, Traffic Server sends the client a message saying that -access is denied. diff --git a/example/plugins/c-api/blocklist_0/blocklist_0.c b/example/plugins/c-api/denylist_0/denylist_0.c similarity index 93% rename from example/plugins/c-api/blocklist_0/blocklist_0.c rename to example/plugins/c-api/denylist_0/denylist_0.c index a7da67c69a2..67a4796f414 100644 --- a/example/plugins/c-api/blocklist_0/blocklist_0.c +++ b/example/plugins/c-api/denylist_0/denylist_0.c @@ -22,8 +22,8 @@ */ /* - * blocklist_0.c: - * original version of blocklist-1, now used for internal testing + * denylist_0.c: + * original version of denylist-1, now used for internal testing * * * Usage: @@ -34,7 +34,7 @@ #include #include -#define PLUGIN_NAME "blocklist_0" +#define PLUGIN_NAME "denylist_0" static char **sites; static int nsites; @@ -69,7 +69,7 @@ handle_dns(TSHttpTxn txnp, TSCont contp) } for (i = 0; i < nsites; i++) { if (strncmp(host, sites[i], host_length) == 0) { - printf("blocklisting site: %s\n", sites[i]); + printf("denylisting site: %s\n", sites[i]); TSHttpTxnHookAdd(txnp, TS_HTTP_SEND_RESPONSE_HDR_HOOK, contp); TSHandleMLocRelease(bufp, hdr_loc, url_loc); TSHandleMLocRelease(bufp, TS_NULL_MLOC, url_loc); @@ -130,7 +130,7 @@ handle_response(TSHttpTxn txnp) } static int -blocklist_plugin(TSCont contp, TSEvent event, void *edata) +denylist_plugin(TSCont contp, TSEvent event, void *edata) { TSHttpTxn txnp = (TSHttpTxn)edata; @@ -168,6 +168,6 @@ TSPluginInit(int argc, const char *argv[]) sites[i] = TSstrdup(argv[i + 1]); } - TSHttpHookAdd(TS_HTTP_OS_DNS_HOOK, TSContCreate(blocklist_plugin, NULL)); + TSHttpHookAdd(TS_HTTP_OS_DNS_HOOK, TSContCreate(denylist_plugin, NULL)); } } diff --git a/example/plugins/c-api/blocklist_1/blocklist.txt b/example/plugins/c-api/denylist_1/denylist.txt similarity index 100% rename from example/plugins/c-api/blocklist_1/blocklist.txt rename to example/plugins/c-api/denylist_1/denylist.txt diff --git a/example/plugins/c-api/blocklist_1/blocklist_1.c b/example/plugins/c-api/denylist_1/denylist_1.c similarity index 89% rename from example/plugins/c-api/blocklist_1/blocklist_1.c rename to example/plugins/c-api/denylist_1/denylist_1.c index 0475b4eabb7..0cbcec2e928 100644 --- a/example/plugins/c-api/blocklist_1/blocklist_1.c +++ b/example/plugins/c-api/denylist_1/denylist_1.c @@ -1,6 +1,6 @@ /** @file - An example plugin that denies client access to blocklisted sites (blocklist.txt). + An example plugin that denies client access to specified sites (denylist.txt). @section license License @@ -27,7 +27,7 @@ #include "ts/ts.h" #include "tscore/ink_defs.h" -#define PLUGIN_NAME "blocklist_1" +#define PLUGIN_NAME "denylist_1" #define MAX_NSITES 500 #define RETRY_TIME 10 @@ -95,7 +95,7 @@ handle_dns(TSHttpTxn txnp, TSCont contp) } /* We need to lock the sites_mutex as that is the mutex that is - protecting the global list of all blocklisted sites. */ + protecting the global list of all denylisted sites. */ if (TSMutexLockTry(sites_mutex) != TS_SUCCESS) { TSDebug(PLUGIN_NAME, "Unable to get lock. Will retry after some time"); TSHandleMLocRelease(bufp, hdr_loc, url_loc); @@ -107,9 +107,9 @@ handle_dns(TSHttpTxn txnp, TSCont contp) for (i = 0; i < nsites; i++) { if (strncmp(host, sites[i], host_length) == 0) { if (log) { - TSTextLogObjectWrite(log, "blocklisting site: %s", sites[i]); + TSTextLogObjectWrite(log, "denylisting site: %s", sites[i]); } else { - TSDebug(PLUGIN_NAME, "blocklisting site: %s", sites[i]); + TSDebug(PLUGIN_NAME, "denylisting site: %s", sites[i]); } TSHttpTxnHookAdd(txnp, TS_HTTP_SEND_RESPONSE_HDR_HOOK, contp); TSHandleMLocRelease(bufp, hdr_loc, url_loc); @@ -174,13 +174,13 @@ handle_response(TSHttpTxn txnp, TSCont contp ATS_UNUSED) } static void -read_blocklist(TSCont contp) +read_denylist(TSCont contp) { - char blocklist_file[1024]; + char denylist_file[1024]; TSFile file; - sprintf(blocklist_file, "%s/blocklist.txt", TSPluginDirGet()); - file = TSfopen(blocklist_file, "r"); + sprintf(denylist_file, "%s/denylist.txt", TSPluginDirGet()); + file = TSfopen(denylist_file, "r"); nsites = 0; /* If the Mutex lock is not successful try again in RETRY_TIME */ @@ -215,7 +215,7 @@ read_blocklist(TSCont contp) TSfclose(file); } else { - TSError("[%s] Unable to open %s", PLUGIN_NAME, blocklist_file); + TSError("[%s] Unable to open %s", PLUGIN_NAME, denylist_file); TSError("[%s] All sites will be allowed", PLUGIN_NAME); } @@ -223,7 +223,7 @@ read_blocklist(TSCont contp) } static int -blocklist_plugin(TSCont contp, TSEvent event, void *edata) +denylist_plugin(TSCont contp, TSEvent event, void *edata) { TSHttpTxn txnp; cdata *cd; @@ -276,7 +276,7 @@ blocklist_plugin(TSCont contp, TSEvent event, void *edata) break; } } else { - read_blocklist(contp); + read_denylist(contp); return 0; } default: @@ -291,7 +291,7 @@ handle_txn_start(TSCont contp ATS_UNUSED, TSHttpTxn txnp) TSCont txn_contp; cdata *cd; - txn_contp = TSContCreate((TSEventFunc)blocklist_plugin, TSMutexCreate()); + txn_contp = TSContCreate((TSEventFunc)denylist_plugin, TSMutexCreate()); /* create the data that'll be associated with the continuation */ cd = (cdata *)TSmalloc(sizeof(cdata)); TSContDataSet(txn_contp, cd); @@ -319,8 +319,8 @@ TSPluginInit(int argc ATS_UNUSED, const char *argv[] ATS_UNUSED) TSError("[%s] Plugin registration failed", PLUGIN_NAME); } - /* create an TSTextLogObject to log blocklisted requests to */ - error = TSTextLogObjectCreate("blocklist", TS_LOG_MODE_ADD_TIMESTAMP, &log); + /* create an TSTextLogObject to log denied requests to */ + error = TSTextLogObjectCreate("denylist", TS_LOG_MODE_ADD_TIMESTAMP, &log); if (!log || error == TS_ERROR) { TSDebug(PLUGIN_NAME, "error while creating log"); } @@ -332,8 +332,8 @@ TSPluginInit(int argc ATS_UNUSED, const char *argv[] ATS_UNUSED) sites[i] = NULL; } - global_contp = TSContCreate(blocklist_plugin, sites_mutex); - read_blocklist(global_contp); + global_contp = TSContCreate(denylist_plugin, sites_mutex); + read_denylist(global_contp); /*TSHttpHookAdd (TS_HTTP_OS_DNS_HOOK, contp); */ TSHttpHookAdd(TS_HTTP_TXN_START_HOOK, global_contp); diff --git a/example/plugins/c-api/denylist_1/readme.txt b/example/plugins/c-api/denylist_1/readme.txt new file mode 100644 index 00000000000..70a75fdc686 --- /dev/null +++ b/example/plugins/c-api/denylist_1/readme.txt @@ -0,0 +1,17 @@ +How to run the denylist plugin +=============================== + +1. Modify denylist.cgi to specify the location of perl and traffic server. +2. Copy denylist.cgi, denylist_1.so, PoweredByInktomi.gif to the directory + specified by the variable proxy.config.plugin.plugin_dir. +3. Modify plugin.config to load the denylist plugin. + + + +About the denylist plugin +========================== + +The denylist plugin allows Traffic Server to compare all incoming request +origin servers with a deny-listed set of web servers. If the requested origin +server is listed, Traffic Server sends the client a message saying that +access is denied. diff --git a/plugins/cachekey/configs.cc b/plugins/cachekey/configs.cc index ae366f92bee..b2bc42d5e70 100644 --- a/plugins/cachekey/configs.cc +++ b/plugins/cachekey/configs.cc @@ -274,11 +274,11 @@ makeConfigPath(const String &path) /** * @brief a helper function which loads the classifier from files. * @param args classname + filename in ':' format. - * @param blocklist true - load as a blocklist classifier, false - allowlist. + * @param denylist true - load as a denylist classifier, false - allowlist. * @return true if successful, false otherwise. */ bool -Configs::loadClassifiers(const String &args, bool blocklist) +Configs::loadClassifiers(const String &args, bool denylist) { static const char *EXPECTED_FORMAT = ":"; @@ -310,7 +310,7 @@ Configs::loadClassifiers(const String &args, bool blocklist) } MultiPattern *multiPattern; - if (blocklist) { + if (denylist) { multiPattern = new NonMatchingMultiPattern(classname); } else { multiPattern = new MultiPattern(classname); @@ -341,8 +341,8 @@ Configs::loadClassifiers(const String &args, bool blocklist) p = new Pattern(); if (nullptr != p && p->init(regex)) { - if (blocklist) { - CacheKeyDebug("Added pattern '%s' to block list '%s'", regex.c_str(), classname.c_str()); + if (denylist) { + CacheKeyDebug("Added pattern '%s' to deny list '%s'", regex.c_str(), classname.c_str()); multiPattern->add(p); } else { CacheKeyDebug("Added pattern '%s' to allow list '%s'", regex.c_str(), classname.c_str()); @@ -386,7 +386,7 @@ Configs::init(int argc, const char *argv[], bool perRemapConfig) {const_cast("include-cookies"), optional_argument, nullptr, 'h'}, {const_cast("ua-capture"), optional_argument, nullptr, 'i'}, {const_cast("ua-allowlist"), optional_argument, nullptr, 'j'}, - {const_cast("ua-blocklist"), optional_argument, nullptr, 'k'}, + {const_cast("ua-denylist"), optional_argument, nullptr, 'k'}, {const_cast("static-prefix"), optional_argument, nullptr, 'l'}, {const_cast("capture-prefix"), optional_argument, nullptr, 'm'}, {const_cast("capture-prefix-uri"), optional_argument, nullptr, 'n'}, @@ -453,14 +453,14 @@ Configs::init(int argc, const char *argv[], bool perRemapConfig) } break; case 'j': /* ua-allowlist */ - if (!loadClassifiers(optarg, /* blocklist = */ false)) { + if (!loadClassifiers(optarg, /* denylist = */ false)) { CacheKeyError("failed to load User-Agent pattern allow-list '%s'", optarg); status = false; } break; - case 'k': /* ua-blocklist */ - if (!loadClassifiers(optarg, /* blocklist = */ true)) { - CacheKeyError("failed to load User-Agent pattern block-list '%s'", optarg); + case 'k': /* ua-denylist */ + if (!loadClassifiers(optarg, /* denylist = */ true)) { + CacheKeyError("failed to load User-Agent pattern deny-list '%s'", optarg); status = false; } break; diff --git a/plugins/cachekey/configs.h b/plugins/cachekey/configs.h index 7f3e8e6a442..e98b69afd48 100644 --- a/plugins/cachekey/configs.h +++ b/plugins/cachekey/configs.h @@ -217,16 +217,16 @@ class Configs Pattern _prefixCaptureUri; /**< @brief cache key prefix captured from the URI as a whole */ Pattern _pathCapture; /**< @brief cache key element captured from the URI path */ Pattern _pathCaptureUri; /**< @brief cache key element captured from the URI as a whole */ - Classifier _classifier; /**< @brief blocklist and allow-list classifier used to classify User-Agent header */ + Classifier _classifier; /**< @brief denylist and allow-list classifier used to classify User-Agent header */ private: /** * @brief a helper function which loads the classifier from files. * @param args classname + filename in ':' format. - * @param blocklist true - load as a blocklist classifier, false - allow-list. + * @param denylist true - load as a denylist classifier, false - allow-list. * @return true if successful, false otherwise. */ - bool loadClassifiers(const String &args, bool blocklist = true); + bool loadClassifiers(const String &args, bool denylist = true); bool _prefixToBeRemoved = false; /**< @brief instructs the prefix (i.e. host:port) not to added to the cache key */ bool _pathToBeRemoved = false; /**< @brief instructs the path not to added to the cache key */ diff --git a/plugins/experimental/access_control/config.cc b/plugins/experimental/access_control/config.cc index 07360aeb536..b401e6fc838 100644 --- a/plugins/experimental/access_control/config.cc +++ b/plugins/experimental/access_control/config.cc @@ -261,14 +261,14 @@ AccessControlConfig::init(int argc, char *argv[]) _useRedirects = ::isTrue(optarg); } break; case 'o': /* include-uri-paths-file */ - if (!loadMultiPatternsFromFile(optarg, /* blocklist = */ false)) { + if (!loadMultiPatternsFromFile(optarg, /* denylist = */ false)) { AccessControlError("failed to load uri-path multi-pattern allow-list '%s'", optarg); status = false; } break; case 'p': /* exclude-uri-paths-file */ - if (!loadMultiPatternsFromFile(optarg, /* blocklist = */ true)) { - AccessControlError("failed to load uri-path multi-pattern block-list '%s'", optarg); + if (!loadMultiPatternsFromFile(optarg, /* denylist = */ true)) { + AccessControlError("failed to load uri-path multi-pattern deny-list '%s'", optarg); status = false; } break; @@ -297,11 +297,11 @@ AccessControlConfig::init(int argc, char *argv[]) /** * @brief a helper function which loads the classifier from files. * @param filename file name - * @param blocklist true - load as a blocklist of patterns, false - allow-list of patterns + * @param denylist true - load as a denylist of patterns, false - allow-list of patterns * @return true if successful, false otherwise. */ bool -AccessControlConfig::loadMultiPatternsFromFile(const String &filename, bool blocklist) +AccessControlConfig::loadMultiPatternsFromFile(const String &filename, bool denylist) { if (filename.empty()) { AccessControlError("filename cannot be empty"); @@ -322,7 +322,7 @@ AccessControlConfig::loadMultiPatternsFromFile(const String &filename, bool bloc /* Have the multiplattern be named as same as the filename, would be used only for debugging. */ MultiPattern *multiPattern; - if (blocklist) { + if (denylist) { multiPattern = new NonMatchingMultiPattern(filename); AccessControlDebug("NonMatchingMultiPattern('%s')", filename.c_str()); } else { @@ -355,8 +355,8 @@ AccessControlConfig::loadMultiPatternsFromFile(const String &filename, bool bloc p = new Pattern(); if (nullptr != p && p->init(regex)) { - if (blocklist) { - AccessControlDebug("Added pattern '%s' to block list uri-path multi-pattern '%s'", regex.c_str(), filename.c_str()); + if (denylist) { + AccessControlDebug("Added pattern '%s' to deny list uri-path multi-pattern '%s'", regex.c_str(), filename.c_str()); multiPattern->add(p); } else { AccessControlDebug("Added pattern '%s' to allow list uri-path multi-pattern '%s'", regex.c_str(), filename.c_str()); diff --git a/plugins/experimental/access_control/config.h b/plugins/experimental/access_control/config.h index d35e353b58d..1391a4a9d02 100644 --- a/plugins/experimental/access_control/config.h +++ b/plugins/experimental/access_control/config.h @@ -38,7 +38,7 @@ class AccessControlConfig virtual ~AccessControlConfig() { delete _tokenFactory; } bool init(int argc, char *argv[]); - bool loadMultiPatternsFromFile(const String &filename, bool blocklist = true); + bool loadMultiPatternsFromFile(const String &filename, bool denylist = true); StringMap _symmetricKeysMap; /** @brief a map secrets accessible by key string (KID) */ @@ -66,5 +66,5 @@ class AccessControlConfig String _extrTokenIdHdrName; /** @brief header name to extract the token id, if empty => no extraction */ String _extrValidationHdrName; /** @brief header name to extract the token validation status, if empty => no extraction */ bool _useRedirects = false; /** @brief true - use redirect to set the access token cookie, @todo not used yet */ - Classifier _uriPathScope; /**< @brief blocklist (exclude) and allow-list (include) which path should have the access control */ + Classifier _uriPathScope; /**< @brief denylist (exclude) and allow-list (include) which path should have the access control */ };