traffic_ctl¶

Synopsis¶

traffic_ctl [OPTIONS] SUBCOMMAND [OPTIONS]

Note

traffic_ctl now uses a JSONRPC endpoint instead of traffic_manager. traffic_manager is not required. To build this version of traffic_ctl --enable-jsonrpc-tc should be passed when configure the build.

Description¶

traffic_ctl is used to display,manipulate and configure a running Traffic Server. traffic_ctl includes a number of subcommands that control different aspects of Traffic Server:

traffic_ctl config: Manipulate and display configuration records
traffic_ctl metric: Manipulate performance and status metrics
traffic_ctl server: Stop, restart and examine the server
traffic_ctl storage: Manipulate cache storage
traffic_ctl plugin: Interact with plugins.
traffic_ctl host: Manipulate host status. parents for now but will be expanded to origins.
traffic_ctl rpc: Interact directly with the JSONRPC 2.0 server in Traffic Server

Options¶

--debug¶: Enable debugging output.

-V, --version¶: Print version information and exit.

-f, --format¶

Specify the output print style.

Options	Description
`legacy`	Will honour the old traffic_ctl output messages. This is the default format type.
`pretty`	<if available> will print a different output, a prettier output. This depends on the implementation, it’s not required to always implement a pretty output
`json`	It will show the response message formatted to JSON. This is ideal if you want to redirect the stdout to a different source. It will only stream the json response, no other messages.
`data:`	This is an addon to the default format style, data can be: `{req\|resp\|all}` which will make traffic_ctl to print in json format the request or response or both.

In case of a record request(config) --records overrides this flag.

Default: legacy

Example:

traffic_ctl config get variable --format data:req
--> {request}

$ traffic_ctl config get variable --format data:resp
<-- {response}

$ traffic_ctl config get variable --format data:all
--> {request}
<-- {response}

$ traffic_ctl config get variable --format json
{response}

There will be no print out beside the json response. This is ideal to redirect to a file.

--records¶: Option available only for records request.

--run-root¶: Path to the runroot file.

Subcommands¶

traffic_ctl alarm¶

Warning

Option not available in the JSONRPC 2.0 version.

traffic_ctl config¶

defaults [--records]¶: Display the default values for all configuration records. The --records flag has the same behavior as traffic_ctl config get --records.

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.

Error output available if --format pretty is specified.

diff [--records]¶: Display configuration records that have non-default values. The --records flag has the same behavior as traffic_ctl config get --records.

get [--records] RECORD [RECORD...]¶

Display the current value of a configuration record.

Error output available if --format pretty is specified.

--records¶: If this flag is provided, traffic_ctl config get will emit results in records.config format.

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 traffic_ctl config get --records.

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.

set RECORD VALUE¶: Set the named configuration record to the specified value. Refer to the records.config documentation for a list of the configuration variables you can specify. Note that this is not a synchronous operation.

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.

registry¶: Display information about the registered files in Traffic Server. This includes the full file path, config record name, parent config (if any) if needs root access and if the file is required in Traffic Server. This command uses filemanager.get_files_registry

traffic_ctl metric¶

get METRIC [METRIC...]¶

Display the current value of the specified statistics.

Error output available if --format pretty is specified.

match REGEX [REGEX...]¶: Display the current values of all statistics whose names match the given regular expression.

zero METRIC [METRIC...]¶: Reset the named statistics to zero.

describe RECORD [RECORD...]¶

Display all the known information about a metric record.

Error output available if --format pretty is specified.

traffic_ctl server¶

