Added: incubator/trafficserver/site/trunk/docs/admin/trouble.htm URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/admin/trouble.htm?rev=831152&view=auto ============================================================================== --- incubator/trafficserver/site/trunk/docs/admin/trouble.htm (added) +++ incubator/trafficserver/site/trunk/docs/admin/trouble.htm Thu Oct 29 23:23:25 2009 @@ -0,0 +1,784 @@ + + +FAQs and Troubleshooting Tips + + + +

+Appendix G - FAQs and Troubleshooting Tips

+

+This appendix contains the following sections:

+ + +

+Frequently Asked Questions

+

+The following table lists the frequently asked questions (FAQs) discussed in this section.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+FAQs

+

+How do you create a raw disk for the cache if all your disks have mounted file systems?

+

+How do disk I/O errors affect the cache and what does Traffic Server do when a cache disk fails?

+

+ If a client disconnects during the time that Traffic Server is downloading a large object, is any of the object saved in the cache?

+

+Can Traffic Server cache Java applets, JavaScript programs, or other application files like VBScript?

+

+ How do you apply changes to the logs_xml.config file to all nodes in a cluster?

+

+In Squid- and Netscape-format log files, what do the cache result codes mean?

+

+What does the cqtx field record in a custom log file?

+

+Does Traffic Server refresh entries in its host database after a certain period of time if they haven't been used?

+

+Can you improve the look of your custom response pages by using images, animated .gifs, and Java applets?

+

+Can Traffic Server run in both forward proxy and reverse proxy mode at the same time?

+

+ How do you create a raw disk for the cache if all your disks have mounted file systems?

+

+ To create a raw disk:

+ +
    +
  1. + As root, enter the following command at the prompt to examine which file systems are mounted on the disk you want to use for the Traffic Server cache:
    + df -k
    +
  2. +
  3. + In a text editor, open the + /etc/fstab + file and comment out/delete the file system entries for the disk.
  4. +
  5. + Save and close the fstab file.
  6. +
  7. + Enter the following command for each file system you want to unmount:
    + umount file_system +
    + where file_system is a file system you want to unmount.

    +
  8. + Install Traffic Server. When the installation script prompts you for a cache disk, select the raw disk you just created.
  9. +
+ +

+How do disk I/O errors affect the cache and what does Traffic Server do when a cache disk fails?

+
+

If a disk drive fails five successive I/O operations, then Traffic Server considers the drive inaccessible and removes the whole disk from the cache. Normal cache operations continue for all other Traffic Server disk drives. +

+ +

+If a client disconnects during the time that Traffic Server is downloading a large object, is any of the object saved in the cache?

+
+

When a client disconnects during an HTTP operation, Traffic Server continues to download the object from the origin server for up to 10 seconds. If the transfer from the origin server completes successfully within 10 seconds after the client disconnect, then Traffic Server stores the object in the cache. If the origin server download does not complete successfully within 10 seconds, then Traffic Server disconnects from the origin server and deletes the object from the cache. Traffic Server does not store partial documents in the cache.

+ +

+Can Traffic Server cache Java applets, JavaScript programs, or other application files like VBScript?

+
+

Yes, Traffic Server can store and serve Java applets, JavaScript programs, VBScripts, and other executable objects from its cache according to the freshness and cacheability rules for HTTP objects. +
+Traffic Server does not execute the applets, scripts, or programs; these objects run only when the client system that sent the request loads them. + +

+ +

+How do you apply changes to the logs_xml.config file to all nodes in a cluster?

+
+

After you modify the + logs_xml.config + file on one Traffic Server node, enter the following command from the Traffic Server + bin +directory:
traffic_line -x + +

+Traffic Server applies the changes to all nodes in the cluster. The changes take effect immediately.

+

+In Squid- and Netscape-format log files, what do the cache result codes mean?

+
+

The following table describes the cache result codes in Squid and Netscape log files.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ Cache Result Code

+
+

+ Description

+
+

+ TCP_HIT

+
+

+ A valid copy of the requested object was in the cache and Traffic Server sent the object to the client.

+
+

+ TCP_MISS

+
+

+ The requested object was not in the cache, so Traffic Server retrieved the object from the origin server or a parent proxy and sent it to the client.

+
+

+ TCP_REFRESH_HIT

+
+

