traffic_ops_ort package

This package is meant to fully implement the Traffic Ops Operational Readiness Test - which was originally written in a single, chickenscratch Perl script. When the main() function is run, it acts (more or less) exactly like that legacy script, with the ability to set system configuration files and start, stop, and restart HTTP cache servers etc.

This package provides an executable script named traffic_ops_ort

Usage

There are two main ways to invoke traffic_ops_ort. The first method uses what’s referred to as the “legacy call signature” and is meant to match the Perl command line arguments.

#75 Legacy Call Signature
traffic_ops_ort [-k] [-h] [-v] [--dispersion DISP] [--login_dispersion DISP]
         [--retries RETRIES] [--wait_for_parents INT] [--rev_proxy_disable]
         [--ts_root PATH] MODE LOG_LEVEL TO_URL LOGIN``

The second method - called the “new call signature” - aims to reduce the complexity of the ORT command line. Rather than require a URL and “login string” for connecting and authenticating with the Traffic Ops server, these pieces of information are optional and may be provided by the --to_url, -u/--to_user, and -p/--to_password options, respectively. If they are NOT provided, then their values will be obtained from the TO_URL, TO_USER, and TO_PASSWORD environment variables, respectively. Note that traffic_ops_ort cannot be run using the new call signature without providing a definition for each of these, either on the command line or in the execution environment.

#76 New call signature
traffic_ops_ort [-k] [-h] [-v] [--dispersion DISP] [--login_dispersion DISP]
     [--retries RETRIES] [--wait_for_parents INT] [--rev_proxy_disable]
     [--ts_root PATH] [-l LOG_LEVEL] [-u USER] [-p PASSWORD] [--to_url URL] MODE

These two call signatures should not be mixed, and traffic_ops_ort will exit with an error if they are.

Arguments and Flags

-h, --help

Print usage information and exit

-v, --version

Print version information and exit

-k, --insecure

An optional flag which, when used, disables the checking of SSL certificates for validity

--dispersion DISP

Wait a random number between 0 and DISP seconds before starting. This option only has any effect if MODE is SYNCDS. (Default: 300)

--login_dispersion DISP

Wait a random number between 0 and DISP seconds before authenticating with Traffic Ops. (Default: 0)

--retries RETRIES

If connection to Traffic Ops fails, retry RETRIES times before giving up (Default: 3).

--wait_for_parents INT

If INT is anything but 0, do not apply updates if parents of this server have pending updates. This option requires an integer argument for legacy compatibility reasons; 0 is considered False, anything else is True. (Default: 1)

--rev_prox_disable

Make requests directly to the Traffic Ops server, bypassing a reverse proxy if one exists.

--ts_root PATH

An optional flag which, if present, specifies the absolute path to the install directory of Apache Traffic Server. A common alternative to the default is /opt/trafficserver. (Default: /)

MODE

Specifies traffic_ops_ort’s mode of operation. Must be one of:

REPORT

Runs as though the mode was BADASS, but doesn’t actually change anything on the system.

Tip

This is normally useful with a verbose LOG_LEVEL to check the state of the system

INTERACTIVE
Runs as though the mode was BADASS, but asks the user for confirmation before making changes
REVALIDATE
Will not restart Apache Traffic Server, install packages, or enable/disable system services and will exit immediately if this server does not have revalidations pending. Also, the only configuration file that will be updated is regex_revalidate.config.
SYNCDS
Will not restart Apache Traffic Server, and will exit immediately if this server does not have updates pending. Otherwise, the same as BADASS
BADASS
Applies all pending configuration in Traffic Ops, and attempts to solve encountered problems when possible. This will install packages, enable/disable system services, and will start or restart Apache Traffic Server as necessary.
LOG_LEVEL, -l LOG_LEVEL, --log_level LOG_LEVEL

Sets the verbosity of output provided by traffic_ops_ort. This argument is positional in the legacy call signature, but optional in the new call signature, wherein it has a default value of “WARN”. Must be one of (case-insensitive):

NONE
Will output nothing, not even fatal errors.
CRITICAL
Will only output error messages that indicate an unrecoverable error.
FATAL
A synonym for “CRITICAL”
ERROR
Will output more general errors about conditions that are causing problems of some kind.
WARN
In addition to error information, will output warnings about conditions that may cause problems, or possible misconfiguration.
INFO
Outputs informational messages about what traffic_ops_ort is doing as it progresses.
DEBUG

Outputs detailed debug information, including stack traces.

Note

Not all stack traces indicate problems with traffic_ops_ort. Stack traces are printed whenever an exception is encountered, whether or not it could be handled.

TRACE
A synonym for “DEBUG”
ALL
A synonym for “DEBUG”

Note

All logging is sent to STDERR. INTERACTIVE MODE prompts are printed to STDOUT

TO_URL, --to_url TO_URL

This must be at minimum an FQDN that resolves to the Traffic Ops server, but may optionally include the schema and/or port number. E.g. https://trafficops.infra.ciab.test:443, https://trafficops.infra.ciab.test, trafficops.infra.ciab.test:443, and trafficops.infra.ciab.test are all acceptable, and in fact are all equivalent. When given a value without a schema, HTTPS will be the assumed protocol, and when a port number is not present, 443 will be assumed except in the case that the schema is provided and is http:// (case-insensitive) in which case 80 will be assumed.

This argument is positional in the legacy call signature, but is optional in the new call signature. When the new call signature is used and this option is not present on the command line, its value will be obtained from TO_URL. Note that traffic_ops_ort cannot be run using the new call signature unless this value is defined, either on the command line or in the execution environment.

LOGIN

