Added: websites/staging/trafficserver/trunk/content/docs/trunk/admin/configuration-files/hosting.config.en.html ============================================================================== --- websites/staging/trafficserver/trunk/content/docs/trunk/admin/configuration-files/hosting.config.en.html (added) +++ websites/staging/trafficserver/trunk/content/docs/trunk/admin/configuration-files/hosting.config.en.html Wed Mar 23 01:14:34 2011 @@ -0,0 +1,3671 @@ + + + + + + + + + + Configuration Files + + + + + + + + + +
+ +
+

Available Languages: [LANG]

+

Appendix E - Configuration Files

+

This appendix describes Traffic Server configuration files that you can edit.

+ +

bypass.config

+

The bypass.config file contains static bypass rules that Traffic Server +uses in transparent proxy caching mode. Static bypass rules instruct +Traffic Server to bypass certain incoming client requests so they are +served by the origin server. The bypass.config file also accepts +Dynamic Deny Bypass Rules.

+

You can configure three types of static bypass rules: +- Source bypass rules configure Traffic Server to bypass a particular + source IP address or range of IP addresses. For example: bypass + clients that do not want to use caching. +- Destination bypass rules configure Traffic Server to bypass a + particular destination IP address or range of IP addresses. For + example: bypass origin servers that use IP authentication based on the + client's real IP address. + IMPORTANT: Destination bypass rules prevent Traffic Server from + caching an entire site. You will experience hit rate impacts if the + site you bypass is popular. +- Source/destination pair bypass rules configure Traffic Server to + bypass requests that originate from the specified source to the + specified destination. For example: route around specific + client-server pairs that experience broken IP authentication or + out-of-band HTTP traffic problems when cached. Source/destination + bypass rules can be preferable to destination rules because they block + a destination server only for users that experience problems.

+

IMPORTANT: After you modify the bypass.config file, you must restart +Traffic Server.

+

Format

+

Bypass rules follow the format below:

+
bypass src ipaddress | dst ipaddress | src ipaddress AND dst ipaddress
+
+ + +

The following list describes the variables.

+
+
src ipaddress
+
Specifies the source (client) IP address in incoming requests Traffic
+
+

Server must bypass.

+

The variable ipaddress can be one of the following:

+ +
+
dst ipaddress
+
Specifies the destination (origin server) IP address in incoming
+
+

requests Traffic Server must bypass.

+

The variable ipaddress can be one of the following:

+ +
+
src ipaddress AND dst ipaddress
+
Specifies the source and destination IP address pair Traffic Server must
+
+

bypass.

+

The variable ipaddress must be a single IP address, such as 123.45.67.8

+

Dynamic Deny Bypass Rules #### {#dynamic.bypass_rules}

+

In addition to static bypass rules, the bypass.config file also accepts +dynamic deny bypass rules that prevent Traffic Server from bypassing +certain incoming client requests dynamically (a deny bypass rule can +prevent Traffic Server from bypassing itself). Dynamic deny bypass rules +can be source, destination, or source/destination and have the following +format:

+
deny_dyn_bypass src ipaddress | dst ipaddress | src ipaddresss AND ipaddress
+
+ + +

For a description of the options, refer to the table above. For the +dynamic deny bypass rules to work, you must set the variable +proxy.config.arm.bypass_dynamic_enabled to 1 in the +records.config file.

+

IMPORTANT: Static bypass rules overwrite dynamic deny bypass rules. If a +static bypass rule and a dynamic bypass rule contain the same IP address, +then the dynamic deny bypass rule will be ignored.

+

Examples

+

The following example shows source, destination, and source/destination +bypass rules:

+
bypass src 1.1.1.0/24, 25.25.25.25, 128.252.11.11-128.252.11.255
+bypass dst 24.24.24.0/24
+bypass src 25.25.25.25 AND dst 24.24.24.0
+
+ + +

The following example shows source, destination, and source/destination +dynamic deny bypass rules:

+
deny_dyn_bypass src 128.252.11.11-128.252.11.255
+deny_dyn_bypass dst 111.111.11.1
+deny_dyn_bypass src 111.11.11.1 AND dst 111.11.1.1
+
+ + +

cache.config

+

The cache.config file defines how Traffic Server caches web objects. You +can add caching rules to specify the following: +- Not to cache objects from specific IP addresses +- How long to pin particular objects in the cache +- How long to consider cached objects as fresh +- Whether to ignore no-cache directives from the server

+

IMPORTANT: After you modify the cache.config file, navigate to the Traffic +Server bin directory; then run the traffic_line -x command to apply +changes. When you apply the changes to a node in a cluster, Traffic Server +automatically applies the changes to all other nodes in the cluster.

+

Format

+

Each line in the cache.config file contains a caching rule. Traffic Server +recognizes three space-delimited tags:

+
primary_destination=value secondary_specifier=value action=value
+
+ + +

You can use more than one secondary specifier in a rule. However, you +cannot repeat a secondary specifier. +The following list shows the possible primary destinations with allowed values.

+
+
dest_domain
+
A requested domain name. Traffic Server matches the domain name of the
+
+

destination from the URL in the request.

+
+
dest_host
+
A requested hostname. Traffic Server matches the hostname of the
+
+

destination from the URL in the request.

+
+
dest_ip
+
A requested IP address. Traffic Server matches the IP address of the
+
+

destination in the request.

+
+
url_regex
+
A regular expression (regex) to be found in a URL.
+
+

The secondary specifiers are optional in the cache.config file. The +following list shows possible secondary specifiers with allowed values.

+
+
port
+
A requested URL port.
+
scheme
+
A request URL protocol: http or https.
+
prefix
+
A prefix in the path part of a URL.
+
suffix
+
A file suffix in the URL.
+
method
+
A request URL method: get, put, post, trace.
+
time
+
A time range, such as 08:00-14:00.
+
src_ip
+
A client IP address.
+
+

