NAME

       traffic_ctl - Traffic Server command line tool

SYNOPSIS

       traffic_ctl [OPTIONS] SUBCOMMAND [OPTIONS]

DESCRIPTION

       traffic_ctl  is used to display and manipulate configure a running Traffic Server. traffic_ctl includes a
       number of subcommands that control different aspects of Traffic 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.

       To use traffic_ctl, traffic_manager needs to be running.

OPTIONS

       --debug
              Enable debugging output.

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

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 arguments are a specific alarm number (e.g. ''1''), or  an
              alarm string identifier (e.g.  ''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.  This  includes  the  current  and
              default values, the data type, the record class and syntax checking expression.

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

   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.

   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.

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

COPYRIGHT

       2024, dev@trafficserver.apache.org

9.2                                               Apr 01, 2024                                    TRAFFIC_CTL(8)