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
20.. _developer-plugins-getting-started-simple-plugin:
21
22A Simple Plugin
23***************
24
25This section describes how to write, compile, configure, and run a
26simple Traffic Server plugin. You'll follow the steps below:
27
281. Make sure that your plugin source code contains an :c:func:`TSPluginInit`
29   initialization function.
30
312. Compile your plugin source code, creating a shared library.
32
333. Add an entry to :file:`plugin.config`.
34
354. Add the path to your plugin shared library into :file:`records.config`.
36
375. Restart Traffic Server.
38
39Compile Your Plugin
40===================
41
42The process for compiling a shared library varies with the platform
43used, so the Traffic Server API provides the tsxs tool which you can use
44to create shared libraries on all the supported Traffic Server
45platforms.
46
47Example
48-------
49
50Assuming the sample program is stored in the file ``hello_world.c``, you
51could use the following commands to build a shared library::
52
53    tsxs -o hello_world.so -c hello_world.c
54
55``tsxs`` is installed in the ``bin`` directory of |TS|.
56
57This shared library will be your plugin. In order to install it, run::
58
59    sudo tsxs -o hello_world.so -i
60
61or the equivalent to ``sudo`` on your platform.
62
63Update the plugin configuration file
64====================================
65
66Your next step is to tell Traffic Server about the plugin by adding the
67following line to :file:`plugin.config` file. Since our simple plugin
68does not require any arguments, the following :file:`plugin.config` will
69work::
70
71    # a simple plugin.config for hello_world
72    hello_world.so
73
74|TS| can accommodate multiple plugins. If several plugin
75functions are triggered by the same event, then Traffic Server invokes
76each plugin's function in the order each was defined in :file:`plugin.config`.
77
78.. _specify-the-plugins-location:
79
80Specify the Plugin's Location
81=============================
82
83All plugins must be located in the directory specified by the
84configuration variable ``proxy.config.plugin.plugin_dir``, which is
85located in the :file:`records.config` file. The directory can be specified
86as an absolute or relative path.
87
88If a relative path is used, then the starting directory will be the
89Traffic Server installation directory as specified in
90``etc/traffic_server``. The default value is ``libexec/trafficserver``,
91but this can vary based on how the software was configured and built. It
92is common to use the default directory. Be sure to place the shared
93library ``hello_world.so`` inside the directory you've configured.
94
95Restart Traffic Server
96======================
97
98The last step is to start/restart Traffic Server. Shown below is the
99output displayed after you've created and loaded your ``hello_world``
100plugin.
101
102::
103
104    # ls libexec/trafficserver
105    hello_world.so*
106    # bin/traffic_server
107    [Mar 27 19:06:31.669] NOTE: updated diags config
108    [Mar 27 19:06:31.680] NOTE: loading plugin 'libexec/trafficserver/hello_world.so'
109    hello world
110    [Mar 27 19:06:32.046] NOTE: cache disabled (initializing)
111    [Mar 27 19:06:32.053] NOTE: cache enabled
112    [Mar 27 19:06:32.526] NOTE: Traffic Server running
113
114.. note::
115
116  In the example above, Traffic Server notes are directed to the
117  console by specifying ``E`` for :ts:cv:`proxy.config.diags.output.note` in
118  :file:`records.config`. The second note shows Traffic Server attempting to
119  load the ``hello_world`` plugin. The third line of Traffic Server output
120  is from your plugin.
121