diff --git a/doc/admin/transparent-proxy.en.rst b/doc/admin/transparent-proxy.en.rst index 750fdf48e1d..2a2eb5c5fee 100644 --- a/doc/admin/transparent-proxy.en.rst +++ b/doc/admin/transparent-proxy.en.rst @@ -27,7 +27,6 @@ Transparent Proxying transparent-proxy/build.en transparent-proxy/bridge.en transparent-proxy/router-inline.en - transparent-proxy/router-inline.en transparent-proxy/wccp-configuration.en Transparent Proxying is the ability of a proxy (such as ATS) to @@ -108,7 +107,7 @@ address of the ATS server via DNS as the origin server address. Some tested scenarios -- -- `Transparent bridging `_ -- `Inline router `_ -- `WCCP Configuration `_ +- :doc:`transparent-proxy/bridge.en` +- :doc:`transparent-proxy/router-inline.en` +- :doc:`transparent-proxy/wccp-configuration.en` diff --git a/doc/admin/transparent-proxy/bridge.en.rst b/doc/admin/transparent-proxy/bridge.en.rst index 266e72c1262..388a9c8fb8f 100644 --- a/doc/admin/transparent-proxy/bridge.en.rst +++ b/doc/admin/transparent-proxy/bridge.en.rst @@ -78,7 +78,7 @@ Although it looks like this will intercept all port 80 traffic it will only affect the two flows described above. ``-j redirect`` marks the packet as being diverted to the bridge and not forwarded, and the ``DROP`` target puts the packets in the normal ``iptables`` routing so -that we can use standard device tests on them [1]_(#1). Although this +that we can use standard device tests on them [1]_. Although this example handles only port 80, other ports are the same except for the port value. Note also the port here is the port from the point of view of the clients and origin servers, not the Traffic Server server port. :: @@ -138,7 +138,7 @@ Additional troubleshooting ~~~~~~~~~~~~~~~~~~~~~~~~~~ * Check to make sure that ``iptables`` is not filtering (blocking) -incoming HTTP connections. + incoming HTTP connections. It is frequently the case that the default tables prevent incoming HTTP. You can clear all filters with the commands:: @@ -154,7 +154,9 @@ incoming HTTP connections. Note that this problem will prevent the basic bridge (without ATS) from allowing HTTP traffic through. -* Verify that IP packet forwarding is enabled. You can check this with:: +* Verify that IP packet forwarding is enabled. + + You can check this with:: cat /proc/sys/net/ipv4/ip_forward diff --git a/doc/admin/transparent-proxy/router-inline.en.rst b/doc/admin/transparent-proxy/router-inline.en.rst index 5e6b64c5a29..f7047b9abc1 100644 --- a/doc/admin/transparent-proxy/router-inline.en.rst +++ b/doc/admin/transparent-proxy/router-inline.en.rst @@ -75,10 +75,9 @@ To configure Traffic Server set the following values in ``proxy.config.http.server_port`` ``STRING`` - Default: *value from* ```--on-port`` <#on_port>`_ + Default: *value from* ``--on-port`` -proxy.config.http.server_port_attr -{#proxy.config.http.server_port_attr} +``proxy.config.http.server_port_attr`` ``STRING`` Default: ``=`` diff --git a/doc/admin/transparent-proxy/wccp-configuration.en.rst b/doc/admin/transparent-proxy/wccp-configuration.en.rst index 4ed75989b95..5a9a41c6bc3 100644 --- a/doc/admin/transparent-proxy/wccp-configuration.en.rst +++ b/doc/admin/transparent-proxy/wccp-configuration.en.rst @@ -33,7 +33,7 @@ are - WCCP fails open so that if the Traffic Server machine fails, it is bypassed and users continue to have Internet access. -Use of WCCP only makes sense for client side transparency [1]_(#1) +Use of WCCP only makes sense for client side transparency [1]_ because if the clients are explicitly proxied by Traffic Server there's no benefit to WCCP fail open, as the clients will continue to directly access the unresponsive Traffic Server host. It would be better to @@ -85,7 +85,7 @@ are to be used. In general the dedicated topology is preferred. However, if the router has only two interfaces one of the shared topologies will be -required [2]_(#2). Click the links above for more detailed configuration +required [2]_ Click the links above for more detailed configuration information on a specific topology. Shared interface issues @@ -102,7 +102,7 @@ the dedicated interface case. This enables the packets to be distinguished at layer 3. For this reason, layer 2 redirection cannot be used because the WCCP configuration cannot distinguish between packets returning from the origin server and packets returning from Traffic -Server as they are distinguished only by layer 2 addressing [3]_(#3). +Server as they are distinguished only by layer 2 addressing [3]_. Fortunately the GRE tunnel used for packet forwarding and return can be used as the simulated interface for Traffic Server. diff --git a/doc/reference/configuration/records.config.en.rst b/doc/reference/configuration/records.config.en.rst index c92f3511488..616dd04dbb3 100644 --- a/doc/reference/configuration/records.config.en.rst +++ b/doc/reference/configuration/records.config.en.rst @@ -1313,6 +1313,7 @@ Customizable User Response Pages ================================ .. ts:cv:: CONFIG proxy.config.body_factory.enable_customizations INT 1 + Specifies whether customizable response pages are language specific or not: diff --git a/doc/sdk/continuations.en.rst b/doc/sdk/continuations.en.rst index df93565036a..1981fd7d888 100644 --- a/doc/sdk/continuations.en.rst +++ b/doc/sdk/continuations.en.rst @@ -31,11 +31,11 @@ mutex. This chapter covers the following topics: -- `Mutexes and Data `__ +- `Mutexes and Data`_ -- `How to Activate Continuations `__ +- :doc:`continuations/how-to-activate-continuations.en` -- `Writing Handler Functions `__ +- :doc:`continuations/writing-handler-functions.en` Mutexes and Data ---------------- @@ -55,15 +55,13 @@ one of the following: Before being activated, a caller must grab the continuation's mutex. This requirement makes it possible for a continuation's handler function to safely access its data and to prevent multiple callers from running -it at the same time (see the `sample Protocol -plugin <../new-protocol-plugins#AboutSampleProtocol>`__ for usage). The +it at the same time (see the :ref:`about-the-sample-protocol` for usage). The data protected by the mutex is any global or continuation data associated to the continuation by ``TSContDataSet``. This does not include the local data created by the continuation handler function. A typical example of continuations created with associated data structures and mutexes is the transaction state machine created in the sample -Protocol plugin (see `One Way to Implement a Transaction State -Machine <../new-protocol-plugins#OneWayImplementaTransactionStateMachine>`__). +Protocol plugin (see :ref:`one-way-to-implement-a-transaction-state-machine`). A reentrant call occurs when the continuation passed as an argument to the API can be called in the same stack trace as the function calling diff --git a/doc/sdk/getting-started.en.rst b/doc/sdk/getting-started.en.rst index a39d0cfc406..38c14bb2418 100644 --- a/doc/sdk/getting-started.en.rst +++ b/doc/sdk/getting-started.en.rst @@ -31,22 +31,19 @@ The Traffic Server API enables you to create plugins, using the C programming language, that customize the behavior of your Traffic Server installation. This chapter contains the following sections: -- `Understanding Traffic Server Plugins <#UnderstandingTSPlugins>`__ -- - a brief introduction to plugins. For more details, see `How to Create - Traffic Server Plugins <../how-to-create-trafficserver-plugins>`__ +- `Understanding Traffic Server Plugins`_ -- a brief introduction to plugins. + For more details, see :doc:`how-to-create-trafficserver-plugins.en` -- `A Simple Plugin `__ -- walks through compiling and +- :doc:`getting-started/a-simple-plugin.en` -- walks through compiling and loading an example ``hello world`` plugin. -- `Plugin Registration and Version - Checking `__ -- shows you - how to register your plugin and make sure it's compatible with the +- :doc:`getting-started/plugin-registration-and-version-checking.en` -- shows + you how to register your plugin and make sure it's compatible with the version of Traffic Server you're using. -- `Naming Conventions `__ -- outlines Traffic +- :doc:`getting-started/naming-conventions.en` -- outlines Traffic Server API naming conventions. For guidelines on creating plugin - source code, see `How to Create Traffic Server - Plugins <../how-to-create-trafficserver-plugins>`__ + source code, see :doc:`how-to-create-trafficserver-plugins.en` Understanding Traffic Server Plugins ------------------------------------ @@ -80,7 +77,9 @@ call-back functions you've registered for that event type. out-of-range pointer, can cause Traffic Server processes to crash and may ultimately result in unpredictable behavior. -**Plugin Process** {#PluginProcess} +**Plugin Process** + +.. _PluginProcess: .. figure:: /static/images/sdk/plugin_process.jpg :align: center @@ -123,10 +122,11 @@ Some examples of plugins include: designated port and then uses Traffic Server's proxy server & cache to serve client requests. -The figure below, `Possible Traffic Server -Plugins <#possibleTSplugins>`__, illustrates several types of plugins. +The figure below, :ref:`possibleTSplugins`, illustrates several types of plugins. + +**Possible Traffic Server Plugins** -**Possible Traffic Server Plugins** {#possibleTSplugins} +.. _possibleTSplugins: .. figure:: /static/images/sdk/Uses.jpg :align: center @@ -137,8 +137,8 @@ Plugins <#possibleTSplugins>`__, illustrates several types of plugins. You can find basic examples for many plugins in the SDK sample code: - ``append-transform.c`` adds text from a specified file to HTTP/text - responses. This plugin is explained in `The Append-Transform - Plugin <../http-transformation-plugin/append-transform-plugin>`__ + responses. This plugin is explained in + :doc:`http-transformation-plugin/append-transform-plugin.en` - The compression plugin in the figure communicates with the server that actually does the compression. The ``server-transform.c`` plugin @@ -152,8 +152,7 @@ You can find basic examples for many plugins in the SDK sample code: - ``blacklist-1.c`` reads blacklisted servers from a configuration file and denies client access to these servers. This plugin is explained - in `The Blacklist - Plugin <../header-based-plugin-examples/blacklist-plugin>`__. + in :doc:`header-based-plugin-examples/blacklist-plugin.en`. Plugin Loading ~~~~~~~~~~~~~~ @@ -163,8 +162,7 @@ file to determine the names of all shared plugin libraries that need to be loaded. The ``plugin.config`` file also defines arguments that are to be passed to each plugin's initialization function, ``TSPluginInit``. The :file:`records.config` file defines the path to each plugin shared -library, as described in `Specify the Plugin's -Location `__. +library, as described in :ref:`specify-the-plugins-location`. .. note:: The path for each of these files is **\ ``/config/``, where ** is where you installed Traffic Server. @@ -243,5 +241,4 @@ The ``TSPluginInit`` function has two arguments: - The ``argv`` argument is an array of pointers to the actual arguments defined in the ``plugin.config`` file for that plugin -See `TSPluginInit `__ for -details about ``TSPluginInit``. +See :c:func:`TSPluginInit` for details about ``TSPluginInit``. diff --git a/doc/sdk/getting-started/a-simple-plugin.en.rst b/doc/sdk/getting-started/a-simple-plugin.en.rst index 31f47330d9e..18d0f781543 100644 --- a/doc/sdk/getting-started/a-simple-plugin.en.rst +++ b/doc/sdk/getting-started/a-simple-plugin.en.rst @@ -77,6 +77,8 @@ functions are triggered by the same event, then Traffic Server invokes each plugin's function in the order each was defined in the ``plugin.config`` file. +.. _specify-the-plugins-location: + Specify the Plugin's Location ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst b/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst index b7171c7c15d..7b403b89b85 100644 --- a/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst +++ b/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst @@ -23,8 +23,8 @@ version of Traffic Server. Use the following interfaces: -- ```TSPluginRegister`` `__ -- ```TSTrafficServerVersionGet`` `__ +- `TSPluginRegister `_ +- `TSTrafficServerVersionGet `_ The following version of ``hello-world`` registers the plugin and ensures it's running with a compatible version of Traffic Server. diff --git a/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst b/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst index 91c782d0156..85048e957a1 100644 --- a/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst +++ b/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst @@ -25,8 +25,7 @@ blacklisted 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 `"Blacklist -Plugin" <../../how-to-create-trafficserver-plugins#BlacklistPlugin>`__. +the figure titled :ref:`BlackListPlugin`. This example also contains a simple configuration management interface. It can read a list of blacklisted sites from a file (``blacklist.txt``) that can be updated by a Traffic Server administrator. When the @@ -49,7 +48,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 -:file:blacklist-1.c`: +``blacklist-1.c``: .. code-block:: c @@ -93,9 +92,9 @@ 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 established in ``TSPluginInit``, ``TS_EVENT_HTTP_SEND_RESPONSE_HDR`` is -sent because the plugin contains a transaction hook (see `Setting Up a -Transaction Hook `__). It is good -practice to have a default case in your switch statements. +sent because the plugin contains a transaction hook +(see :doc:`blacklist-plugin/setting-up-a-transaction-hook.en`). +It is good practice to have a default case in your switch statements. .. toctree:: :maxdepth: 2 diff --git a/doc/sdk/how-to-create-trafficserver-plugins.en.rst b/doc/sdk/how-to-create-trafficserver-plugins.en.rst index 9e7a11c7c2d..0c266105f5e 100644 --- a/doc/sdk/how-to-create-trafficserver-plugins.en.rst +++ b/doc/sdk/how-to-create-trafficserver-plugins.en.rst @@ -1,4 +1,4 @@ -.. _how-to-create-traffic-server-plugins: +.. _how-to-create-trafficserver-plugins: How to Create Traffic Server Plugins ************************************ @@ -39,7 +39,7 @@ Reading this chapter will help you to understand: - How plugins can hook onto and modify/extend Traffic Server's HTTP processing. -- A `roadmap for writing plugins `__, +- A :doc:`roadmap for writing plugins `, with an overview of the functionality provided by the Traffic Server API. @@ -74,7 +74,7 @@ implemented as continuations. Continuation objects are used throughout Traffic Server. Some might live for the duration of the Traffic Server process, while others are created (perhaps by other continuations) for specific needs and then destroyed. -`Traffic Server Internals <#TSInternals>`__ (below) shows how the major +:ref:`TSInternals` (below) shows how the major components of Traffic Server interact. Traffic Server has several **processors**, such as *cache processor* and *net processor*, that consolidate cache or network I/O tasks. Processors talk to the event @@ -83,7 +83,9 @@ continuation by sending it an event. When a continuation receives an event, it wakes up, does some work, and either destroys itself or goes back to sleep & waits for the next event. -**Traffic Server Internals** {#TSInternals} +**Traffic Server Internals** + +.. _TSInternals: .. figure:: /static/images/sdk/event_sys80.jpg :alt: Traffic Server Internals @@ -95,7 +97,9 @@ code plugins (except ``hello-world``) are continuations that are created when Traffic Server starts up; they then wait for events that trigger them into activity. -**Traffic Server with Plugins** {#TSwithPlugins} +**Traffic Server with Plugins** + +.. _TSwithPlugins: .. figure:: /static/images/sdk/evt_plugin120.jpg :alt: Traffic Server with Plugins @@ -135,15 +139,13 @@ is handled by an HTTP state machine. These machines follow a complex state diagram that includes all of the states required to support Traffic Server's features. The Traffic Server API provides hooks to a subset of these states, chosen for their relevance to plugins. You can -view the API hooks and corresponding HTTP states in the `HTTP -Transaction State -Diagram <../http-hoooks-and-transactions#HHTTPTransactionStateDiagram>`__. +view the API hooks and corresponding HTTP states in the +:ref:`http-txn-state-diagram`. The example in this section (below) explains how a plugin typically intervenes and extends Traffic Server's processing of an HTTP transaction. Complete details about hooking on to Traffic Server -processes are provided in `HTTP Hooks and -Transactions `__. +processes are provided in :doc:`http-hooks-and-transactions.en`. HTTP Transaction ^^^^^^^^^^^^^^^^ @@ -156,7 +158,9 @@ origin server. The following diagram shows some states in a typical transaction - specifically, the scenario wherein content is served from cache. -**Simplified HTTP Transaction** {#SimplifiedHTTPTransaction} +**Simplified HTTP Transaction** + +.. _SimplifiedHTTPTransaction: .. figure:: /static/images/sdk/transact75.jpg :alt: Simplified HTTP Transaction @@ -173,14 +177,16 @@ the cache (a "hit"), then Traffic Server checks it for freshness. If the content is fresh, then Traffic Server sends a reply header to the client. If the content is stale, then Traffic Server opens a connection to the origin server and requests the content. The figure above, -`Simplified HTTP Transaction <#SimplifiedHTTPTransaction>`__, does *not* +:ref:`SimplifiedHTTPTransaction`, does *not* show behavior in the event of an error. If there is an error at a any stage, then the HTTP state machine jumps to the "send reply header" state and sends a reply. If the reply is an error, then the transaction closes. If the reply is not an error, then Traffic Server first sends the response content before it closes the transaction. -**API Hooks Corresponding to States** {#APIHooksCorrespondingtoStates} +**API Hooks Corresponding to States** + +.. _APIHooksCorrespondingtoStates: .. figure:: /static/images/sdk/transact_hook75.jpg :alt: API Hooks Corresponding to States Listed in @@ -192,10 +198,12 @@ 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 `Blacklist -Plugin <#BlacklistPlugin>`__ diagram below. +Blacklist plugin works in this manner, as shown in the :ref:`BlackListPlugin` +diagram below. + +**Blacklist Plugin** -**Blacklist Plugin** {#BlacklistPlugin} +.. _BlackListPlugin: .. figure:: /static/images/sdk/blacklist75.jpg :alt: Blacklist Plugin @@ -220,9 +228,8 @@ to the "send reply header" state is a **tr**\ ***ansaction hook***, meaning that this hook is only invoked for *specified transactions* (in the Blacklist example, it's only used for requests to blacklisted servers). Several examples of setting up hooks are provided in the code -example chapters: `Header-Based Plugin -Examples <../header-based-plugin-examples>`__ and `HTTP Transformation -Plugins <../http-transformation-plugin>`__ +example chapters: :doc:`header-based-plugin-examples.en` and +:doc:`http-transformation-plugin.en` **Header manipulation plugins**, such as filtering, basic authorization, or redirects, usually have a global hook to the DNS lookup or the read diff --git a/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst b/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst index c9759e48804..7634bfe39b4 100644 --- a/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst +++ b/doc/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst @@ -61,21 +61,18 @@ Below are some guidelines for creating a plugin: These examples are discussed in the next three chapters. 2. Determine where your plugin needs to hook on to Traffic Server's HTTP - processing (view the `HTTP Transaction State - Diagram <../http-hoooks-and-transactions#HTTPTransactionStateDiagram>`__ + processing (view the :ref:`http-txn-state-diagram` -3. Read `Header-Based Plugin - Examples <../header-based-plugin-examples>`_ to learn the basics of +3. Read :doc:`../header-based-plugin-examples.en` to learn the basics of writing plugins: creating continuations and setting up hooks. If you - want to write a plugin that transforms data, then read `HTTP - Transformation Plugins `_. + want to write a plugin that transforms data, then read + :doc:`../http-transformation-plugin.en` 4. Figure out what parts of the Traffic Server API you need to use and then read about the details of those APIs in this manual's reference chapters. -5. Compile and load your plugin (see `Getting - Started <../getting-started>`_ +5. Compile and load your plugin (see :doc:`../getting-started.en` 6. Depending on your plugin's functionality, you might start testing it by issuing requests by hand and checking for the desired behavior in diff --git a/doc/sdk/http-headers/marshal-buffers.en.rst b/doc/sdk/http-headers/marshal-buffers.en.rst index 28088b755ea..d3f0664a970 100644 --- a/doc/sdk/http-headers/marshal-buffers.en.rst +++ b/doc/sdk/http-headers/marshal-buffers.en.rst @@ -28,9 +28,9 @@ object (``TSMLoc``) and the marshal buffer containing the object Routines exist for manipulating the object based on these two pieces of information. For example, see one of the following: -- `HTTP Headers `__ -- `URLs `__ -- `MIME Headers `__ +- :doc:`http-headers.en` +- :doc:`urls.en` +- :doc:`mime-headers.en` The **marshal buffer functions** enable you to create and destroy Traffic Server's marshal buffers, which are the data structures that diff --git a/doc/sdk/new-protocol-plugins.en.rst b/doc/sdk/new-protocol-plugins.en.rst index 4ca91e7adab..195fce81275 100644 --- a/doc/sdk/new-protocol-plugins.en.rst +++ b/doc/sdk/new-protocol-plugins.en.rst @@ -29,6 +29,8 @@ plugins that support new protocols. It also provides a detailed review of code for a sample Protocol plugin that supports a very simple artificial HTTP-like protocol. +.. _about-the-sample-protocol: + About the Sample Protocol ------------------------- @@ -178,6 +180,8 @@ lookups or cache writes uses ``TSCacheRead``, ``TSCacheWrite``, Cache Processor and Traffic Server event system. Similarly, any plugin that does DNS lookups receives events from the Host Database Processor. +.. _one-way-to-implement-a-transaction-state-machine: + One Way to Implement a Transaction State Machine ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -244,7 +248,7 @@ Plugin" <#ImplementTransStMachine>`__. **How Transaction State Machines are Implemented in the Protocol Plugin** {#ImplementTransStMachine} -.. figure:: /images/sdk/txn_sm.jpg +.. figure:: ../static/images/sdk/txn_sm.jpg :alt: How Transaction State Machines are Implemented in the Protocol Plugin How Transaction State Machines are Implemented in the Protocol Plugin diff --git a/doc/sdk/preface.en.rst b/doc/sdk/preface.en.rst index 2c188760c22..c2c6318a7af 100644 --- a/doc/sdk/preface.en.rst +++ b/doc/sdk/preface.en.rst @@ -31,7 +31,7 @@ creating plugins. **Plugins** are programs that add services (such as filtering or content transformation) or entire features (such as new protocol support) to Traffic Server. If you are new to writing Traffic Server plugins, then read the first two chapters, :ref:`sdk-getting-started` -and :ref:`how-to-create-to-create-trafficserver-plugins`, and use the +and :ref:`how-to-create-trafficserver-plugins`, and use the remaining chapters as needed. :ref:`header-based-plugin-examples` provides details about plugins that work on HTTP headers, while :ref:`http-transformation-plugin` explains how to write a plugin that transforms or scans the body of an HTTP response. If you diff --git a/doc/sdk/preface/how-to-use-this-book.en.rst b/doc/sdk/preface/how-to-use-this-book.en.rst index 764e4eab527..6c437fdb9f7 100644 --- a/doc/sdk/preface/how-to-use-this-book.en.rst +++ b/doc/sdk/preface/how-to-use-this-book.en.rst @@ -29,16 +29,14 @@ This book has the following basic components: - Reference material -If you're new to writing Traffic Server plugins, then read `Getting -Started <../getting-started>`_ and `Creating Traffic Server -Plugins <../how-to-create-trafficserver-plugins>`_, and use the -remaining chapters as needed. `Header-Based Plugin -Examples <../header-based-plugin-examples>`_ provides details about -plugins that work on HTTP headers, while `HTTP Transformation -Plugins <../http-transformation-plugin>`_ explains how to write a -plugin that transforms or scans the body of an HTTP response. `New -Protocol Plugins <../new-protocol-plugins>`_ provides essential -information if you want to support your own protocol on Traffic Server. +If you're new to writing Traffic Server plugins, then read +:doc:`../getting-started.en` and :doc:`../how-to-create-trafficserver-plugins.en`, +and use the remaining chapters as needed. :doc:`../header-based-plugin-examples.en` +provides details about plugins that work on HTTP headers, while +:doc:`../http-transformation-plugin.en` explains how to write a plugin that +transforms or scans the body of an HTTP response. :doc:`../new-protocol-plugins.en` +provides essential information if you want to support your own protocol on +Traffic Server. You can look up information in the following reference sections: @@ -48,36 +46,36 @@ You can look up information in the following reference sections: Doxygen reference - `Type Index `_ -- `Sample Source Code <../sample-source-code>`_ +- :doc:`Sample Source Code <../sample-source-code.en>` - `Deprecated Functions `_ Below is a section-by-section breakdown of this guide: -- `Getting Started <../getting-started>`_ +- :doc:`Getting Started <../getting-started.en>` How to compile and load plugins. Walks through a simple "hello world" example; explains how to initialize and register plugins. -- `How to Create Traffic Server - Plugins <../how-to-create-trafficserver-plugins>`_ +- :doc:`How to Create Traffic Server + Plugins <../how-to-create-trafficserver-plugins.en>` Basic structures that all plugins use: events, continuations, and how to hook on to Traffic Server processes. Detailed explication of a sample blacklisting plugin. -- `Remap Plugin <../remap-plugin>`_ +- :doc:`Remap Plugin <../remap-plugin.en>` This chapter demonstrates on a practical example how you can exploit the Traffic Server remap API for your plugins. -- `Header-Based Plugin Examples <../header-based-plugin-examples>`_ +- :doc:`Header-Based Plugin Examples <../header-based-plugin-examples.en>` Detailed explanation about writing plugins that work on HTTP headers; discusses sample blacklisting and basic authorization plugins. -- `HTTP Transformation Plugins <../http-transformation-plugin>`_ +- :doc:`HTTP Transformation Plugins <../http-transformation-plugin.en>` Detailed explanation of the null-transform example; also discusses ``VConnections``, ``VIOs``, and IO buffers. -- `New Protocol Plugins <../new-protocol-plugins>`_ +- :doc:`New Protocol Plugins <../new-protocol-plugins.en>` Detailed explanation of a sample protocol plugin that supports a synthetic protocol. Discusses ``VConnections`` and mutexes, as well as the new ``NetConnection``, DNS lookup, logging, and cache APIs. @@ -85,44 +83,44 @@ Below is a section-by-section breakdown of this guide: The remaining sections comprise the API function reference and are organized by function type: -- `Miscellaneous Interface Guide <../misc-interface-guide>`_ +- :doc:`Miscellaneous Interface Guide <../misc-interface-guide.en>` Details error-writing and tracing functions, thread functions, and Traffic Server API versions of the ``malloc`` and ``fopen`` families. The Traffic Server API versions overcome various C library limitations. -- `HTTP Hooks and Transactions <../http-hoooks-and-transactions>`_ +- :doc:`HTTP Hooks and Transactions <../http-hooks-and-transactions.en>` Functions in this chapter hook your plugin to Traffic Server HTTP processes. -- `HTTP Headers <../http-headers>`_ +- :doc:`HTTP Headers <../http-headers.en>` Contains instructions for implementing performance enhancements for all plugins that manipulate HTTP headers. These functions examine and modify HTTP headers, MIME headers, URLs, and the marshal buffers that contain header information. If you are working with headers, then be sure to read this chapter. -- `Mutex Guide <../mutex-guide>`_ +- :doc:`Mutex Guide <../mutex-guide.en>` -- `Continuations <../continuations>`_ +- :doc:`Continuations <../continuations.en>` Continuations provide the basic callback mechanism and data abstractions used in Traffic Server. -- `Plugin Configurations <../plugin-configurations>`_ +- :doc:`Plugin Configurations <../plugin-configurations.en>` -- `Actions Guide <../actions-guide>`_ +- :doc:`Actions Guide <../actions-guide.en>` Describes how to use ``TSActions`` and the ``TSDNSLookup`` API. -- `IO Guide <../io-guide>`_ +- :doc:`IO Guide <../io-guide.en>` Describes how to use the Traffic Server IO interfaces: ``TSVConnection``, ``TSVIO``, ``TSIOBuffer``, ``TSNetVConnection``, the Cache API. -- `Plugin Management <../plugin-management>`_ +- :doc:`Plugin Management <../plugin-management.en>` These functions enable you to set up a configuration interface for plugins, access installed plugin files, and set up plugin licensing. -- `Adding Statistics <../adding-statistics>`_ +- :doc:`Adding Statistics <../adding-statistics.en>` These functions add statistics to your plugin. - `Function diff --git a/doc/sdk/remap-plugin.en.rst b/doc/sdk/remap-plugin.en.rst index 6506653f88d..9a22cc3c2f6 100644 --- a/doc/sdk/remap-plugin.en.rst +++ b/doc/sdk/remap-plugin.en.rst @@ -54,16 +54,16 @@ Required Functions A remap plugin is required to implement the following functions: -- ```TSRemapInit`` `__: +- `TSRemapInit `_: the remap initialization function, called once when the plugin is loaded -- ```TSRemapNewInstance`` `__: +- `TSRemapNewInstance `_: a new instance is created for each rule associated with the plugin. Called each time the plugin used in a remap rule (this function is what processes the pparam values) -- ```TSRemapDoRemap`` `__: +- `TSRemapDoRemap `_: the entry point used by Traffic Server to find the new URL to which it remaps; called every time a request comes in diff --git a/doc/sdk/sample-source-code.en.rst b/doc/sdk/sample-source-code.en.rst index 42be2a9a3aa..3568f410527 100644 --- a/doc/sdk/sample-source-code.en.rst +++ b/doc/sdk/sample-source-code.en.rst @@ -22,7 +22,7 @@ This appendix provides several source code examples. In the online formats of this book, function calls are linked to their references in the previous chapters. The following sample plugins are provided: -- `blacklist-1.c `__ +- `blacklist-1.c`_ blacklist-1.c ------------- diff --git a/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst b/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst index 606c1448ca3..0d8f7f3af3a 100644 --- a/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst +++ b/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst @@ -32,5 +32,5 @@ To load plugins, follow the steps below. 5. Restart Traffic Server. -For detailed information about each step above, refer to `A Simple -Plugin <../getting-started/a-simple-plugin>`__. +For detailed information about each step above, refer to +:doc:`../getting-started/a-simple-plugin.en`.