The following list shows possible actions and their allowed values.

+
+
action
+
One of the following values:
+
+

never-cache configures Traffic Server to never cache specified objects.
+ignore-no-cache configures Traffic Server to ignore all + Cache-Control: no-cache headers.
+ignore-client-no-cache configures Traffic Server to ignore + Cache-Control: no-cache headers from client requests.
+ignore-server-no-cache configures Traffic Server to ignore + Cache-Control: no-cache headers from origin server responses.

+
+
pin-in-cache
+
The amount of time you want to keep the object(s) in the cache. The
+
+

following time formats are allowed:

+

d for days; for example: 2d + h for hours; for example: 10h + m for minutes; for example: 5m + s for seconds; for example: 20s + mixed units; for example: 1h15m20s

+
+
revalidate
+
The amount of time object(s) are to be considered fresh. Use the same
+
+

time formats as pin-in-cache.

+
+
ttl-in-cache
+
The amount of time object(s) are to be kept in the cache, regardless of
+
+

Cache-Control response headers. Use the same time formats as + pin-in-cache and revalidate .

+

Examples

+

The following example configures Traffic Server to revalidate gif and jpeg +objects in the domain mydomain.com every 6 hours, and all other objects in +mydomain.com every hour. The rules are applied in the order listed.

+
dest_domain=mydomain.com suffix=gif revalidate=6h
+dest_domain=mydomain.com suffix=jpeg revalidate=6h
+dest_domain=mydomain.com revalidate=1h
+
+ + +

congestion.config

+

The congestion.config file enables you to configure Traffic Server to stop +forwarding HTTP requests to origin servers when they become congested, and +then send the client a message to retry the congested origin server later. +After you modify the congestion.control file, navigate to the Traffic +Server bin directory; then run the traffic_line -x command to apply +changes. When you apply the changes to a node in a cluster, Traffic Server +automatically applies the changes to all other nodes in the cluster. +Traffic Server uses the congestion.config file only if you enable the +Congestion Control option.

+

You can create rules in the congestion.config file to specify: +- Which origin servers Traffic Server tracks for congestion. +- The timeouts Traffic Server uses, depending on whether a server is + congested. +- The page Traffic Server sends to the client when a server becomes + congested. +- If Traffic Server tracks the origin servers per IP address or per + hostname.

+

Format

+

Each line in congestion.config must follow the format below. Traffic +Server applies the rules in the order listed, starting at the top of the +file. +Traffic Server recognizes three space-delimited tags:

+
primary_destination=value secondary_specifier=value action=value
+
+ + +

The following list shows possible primary destinations with allowed +values.

+
+
dest_domain
+
A requested domain name.
+
dest_host
+
A requested hostname.
+
dest_ip
+
A requested IP address.
+
url_regex
+
A regular expression (regex) to be found in a URL.
+
+

The secondary specifiers are optional in the congestion.config file. The +following list shows possible secondary specifiers with allowed values. +You can use more than one secondary specifier in a rule; however, you +cannot repeat a secondary specifier.

+
+
port
+
A requested URL port or range of ports.
+
prefix
+
A prefix in the path part of a URL.
+
+

The following list shows the possible tags and their allowed values.

+
+
max_connection_failures
+
Default: 5
+
The maximum number of connection failures allowed within the fail
+
+

window described below before Traffic Server marks the origin server as + congested.

+
+
fail_window
+
Default: 120 seconds.
+
The time period during which the maximum number of connection failures
+
+

can occur before Traffic Server marks the origin server as congested.

+
+
proxy_retry_interval
+
Default: 10 seconds.
+
The number of seconds that Traffic Server waits before contacting a
+
+

congested origin server again.

+
+
client_wait_interval
+
Default: 300 seconds.
+
The number of seconds that the client is advised to wait before
+
+

retrying the congested origin server.

+
+
wait_interval_alpha
+
Default: 30 seconds
+
The upper limit for a random number that is added to the wait interval.
+
live_os_conn_timeout
+
Default: 60 seconds.
+
The connection timeout to the live (uncongested) origin server.
+
+

If a client stops a request before the timeout occurs, then Traffic + Server does not record a connection failure.

+
+
live_os_conn_retries
+
Default: 2
+
The maximum number of retries allowed to the live (uncongested) origin
+
+

server.

+
+
dead_os_conn_timeout
+
Default: 15 secondsj
+
The connection timeout to the congested origin server.
+
dead_os_conn_retries
+
Default: 1
+
The maximum number of retries allowed to the congested origin server.
+
max_connection
+
Default: -1
+
The maximum number of connections allowed from Traffic Server to the
+
+

origin server.

+
+
error_page
+
Default: "congestion#retryAfter"
+
The error page sent to the client when a server is congested. You must
+
+

enclose the value in quotes;

+
+
congestion_scheme
+
Default: "per_ip"
+
Specifies if Traffic Server applies the rule on a per-host ("per_host")
+
+

or per-IP basis ("per_ip"). You must enclose the value in quotes.

+

For example: if the server www.host1.com has two IP addresses and you + use the tag value "per_ip", then each IP address has its own number of + connection failures and is marked as congested independently. If you + use the tag value "per_host" and the server www.host1.com is marked as + congested, then both IP addresses are marked as congested.

+

Examples

+

The following congestion.config rule configures Traffic Server to stop +forwarding requests to the server www.host.com on port 80 (HTTP traffic) +if the server is congested, according to the timeouts specified. Traffic +Server uses the default tag values because no tag has been specified.

+
dest_host=www.host.com port=80
+
+ + +

You can use one or more tags in a rule, but each tag must have one value +only. If you specify no tags in the rule, then Traffic Server uses the +default values.

+

You can override any of the default tag values by adding configuration +variables at the end of records.config as follows:

+
CONFIG proxy.config.http.congestion_control.default.tag INT|STRING value
+
+ + +

where tag is one of the tags described in the table under +congestion.config and value is the value you want to use.

+

For example:

+
CONFIG proxy.config.http.congestion_control.default.congestion_scheme STRING per_host
+
+ + +

IMPORTANT: Rules in the congestion.config file override the following +variables in the records.config file:

+
proxy.config.http.connect_attempts_max_retries
+proxy.config.http.connect_attempts_max_retries_dead_server
+proxy.config.http.connect_attempts_rr_retries
+proxy.config.http.connect_attempts_timeout
+proxy.config.http.down_server.cache_time
+proxy.config.http.down_server.abort_threshold
+
+ + +

hosting.config

+

The hosting.config file enables you to assign cache partitions to specific +origin servers and/or domains so that you can manage cache space +efficiently and restrict disk usage. For step-by-step instructions on +partitioning the cache according to origin servers and/or domains, refer +to Partitioning the Cache According to Origin Server or Domain. +Before you can assign cache partitions to specific origin servers and/or +domains, you must first partition your cache according to size and +protocol in the partition.config file. +For step-by-step instructions about partitioning your cache, refer to +Partitioning the Cache. For a description of the +partition.config file, refer to partition.config.

+

After you modify hosting.config, navigate to the Traffic Server bin +directory and run the traffic_line -x command to apply your changes. When +you apply the changes to a node in a cluster, Traffic Server automatically +applies the changes to all other nodes in the cluster.

+

IMPORTANT: The partition configuration must be the same on all nodes in a +cluster.

+

Format

+

Each line in the hosting.config file must have one of the following +formats:

+
hostname= hostname partition= partition_numbers
+domain= domain_name partition= partition_numbers
+
+ + +

where hostname is the fully-qualified hostname of the origin server whose +content you want to store on a particular partition (for example, +www.myhost.com); domain_name is the domain whose content you want to store +on a particular partition(for example, mydomain.com); and +partition_numbers is a comma-separated list of the partitions on which you +want to store the content that belongs to the origin server or domain +listed. The partition numbers must be valid numbers listed in the +partition.config file.

+

Note: To allocate more than one partition to an origin server or domain, +you must enter the partitions in a comma-separated list on one line, as +shown in the example below. The hosting.config file +cannot contain multiple entries for the same origin server or domain.

+

Generic Partition

+

When configuring the hosting.config file, you must assign a generic +partition to use for content that does not belong to any of the origin +servers or domains listed. If all partitions for a particular origin +server become corrupt, Traffic Server will also use the generic partition +to store content for that origin server.

+

The generic partition must have the following format:

+
hostname=* partition=partition_numbers
+
+ + +

where partition_numbers is a comma-separated list of generic partitions.

+

Examples

+

The following example configures Traffic Server to store content from the +domain mydomain.com in partition 1 and content from www.myhost.com in +partition 2. Traffic Server stores content from all other origin servers +in partitions 3 and 4.

+
domain=mydomain.com partition=1
+hostname=www.myhost.com partition=2
+hostname=* partition=3,
+
+ + +

icp.config

+

The icp.config file defines ICP peers (parent and sibling caches).

+

IMPORTANT: After you modify the icp.config file, navigate to the Traffic +Server bin directory and run the traffic_line -x command to apply the +changes. When you apply the changes to a node in a cluster, Traffic Server +automatically applies the changes to all other nodes in the cluster.

+

Format

+

Each line in the icp.config file contains the name and configuration +information for a single ICP peer in the following format:

+
host : host_IP : peer_type : proxy_port : icp_port : MC_on : MC_IP : MC_TTL :
+
+ + +

Each field is described in the following list.

+
+
host
+
The hostname of the ICP peer.
+
+

This field is optional; if you do not specify the hostname of the ICP + peer, you must specify the IP address.

+
+
host _IP
+
The IP address of the ICP peer.
+
+

This field is optional; if you do not specify the IP address of the ICP + peer, you must specify the hostname.

+
+
ctype
+
Use the following options:
+
+

1 to indicate an ICP parent cache + 2 to indicate an ICP sibling cache

+
+
proxy_port
+
The port number of the TCP port used by the ICP peer for proxy
+
+

communication.

+
+
icp_port
+
The port number of the UDP port used by the ICP peer for ICP
+
+

communication.

+

Examples

+

The following example configuration is for three nodes: the local host, +one parent, and one sibling.

+
localhost:0.0.0.0:3:8080:3130:0:0.0.0.0:1
+host1:123.12.1.23:1:8080:3131:0:0.0.0.0:1
+host2:123.12.1.24:2:8080:3131:0:0.0.0.0:1
+
+ + +

ip_allow.config ## {#ip_allow.config}

+

The ip_allow.config file controls client access to the Traffic Server +proxy cache. You can specify ranges of IP addresses that are allowed to +use the Traffic Server as a web proxy cache. +After you modify the ip_allow.config file, navigate to the Traffic Server +bin directory and run the traffic_line -x command to apply changes. When +you apply the changes to a node in a cluster, Traffic Server automatically +applies the changes to all other nodes in the cluster.

+

Format

+

Each line in the ip_allow.config file must have the following format:

+
src_ip=ipaddress action=ip_allow | ip_deny
+
+ + +

where ipaddress is the IP address or range of IP addresses of the clients +allowed to access the Traffic Server proxy cache, the action ip_allow +enables the specified clients to access the Traffic Server proxy cache, +and ip_deny denies the specified clients to access the Traffic Server +proxy cache.

+

By default, the ip_allow.config file contains the following line, which +allows all clients to access the Traffic Server proxy cache. To restrict +access, comment out or delete this line before adding rules:

+
src_ip=0.0.0.0-255.255.255.255 action=ip_allow
+
+ + +

