Skip to content

Commit f7131e4

Browse files
SolidWallOfCodeSolidWallOfCode
committed
Doc: Clean up some errors and formatting in traffic_ctl documentation.
1 parent 230c7bf commit f7131e4

File tree

1 file changed

+126
-113
lines changed

1 file changed

+126
-113
lines changed

‎doc/appendices/command-line/traffic_ctl.en.rst‎

Lines changed: 126 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,15 @@
1-
.. Licensed to the Apache Software Foundation (ASF) under one
2-
or more contributor license agreements. See the NOTICE file
3-
distributed with this work for additional information
4-
regarding copyright ownership. The ASF licenses this file
5-
to you under the Apache License, Version 2.0 (the
6-
"License"); you may not use this file except in compliance
7-
with the License. You may obtain a copy of the License at
1+
.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license
2+
agreements. See the NOTICE file distributed with this work for additional information regarding
3+
copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0
4+
(the "License"); you may not use this file except in compliance with the License. You may obtain
5+
a copy of the License at
86
97
http://www.apache.org/licenses/LICENSE-2.0
108
11-
Unless required by applicable law or agreed to in writing,
12-
software distributed under the License is distributed on an
13-
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14-
KIND, either express or implied. See the License for the
15-
specific language governing permissions and limitations
16-
under the License.
9+
Unless required by applicable law or agreed to in writing, software distributed under the License
10+
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11+
or implied. See the License for the specific language governing permissions and limitations
12+
under the License.
1713
1814
.. include:: ../../common.defs
1915

@@ -37,19 +33,19 @@ a running Traffic Server. :program:`traffic_ctl` includes a number
3733
of subcommands that control different aspects of Traffic Server:
3834

3935
:program:`traffic_ctl alarm`
40-
Display and manipulate Traffic Server alarms
36+
Display and manipulate Traffic Server alarms
4137
:program:`traffic_ctl config`
42-
Manipulate and display configuration records
38+
Manipulate and display configuration records
4339
:program:`traffic_ctl metric`
44-
Manipulate performance and status metrics
40+
Manipulate performance and status metrics
4541
:program:`traffic_ctl server`
46-
Stop, restart and examine the server
42+
Stop, restart and examine the server
4743
:program:`traffic_ctl storage`
48-
Manipulate cache storage
44+
Manipulate cache storage
4945
:program:`traffic_ctl plugin`
50-
Interact with plugins.
46+
Interact with plugins.
5147
:program:`traffic_ctl host`
52-
Manipulate host status. parents for now but will be expanded to origins.
48+
Manipulate host status. parents for now but will be expanded to origins.
5349

5450
To use :program:`traffic_ctl`, :ref:`traffic_manager` needs to be running.
5551

@@ -59,11 +55,11 @@ Options
5955
.. program:: traffic_ctl
6056
.. option:: --debug
6157

62-
Enable debugging output.
58+
Enable debugging output.
6359

6460
.. option:: -V, --version
6561

66-
Print version information and exit.
62+
Print version information and exit.
6763

6864
Subcommands
6965
===========
@@ -92,69 +88,62 @@ traffic_ctl config
9288
.. program:: traffic_ctl config
9389
.. option:: defaults [--records]
9490

95-
Display the default values for all configuration records. The
96-
*--records* flag has the same behavior as :option:`traffic_ctl
97-
config get --records`.
91+
Display the default values for all configuration records. The --records* flag has the same
92+
behavior as :option:`traffic_ctl config get --records`.
9893

9994
.. program:: traffic_ctl config
10095
.. option:: describe RECORD [RECORD...]
10196

102-
Display all the known information about a configuration record.
103-
This includes the current and default values, the data type,
104-
the record class and syntax checking expression.
97+
Display all the known information about a configuration record. This includes the current and
98+
default values, the data type, the record class and syntax checking expression.
10599

106100
.. program:: traffic_ctl config
107101
.. option:: diff [--records]
108102

109-
Display configuration records that have non-default values. The
110-
*--records* flag has the same behavior as :option:`traffic_ctl
111-
config get --records`.
103+
Display configuration records that have non-default values. The --records* flag has the same
104+
behavior as :option:`traffic_ctl config get --records`.
112105

113106
.. program:: traffic_ctl config
114107
.. option:: get [--records] RECORD [RECORD...]
115108

