1.. Licensed to the Apache Software Foundation (ASF) under one
2   or more contributor license agreements.  See the NOTICE file
3   distributed with this work for additional information
4   regarding copyright ownership.  The ASF licenses this file
5   to you under the Apache License, Version 2.0 (the
6   "License"); you may not use this file except in compliance
7   with the License.  You may obtain a copy of the License at
8
9   http://www.apache.org/licenses/LICENSE-2.0
10
11   Unless required by applicable law or agreed to in writing,
12   software distributed under the License is distributed on an
13   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14   KIND, either express or implied.  See the License for the
15   specific language governing permissions and limitations
16   under the License.
17
18.. include:: ../../common.defs
19
20plugin.config
21*************
22
23.. configfile:: plugin.config
24
25Description
26===========
27
28The :file:`plugin.config` file controls run-time loadable plugins available to
29|TS|, as well as their configuration.  Plugins listed in this file are referred
30to as *global plugins* because they are always loaded and have global effect.
31This is in contrast to plugins specified in :file:`remap.config`, whose effects
32are limited to the specific mapping rules to which they are applied.
33
34Each configuration line consists of a path to an ``.so`` file. This path can
35either be absolute, or relative to the plugin directory (usually
36``/usr/local/libexec/trafficserver``).  Failure to load a plugin is fatal, and
37will cause |TS| to abort. In general, it is not possible to know whether it is
38safe for the service to run without a particular plugin, since plugins can have
39arbitrary effects on caching and authorization policies.
40
41.. important::
42
43   Plugins should only be listed once. The order in which the plugins
44   are listed is also the order in which they are chained for request
45   processing.
46
47An option list of whitespace-separated arguments may follow the plugin name.
48These are passed as an argument vector to the plugin's initialization function,
49:c:func:`TSPluginInit`. Arguments that begin with the ``$`` character designate
50|TS| configuration variables. These arguments will be replaced with the value
51of the corresponding configuration variable before the plugin is loaded.  When
52using configuration variable expansion, note that most |TS| configuration can
53be changed. If a plugin requires the current value, it must obtain that using
54the management API.
55
56Examples
57========
58
59::
60
61     # Comments start with a '#' and continue to the end of the line
62     # Blank lines are ignored
63     #
64     # test-plugin.so arg1 arg2 arg3
65     #
66     plugins/iwx/iwx.so
67     plugins/abuse/abuse.so etc/trafficserver/abuse.config
68     plugins/icx/icx.so etc/trafficserver/icx.config $proxy.config.http.connect_attempts_timeout
69
70See Also
71========
72
73:manpage:`TSAPI(3ts)`,
74:manpage:`TSPluginInit(3ts)`,
75:manpage:`remap.config(5)`
76