Examples

+

The following example enables all clients to access the Traffic Server +proxy cache:

+
src_ip=0.0.0.0-255.255.255.255 action=ip_allow
+
+ + +

The following example allows all clients on a specific subnet to access +the Traffic Server proxy cache:

+
src_ip=123.12.3.000-123.12.3.123 action=ip_allow
+
+ + +

The following example denies all clients on a specific subnet to access +the Traffic Server proxy cache:

+
src_ip=123.45.6.0-123.45.6.123 action=ip_deny
+
+ + +

logs.config

+

The logs.config file establishes and formats traditional +custom transaction log files. +Although Traffic Server supports traditional custom logging, you +should use the more versatile XML-based custom logging (refer to +Using the Custom Format and +logs_xml.config). If you opt to use +traditional custom logging instead of the more versatile XML-based +custom logging, then you must enable the traditional custom logging +option manually (refer to +Support for Traditional Custom Logging).

+

IMPORTANT: After you modify logs.config, navigate to the +Traffic Serverbin directory and run the traffic_line -x command +to apply changes. When you apply the changes to a node in a +cluster, Traffic Server automatically applies the changes to all +other nodes in the cluster.

+

Format

+

Each line in the logs.config file establishes and formats a +custom transaction log file. Lines consist of the following fields, +separated by colons (:).

+
+
format
+
All lines must begin with the word format .
+
activation flag
+
Specifies if the custom log file is activated. You can specify one
+
+

of the following options:

+
   enabled
+   disabled
+
+ + +
+
unique format identifier
+
You must use a unique integer for each custom log file you create.
+
format name
+
The name for the format you define.
+
format string
+
Identifies the printf -style format string specifying the field
+
+

symbols to be displayed and how they should look in ASCII. Refer to + this Appendix for a list of the available field + symbols and their meanings.

+

Field symbols are indicated by %<field_symbol > format. For + example: to indicate that chi is the client host IP and not the + string chi to be printed, enter % <chi> .

+
+
file name
+
The name of the custom log file you create.
+
file type
+
The format of the file: ASCII or BINARY.
+
file header data
+
The header text. Enter none if you do not want header text; enter
+
+

the text of the header if you want your custom log file to have a + header.

+

Examples

+

The following example shows a custom log format for a file named +minimalist. It records the client host IP address (chi), +the client request universal resource identifier (cqu), and the +proxy response status code (pssc).

+
format:enabled:1:minimal:%<chi> / %<cqu> / %<pssc>:minimalist:ASCII:none
+
+ + +

The output file for the above example format is:

+
123.12.3.123 / GET http://earth/ocean/index.html HTTP/1.0 / 200
+
+ + +

The following example shows a custom log format for a file named +test. It records the User-Agentvalue of the client +request header (cqh) and the Retry-After value of the proxy +response header (psh).

+
format:enabled:1:test:%<{User-Agent}cqh> %<{Retry-After}psh>:test:ASCII:none
+
+ + +

WELF

+

Traffic Server supports WELF, the WebTrends Enhanced Log +format, so you can analyze Traffic Server log files with WebTrends +reporting tools. A predefined custom format for WELF is provided in +the logs.config file. To create a WELF format log file, comment +out the following section at the end of the file and replace +<FORMAT_ID> with a unique integer.

+
#format:enabled:<FORMAT_ID>:welf:id=firewall time="%<cqtd> %<cqtt>" fw=%<phn> pri=6 proto=%<cqus> duration=%<ttmsf> sent=%<psql> rcvd=%<cqhl> src=%<chi> dst=%<shi> dstname=%<shn> user=%<caun> op=%<cqhm> arg="%<cqup>" result=%<pssc> ref="%<{Referer}cqh>" agent="%<{user-agent}cqh>" cache=%<crc>:welf:ASCII:none
+
+#
+
+ + +

log_hosts.config ## {#log_hosts.config}

+

To record HTTP transactions for different origin servers in +separate log files, you must list each origin server hostname in +the log_hosts.config file. In addition, you must enable the +HTTP Host Log Splitting option. You should use the same +log_hosts.config file on every Traffic Server node in your +cluster. After you modify the log_hosts.config file, +navigate to the Traffic Serverbin directory and run the +traffic_line -x command to apply the changes. When you apply the +changes to a node in a cluster, Traffic Server automatically +applies the changes to all other nodes in the cluster.

+

Format

+

Each line in the log_hosts.config file has the following format:

+

hostname

+

where hostname is the hostname of the origin server.

+

Tip: You can specify keywords in the log_hosts.config file to +record all transactions from origin servers with the specified +keyword in their names in a separate log file. See the example +below.

+

Examples

+

The following example configures Traffic Server to create separate +log files containing all HTTP transactions for the origin servers +webserver1, webserver2, and webserver3.

+
webserver1
+webserver2
+webserver3
+
+ + +

The following example records all HTTP transactions from origin +servers that contain sports in their names. For example: +sports.yahoo.com and www.foxsports.com in a log file called +squid-sport.log (the Squid format is enabled).

+
sports
+
+ + +

logs_xml.config ## {#logs_xml.config}

+

The logs_xml.config file defines the custom log file formats, +filters, and processing options. The format of this file is modeled +after XML, the Extensible Markup Language.

+

Format

+

The logs_xml.config file contains the specifications below:

+ +

The logs_xml.config file ignores extra white space, blank lines, +and all comments.

+

LogFormat

+

The following list shows LogFormat specifications.

+
+
<Name = "valid_format_name"/>
+
Required. Valid format names include any name except squid,
+
+

common, extended, or extended2, which are pre-defined + formats. There is no default for this tag.

+
+
<Format = "valid_format_specification"/>
+
Required. A valid format specification is a printf-style string
+
+