116-
Display the current value of a configuration record.
109+
Display the current value of a configuration record.
117110

118111
.. program:: traffic_ctl config get
119112
.. option:: --records
120113

121-
If this flag is provided, :option:`traffic_ctl config get` will emit
122-
results in :file:`records.config` format.
114+
If this flag is provided, :option:`traffic_ctl config get` will emit results in
115+
:file:`records.config` format.
123116

124117
.. program:: traffic_ctl config
125118
.. option:: match [--records] REGEX [REGEX...]
126119

127-
Display the current values of all configuration variables whose
128-
names match the given regular expression. The *--records* flag
129-
has the same behavior as :option:`traffic_ctl config get --records`.
120+
Display the current values of all configuration variables whose names match the given regular
121+
expression. The *--records* flag has the same behavior as :option:`traffic_ctl config get
122+
--records`.
130123

131124
.. program:: traffic_ctl config
132125
.. option:: reload
133126

134-
Initiate a Traffic Server configuration reload. Use this command
135-
to update the running configuration after any configuration
136-
file modification. If no configuration files have been modified
137-
since the previous configuration load, this command is a no-op.
127+
Initiate a Traffic Server configuration reload. Use this command to update the running
128+
configuration after any configuration file modification. If no configuration files have been
129+
modified since the previous configuration load, this command is a no-op.
138130

139-
The timestamp of the last reconfiguration event (in seconds
140-
since epoch) is published in the `proxy.node.config.reconfigure_time`
141-
metric.
131+
The timestamp of the last reconfiguration event (in seconds since epoch) is published in the
132+
`proxy.node.config.reconfigure_time` metric.
142133

143134
.. program:: traffic_ctl config
144135
.. option:: set RECORD VALUE
145136

146-
Set the named configuration record to the specified value.
147-
Refer to the :file:`records.config` documentation for a list
148-
of the configuration variables you can specify. Note that this
149-
is not a synchronous operation.
137+
Set the named configuration record to the specified value. Refer to the :file:`records.config`
138+
documentation for a list of the configuration variables you can specify. Note that this is not a
139+
synchronous operation.
150140

151141
.. program:: traffic_ctl config
152142
.. option:: status
153143

154-
Display detailed status about the Traffic Server configuration
155-
system. This includes version information, whether the internal
156-
configuration store is current and whether any daemon processes
157-
should be restarted.
144+
Display detailed status about the Traffic Server configuration system. This includes version
145+
information, whether the internal configuration store is current and whether any daemon processes
146+
should be restarted.
158147

159148
.. _traffic-ctl-metric:
160149

@@ -163,40 +152,39 @@ traffic_ctl metric
163152
.. program:: traffic_ctl metric
164153
.. option:: get METRIC [METRIC...]
165154

166-
Display the current value of the specifies statistics.
155+
Display the current value of the specifies statistics.
167156

168157
.. program:: traffic_ctl metric
169158
.. option:: match REGEX [REGEX...]
170159

171-
Display the current values of all statistics whose names match
172-
the given regular expression.
160+
Display the current values of all statistics whose names match
161+
the given regular expression.
173162

174163
.. program:: traffic_ctl metric
175164
.. option:: zero METRIC [METRIC...]
176165

177-
Reset the named statistics to zero.
166+
Reset the named statistics to zero.
178167

179168
traffic_ctl server
180169
------------------
181170
.. program:: traffic_ctl server
182171
.. option:: restart
183172

184-
Shut down and immediately restart Traffic Server
173+
Shut down and immediately restart Traffic Server
185174

186175
.. program:: traffic_ctl server restart
187176
.. option:: --drain
188177

189-
This option modifies the behavior of :option:`traffic_ctl server restart`
190-
such that :program:`traffic_server` is not shut down until the
191-
number of active client connections drops to the number given
192-
by the :ts:cv:`proxy.config.restart.active_client_threshold`
193-
configuration variable.
178+
This option modifies the behavior of :option:`traffic_ctl server restart` such that
179+
:program:`traffic_server` is not shut down until the number of active client connections drops to
180+
the number given by the :ts:cv:`proxy.config.restart.active_client_threshold` configuration
181+
variable.
194182

195183
.. option:: --manager
196184