drain¶: Drop the number of active client connections.{

status¶: Option not yet available

traffic_ctl storage¶

offline PATH [PATH ...]¶: Mark a cache storage device as offline. The storage is identified by PATH which must match exactly a path specified in 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 traffic_server process.

traffic_ctl plugin¶

msg TAG DATA¶: Send a message to plugins. All plugins that have hooked the TSLifecycleHookID::TS_LIFECYCLE_MSG_HOOK will receive a callback for that hook. The TAG and DATA will be available to the plugin hook processing. It is expected that plugins will use TAG to select relevant messages and determine the format of the DATA.

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 traffic_ctl metric command or through the stats_over_http endpoint.

--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.

--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 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”.

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.

down HOSTNAME [HOSTNAME ...]¶

Marks the listed hosts as down so that they will not be chosen as a next hop parent. If --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 --time, --reason.

up HOSTNAME [HOSTNAME ...]¶

Marks the listed hosts as up so that they will be available for use as a next hop parent. Use --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 --reason.

traffic_ctl rpc¶

A mechanism to interact directly with the Traffic Server JSONRPC 2.0 endpoint. This means that this is not tied to any particular API but rather to the rpc endpoint, so you can directly send requests and receive responses from the server.

file¶

Reads a file or a set of files from the disc, use the content of the files as message(s) to the JSONRPC 2.0 endpoint. All jsonrpc messages will be validated before sending them. If the file contains invalid json|yaml format the message will not be send, in case of a set of files, if a particular file is not a proper json/yaml format then that particular file will be skipped.

Example:

traffic_ctl rpc file jsonrpc_cmd1.json jsonrpc_cmd2.yaml

get-api¶

Request the entire admin api. This will retrieve all the registered methods and notifications on the server side.

Example:

$ traffic_ctl rpc get-api
Methods:
- admin_host_set_status
- admin_server_stop_drain
- admin_server_start_drain
- admin_clear_metrics_records
- admin_clear_all_metrics_records
- admin_plugin_send_basic_msg
- admin_lookup_records
- admin_config_set_records
- admin_storage_get_device_status
- admin_storage_set_device_offline
- admin_config_reload
- show_registered_handlers
Notifications:
- some_registered_notification_handler

input¶

Input mode, traffic_ctl will provide a control input from a stream buffer. Once the content is written the terminal traffic_ctl will wait for the user to press Control-D to send the request to the rpc endpoint. This feature allows you to directly interact with the jsonrpc endpoint and test your API easily and without the need to know the low level implementation details of the transport layer. traffic_ctl will validate the input format, not the message content. The message content will be validated by the server. See example input_example_2.

--raw, -r¶: No json/yaml parse validation will take place, the input content will be directly send to the server.

Example:

$ traffic_ctl rpc input
>> Ctrl-D to fire the request
{
   "id":"86e59b43-185b-4a0b-b1c1-babb1a3d5401",
   "jsonrpc":"2.0",
   "method":"admin_lookup_records",
   "params":[
      {
         "record_name":"proxy.config.diags.debug.tags",
         "rec_types":[
            "1",
            "16"
         ]
      }
   ]
}
<pressed Ctrl-D>

<-- Server's response.
{
   "jsonrpc":"2.0",
   "result":{
      "recordList":[
         {
            "record":{
               "record_name":"proxy.config.diags.debug.tags",
               "record_type":"3",
               "version":"0",
               "raw_stat_block":"0",
               "order":"423",
               "config_meta":{
                  "access_type":"0",
                  "update_status":"0",
                  "update_type":"1",
                  "checktype":"0",
                  "source":"3",
                  "check_expr":"null"
               },
               "record_class":"1",
               "overridable":"false",
               "data_type":"STRING",
               "current_value":"rpc",
               "default_value":"http|dns"
            }
         }
      ]
   },
   "id":"86e59b43-185b-4a0b-b1c1-babb1a3d5401"
}

Example 2:

You can see a valid json {} but an invalid JSONRPC 2.0 message. In this case the server is responding.
$ traffic_ctl rpc input
>> Ctrl-D to fire the request
{}
<pressed Ctrl-D>
< -- Server's response
{
   "jsonrpc":"2.0",
   "error":{
      "code":-32600,
      "message":"Invalid Request"
   }
}

Examples¶

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

.. code-block:: bash

   # traffic_ctl host down cdn-cache-02.foo.com --reason manual

   # 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

Autest¶

If you want to interact with Traffic Server under a unit test, then a few things need to be considered.

Runroot needs to be configured in order to let traffic_ctl knows where to find the socket.
There are currently two ways to do this:
1. Using run-root param.
  1. Let Test.MakeATSProcess to create the runroot file under the Traffic Server config directory. This can be done by passing dump_runroot=True to the above function:
  ts = Test.MakeATSProcess(..., dump_runroot=True)
  dump_runroot will write out some of the keys inside the runroot file, in this case the runtimedir.
  1. Then you should specify the traffic_ctl --run-root when invoking the command:
    
    tr.Processes.Default.Command = f'traffic_ctl config reload --run-root {ts.Disk.runroot_yaml.Name}'
2. Setting up the TS_RUNROOT environment variable. This is very similar to 1 but, instead of passing the –run-root param to traffic_ctl, you just need to specify the TS_RUNROOT environment variable. To do that, just do as 1.1 shows and then:
  ts.SetRunRootEnv()
  The above call will set the variable, please be aware that this variable will also be read by TS.

traffic_ctl¶

Synopsis¶

Description¶

Options¶

Subcommands¶

traffic_ctl alarm¶

traffic_ctl config¶

traffic_ctl metric¶

traffic_ctl server¶

traffic_ctl storage¶

traffic_ctl plugin¶

traffic_ctl host¶

traffic_ctl rpc¶

Examples¶

Autest¶

See also¶