describing each log entry when formatted for ASCII output. Use + %< *field* > as a placeholder for valid field names. For + more information, refer to + Custom Logging Fields.

+

The specified field can be one of the following types:

+

Simple. For example: %<cqu>
+ A field within a container, such as an HTTP header or a statistic. + Fields of this type have the syntax:

+
   %<{ field } containe>
+
+ + +

Aggregates, such as COUNT, SUM, AVG, FIRST, LAST. Fields + of this type have the syntax: %<operator ( field )>
+Note: You cannot create a format specification that contains + both aggregate operators and regular fields.

+
+
<Interval = "aggregate_interval_secs"/>
+
Use this tag when the format contains aggregate operators. The
+
+

value "aggregate_interval_secs" represents the number of seconds + between individual aggregate values being produced.

+

The valid set of aggregate operators are:

+
COUNT
+SUM
+AVG
+FIRST
+LAST
+
+ + +

LogFilters

+

The following list shows the LogFilter specifications.

+
+
<Name = "valid_filter_name"/>
+
Required. All filters must be uniquely named.
+
<Condition = "valid_log_field valid_operator valid_comparison_value"/>
+
Required. This field contains the following elements:
+
+

valid_log_field - the field that will be compared against + the given value. For more information, refer to + Logging Format Cross-Reference.

+

valid_operator_field - any one of the following: MATCH, + CASE_INSENSITIVE_MATCH, CONTAIN, CASE_INSENSITIVE_CONTAIN.

+ +

valid_comparison_value - any string or integer matching + the field type. For integer values, all of the operators are + equivalent and mean that the field must be equal to the specified + value.

+

Note: There are no negative comparison operators. If you want to + specify a negative condition, then use the Action field to + REJECT the record.

+
+
<Action = "valid_action_field"/>
+
This instructs Traffic Server to either accept or reject records
+
+

that satisfy the filter condition. <br />Required:ACCEPT or + REJECT .

+

LogObject

+

The following list shows the LogObject specifications.

+
+
<Format = "valid_format_name"/>
+
Required. Valid format names include the predefined logging
+
+

formats: squid, common, extended, and extended2, as well as + any previously-defined custom log formats. There is no default for + this tag.

+
+
<Filename = "file_name"/>
+
Required. The filename to which the given log file is written on
+
+

the local file system or on a remote collation server. No local log + file will be created if you fail to specify this tag. All filenames + are relative to the default logging directory.

+

If the name does not contain an extension (for example, squid), + then the extension .log is automatically appended to it for ASCII + logs and .blog for binary logs (refer to + Mode = "valid_logging_mode").

+

If you do not want an extension to be added, then end the filename with a + single (.) dot (for example: squid. ).

+
+
<Mode = "valid_logging_mode"/>
+
Valid logging modes include ascii , binary , and ascii_pipe .
+
+

The default is ascii .

+ +

If you are using a collation server, then the log is written to a + pipe on the collation server. A local pipe is created even before a + transaction is processed, so you can see the pipe right after + Traffic Server starts. Pipes on a collation server, however, are + created when Traffic Server starts.

+
+
<Filters = "list_of_valid_filter_names"/>
+
A comma-separated list of names of any previously-defined log
+
+

filters. If more than one filter is specified, then all filters + must accept a record for the record to be logged.

+
+
<Protocols = "list_of_valid_protocols"/>
+
A comma-separated list of the protocols this object should log.
+
+

Valid protocol names for this release are HTTP (FTP is + deprecated).

+
+
<ServerHosts = "list_of_valid_servers"/>
+
A comma-separated list of valid hostnames.This tag indicates that
+
+

only entries from the named servers will be included in the file.

+
+
<CollationHosts = "list_of_valid_hostnames"/>
+
A comma-separated list of collation servers to which all log
+
+

entries (for this object) are forwarded. Collation servers can be + specified by name or IP address. Specify the collation port with a + colon after the name; for example, host:port .

+
+
<Header = "header"/>
+
The header text you want the log files to contain. The header text
+
+

appears at the beginning of the log file, just before the first + record.

+
+
<RollingEnabled = "truth value"/>
+
Enables or disables log file rolling for the LogObject. This
+
+

setting overrides the value for the + proxy.config.log.rolling_enabled variable in the + records.config file. Set truth value to one of the + following values:

+

0 to disable rolling for this particular LogObject.
+1 to roll log files at specific intervals during the day (you + specify time intervals with the RollingIntervalSec and + RollingOffsetHr fields).
+2 to roll log files when they reach a certain size (you specify + the size with theRollingSizeMb field).
+3 to roll log files at specific intervals during the day or when + they reach a certain size (whichever occurs first).
+4 to roll log files at specific intervals during the day when log + files reach a specific size (at a specified time if the file is of + the specified size).

+
+
<RollingIntervalSec = "seconds"/>
+
The seconds between log file rolling for the LogObject; enables
+
+

you to specify different rolling intervals for different + LogObjects. + This setting overrides the value for + proxy.config.log.rolling_interval_sec in the + records.config file.

+
+
<RollingOffsetHr = "hour"/>
+
Specifies an hour (from 0 to 23) at which rolling is guaranteed to
+
+

align. Rolling might start before then, but a rolled file will be + produced only at that time. The impact of this setting is only + noticeable if the rolling interval is larger than one hour. + This setting overrides the configuration setting + for proxy.config.log.rolling_offset_hr in the + records.config file.

+
+
<RollingSizeMb = "size_in_MB"/>
+
The size at which log files are rolled.
+
+

Examples

+

The following is an example of a LogFormat specification +that collects information using three common fields:

+
     <LogFormat>
+         <Name = "minimal"/>
+         <Format = "%<chi> : %<cqu> : %<pssc>"/>
+     </LogFormat>
+
+ + +

The following is an example of a LogFormat specification +that uses aggregate operators:

+
     <LogFormat>
