| .. 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. |
| |
| .. include:: ../../common.defs |
| |
| .. _traffic_ctl: |
| |
| traffic_ctl |
| *********** |
| |
| Synopsis |
| ======== |
| |
| :program:`traffic_ctl` [OPTIONS] SUBCOMMAND [OPTIONS] |
| |
| .. _traffic-ctl-commands: |
| |
| Description |
| =========== |
| |
| :program:`traffic_ctl` is used to display and manipulate configure |
| 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 |
| :program:`traffic_ctl config` |
| Manipulate and display configuration records |
| :program:`traffic_ctl metric` |
| Manipulate performance and status metrics |
| :program:`traffic_ctl server` |
| Stop, restart and examine the server |
| :program:`traffic_ctl storage` |
| Manipulate cache storage |
| :program:`traffic_ctl plugin` |
| Interact with plugins. |
| :program:`traffic_ctl host` |
| Manipulate host status. parents for now but will be expanded to origins. |
| |
| To use :program:`traffic_ctl`, :ref:`traffic_manager` needs to be running. |
| |
| Options |
| ======= |
| |
| .. program:: traffic_ctl |
| .. option:: --debug |
| |
| Enable debugging output. |
| |
| .. option:: -V, --version |
| |
| Print version information and exit. |
| |
| Subcommands |
| =========== |
| |
| traffic_ctl alarm |
| ----------------- |
| .. program:: traffic_ctl alarm |
| .. option:: list |
| |
| List all alarm events that have not been acknowledged (cleared). |
| |
| .. program:: traffic_ctl alarm |
| .. option:: clear |
| |
| Clear (acknowledge) all current alarms. |
| |
| .. program:: traffic_ctl alarm |
| .. option:: resolve ALARM [ALARM...] |
| |
| Clear (acknowledge) an alarm event. The arguments are a specific |
| alarm number (e.g. ''1''), or an alarm string identifier (e.g. |
| ''MGMT_ALARM_PROXY_CONFIG_ERROR''). |
| |
| 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`. |
| |
| .. 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. |
| |
| .. 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`. |
| |
| .. program:: traffic_ctl config |
| .. option:: get [--records] RECORD [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. |
| |
| .. 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`. |
| |
| .. 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. |
| |
| 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. |
| |
| .. 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. |
| |
| .. _traffic-ctl-metric: |
| |
| traffic_ctl metric |
| ------------------ |
| .. program:: traffic_ctl metric |
| .. option:: get METRIC [METRIC...] |
| |
| 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. |
| |
| .. program:: traffic_ctl metric |
| .. option:: zero METRIC [METRIC...] |
| |
| Reset the named statistics to zero. |
| |
| traffic_ctl server |
| ------------------ |
| .. program:: traffic_ctl server |
| .. option:: restart |
| |
| 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. |
| |
| .. 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. |
| |
| .. program:: traffic_ctl server |
| .. option:: start |
| |
| Start :program:`traffic_server` if it is already running. |
| |
| .. program:: traffic_ctl server start |
| .. option:: --clear-cache |
| |
| Clear the disk cache upon startup. |
| |
| .. option:: --clear-hostdb |
| |
| Clear the DNS resolver cache upon startup. |
| |
| .. program:: traffic_ctl server |
| .. option:: status |
| |
| Show the current proxy server status, indicating if we're running or not. |
| |
| .. program:: traffic_ctl server |
| .. option:: stop |
| |
| Stop the running :program:`traffic_server` process. |
| |
| .. program:: traffic_ctl server |
| .. option:: backtrace |
| |
| 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 |
| :program:`traffic_server` process. |
| |
| 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`. |
| |
| 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 specified hosts with respect to their use as targets for parent |
| selection. This returns the same information as the per host stat. |
| |
| .. 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. |
| |
| Supports :option:`--time`, :option:`--reason`. |
| |
| .. 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 |
| |
| |
| 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 |
| |
| $ /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 |
| |
| 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 |
| |
| See also |
| ======== |
| |
| :manpage:`records.config(5)`, |
| :manpage:`storage.config(5)` |