atstccfg

atstccfg is a tool for generating configuration files server-side on ATC cache servers.

Warning

atstccfg does not have a stable command-line interface, it can and will change without warning. Scripts should avoid calling it for the time being, as its only intended caller is ORT.

The source code for atstccfg may be found in traffic_ops/ort/atstccfg, and the Go module reference is github.com/apache/trafficcontrol/traffic_ops/ort/atstccfg.

Usage

  • atstccfg -h

  • atstccfg -v

  • atstccfg -l

  • atstccfg [-e ERROR_LOCATION] [-i INFO_LOCATION] [-p] [-P TO_PASSWORD] [-r N] [-s] [-t TIMEOUT] [-u TO_URL] [-U TO_USER] [-w WARNING_LOCATION] [-y] [--dir TSROOT] -n CACHE_NAME

  • atstccfg [-e ERROR_LOCATION] [-i INFO_LOCATION] [-p] [-P TO_PASSWORD] [-r N] [-s] [-t TIMEOUT] [-u TO_URL] [-U TO_USER] [-w WARNING_LOCATION] [--dir TSROOT] -n CACHE_NAME -d DATA

  • atstccfg [-e ERROR_LOCATION] [-i INFO_LOCATION] [-p] [-P TO_PASSWORD] [-r N] [-s] [-t TIMEOUT] [-u TO_URL] [-U TO_USER] [-w WARNING_LOCATION] [--dir TSROOT] -n CACHE_NAME -a REVAL_STATUS -q QUEUE_STATUS

When called using the fourth form, atstccfg provides its normal output. This is the entirety of all configuration files necessary for the server, all provided at once. The output is in mixed/multipart format, defined by RFC 1521. Each chunk of the message comes with the proprietary Path header, which specifies the exact location on disk of the file whose contents are contained in that chunk.

Options

-a REVAL_STATUS, --set-reval-status REVAL_STATUS

Sets the reval_pending property of the server in Traffic Ops. Must be ‘true’ or ‘false’. Requires --set-queue-status also be set. This disables normal output.

-e ERROR_LOCATION, --log-location-error ERROR_LOCATION

The file location to which to log errors. Respects the special string constants of github.com/apache/trafficcontrol/lib/go-log. Default: ‘stderr’

-d DATA, --get-data DATA

Specifies non-configuration-file data to retrieve from Traffic Ops. This disables normal output. Valid values are:

chkconfig

Retrieves information about the services which should be running on the cache server. The output will be in JSON-encoded format as an array of objects with these fields:

name

The name of the service. This should correspond to an existing systemd service unit file.

value

A “chkconfig” line describing on which “run-levels” the services should be running. See the chkconfig(8) manual pages for details on what this field means.

packages

Retrieves information about the packages which should exist on the cache server. The output will be in JSON-encoded format as an array of objects with these fields:

name

The name of the package. This should hopefully be a meaningful package name for the cache server’s package management system.

version

The version of the package which should be installed. This might also be an empty string which means “any version will do”.

statuses

Retrieves all statuses from Traffic Ops. This is defined to be exactly the response object from the response to a GET request made to the statuses Traffic Ops API endpoint.

system-info

Retrieves generic information about the Traffic Control system from the system/info API endpoint. The output is the parameters object of the responses from GET requests to that endpoint (still JSON-encoded).

update-status

Retrieves information about the current update status using servers/{{hostname}}/update_status. The response is in the same format as the responses for that endpoint’s GET method handler - except that that endpoint returns an array and this atstccfg call signature returns a single one of those elements. Which one is chosen is arbitrary (hence undefined behavior when more than one server with the same hostname exists).

--dir TSROOT

Specifies a directory path in which to place Traffic Server configuration files, in the event that “location” Parameters are not found for them. If this is not given and location Parameters are not found for required files, then atstccfg will exit with an error.

The files that atstccfg considers “required” for these purposes are:

  • cache.config

  • hosting.config

  • parent.config

  • plugin.config

  • records.config

  • remap.config

  • storage.config

  • volume.config

-h, --help

Print usage information and exit.

-i INFO_LOCATION, --log-location-info INFO_LOCATION

The file location to which to log information messages. Respects the special string constants of github.com/apache/trafficcontrol/lib/go-log. Default: ‘stderr’

-l, --list-plugins

List the loaded plug-ins and then exit.

-n NAME, --cache-host-name NAME

Required. Specifies the (short) hostname of the cache server for which output will be generated. Must be the server hostname in Traffic Ops, not a URL, or FQDN. Behavior when more than one server exists with the passed hostname is undefined.

-p, --traffic-ops-disable-proxy

Bypass the Traffic Ops caching proxy and make requests directly to Traffic Ops. Has no effect if no such proxy exists.

-P TO_PASSWORD, --traffic-ops-password TO_PASSWORD

Authenticate using this password - if not given, atstccfg will attempt to use the value of the TO_PASSWORD environment variable.

-q QUEUE_STATUS, --set-queue-status QUEUE_STATUS

Sets the upd_pending property of the server identified by --cache-host-name to the specified value, which must be ‘true’ or ‘false’. Requires --set-reval-status to also be set.

-r N, --num-retries N

The number of times to retry getting a file if it fails. Default: 5

-s, --traffic-ops-insecure

If given, SSL certificate errors will be ignored when communicating with Traffic Ops.

Caution

The use of this option in production environments is discouraged.

-t TIMEOUT, --traffic-ops-timeout-milliseconds TIMEOUT

Sets the timeout - in milliseconds - for requests made to Traffic Ops. Default: 30000

-u TO_URL, --traffic-ops-url TO_URL

Request this URL, e.g. https://trafficops.infra.ciab.test/servers/edge/configfiles/ats. If not given, atstccfg will attempt to use the value of the TO_URL environment variable.

-U TO_USER, --traffic-ops-user TO_USER

Authenticate as the user TO_USER - if not given, atstccfg will attempt to use the value of the TO_USER environment variable.

-v, --version

Print version information and exit.

-w WARNING_LOCATION, --log-location-warning WARNING_LOCATION

The file location to which to log warnings. Respects the special string constants of github.com/apache/trafficcontrol/lib/go-log. Default: ‘stderr’

-y, --revalidate-only

When given, atstccfg will only emit files relevant for updating Content Invalidation Jobs. for Apache Traffic Server implementations, this limits the output to be only files named regex_revalidate.config. Has no effect if --get-data or --set-queue-status/--set-reval-status is/are used.

Environment Variables

atstccfg supports authentication with a Traffic Ops instance using the environment variables TO_URL (if -u/--traffic-ops-url is not given), TO_USER (if -U/--traffic-ops-user is not given), and TO_PASSWORD (if -P/--traffic-ops-password is not given).