+         <Name = "summary"/>
+         <Format = "%<LAST(cqts)> : %<COUNT(*)> : %<SUM(psql)>"/>
+         <Interval = "10"/>
+     </LogFormat>
+
+ + +

The following is an example of a LogFilter that will cause +only REFRESH_HIT entries to be logged:

+
     <LogFilter>
+          <Name = "only_refresh_hits"/>
+          <Action = "ACCEPT"/>
+          <Condition = "%<pssc> MATCH REFRESH_HIT"/>
+     </LogFilter>
+
+ + +

Note: When specifying the field in the filter condition, you +can omit the%<>. This means that the filter below is equivalent +to the example directly above:

+
     <LogFilter>
+         <Name = "only_refresh_hits"/>
+         <Action = "ACCEPT"/>
+         <Condition = "pssc MATCH REFRESH_HIT"/>
+     </LogFilter>
+
+ + +

The following is an example of a LogObject specification +that creates a local log file for the minimal format defined +earlier. The log filename will be minimal.log because this is an +ASCII log file (the default).

+
     <LogObject>
+         <Format = "minimal"/>
+         <Filename = "minimal"/>
+     </LogObject>
+
+ + +

The following is an example of a LogObject specification +that includes only HTTP requests served by hosts in the domain +company.com or by the specific server server.somewhere.com. Log +entries are sent to port 4000 of the collation host +logs.company.com and to port 5000 of the collation host +209.131.52.129.

+
     <LogObject>
+          <Format = "minimal"/>
+          <Filename = "minimal"/>
+          <ServerHosts = "company.com,server.somewhere.com"/>
+          <Protocols = "http"/>
+          <CollationHosts = "logs.company.com:4000,209.131.52.129:5000"/>
+     </LogObject>
+
+ + +

WELF

+

Traffic Server supports WELF (WebTrends Enhanced Log Format) so you +can analyze Traffic Server log files with WebTrends reporting +tools. A predefined <LogFormat> that is compatible with WELF is +provided at the end of the logs.config file (shown below). +To create a WELF format log file, create a <LogObject> that +uses this predefined format.

+
     <LogFormat>
+         <Name = "welf"/>
+         <Format = "id=firewall time=\"%<cqtd> %<cqtt>\" fw=%<phn> pri=6
+         proto=%<cqus> duration=%<ttmsf> sent=%<psql> rcvd=%<cqhl>
+         src=%<chi> dst=%<shi> dstname=%<shn> user=%<caun> op=%<cqhm>
+         arg=\"%<cqup>\" result=%<pssc> ref=\"%<{Referer}cqh>\"
+         agent=\"%<{user-agent}cqh>\" cache=%<crc>"/>
+     </LogFormat>
+
+ + +

parent.config

+

The parent.config file identifies the parent proxies used in an +cache hierarchy. Use this file to perform the following +configuration:

+ +

Traffic Server uses the parent.config file only when the parent +caching option is enabled (refer to +Configuring Traffic Server to Use a Parent Cache).

+

IMPORTANT: After you modify the parent.config file, navigate +to the Traffic Serverbin directory and run the traffic_line -x +command to apply your changes. When you apply the changes to one +node in a cluster, Traffic Server automatically applies the changes +to all other nodes in the cluster.

+

Format

+

Each line in the parent.config file must contain a parent caching +rule. Traffic Server recognizes three space-delimited tags:

+
primary_destination=value secondary_specifie=value  action=value
+
+ + +

The following list shows the possible primary destinations and +their allowed values.

+
+
dest_domain
+
A requested domain name.
+
dest_host
+
A requested hostname.
+
dest_ip
+
A requested IP address or range of IP addresses separated by a dash
+
+

(-).

+
+
url_regex
+
A regular expression (regex) to be found in a URL
+
+

The secondary specifiers are optional in the parent.config file. +The following list shows the possible secondary specifiers and +their allowed values.

+
+
port
+
A requested URL port.
+
scheme
+
A request URL protocol: http or https.
+
prefix
+
A prefix in the path part of a URL.
+
suffix
+
A file suffix in the URL.
+
method
+
+

A request URL method. It can be one of the following:

+

get +post +put +trace

+
+
time
+
+

A time range, such as 08:00-14:00, during which the parent cache is

+
+
+

used to serve requests.

+
+
src_ip
+
A client IP address.
+
+

The following list shows the possible actions and their allowed +values.

+
+
parent
+
An ordered list of parent servers. If the request cannot be handled
+
+

by the last parent server in the list, then it will be routed to + the origin server. You can specify either a hostname or an IP + address, but; you must specify the port number.

+
+
round_robin
+
One of the following values:
+
+

true - Traffic Server goes through the parent cache list in a + round robin-based on client IP address. + strict - Traffic Server machines serve requests strictly in turn. + For example: machine proxy1 serves the first request, proxy2 + serves the second request, and so on. + false - Round robin selection does not occur.

+
+
go_direct
+
One of the following values:
+
+

true - requests bypass parent hierarchies and go directly to the + origin server. + false - requests do not bypass parent hierarchies.

+

Examples

+

The following rule configures a parent cache hierarchy consisting +of Traffic Server (which is the child) and two parents, p1.x.com +and p2.x.com. Traffic Server forwards the requests it cannot +serve to the parent servers p1.x.com and p2.x.com in a +round-robin fashion because:

+
round_robin=true
+dest_domain=. method=get parent="p1.x.com:8080; p2.y.com:8080" round_robin=true
+
+ + +

The following rule configures Traffic Server to route all requests +containing the regular expression politics and the path +/viewpoint directly to the origin server (bypassing any parent +hierarchies): +url_regex=politics prefix=/viewpoint go_direct=true

+

Every line in the parent.config file must contain either a +parent= or go_direct= directive.

+

partition.config

+