The information used to authenticate with Traffic Ops. This must consist of a username and a password, delimited by a colon (:). E.g. admin:twelve. This argument is not used in the new call signature, instead -u/--to_user and -p/--to_password are used to separately set the authentication user and password, respectively.

Warning

The first colon found in this string is considered the delimiter. There is no way to escape the delimeter. This effectively means that usernames containing colons cannot be used to authenticate with Traffic Ops, though passwords containing colons should be fine.

-u USER, --to_user USER

Specifies the username of the user as whom to authenticate when connecting to Traffic Ops. This option is only available using the new call signature. If not provided when using said new call signature, the value will be obtained from the TO_USER environment variable. Note that traffic_ops_ort cannot be run using the new call signature unless this value is defined, either on the command line or in the execution environment.

-p PASSWORD, --to_password PASSWORD

Specifies the password of the user identified by TO_USER (or -u/--to_user if overridden) to use when authenticating to Traffic Ops. This option is only available using the new call signature. If not provided when using said new call signature, the value will be obtained from the TO_PASSWORD environment variable. Note that traffic_ops_ort cannot be run using the new call signature unless this value is defined, either on the command line or in the execution environment.

Environment Variables

TO_URL

Should be set to the URL of a Traffic Ops server. This doesn’t need to be a full URL, an FQDN will do just as well. It may also omit the port number on which the Traffic Ops server listens for incoming connections - port 443 will be assumed unless TO_URL is prefixed by http:// (case-insensitive), in which case port 80 will be assumed. The value of this environment variable will only be considered if traffic_ops_ort was invoked using the new call signature, which allows it to be overridden on the command line by the value of --to_url.

TO_USER

The username to use when authenticating to the Traffic Ops server. The value of this environment variable will only be considered if traffic_ops_ort was invoked using the new call signature, which allows it to be overridden on the command line by the value of -u/--to_user.

TO_PASSWORD

The password to use when authenticating to the Traffic Ops server. The value of this environment variable will only be considered if traffic_ops_ort was invoked using the new call signature, which allows it to be overridden on the command line by the value of -p/--to_password.

Strings with Special Meaning to ORT

When processing configuration files, if traffic_ops_ort encounters any of the strings in the Replacement Strings table it will perform the indicated replacement. This means that these strings can be used to create templates in Profile Parameters and certain Delivery Service configuration fields.

Table 48 Replacement Strings
String Replaced With
__CACHE_IPV4__ The IPv4 address of the cache server on which traffic_ops_ort is running.
__FULL_HOSTNAME__ The full hostname (i.e. including the full domain to which it belongs) of the cache server on which traffic_ops_ort is running.
__HOSTNAME__ The (short) hostname of the cache server on which traffic_ops_ort is running.
__RETURN__ A newline character (\n).
__SERVER_TCP_PORT__ If the cache server on which traffic_ops_ort is being run has a TCP port configured to something besides 80, this will be replaced with that TCP port value. If it is set to ``80``, this string will simply be removed, NOT replaced with ANYTHING.
##OVERRIDE## This string is only valid in the content of files named “remap.config”. It is further described in Remap Override

Deprecated since version ATCv4.0: The use of __RETURN__ in lieu of a true newline character is (finally) no longer necessary, and the ability to do so will be removed in the future.

Note

There is currently no way to indicate that a server’s IPv6 address should be inserted - only IPv4 is supported.

Remap Override

Warning

The ANY_MAP ##OVERRIDE## special string is a temporary solution and will be deprecated once Delivery Service Versioning is implemented. For this reason it is suggested that it not be used unless absolutely necessary.

The ##OVERRIDE## template string allows the Delivery Service Raw Remap Text field to override to fully override the Delivery Service’s line in the remap.config ATS configuration file, generated by Traffic Ops. The end result is the original, generated line commented out, prepended with ##OVERRIDDEN## and the ##OVERRIDE## rule is activated in its place. This behavior is used to incrementally deploy plugins used in this configuration file. Normally, this entails cloning the Delivery Service that will have the plugin, ensuring it is assigned to a subset of the cache servers that serve the Delivery Service content, then using this ##OVERRIDE## rule to create a remap.config rule that will use the plugin, overriding the normal rule. Simply grow the subset over time at the desired rate to slowly deploy the plugin. When it encompasses all cache servers that serve the original Delivery Service’s content, the “override Delivery Service” can be deleted and the original can use a non-##OVERRIDE## Raw Remap Text to add the plugin.

#77 Example of Remap Override
# This is the original line as generated by Traffic Ops
map http://from.example.com/ http://to.example.com/

# This is the raw remap text as configured on the delivery service
##OVERRIDE## map http://from.example.com/ http://to.example.com/ some_plugin.so

# The resulting content is what actually winds up in the remap.config file:
##OVERRIDE##
map http://from.example.com/ http://to.example.com/ some_plugin.so
##OVERRIDDEN## map http://from.example.com/ http://to.example.com/

Warning

The “from” URL must exactly match for this to properly work (e.g. including trailing URL ‘/’), otherwise ATS may fail to initialize or reload while processing remap.config.

Tip

To assist in troubleshooting, it is strongly recommended that any ##OVERRIDE## rules in use should be documented on the original Delivery Service.

Module Contents

traffic_ops_ort.doMain(args)

Runs the main routine based on the parsed arguments to the script

Parameters:args (Namespace) – A parsed argument list as returned from argparse.ArgumentParser.parse_args()
Return type:int
Returns:an exit code for the script.
Raises:AttributeError – when the namespace is missing required arguments
traffic_ops_ort.main()

The ORT entrypoint, parses argv before handing it off to doMain().

Return type:int
Returns:An exit code for traffic_ops_ort