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