The partition.config file enables you to manage your cache space +more efficiently and restrict disk usage by creating cache +partitions of different sizes for specific protocols. You can +further configure these partitions to store data from certain +origin servers and/or domains in +the hosting.config file.

+

IMPORTANT: The partition configuration must be the same on all +nodes in a cluster. You must stop Traffic Server before you change +the cache partition size and protocol assignment. For step-by-step +instructions about partitioning the cache, refer to +Partitioning the Cache.

+

Format

+

For each partition you want to create, enter a line with the +following format:

+
partition=partition_number  scheme=protocol_type  size=partition_size
+
+ + +

where partition_number is a number between 1 and 255 (the +maximum number of partitions is 255) and protocol_type is +http. Traffic Server supports http for HTTP partition types; +partition_size is the amount of cache space allocated to +the partition. This value can be either a percentage of the total +cache space or an absolute value. The absolute value must be a +multiple of 128 MB, where 128 MB is the smallest value. If you +specify a percentage, then the size is rounded down to the closest +multiple of 128 MB.

+

Each partition is striped across several disks to achieve parallel +I/O. For example: if there are four disks, then a 1-GB partition +will have 256 MB on each disk (assuming each disk has enough free +space available). If you do not allocate all the disk space in the +cache, then the extra disk space is not used. You can use the extra +space later to create new partitions without deleting and clearing +the existing partitions.

+

Examples

+

The following example partitions the cache evenly between HTTP and +HTTPS requests:

+
partition=1 scheme=http size=50%
+partition=2 scheme=https size=50%
+
+ + +

records.config

+

The records.config file is a list of configurable variables used +by the Traffic Server software. Many of the variables in the +records.config file are set automatically when you set +configuration options in Traffic Line or Traffic Shell. After you +modify the records.config file, navigate to the Traffic +Serverbin directory and run the command traffic_line -x to +apply the changes. When you apply changes to one node in a cluster, +Traffic Server automatically applies the changes to all other nodes +in the cluster.

+

Format

+

Each variable has the following format:

+
CONFIG variable_name DATATYPE variable_value
+
+ + +

where DATATYPE is INT (integer), STRING (string), or FLOAT +(floating point).

+

Examples

+

In the following example, the +variable proxy.config.proxy_name is a STRING datatype +with the value my_server. This means that the name of the Traffic +Server proxy is my_server.

+
CONFIG proxy.config.proxy_name STRING my_server
+
+ + +

In the following example, the variable +proxy.config.arm.enabled is a yes/no flag. A value of +0 (zero) disables the option; a value of 1 enables the option.

+
CONFIG proxy.config.arm.enabled INT 0
+
+ + +

In the following example, the variable sets the cluster startup +timeout to 10 seconds.

+
CONFIG proxy.config.cluster.startup_timeout INT 10
+
+ + +

Configuration Variables

+

The following list describes the configuration variables available in +the records.config file.

+

System Variables

+
+
proxy.config.product_company
+
STRING
+
Apache Software Foundation
+
The name of the organization developing Traffic Server.
+
proxy.config.product_vendor
+
STRING
+
Apache
+
The name of the vendor providing Traffic Server.
+
proxy.config.product_name
+
STRING
+
Traffic Server
+
The name of the product.
+
proxy.config.proxy_name
+
STRING
+
<proxy_name>
+
The name of the Traffic Server node.
+
proxy.config.bin_path
+
STRING
+
bin
+
The location of the Traffic Server bin directory.
+
proxy.config.proxy_binary
+
STRING
+
traffic_server
+
The name of the executable that runs the traffic_server process.
+
proxy.config.proxy_binary_opts
+
STRING
+
-M
+
The command-line options for starting Traffic Server.
+
proxy.config.manager_binary
+
STRING
+
traffic_manager
+
The name of the executable that runs the traffic_manager
+
+

process.

+
+
proxy.config.cli_binary
+
STRING
+
traffic_line
+
The name of the executable that runs the command-line interface
+
+

(Traffic Line).

+
+
proxy.config.watch_script
+
STRING
+
traffic_cop
+
The name of the executable that runs the traffic_cop process.
+
proxy.config.env_prep
+
STRING
+
example_prep.sh
+
The script executed before the traffic_manager process spawns the
+
+

traffic_server process.

+
+
proxy.config.config_dir
+
STRING
+
config
+
The directory that contains Traffic Server configuration files.
+
proxy.config.temp_dir
+
STRING
+
/tmp
+
The directory used for Traffic Server temporary files.
+
proxy.config.alarm_email
+
STRING
+
The email address to which Traffic Server sends alarm messages.
+
+

During a custom Traffic Server installation, you can specify the + email address; otherwise, Traffic Server uses the Traffic Server + user account name as the default value for this variable.

+
+
proxy.config.syslog_facility
+
STRING
+
LOG_DAEMON
+
The facility used to record system log files.
+
+

Refer to + Understanding Traffic Server Log Files.

+
+
proxy.config.cop.core_signal
+
INT
+
0
+
The signal sent to traffic_cop's managed processes to stop them.
+
+

0 = no signal is sent.

+
+
proxy.config.cop.linux_min_swapfree_kb
+
INT
+
10240
+
The minimum amount of free swap space allowed before Traffic Server
+
+

stops the traffic_serverand traffic_manager processes to + prevent the system from hanging.

+

This configuration variable applies if swap is enabled in Linux 2.2 + only.

+
+
proxy.config.output.logfile
+
STRING
+
traffic.out
+
The name and location of the file that contains warnings, status
+
+

messages, and error messages produced by the Traffic Server + processes.

+

If no path is specified, then Traffic Server creates the file in + its logging directory.

+
+
proxy.config.snapshot_dir
+
STRING
+
snapshots
+
The directory in which Traffic Server stores configuration
+
+

