trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a..@apache.org
Subject [trafficserver] branch master updated: Doc: Clean up some errors and formatting in traffic_ctl documentation.
Date Thu, 09 May 2019 17:42:28 GMT
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 <amc@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
 ========


Mime
View raw message