+ The object was in the cache but was stale. Traffic Server made an + if-modified-since + request to the origin server and the origin server sent a + 304 not-modified + response. Traffic Server sent the cached object to the client.

+
+

+ TCP_REF_FAIL_HIT

+
+

+ The object was in the cache but was stale. Traffic Server made an + if-modified-since + request to the origin server but the server did not respond; Traffic Server sent the cached object to the client.

+
+

+ TCP_REFRESH_MISS

+
+

+ The object was in the cache but was stale. Traffic Server made an + if-modified-since + request to the origin server and the server returned a new object; Traffic Server served the new object to the client.

+
+

+ TCP_CLIENT_REFRESH

+
+

+ The client issued a request with a no-cache header. Traffic Server obtained the requested object from the origin server and sent a copy to the client. Traffic Server deletes any previous copy of the object from the cache.

+
+

+ TCP_IMS_HIT

+
+

+ The client issued an + if-modified-since + request and the object was in the cache and fresher than the IMS date, or an + if-modified-since + request to the origin server found that the cache object was fresh. Traffic Server served the cached object to the client.

+
+

+ TCP_IMS_MISS

+
+

+ The client issued an + if-modified-since + request and the object was either not in cache or was stale in cache. Traffic Server sent an + if-modified-since + request to the origin server and received the new object. Traffic Server sent the updated object to the client.

+
+

+ TCP_SWAPFAIL

+
+

+ The object was in the cache but could not be accessed. The client did not receive the object.

+
+

+ ERR_CLIENT_ABORT

+
+

+ The client disconnected before the complete object was sent.

+
+

+ ERR_CONNECT_FAIL

+
+

+ Traffic Server could not reach the origin server.

+
+

+ ERR_DNS_FAIL

+
+

+ The Domain Name Server could not resolve the origin server name, or no Domain Name Server could be reached.

+
+

+ ERR_INVALID_REQ

+
+

+ The client HTTP request was invalid. Traffic Server forwards requests with unknown methods to the origin server.

+
+

+ ERR_READ_TIMEOUT

+
+

+ The origin server did not respond to the Traffic Server request within the timeout interval.

+
+

+ ERR_PROXY_DENIED

+
+

+ Client service was denied.

+
+

+ ERR_UNKNOWN

+
+

+ The client connected but subsequently disconnected without sending a request.

+
+

+What is recorded by the cqtx field in a custom log file?

+
+

In forward proxy mode, the + cqtx + field records the complete client request in the log file: for example, + GET http://www.company.com HTTP/1.0 + . In reverse proxy mode, the + cqtx + field records the hostname or IP address of the origin server because Traffic Server first remaps the request as per map rules in the + remap.config +file.

+ +

+Does Traffic Server refresh entries in its host database after a certain period of time if they have not been used?

+
+

By default, the Traffic Server host database observes the time-to-live (ttl) values set by name servers. You can reconfigure Traffic Server to ignore the ttl set by name servers and use a specific Traffic Server setting instead. Alternatively, you can configure Traffic Server to compare the ttl value set by the name server with the ttl value set by Traffic Server, and then use either the lower or the higher value.

+ +

To adjust the host database settings:

+ +
    + +
  1. In a text editor, open the + records.config + file located in the Traffic Server + config + directory.
  2. +
  3. + Set the value of the variable + proxy.config.hostdb.ttl_mode + to:
  4. + + + +
  5. + Save and close the + records.config + file. +
    + From the Traffic Server + bin + directory, run the command + traffic_line -x + to apply the configuration changes. +
  6. +
+ +

+Can you improve the look of your custom response pages by using images, animated .gifs, and Java applets?

+
+

No, because Traffic Server can only respond to clients with a single text or HTML document. As a workaround, however, you can provide references on your custom response pages to images, animated .gifs, Java applets, or objects other than text that are located on a web server. Add links in the + body_factory +template files in the same way you do for any image in an HTML document, with the full URL in the SRC attribute.

+ +

+Can Traffic Server run in both forward proxy and reverse proxy mode at the same time?

+
+

+ Yes. When you enable reverse proxy mode, Traffic Server remaps incoming requests according to the map rules in the + remap.config + file. All other requests that do not match a map rule are simply served in forward proxy mode.
+ If you want to run in reverse proxy + only + mode (where Traffic Server does not serve requests that fail to match a map rule), then you must set the configuration variable + proxy.config.url_remap.remap_required + to 1 in the + records.config +file.