snapshots on the local system. Unless you specify an absolute path, + this directory is located in the Traffic Server config + directory.

+
+
proxy.config.accept_threads
+
INT
+
0
+
When enabled (1), runs a separate thread for accept processing.
+
+

If disabled (0), then only 1 thread can be created.

+
+
proxy.config.thread.default.stacksize
+
INT
+
1096908
+
The new default thread stack size, for all threads. The original
+
+

default is set at 1 MB.

+

Local Manager

+
+
proxy.config.lm.sem_id
+
INT
+
11452
+
The semaphore ID for the local manager.
+
proxy.local.cluster.type
+
INT
+
3
+
Sets the clustering mode:
+
+

1 = full-clustering mode + 2 = management-only mode + 3 = no clustering

+
+
proxy.config.cluster.rsport
+
INT
+
8088
+
The reliable service port. The reliable service port is used to
+
+

send configuration information between the nodes in a cluster. All + nodes in a cluster must use the same reliable service port.

+
+
proxy.config.admin.autoconf_port
+
INT
+
8083
+
The autoconfiguration port.
+
proxy.config.admin.overseer_port
+
INT
+
8082
+
+

The port used for retrieving and setting statistics and + configuration variables.

+
+
proxy.config.admin.number_config_bak
+
INT
+
3
+
The maximum number of copies of rolled configuration files to
+
+

keep.

+
+
proxy.config.admin.admin_password
+
STRING
+
Specifies the encrypted administrator password that controls access
+
+

to Traffic Manager. The format can be recreated with:

+
1
+2
+3
+4
+5
#!/usr/bin/php
+<?php
+    $foo = md5('admin',true);
+    echo strtoupper(substr(bin2hex($foo),0,23)) . "\n";
+?>
+
+
+ +

or

+
+
+ + +

Note that the web interface is not being maintained.

+
+
proxy.config.admin.user_id
+
STRING
+
nobody
+
Option used to specify who to run the traffic_serverprocess as;
+
+

also used to specify ownership of config and log files.

+

The nonprivileged user account designated to Traffic Server.

+

As of version 2.1.1 if the user_id is prefixed with pound + character (#) the remaining of the string is considered to be + numeric user identifier. + If the value is set to '#-1' Traffic Server will not change the + user during startup.

+

Setting user_id to root or #0 is now forbidden to increase + security. Trying to do so, will cause the traffic_server fatal + failure. However there are two ways to bypass that restriction: + Specify -DBIG_SECURITY_HOLE in CXXFLAGS during compilation + Set the user_id=#-1 and start trafficserver as root.

+

Process Manager

+
+
proxy.config.process_manager.mgmt_port
+
INT
+
8084
+
The port used for internal communication between the
+
+

traffic_manager and traffic_server processes.

+

Alarm Configuration

+
+
proxy.config.alarm.bin
+
STRING
+
example_alarm_bin.sh
+
Name of the script file that can execute certain actions when an
+
+

alarm is signaled. The default file is a sample script named + example_alarm_bin.sh located in the bin directory. You must + edit the script to suit your needs.

+
+
proxy.config.alarm.abs_path
+
STRING
+
NULL
+
The full path to the script file that sends email to alert someone
+
+

about Traffic Server problems.

+

Authentication Basic Realm

+
+
proxy.config.proxy.authenticate.basic.realm
+
STRING
+
NULL
+
The authentication realm name. If the default of NULL is
+
+

specified, thentraffic_edge is used.

+

HTTP Engine

+
+
proxy.config.http.server_port
+
INT
+
8080
+
The port that Traffic Server uses when acting as a web proxy server
+
+

for web traffic.

+
+
proxy.config.http.server_port_attr
+
STRING
+
X
+
+

The server port options. You can specify one of the following:

+

C=SERVER_PORT_COMPRESSED +X=SERVER_PORT_DEFAULT +T=SERVER_PORT_BLIND_TUNNEL

+
+
proxy.config.http.server_other_ports
+
+

STRING

+
+
+

NULL

+
+
+

The ports other than the port specified by the variable

+
+
+

proxy.config.http.server_port to bind for incoming HTTP + requests. Example:

+
CONFIG proxy.config.http.server_other_ports STRING 6060:X 9090:X
+
+ + +

would listed to ports 6060, 9090, and the port specified by + proxy.config.http.server_port.

+
+
proxy.config.http.ssl_ports
+
STRING
+
443 563
+
The range of ports used for tunneling. Traffic Server allows
+
+

tunnels only to the specified ports.

+

For example: to retrieve an object using HTTPS via Traffic Server, + a tunnel must be established to an origin server via Traffic + Server.

+
+
proxy.config.http.insert_request_via_str
+
INT
+
1
+
You can specify one of the following:
+
+

0 = no extra information is added to the string. + 1 = all extra information is added. + 2 = some extra information is added.

+

Note: the Via: header string interpretation is + documented here.

+
+
proxy.config.http.insert_response_via_str
+
INT
+
1
+
You can specify one of the following:
+
+

0 no extra information is added to the string.
+1 all extra information is added.
+2 some extra information is added.
+

+
+
proxy.config.http.response_server_enabled
+
INT
+
1
+
You can specify one of the following:
+
+

0 no Server: header is added to the response. + 1 the Server: header is added (see string below). + 2 the Server: header is added only if the response from Origin + does not have one already.

+
+
proxy.config.http.response_server_str
+
STRING
+
ATS/
+
The Server: string that ATS will insert in a response header
+
+

(if requested, see above). Note that the current version number + is always appended to this string.

+
+
proxy.config.http.enable_url_expandomatic
+
INT
+
1
+
Enables (1) or disables (0) .com domain expansion. This
+
+

configures the Traffic Server to resolve unqualified hostnames by + prepending with www. and appending with .com before redirecting + to the expanded address.

[... 2004 lines stripped ...]