.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. .. include:: ../../common.defs .. _admin-plugins-conf-remap: Configuration Remap Plugin ************************** This plugin allows you to override configuration directives dependent on remapping rules. Purpose ======= |TS| provides a plethora of configuration options, but specifying the values of those options in :file:`records.config` is global. All requests, regardless of the cache object or its origin, will be evaluated within the same collection of settings. Sometimes you may want |TS| to behave differently for portions of your cache. Perhaps you have :ref:`admin-negative-response-caching` enabled, but you wish to greatly reduce the validity times for just one of your origin servers while allowing the rest of your origins to have their errors cached for long durations. Or maybe you make use of :ref:`admin-heuristic-expiration` but require different fuzz times for various objects because of the nature of their content and expected lifetimes. Any configuration directive which is overridable can be modified on a per-map basis with this plugin. This opens up a level of flexibility in your configurations for effectively managing and caching content with varied needs, without having to resort to multiple |TS| instances. Installation ============ This plugin is considered stable and is included with |TS| by default. There are no special steps necessary for its installation. Configuration ============= Configuration of this plugin is performed alongside the actual remapping rules which trigger the desired configuration directive changes. There are two methods available for specifying the actual directives and their modified values. Inline Directives ----------------- In cases where you have very few remapping rules which modify directives, and they are modifying only a small number of directives, you may find it easiest to simply specify those directive changes in-line with your remapping rules. This is done by specifying *key* = *value* pairs, where the key is the configuration directive name and the value is its desired setting for the remapping rule. For example, the enable :ts:cv:`proxy.config.url_remap.pristine_host_hdr` for a single `map` rule, you would add the following to your :file:`remap.config`:: map http://cdn.example.com/ http://origin.example.com/ \ @plugin=conf_remap.so @pparam=proxy.config.url_remap.pristine_host_hdr=1 External Configuration ---------------------- There may be situations in which you have many directives you wish to modify, or where multiple remapping rules perform the same directive changes. External configurations can simplify management of these rules, and help to reduce the possibility of transcription errors, or keeping all the directive settings in sync across all the remapping rules over time. Instead of specifying the directives and their values in :file:`remap.config` as you do with the in-line method, you place all the affected directives in a separate text file. The location and name is entirely up to you, but we'll use `/etc/trafficserver/cdn_conf_remap.config` here. The contents of this file should mirror how configuration directives are written in :file:`records.config`:: CONFIG proxy.config.url_remap.pristine_host_hdr INT 1 Your :file:`remap.config` will then contain remapping rules that point to this external file:: map http://cdn.example.com/ http://some-server.example.com \ @plugin=conf_remap.so @pparam=/etc/trafficserver/cdn_conf_remap.config Your external configuration may contain as many directives as you wish. Caveats ======= This plugin can only modify the values for those configuration directives which are *overridable*, meaning they are not fixed upon |TS| startup. While this generally shouldn't prove too onerous a restriction, you should consult the individual directives' documentation to confirm whether they may be overridden. Further Reading =============== For more information about the implementation of overridable configuration directives, you may consult the developer's documentation for :ref:`ts-overridable-config`.