+

+ +Troubleshooting Tips

+

+The following table lists the troubleshooting tips discussed in this section.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ Troubleshooting Tip

+

+ The throughput statistic is inaccurate

+

+ You are unable to execute Traffic Line commands

+

+ You observe inconsistent behavior when one node obtains an object from another node in the cluster

+

+ Web browsers might display an error document with a data missing message

+

+ Traffic Server does not resolve any websites

+

+ Maximum document size exceeded message in the system log file

+

+ DrainIncomingChannel message in the system log file

+

+ No cop file message in the system log file

+

+ Warning in system log file when manually editing vaddrs.config

+

+ Nontransparent requests fail after enabling always_query_destination

+

+ Traffic Server is running but no log files are created

+

+ Traffic Server shows an error indicating too many network connections

+

+ Low memory symptoms

+

+ Connection timeouts with the origin server

+

+ IBM Web servers do not work with Traffic Server

+

 

+
+ +

+The throughput statistic is inaccurate

+
+

Traffic Server updates the throughput statistic after it has transferred an entire object. For larger files, the byte count increases sharply at the end of a transfer. The complete number of bytes transferred is attributed to the last 10-second interval, although it can take several minutes to transfer the object. This inaccuracy is more noticeable with a light load. A heavier load yields a more accurate statistic.

+ +

+You are unable to execute Traffic Line commands

+
+

+Traffic Line commands do not execute under the following conditions:

+ + +

+You observe inconsistent behavior when one node obtains an object from another node in the cluster

+
+

As part of the initial system preparation process, you must synchronize the clocks on all the nodes in your cluster. Minor time differences cause no problems, but differences of more than a few minutes can affect Traffic Server operation.

+

+ You should run a clock synchronization daemon such as + xntpd + . You can obtain the latest version of + xntpd +from the following URL:
+http://www.eecis.udel.edu/~ntp/
+

+

+Web browsers might display an error document with a data missing message

+
+A message similar to the following displays in web browsers: +
+ Data Missing
+ +This document resulted from a POST operation and has expired from the cache. If you wish you can repost the form data to re-create the document by pressing the reload button.
+

+ This is a Web browser issue and not a problem with Traffic Server. Because Web browsers maintain a separate local cache in memory and/or disk on the client system, messages about documents that have expired from cache refer to the browser's local cache and + not +to the Traffic Server cache. There is no Traffic Server message or condition that can cause such messages to appear in a web browser.

+ +

+Traffic Server does not resolve any websites

+
+

The browser indicates that it is contacting the host and then times out with the following message:

+
+

+ + The document contains no data; Try again later, or contact the server's Administrator.... +

+
+

+Make sure the system is configured correctly and that Traffic Server can read the name resolution file:

+ + +

+Maximum document size exceeded message in the system log file

+
+

The following message appears in the system log file:

+
+

+ + WARNING: Maximum document size exceeded +

+
+

+A requested object was larger than the maximum size allowed in the Traffic Server cache, so Traffic Server provided proxy service for the oversized object but did not cache it. To set the object size limit for the cache, modify the + proxy.config.cache.limits.http.max_doc_size + variable in the + records.config +file. If you do not want to limit the size of objects in the cache, then set the document size to 0(zero).

+ +

+DrainIncomingChannel message in the system log file

+
+

The following messages appear in the system log file:

+
+

+ Feb 20 23:53:40 louis traffic_manager[4414]: ERROR ==> +

+

+ [drainIncomingChannel] Unknown message: 'GET http://www.telechamada.pt/ +

+

+ HTTP/1.0'

+

+ Feb 20 23:53:46 louis last message repeated 1 time

+

+ Feb 20 23:53:58 louis traffic_manager[4414]: ERROR ==> +

+

+ [drainIncomingChannel] Unknown message: 'GET http://www.ip.pt/ HTTP/1.0' +

+
+

+These error messages indicate that a browser is sending HTTP requests to one of the Traffic Server cluster ports - either rsport (default port 8088) or mcport (default port 8089). Traffic Server discards the request; this error does not cause any Traffic Server problems. The misconfigured browser must be reconfigured to use the correct proxy port. Traffic Server clusters work best when configured to use a separate network interface and cluster on a private subnet, so that client machines have no access to the cluster ports.

+ +

+No cop file message in the system log file

+
+

The following message appears repeatedly in the system log file:

+
+

+ traffic_cop[16056]: encountered "config/internal/no_cop" file...exiting +

+
+

+ The file config/internal/no_cop acts as an administrative control that instructs the traffic_cop process to exit immediately without starting traffic_manager or performing any health checks. The no_cop file prevents Traffic Server from starting automatically when it has been stopped with the stop_traffic_server command. Without such a static control, Traffic Server would restart automatically upon system reboot. The no_cop control keeps Traffic Server off until it is explicitly restarted with the +start_traffic_server command.

+

+ The Traffic Server installation script also creates a + no_cop + file so that Traffic Server does not start automatically. After you have completed installation and configuration, and have rebooted the operating system, use the + start_traffic_server +command to start Traffic Server.

+ +

+Warning in system log file when manually editing vaddrs.config

+
+

If you manually edit the + vaddrs.config +file as a nonroot user, then Traffic Server issues a warning message in the system log file similar to the following:

+
+

+ + WARNING: interface is ignored: Operation not permitted +

+
+

+You can safely ignore this message; Traffic Server does apply your configuration edits.

+ +

+Nontransparent requests fail after enabling always_query_destination

+
+

The variable + proxy.config.arm.always_query_dest + in the + records.config +file configures Traffic Server in transparent mode to ignore host headers and always ask for the IP address of the origin server. When you enable this variable, Traffic Server obtains the origin server IP address from the existing NAT map list rather than trying to resolve the destination hostname with a DNS lookup. As a result, logged URLs contain only IP addresses and no hostnames. However, explicit requests (nontransparent requests, including requests on port 80) fail, as there is no matching map in the NAT list. The always_query_destination option works only on the primary proxy port.

+ +

+Traffic Server is running but no log files are created

+
+

Traffic Server only writes event log files when there is information to record. If Traffic Server is idle, then it's possible/probable that no log files exist. In addition: +

