TRAFFIC_CTL(8)

📦
version 9.2.5 · 4 versions
, in ubuntu noble, ubuntu questing

👑 TRAFFIC_CTL(8) — the Apache Traffic Server command line tool 👑

okay bestie, sit down, hydrate, and let me tell you about traffic_ctl, the little CLI that runs the whole Traffic Server situation. this is the page from the Apache Traffic Server manual, section 8, and we're doing the whole thing, no skips. 💖

✨ NAME ✨

traffic_ctl — Traffic Server command line tool

✨ SYNOPSIS ✨

traffic_ctl [OPTIONS] SUBCOMMAND [OPTIONS]

✨ DESCRIPTION ✨

traffic_ctl is your remote control for a running Traffic Server — you use it to display stuff and to manipulate configure it (yes, that's what the page says, we don't edit, we just vibe). it ships with a whole lil' family of subcommands, and each one handles a different slice of the server:

  • traffic_ctl alarm — Display and manipulate Traffic Server alarms
  • 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.
IMPORTANT bestie!! To use traffic_ctl, traffic_manager needs to be running. no manager, no vibes. 😭

✨ OPTIONS ✨

  • --debug — Enable debugging output. it's giving verbose, and we respect that.
  • -V, --version — Print version information and exit. short and iconic.

✨ SUBCOMMANDS ✨

💅 traffic_ctl alarm

  • list — List all alarm events that have not been acknowledged (cleared).
  • clear — Clear (acknowledge) all current alarms.
  • resolve ALARM [ALARM...] — Clear (acknowledge) an alarm event. the args are either a specific alarm number (like '1') or an alarm string identifier (like 'MGMT_ALARM_PROXY_CONFIG_ERROR').

💅 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. that's the current and default values, the data type, the record class, and the syntax checking expression. the full dossier, fr fr.
  • 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.
  • --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 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 — so don't @ me expecting instant results. 🫶
  • status — Display detailed status about the Traffic Server configuration system. that includes version information, whether the internal configuration store is current, and whether any daemon processes should be restarted.

💅 traffic_ctl metric

  • get METRIC [METRIC...] — Display the current value of the specifies statistics.
  • 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. back to 0, clean slate, main character energy ✨

💅 traffic_ctl server

  • restart — Shut down and immediately restart Traffic Server
  • --drain — This option modifies the behavior of traffic_ctl server restart such that traffic_server is not shut down until the number of active client connections drops to the number given by the proxy.config.restart.active_client_threshold configuration variable.
  • --manager — The default behavior of traffic_ctl server restart is to restart traffic_server. If this option is specified, traffic_manager is also restarted.
  • start — Start traffic_server if it is already running. 💀 yes that's literally what it says, we are simply reporting the lore.
  • --clear-cache — Clear the disk cache upon startup.
  • --clear-hostdb — Clear the DNS resolver cache upon startup.
  • status — Show the current proxy server status, indicating if we're running or not.
  • stop — Stop the running traffic_server process.
  • backtrace — Show a full stack trace of all the traffic_server threads.

💅 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. The DATA is optional and may not be available to consume; if not available then size will be 0 and the data will be NULL. Any extra passed value beside the tag and the optional data will be ignored. Check TSPluginMsg for more info.

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

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

records.config(5), storage.config(5)

2026, dev@trafficserver.apache.org

and that's the whole page, bestie, you ate it. 🍓 this was version 9.2, dated Feb 12, 2026 — go forth and traffic_ctl responsibly, mwah 💜🦋✨

📦 where this page comes from