197-
The default behavior of :option:`traffic_ctl server restart` is to restart
198-
:program:`traffic_server`. If this option is specified,
199-
:program:`traffic_manager` is also restarted.
185+
The default behavior of :option:`traffic_ctl server restart` is to restart
186+
:program:`traffic_server`. If this option is specified, :program:`traffic_manager` is also
187+
restarted.
200188

201189
.. program:: traffic_ctl server
202190
.. option:: start
@@ -225,91 +213,116 @@ traffic_ctl server
225213
.. program:: traffic_ctl server
226214
.. option:: backtrace
227215

228-
Show a full stack trace of all the :program:`traffic_server` threads.
216+
Show a full stack trace of all the :program:`traffic_server` threads.
229217

230218
traffic_ctl storage
231219
-------------------
232220
.. program:: traffic_ctl storage
233221
.. option:: offline PATH [PATH ...]
234222

235-
Mark a cache storage device as offline. The storage is identified
236-
by :arg:`PATH` which must match exactly a path specified in
237-
:file:`storage.config`. This removes the storage from the cache
238-
and redirects requests that would have used this storage to other
239-
storage. This has exactly the same effect as a disk failure for
240-
that storage. This does not persist across restarts of the
223+
Mark a cache storage device as offline. The storage is identified by :arg:`PATH` which must match
224+
exactly a path specified in :file:`storage.config`. This removes the storage from the cache and
225+
redirects requests that would have used this storage to other storage. This has exactly the same
226+
effect as a disk failure for that storage. This does not persist across restarts of the
241227
:program:`traffic_server` process.
242228

243229
traffic_ctl plugin
244230
-------------------
245231
.. program:: traffic_ctl plugin
246232
.. option:: msg TAG DATA
247233

248-
Send a message to plugins. All plugins that have hooked the :cpp:enumerator:`TSLifecycleHookID::TS_LIFECYCLE_MSG_HOOK`
249-
will receive a callback for that hook. The :arg:`TAG` and :arg:`DATA` will be available to the
250-
plugin hook processing. It is expected that plugins will use :arg:`TAG` to select relevant messages
251-
and determine the format of the :arg:`DATA`.
234+
Send a message to plugins. All plugins that have hooked the
235+
:cpp:enumerator:`TSLifecycleHookID::TS_LIFECYCLE_MSG_HOOK` will receive a callback for that hook.
236+
The :arg:`TAG` and :arg:`DATA` will be available to the plugin hook processing. It is expected
237+
that plugins will use :arg:`TAG` to select relevant messages and determine the format of the
238+
:arg:`DATA`.
252239

253240
traffic_ctl host
254241
----------------
255242
.. program:: traffic_ctl host
243+
244+
A stat to track status is created for each host. The name is the host fqdn with a prefix of
245+
"proxy.process.host_status". The value of the stat is a string which is the serialized
246+
representation of the status. This contains the overall status and the status for each reason. The
247+
stats may be viewed using the :program:`traffic_ctl metric` command or through the `stats_over_http`
248+
endpoint.
249+
250+
.. option:: --time count
251+
252+
Set the duration of an operation to ``count`` seconds. A value of ``0`` means no duration, the
253+
condition persists until explicitly changed. The default is ``0`` if an operation requires a time
254+
and none is provided by this option.
255+
256+
.. option:: --reason active | local | manual
257+
258+
Sets the reason for the operation.
259+
260+
``active``
261+
Set the active health check reason.
262+
263+
``local``
264+
Set the local health check reason.
265+
266+
``manual``
267+
Set the administrative reason. This is the default reason if a reason is needed and not
268+
provided by this option.
269+
270+
Internally the reason can be ``self_detect`` if
271+
:ts:cv:`proxy.config.http.parent_proxy.self_detect` is set to the value 2 (the default). This is
272+
used to prevent parent selection from creating a loop by selecting itself as the upstream by
273+
marking this reason as "down" in that case.
274+
275+
.. note::
276+
277+
The up / down status values are independent, and a host is consider available if and only if
278+
all of the statuses are "up".
279+
256280
.. option:: status HOSTNAME [HOSTNAME ...]
257281

258-
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.
282+
Get the current status of the specified hosts with respect to their use as targets for parent
283+
selection. This returns the same information as the per host stat.
259284