+
  • Ensure that you are looking in the correct directory. By default, Traffic Server creates log files in its + logs + directory.
  • +
  • Check the location of the log files by checking the value of the variable + proxy.config.log2.logfile_dir in the + records.config +file.
  • Check that the log directory has read/write permissions for the Traffic Server user account. If the log directory does not have the correct permissions, then the + traffic_server +process is unable to open or create log files.
  • +
  • Check that logging is enabledby checking the value of the variable + proxy.config.log2.logging_enabled + in the + records.config +file.
  • +
  • Check that a log format is enabled. In the + records.config + file, select the standard or custom format by editing variables in the + Logging Config + section.
  • + +

    +Traffic Server shows an error indicating too many network connections

    +
    +

    +By default, Traffic Server supports 8000 network connections: half of this number is allocated for client connections and half for origin server connections. A connection throttle event occurs when client or origin server connections reach 90% of half the configured limit (3600 by default). When a connection throttle event occurs, Traffic Server continues processing all existing connections but will not accept new client connection requests until the connection count falls below the limit.

    +

    +Connection throttle events can occur under the following conditions:

    + +

    + If necessary, you can reset the maximum number of connections supported by Traffic Server by editing the value of the configuration variable proxy.config.net.connections_throttle in the +records.config file. Do not increase the connection throttle limit unless the system has adequate memory to handle the client connections required. A system with limited RAM might need a throttle limit lower than the default value. Do not set this variable below the minimum value of 100.

    + +

    +Low memory symptoms

    +
    +

    Under heavy load, the Linux kernel can run out of RAM. The low memory condition can cause slow performance and a variety of system problems. RAM exhaustion can occur even if the system has plenty of free swap space.

    +

    + Symptoms of extreme memory exhaustion include the following messages in the system log files ( + /var/log/messages +):

    +
    +

    + WARNING: errno 105 is ENOBUFS (low on kernel memory), consider a memory upgrade +

    +

    + kernel: eth0: can't fill rx buffer (force 0)! +

    +

    + kernel: recvmsg bug: copied E01BA916 seq E01BAB22 +

    +
    +

    +To avoid memory exhaustion, add more RAM to the system or reduce the load on Traffic Server.

    + +

    +Connection timeouts with the origin server

    +
    +

    Certain origin servers take longer than 30 seconds to post HTTP requests, which results in connection timeouts with Traffic Server. To prevent such connection timeouts, you must change the value of the configuration variable + proxy.config.http.connect_attempts_timeout + in the + records.config +file to 60 seconds or more.

    + +

    +IBM Web servers do not work with Traffic Server

    +
    +

    +IBM web servers do not support the TLS (Transport Layer Security) protocol. For IBM web servers to work with Traffic Server, you must edit a configuration variable.

    + +

    To configure Traffic Server to work with IBM web servers:

    +
      +
    1. + In a text editor, open the records.config file located in the Traffic Server config directory.
    2. +
    3. Edit the following configuration variable:
      + + + + + + + + + +
      +

      + Variable

      +
      +

      + Description

      +
      +

      + proxy.config.ssl.TLSv1

      +
      +

      Set this variable to 0 (zero).

      +
      +
    4. Save and close the + records.config + file.
    5. +
    6. + Navigate to the Traffic Server bin directory.
    7. +
    8. + Run the command + traffic_line -x + to apply the configuration changes.
    9. +
    + + Propchange: incubator/trafficserver/site/trunk/docs/admin/trouble.htm ------------------------------------------------------------------------------ svn:executable = * Added: incubator/trafficserver/site/trunk/docs/sdk/ASimplePlugin.html URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/ASimplePlugin.html?rev=831152&view=auto ============================================================================== --- incubator/trafficserver/site/trunk/docs/sdk/ASimplePlugin.html (added) +++ incubator/trafficserver/site/trunk/docs/sdk/ASimplePlugin.html Thu Oct 29 23:23:25 2009 @@ -0,0 +1,156 @@ + + + +A Simple Plugin + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +Home +

    Traffic Server Software Developers Kit

    +
    + +
    +
    +

    +A Simple Plugin

    +

    This section describes how to write, compile, configure, and run a + simple Traffic Server plugin. You’ll follow the steps below:

    +
      +
    1. Make sure that your plugin source code contains an + INKPluginInit initialization function.

    2. +
    3. Compile your plugin source code, creating a shared + library.

    4. +
    5. Add an entry to the plugin.config file + for your plugin.

    6. +
    7. Add the path to your plugin shared library to the + records.config file.

    8. +
    9. Restart Traffic Server.

    10. +
    +
    +

    +Compile Your Plugin

    +

    The process you use to compile a shared library will vary from + platform to platform, so the Traffic Server API includes makefile + templates you can use to create shared libraries on all the supported + Traffic Server platforms.

    +
    +

    +Unix Example

    +

    :Assuming the sample program is stored in the file + hello-world.c, you could use the following + commands to building a shared library on Solaris using the GNU C + compiler.

    +
    gcc -g -Wall -fPIC -o hello-world.o -c hello-world.c
    +gcc -g -Wall -shared -o hello-world.so hello-world.o
    +

    The first command compiles hello-world.c + as Position Independent Code (PIC) and the second command links the + single hello-world.o object file into the + hello-world.so shared library.

    +
    + + + + + +
    [Caution]Caution

    Make sure that your plugin is not statically linked with + system libraries.

    +
    +
    +

    +HPUX Example

    +

    Assuming the sample program is stored in the file + hello_world.c, you could use the following + commands to build a shared library on HPUX:

    +
    cc +z -o hello_world.o -c hello_world.c
    +ld -b -o hello_world.so hello_world.o
    +
    +
    +

    +Compiling for Windows NT

    +

    Your PC must have the following software installed:

    +
      +
    • Windows NT 4.0 SP4

    • +
    • Microsoft Developer Studio 6.0

    • +
    +
    +To compile a plugin for the Windows NT version of + Traffic Server:
    +
      +
    1. Open PlugIn.dsw with Microsoft Visual + C++ (MSVC++). The dsw file should be + included in the SDK CD. Inside VC++, the sample plugins are + listed as separate projects.

    2. +
    3. +

      For each of the projects that need to be built, you need + to tell VC++ where it can find the Traffic Server library: + traffic_server.lib. This library is in your NT + Traffic Server distribution.

      +

      You might need to update the library lookup path. Use the + following procedure:

      +
    4. +
    +
    +To update the library lookup path:
    +
      +
    1. Right-mouse-click on a project.

    2. +
    3. Select the Settings... option.

    4. +
    5. Click the Link tab on the dialog + box.

    6. +
    7. Select Input in the combo-box.

    8. +
    9. Enter the library path in the Additional library + path: text field. Now you can build your + plugin.

    10. +
    +
    +
    +
    + + Propchange: incubator/trafficserver/site/trunk/docs/sdk/ASimplePlugin.html ------------------------------------------------------------------------------ svn:keywords = Id Added: incubator/trafficserver/site/trunk/docs/sdk/AccessPluginFiles.html URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/AccessPluginFiles.html?rev=831152&view=auto ============================================================================== --- incubator/trafficserver/site/trunk/docs/sdk/AccessPluginFiles.html (added) +++ incubator/trafficserver/site/trunk/docs/sdk/AccessPluginFiles.html Thu Oct 29 23:23:25 2009 @@ -0,0 +1,126 @@ + + + +Accessing Installed Plugin Files + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +Home +

    Traffic Server Software Developers Kit

    +
    + +
    +
    +

    +Accessing Installed Plugin Files

    +

    Your plugin might rely on files in addition to its source code, + such as configuration files. When you upgrade Traffic Server, you might + need to make sure your plugin is always able to find its associated + files. The mechanism for preserving relative file locations with + upgrades is the following:

    +
    +

    The format of the plugin.db file is as + follows:

    +
    [name of your plugin]
    +Object=[name of plugin’s shared object file
    +License=[license key]
    +Dir=[name of any directories to be copied over] 
    +
    +

    For example, suppose that you have a blacklist plugin in the + plugin directory. Its object file is Blacklist.so + and it has some user interface files (images and HTML files) in the + Blacklist/ui directory. To make sure that the + blacklist plugin is upgraded properly, plugin.db + needs the following entry:

    +
    [Blacklist plugin]
    +Object=Blacklist.so
    +License=ABCD0123456789
    +Dir=Blacklist/ui
    +

    In this example, if all of the necessary files and directories are + in the Blacklist directory, you could simply specify + Dir=Blacklist.

    +

    This means that the Blacklist image and HTML files are always + located in:

    +

    <Traffic Server install + directory>/<plugin + directory>/Blacklist/ui

    +

    Your plugin might need to specify the absolute location of its + associated files. The following functions provide the Traffic Server + install directory path and plugin directory path:

    +
    +
    + + Propchange: incubator/trafficserver/site/trunk/docs/sdk/AccessPluginFiles.html ------------------------------------------------------------------------------ svn:keywords = Id Added: incubator/trafficserver/site/trunk/docs/sdk/AccessingTransactionProc.html URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/AccessingTransactionProc.html?rev=831152&view=auto ============================================================================== --- incubator/trafficserver/site/trunk/docs/sdk/AccessingTransactionProc.html (added) +++ incubator/trafficserver/site/trunk/docs/sdk/AccessingTransactionProc.html Thu Oct 29 23:23:25 2009 @@ -0,0 +1,97 @@ + + + +Accessing the Transaction Being Processed + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +Home +

    Traffic Server Software Developers Kit

    +
    + +
    +
    +

    +Accessing the Transaction Being Processed

    +

    A continuation’s handler function is of type + INKEventFunc, and the prototype is as follows:

    +
    static int function_name (INKCont contp, INKEvent event, void *edata)
    +

    In general, the return value of the handler function is not + used. The continuation argument is the continuation being called back, + the event is the event being sent to the continuation, and the data + pointed to by void *edata depends on the type of event. The data types + for each event type are listed in “Writing Handler Functions”.

    +

    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 + INKHttpTxn (a data type that represents HTTP transactions). + Your plugin can then do things with the transaction. Here’s how it + looks in the Blacklist plugin’s handler’s code:

    +
    static int
    +blacklist_plugin (INKCont contp, INKEvent event, void *edata)
    +{
    +     INKHttpTxn txnp = (INKHttpTxn) edata; 
    +     switch (event) {
    +          case INK_EVENT_HTTP_OS_DNS:
    +               handle_dns (txnp, contp);
    +               return 0;
    +          case INK_EVENT_HTTP_SEND_RESPONSE_HDR:
    +               handle_response (txnp);
    +               return 0;
    +          case INK_EVENT_MGMT_UPDATE:
    +               read_blacklist ();
    +               return 0;
    +          default:
    +               break;
    +     }
    +     return 0;
    +}
    +

    When, for example, the origin server DNS lookup event is sent, + blacklist_plugin can call handle_dns and pass txnp as an + argument.

    +
    + + Propchange: incubator/trafficserver/site/trunk/docs/sdk/AccessingTransactionProc.html ------------------------------------------------------------------------------ svn:keywords = Id Added: incubator/trafficserver/site/trunk/docs/sdk/ActionFunctions.html URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/ActionFunctions.html?rev=831152&view=auto ============================================================================== --- incubator/trafficserver/site/trunk/docs/sdk/ActionFunctions.html (added) +++ incubator/trafficserver/site/trunk/docs/sdk/ActionFunctions.html Thu Oct 29 23:23:25 2009 @@ -0,0 +1,89 @@ + + + +Action Functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +Home +

    Traffic Server Software Developers Kit

    +
    + +
    +
    +

    +Action Functions

    +

    +
    +

    +INKActionCancel

    +

    Cancels an action.

    +
    +
    Prototype
    +

    INKReturnCode INKActionCancel (INKAction + actionp)

    +
    Description
    +

    Cancels an INKAction. If a NULL argument is + passed to INKActionCancel, Traffic Server + will crash and will not return INK_ERROR. Note that + it is the programmer’s responsibility to ensure that a non-null + value is passed to INKActionCancel.

    +
    Returns
    +
    +

    INK_SUCCESS if the action is successfully + cancelled.

    +

    INK_ERROR if an error occurs.

    +
    +
    First release
    +

    Traffic Server 3.0

    +
    +
    +
    + + Propchange: incubator/trafficserver/site/trunk/docs/sdk/ActionFunctions.html ------------------------------------------------------------------------------ svn:keywords = Id Added: incubator/trafficserver/site/trunk/docs/sdk/ActionsGuide.html URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/ActionsGuide.html?rev=831152&view=auto ============================================================================== --- incubator/trafficserver/site/trunk/docs/sdk/ActionsGuide.html (added) +++ incubator/trafficserver/site/trunk/docs/sdk/ActionsGuide.html Thu Oct 29 23:23:25 2009 @@ -0,0 +1,223 @@ + + + +Chapter 14. Actions Guide + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +Home +

    Traffic Server Software Developers Kit

    +
    + +
    +
    +

    +Chapter 14. Actions Guide

    +
    +

    Table of Contents

    +
    +
    Actions
    +
    Hosts Lookup API
    +
    +
    +

    This chapter contains:

    +
    +
    +

    +Actions

    +

    An action is a handle to an operation initiated by a plugin which + has not yet completed. For example, when a plugin connects to a remote + server it uses the call INKNetConnect which takes + an INKCont as an argument to call back when the + connection is established. INKNetConnect might not + call the continuation back immediately and will return an + INKAction structure which the caller can use to + cancel the operation. Cancelling the operation does not necessarily mean + that the operation will not occur, but that the continuation passed in + to the operation will not be called back. In the above example, the + connection might still occur if the action is cancelled, but the + continuation that initiated the connection would not be called back when + that occurred.

    +

    It is possible that the connection, in the preceding example, will + complete and callback the continuation before + INKNetConnect returns. If this occurs + INKNetConnect will return a special action which + will cause INKActionDone to return 1. Basically + this is specifying that the operation has already completed. There is no + point in trying to cancel the operation. Note that an action will never + change from non-completed to completed. When the operation actually + succeeds and the continuation is called back it is up to the + continuation to zero out its action pointer to indicate to itself that + the operation succeeded.

    +

    The asynchronous nature of all operations in Traffic Server + necessitates actions. You should notice from the above discussion that + once a call to a function like INKNetConnect is + made by a continuation and that function returns a valid action + (INKActionDone returns 0) then it is not safe for + the continuation to do anything else except return from its handler + function. It is not safe to modify or examine the continuation’s data + since the continuation may have already been destroyed.

    +

    Here is an example of a typical usage of an action:

    +
    #include “InkAPI.h”
    +static int
    +handler (INKCont contp, INKEvent event, void *edata)
    +{
    +   if (event == INK_EVENT_IMMEDIATE) {
    +      INKAction actionp = INKNetConnect (contp, 127.0.0.1, 9999);
    +      if (!INKActionDone (actionp)) {
    +   INKContDataSet (contp, actionp);
    +   } else {
    +          /* we've already been called back... */
    +   return 0;
    +   }
    +   } else if (event == INK_EVENT_NET_CONNECT) {
    +      /* net connection succeeded */
    +      INKContDataSet (contp, NULL);
    +      return 0;
    +   } else if (event == INK_EVENT_NET_CONNECT_FAILED) {
    +   /* net connection failed */
    +   INKContDataSet (contp, NULL);
    +   return 0;
    +   } 
    +   return 0;
    +}
    +
    +void
    +INKPluginInit (int argc, const char *argv[])
    +{
    +    INKCont contp;
    +
    +    contp = INKContCreate (handler, INKMutexCreate ());
    +
    +    /* We don't want to call things out of INKPluginInit
    +       directly since it is called before the rest of the
    +       system is initialized. We'll simply schedule an event
    +       on the continuation to occur as soon as the rest of
    +       the system is started up. */
    +    INKContSchedule (contp, 0);
    +}
    +

    The preceding example shows a simple plugin which creates a + continuation and schedules it to be called immediately. When the + plugin’s handler function is called the first time the event will be + INK_EVENT_IMMEDIATE. The plugin then tries to open a net + connection to port 9999 on localhost (127.0.0.1). I’ve left the IP + description in dot notation to make it clearer what is going on. Please + note that the above won’t actually compile until the IP address is + modified. The action returned from INKNetConnect is + examined by the plugin. If the operation has not completed the plugin + stores the action in its continuation. Otherwise the plugin knows it has + already been called back and there is no reason to store the action + pointer.

    +

    A final question might be why would a plugin want to cancel an + action. In the above example a valid reason would be to place a time + limit on how long it takes to open a connection. The plugin could + schedule itself to get called back in 30 seconds and then initiate the + net connection. If the time-out expires first then the plugin would + cancel the action. The following sample code implements this:

    +
    #include “InkAPI.h”
    +static int
    +handler (INKCont contp, INKEvent event, void *edata)
    +{
    +   switch (event) {
    +	case (INK_EVENT_IMMEDIATE):
    +      INKContSchedule (contp, 30000);
    +      INKAction actionp = INKNetConnect(contp, 127.0.0.1, 9999);
    +      if (!INKActionDone (actionp)) {
    +         INKContDataSet (contp, actionp);
    +      } else {
    +         /* we’ve already been called back ... */
    +      }
    +      break;
    +
    +   case (INK_EVENT_TIMEOUT):
    +      INKAction actionp = INKContDataGet (contp);
    +      if (!INKActionDone(actionp)) {
    +         INKActionCancel (actionp);
    +      }
    +      break;
    +
    +   case (INK_EVENT_NET_CONNECT):
    +   /* net connection succeeded */
    +      INKContDataSet (contp, NULL);
    +      break;
    +
    +   case (INK_EVENT_NET_CONNECT_FAILED):
    +   /* net connection failed */
    +      INKContDataSet (contp, NULL);
    +      break;
    +
    +   } 
    +   return 0;
    +}
    +
    +void
    +INKPluginInit (int argc, const char *argv[])
    +{
    +    INKCont contp;
    +
    +    contp = INKContCreate (handler, INKMutexCreate ());
    +    /* We don't want to call things out of INKPluginInit
    +       directly since it is called before the rest of the
    +       system is initialized. We'll simply schedule an event
    +       on the continuation to occur as soon as the rest of
    +       the system is started up. */
    +    INKContSchedule (contp, 0);
    +}
    +

    The action functions are:

    + +
    +
    + + Propchange: incubator/trafficserver/site/trunk/docs/sdk/ActionsGuide.html ------------------------------------------------------------------------------ svn:keywords = Id Added: incubator/trafficserver/site/trunk/docs/sdk/ActivateContinuations.html URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/ActivateContinuations.html?rev=831152&view=auto ============================================================================== --- incubator/trafficserver/site/trunk/docs/sdk/ActivateContinuations.html (added) +++ incubator/trafficserver/site/trunk/docs/sdk/ActivateContinuations.html Thu Oct 29 23:23:25 2009 @@ -0,0 +1,76 @@ + + + +How to Activate Continuations + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +Home +

    Traffic Server Software Developers Kit

    +
    + +
    +
    +

    +How to Activate Continuations

    +

    Continuations are activated when they receive an event or by + INKContSchedule, which schedules a continuation to + receive an event. They might receive an event because:

    +
    +
    + + Propchange: incubator/trafficserver/site/trunk/docs/sdk/ActivateContinuations.html ------------------------------------------------------------------------------ svn:keywords = Id