You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by am...@apache.org on 2019/05/09 17:42:28 UTC
[trafficserver] branch master updated: Doc: Clean up some errors
and formatting in traffic_ctl documentation.
This is an automated email from the ASF dual-hosted git repository.
amc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new f7131e4 Doc: Clean up some errors and formatting in traffic_ctl documentation.
f7131e4 is described below
commit f7131e4c568ae75264e93a47560eabd5c38e940d
Author: Alan M. Carroll <am...@apache.org>
AuthorDate: Thu May 9 09:49:19 2019 -0500
Doc: Clean up some errors and formatting in traffic_ctl documentation.
---
doc/appendices/command-line/traffic_ctl.en.rst | 239 +++++++++++++------------
1 file changed, 126 insertions(+), 113 deletions(-)
diff --git a/doc/appendices/command-line/traffic_ctl.en.rst b/doc/appendices/command-line/traffic_ctl.en.rst
index 653598b..86066ce 100644
--- a/doc/appendices/command-line/traffic_ctl.en.rst
+++ b/doc/appendices/command-line/traffic_ctl.en.rst
@@ -1,19 +1,15 @@
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
+.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license
+ agreements. See the NOTICE file distributed with this work for additional information regarding
+ copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with the License. You may obtain
+ a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
+ Unless required by applicable law or agreed to in writing, software distributed under the License
+ is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ or implied. See the License for the specific language governing permissions and limitations
+ under the License.
.. include:: ../../common.defs
@@ -37,19 +33,19 @@ a running Traffic Server. :program:`traffic_ctl` includes a number
of subcommands that control different aspects of Traffic Server:
:program:`traffic_ctl alarm`
- Display and manipulate Traffic Server alarms
+ Display and manipulate Traffic Server alarms
:program:`traffic_ctl config`
- Manipulate and display configuration records
+ Manipulate and display configuration records
:program:`traffic_ctl metric`
- Manipulate performance and status metrics
+ Manipulate performance and status metrics
:program:`traffic_ctl server`
- Stop, restart and examine the server
+ Stop, restart and examine the server
:program:`traffic_ctl storage`
- Manipulate cache storage
+ Manipulate cache storage
:program:`traffic_ctl plugin`
- Interact with plugins.
+ Interact with plugins.
:program:`traffic_ctl host`
- Manipulate host status. parents for now but will be expanded to origins.
+ Manipulate host status. parents for now but will be expanded to origins.
To use :program:`traffic_ctl`, :ref:`traffic_manager` needs to be running.
@@ -59,11 +55,11 @@ Options
.. program:: traffic_ctl
.. option:: --debug
- Enable debugging output.
+ Enable debugging output.
.. option:: -V, --version
- Print version information and exit.
+ Print version information and exit.
Subcommands
===========
@@ -92,69 +88,62 @@ traffic_ctl config
.. program:: traffic_ctl config
.. option:: defaults [--records]
- Display the default values for all configuration records. The
- *--records* flag has the same behavior as :option:`traffic_ctl
- config get --records`.
+ Display the default values for all configuration records. The --records* flag has the same
+ behavior as :option:`traffic_ctl config get --records`.
.. program:: traffic_ctl config
.. option:: describe RECORD [RECORD...]
- Display all the known information about a configuration record.
- This includes the current and default values, the data type,
- the record class and syntax checking expression.
+ Display all the known information about a configuration record. This includes the current and
+ default values, the data type, the record class and syntax checking expression.
.. program:: traffic_ctl config
.. option:: diff [--records]
- Display configuration records that have non-default values. The
- *--records* flag has the same behavior as :option:`traffic_ctl
- config get --records`.
+ Display configuration records that have non-default values. The --records* flag has the same
+ behavior as :option:`traffic_ctl config get --records`.
.. program:: traffic_ctl config
.. option:: get [--records] RECORD [RECORD...]
- Display the current value of a configuration record.
+ Display the current value of a configuration record.
.. program:: traffic_ctl config get
.. option:: --records
- If this flag is provided, :option:`traffic_ctl config get` will emit
- results in :file:`records.config` format.
+ If this flag is provided, :option:`traffic_ctl config get` will emit results in
+ :file:`records.config` format.
.. program:: traffic_ctl config
.. option:: match [--records] REGEX [REGEX...]
- Display the current values of all configuration variables whose
- names match the given regular expression. The *--records* flag
- has the same behavior as :option:`traffic_ctl config get --records`.
+ Display the current values of all configuration variables whose names match the given regular
+ expression. The *--records* flag has the same behavior as :option:`traffic_ctl config get
+ --records`.
.. program:: traffic_ctl config
.. option:: reload
- Initiate a Traffic Server configuration reload. Use this command
- to update the running configuration after any configuration
- file modification. If no configuration files have been modified
- since the previous configuration load, this command is a no-op.
+ Initiate a Traffic Server configuration reload. Use this command to update the running
+ configuration after any configuration file modification. If no configuration files have been
+ modified since the previous configuration load, this command is a no-op.
- The timestamp of the last reconfiguration event (in seconds
- since epoch) is published in the `proxy.node.config.reconfigure_time`
- metric.
+ The timestamp of the last reconfiguration event (in seconds since epoch) is published in the
+ `proxy.node.config.reconfigure_time` metric.
.. program:: traffic_ctl config
.. option:: set RECORD VALUE
- Set the named configuration record to the specified value.
- Refer to the :file:`records.config` documentation for a list
- of the configuration variables you can specify. Note that this
- is not a synchronous operation.
+ Set the named configuration record to the specified value. Refer to the :file:`records.config`
+ documentation for a list of the configuration variables you can specify. Note that this is not a
+ synchronous operation.
.. program:: traffic_ctl config
.. option:: status
- Display detailed status about the Traffic Server configuration
- system. This includes version information, whether the internal
- configuration store is current and whether any daemon processes
- should be restarted.
+ Display detailed status about the Traffic Server configuration system. This includes version
+ information, whether the internal configuration store is current and whether any daemon processes
+ should be restarted.
.. _traffic-ctl-metric:
@@ -163,40 +152,39 @@ traffic_ctl metric
.. program:: traffic_ctl metric
.. option:: get METRIC [METRIC...]
- Display the current value of the specifies statistics.
+ Display the current value of the specifies statistics.
.. program:: traffic_ctl metric
.. option:: match REGEX [REGEX...]
- Display the current values of all statistics whose names match
- the given regular expression.
+ Display the current values of all statistics whose names match
+ the given regular expression.
.. program:: traffic_ctl metric
.. option:: zero METRIC [METRIC...]
- Reset the named statistics to zero.
+ Reset the named statistics to zero.
traffic_ctl server
------------------
.. program:: traffic_ctl server
.. option:: restart
- Shut down and immediately restart Traffic Server
+ Shut down and immediately restart Traffic Server
.. program:: traffic_ctl server restart
.. option:: --drain
- This option modifies the behavior of :option:`traffic_ctl server restart`
- such that :program:`traffic_server` is not shut down until the
- number of active client connections drops to the number given
- by the :ts:cv:`proxy.config.restart.active_client_threshold`
- configuration variable.
+ This option modifies the behavior of :option:`traffic_ctl server restart` such that
+ :program:`traffic_server` is not shut down until the number of active client connections drops to
+ the number given by the :ts:cv:`proxy.config.restart.active_client_threshold` configuration
+ variable.
.. option:: --manager
- The default behavior of :option:`traffic_ctl server restart` is to restart
- :program:`traffic_server`. If this option is specified,
- :program:`traffic_manager` is also restarted.
+ The default behavior of :option:`traffic_ctl server restart` is to restart
+ :program:`traffic_server`. If this option is specified, :program:`traffic_manager` is also
+ restarted.
.. program:: traffic_ctl server
.. option:: start
@@ -225,19 +213,17 @@ traffic_ctl server
.. program:: traffic_ctl server
.. option:: backtrace
- Show a full stack trace of all the :program:`traffic_server` threads.
+ Show a full stack trace of all the :program:`traffic_server` threads.
traffic_ctl storage
-------------------
.. program:: traffic_ctl storage
.. option:: offline PATH [PATH ...]
- Mark a cache storage device as offline. The storage is identified
- by :arg:`PATH` which must match exactly a path specified in
- :file:`storage.config`. This removes the storage from the cache
- and redirects requests that would have used this storage to other
- storage. This has exactly the same effect as a disk failure for
- that storage. This does not persist across restarts of the
+ Mark a cache storage device as offline. The storage is identified by :arg:`PATH` which must match
+ exactly a path specified in :file:`storage.config`. This removes the storage from the cache and
+ redirects requests that would have used this storage to other storage. This has exactly the same
+ effect as a disk failure for that storage. This does not persist across restarts of the
:program:`traffic_server` process.
traffic_ctl plugin
@@ -245,71 +231,98 @@ traffic_ctl plugin
.. program:: traffic_ctl plugin
.. option:: msg TAG DATA
- Send a message to plugins. All plugins that have hooked the :cpp:enumerator:`TSLifecycleHookID::TS_LIFECYCLE_MSG_HOOK`
- will receive a callback for that hook. The :arg:`TAG` and :arg:`DATA` will be available to the
- plugin hook processing. It is expected that plugins will use :arg:`TAG` to select relevant messages
- and determine the format of the :arg:`DATA`.
+ Send a message to plugins. All plugins that have hooked the
+ :cpp:enumerator:`TSLifecycleHookID::TS_LIFECYCLE_MSG_HOOK` will receive a callback for that hook.
+ The :arg:`TAG` and :arg:`DATA` will be available to the plugin hook processing. It is expected
+ that plugins will use :arg:`TAG` to select relevant messages and determine the format of the
+ :arg:`DATA`.
traffic_ctl host
----------------
.. program:: traffic_ctl host
+
+A stat to track status is created for each host. The name is the host fqdn with a prefix of
+"proxy.process.host_status". The value of the stat is a string which is the serialized
+representation of the status. This contains the overall status and the status for each reason. The
+stats may be viewed using the :program:`traffic_ctl metric` command or through the `stats_over_http`
+endpoint.
+
+.. option:: --time count
+
+ Set the duration of an operation to ``count`` seconds. A value of ``0`` means no duration, the
+ condition persists until explicitly changed. The default is ``0`` if an operation requires a time
+ and none is provided by this option.
+
+.. option:: --reason active | local | manual
+
+ Sets the reason for the operation.
+
+ ``active``
+ Set the active health check reason.
+
+ ``local``
+ Set the local health check reason.
+
+ ``manual``
+ Set the administrative reason. This is the default reason if a reason is needed and not
+ provided by this option.
+
+ Internally the reason can be ``self_detect`` if
+ :ts:cv:`proxy.config.http.parent_proxy.self_detect` is set to the value 2 (the default). This is
+ used to prevent parent selection from creating a loop by selecting itself as the upstream by
+ marking this reason as "down" in that case.
+
+ .. note::
+
+ The up / down status values are independent, and a host is consider available if and only if
+ all of the statuses are "up".
+
.. option:: status HOSTNAME [HOSTNAME ...]
- Get the current status of the hosts used in parent.config as a next hop in a multi-tiered cache hierarchy. The value 0 or 1 is returned indicating that the host is marked as down '0' or marked as up '1'. If a host is marked as down, it will not be used as the next hop parent, another host marked as up will be chosen.
+ Get the current status of the specified hosts with respect to their use as targets for parent
+ selection. This returns the same information as the per host stat.
-.. program:: traffic_ctl host
-.. option:: down --time seconds --reason 'active|local|manual' HOSTNAME [HOSTNAME ...]
-
- Marks the listed hosts as down so that they will not be chosen as a next hop parent.
- If the --time option is included, the host is marked down for the specified number of
- seconds after which the host will automatically be marked up. 0 seconds marks the host
- down indefinitely until marked up manually and is the default. A reason tag may be used
- when marking a host down. Valid values are 'manual', 'active', and 'local', 'manual'
- is used as the default if no reason is specified. The tags are used to indicate wether the host
- was marked down manually or by an 'active' or 'local' health check. 'self_detect' indicates
- that a parent entry in parent.config was marked down because the entry refers to the
- local host so, it is automatically marked down to prevent requests from looping. A host is
- not marked up until all reason codes are cleared by marking up the host for the specified
- reason code.
+.. option:: down HOSTNAME [HOSTNAME ...]
+
+ Marks the listed hosts as down so that they will not be chosen as a next hop parent. If
+ :option:`--time` is included the host is marked down for the specified number of seconds after
+ which the host will automatically be marked up. A host is not marked up until all reason codes
+ are cleared by marking up the host for the specified reason code.
- A stat is created for each host, with a the host fqdn and is prefixed with the string
- `proxy.process.host_status` with a string value. The string value is a
- serialized representation of the Host status struct showing all current data ie, reasons,
- marked down times, and down time for each host. The stats may be viewed using the
- `traffic_ctl metric` command or through the `stats_over_http` endpoint.
+ Supports :option:`--time`, :option:`--reason`.
-.. program:: traffic_ctl host
-.. option:: up --reason 'active|local|manual' HOSTNAME [HOSTNAME ...]
+.. option:: up HOSTNAME [HOSTNAME ...]
+
+ Marks the listed hosts as up so that they will be available for use as a next hop parent. Use
+ :option:`--reason` to mark the host reason code. The 'self_detect' is an internal reason code
+ used by parent selection to mark down a parent when it is identified as itself and
- Marks the listed hosts as up so that they will be available for use as a next hop parent.
- By default, the 'manual' reason tag is used when marking up a host. Use the --reason
- tag to mark the host reason code as up using one of 'manual', 'active', or 'local'.
- The 'self_detect' is an internal reason code used by parent selection to mark down
- a parent when it is identified as itself and `proxy.config.http.parent_proxy.self_detect'
- is set to the default of 2. 'self_detect' down cannot be set or unset with traffic_ctl
+
+ Supports :option:`--reason`.
Examples
========
Mark down a host with `traffic_ctl` and view the associated host stats::
-$ traffic_ctl host down cdn-cache-02.foo.com --reason manual
+ $ traffic_ctl host down cdn-cache-02.foo.com --reason manual
-$ /opt/trafficserver/bin/traffic_ctl metric match host_status
-proxy.process.host_status.cdn-cache-01.foo.com HOST_STATUS_DOWN,ACTIVE:UP:0:0,LOCAL:UP:0:0,MANUAL:DOWN:1556896844:0,SELF_DETECT:UP:0
-proxy.process.host_status.cdn-cache-02.foo.com HOST_STATUS_UP,ACTIVE:UP:0:0,LOCAL:UP:0:0,MANUAL:UP:0:0,SELF_DETECT:UP:0
-proxy.process.host_status.cdn-cache-origin-01.foo.com HOST_STATUS_UP,ACTIVE:UP:0:0,LOCAL:UP:0:0,MANUAL:UP:0:0,SELF_DETECT:UP:0
+ $ /opt/trafficserver/bin/traffic_ctl metric match host_status
+ proxy.process.host_status.cdn-cache-01.foo.com HOST_STATUS_DOWN,ACTIVE:UP:0:0,LOCAL:UP:0:0,MANUAL:DOWN:1556896844:0,SELF_DETECT:UP:0
+ proxy.process.host_status.cdn-cache-02.foo.com HOST_STATUS_UP,ACTIVE:UP:0:0,LOCAL:UP:0:0,MANUAL:UP:0:0,SELF_DETECT:UP:0
+ proxy.process.host_status.cdn-cache-origin-01.foo.com HOST_STATUS_UP,ACTIVE:UP:0:0,LOCAL:UP:0:0,MANUAL:UP:0:0,SELF_DETECT:UP:0
In the example above, 'cdn-cache-01.foo.com' is unavailable, `HOST_STATUS_DOWN` and was marked down
for the `manual` reason, `MANUAL:DOWN:1556896844:0`, at the time indicated by the UNIX time stamp
-`1556896844`. To make the host available, one would have to clear the `manual` reason using::
-`traffic_ctl host up cdn-cache-01.foo.com --reason manual`
+`1556896844`. To make the host available, one would have to clear the `manual` reason using ::
+
+ $ traffic_ctl host up cdn-cache-01.foo.com --reason manual
Configure Traffic Server to insert ``Via`` header in the response to
the client::
- $ traffic_ctl config set proxy.config.http.insert_response_via_str 1
- $ traffic_ctl config reload
+ $ traffic_ctl config set proxy.config.http.insert_response_via_str 1
+ $ traffic_ctl config reload
See also
========