260-
.. program:: traffic_ctl host
261-
.. option:: down --time seconds --reason 'active|local|manual' HOSTNAME [HOSTNAME ...]
262-
263-
Marks the listed hosts as down so that they will not be chosen as a next hop parent.
264-
If the --time option is included, the host is marked down for the specified number of
265-
seconds after which the host will automatically be marked up. 0 seconds marks the host
266-
down indefinitely until marked up manually and is the default. A reason tag may be used
267-
when marking a host down. Valid values are 'manual', 'active', and 'local', 'manual'
268-
is used as the default if no reason is specified. The tags are used to indicate wether the host
269-
was marked down manually or by an 'active' or 'local' health check. 'self_detect' indicates
270-
that a parent entry in parent.config was marked down because the entry refers to the
271-
local host so, it is automatically marked down to prevent requests from looping. A host is
272-
not marked up until all reason codes are cleared by marking up the host for the specified
273-
reason code.
285+
.. option:: down HOSTNAME [HOSTNAME ...]
286+
287+
Marks the listed hosts as down so that they will not be chosen as a next hop parent. If
288+
:option:`--time` is included the host is marked down for the specified number of seconds after
289+
which the host will automatically be marked up. A host is not marked up until all reason codes
290+
are cleared by marking up the host for the specified reason code.
274291

275-
A stat is created for each host, with a the host fqdn and is prefixed with the string
276-
`proxy.process.host_status` with a string value. The string value is a
277-
serialized representation of the Host status struct showing all current data ie, reasons,
278-
marked down times, and down time for each host. The stats may be viewed using the
279-
`traffic_ctl metric` command or through the `stats_over_http` endpoint.
292+
Supports :option:`--time`, :option:`--reason`.
280293

281-
.. program:: traffic_ctl host
282-
.. option:: up --reason 'active|local|manual' HOSTNAME [HOSTNAME ...]
294+
.. option:: up HOSTNAME [HOSTNAME ...]
295+
296+
Marks the listed hosts as up so that they will be available for use as a next hop parent. Use
297+
:option:`--reason` to mark the host reason code. The 'self_detect' is an internal reason code
298+
used by parent selection to mark down a parent when it is identified as itself and
283299

284-
Marks the listed hosts as up so that they will be available for use as a next hop parent.
285-
By default, the 'manual' reason tag is used when marking up a host. Use the --reason
286-
tag to mark the host reason code as up using one of 'manual', 'active', or 'local'.
287-
The 'self_detect' is an internal reason code used by parent selection to mark down
288-
a parent when it is identified as itself and `proxy.config.http.parent_proxy.self_detect'
289-
is set to the default of 2. 'self_detect' down cannot be set or unset with traffic_ctl
300+
301+
Supports :option:`--reason`.
290302

291303
Examples
292304
========
293305

294306
Mark down a host with `traffic_ctl` and view the associated host stats::
295307

296-
$ traffic_ctl host down cdn-cache-02.foo.com --reason manual
308+
$ traffic_ctl host down cdn-cache-02.foo.com --reason manual
297309

298-
$ /opt/trafficserver/bin/traffic_ctl metric match host_status
299-
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
300-
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
301-
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
310+
$ /opt/trafficserver/bin/traffic_ctl metric match host_status
311+
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
312+
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
313+
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
302314

303315
In the example above, 'cdn-cache-01.foo.com' is unavailable, `HOST_STATUS_DOWN` and was marked down
304316
for the `manual` reason, `MANUAL:DOWN:1556896844:0`, at the time indicated by the UNIX time stamp
305-
`1556896844`. To make the host available, one would have to clear the `manual` reason using::
306-
`traffic_ctl host up cdn-cache-01.foo.com --reason manual`
317+
`1556896844`. To make the host available, one would have to clear the `manual` reason using ::
318+
319+
$ traffic_ctl host up cdn-cache-01.foo.com --reason manual
307320

308321
Configure Traffic Server to insert ``Via`` header in the response to
309322
the client::
310323

311-
$ traffic_ctl config set proxy.config.http.insert_response_via_str 1
312-
$ traffic_ctl config reload
324+
$ traffic_ctl config set proxy.config.http.insert_response_via_str 1
325+
$ traffic_ctl config reload
313326

314327
See also
315328
========

0 commit comments

Comments
 (0)