Servers interfaces

CHANGELOG.md

@@ -37,12 +37,17 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Changed ORT Config Generation to be deterministic, which will prevent spurious diffs when nothing actually changed.
 - Changed the access logs in Traffic Ops to now show the route ID with every API endpoint call. The Route ID is appended to the end of the access log line.
 - With the addition of multiple server interfaces, interface data is constructed from IP Address/Gateway/Netmask (and their IPv6 counterparts) and Interface Name and Interface MTU fields on services. These **MUST** have proper, valid data before attempting to upgrade or the upgrade **WILL** fail. In particular IP fields need to be valid IP addresses/netmasks, and MTU must only be positive integers of at least 1280.
+- The `/servers` and `/servers/{{ID}}}` API endpoints have been updated to use and reflect multi-interface servers.
 
 ### Deprecated
 - Deprecated the non-nullable `DeliveryService` Go struct and other structs that use it. `DeliveryServiceNullable` structs should be used instead.
 
 ### Removed
 - Removed deprecated Traffic Ops Go Client methods.
+- Configuration generation logic in the TO API (v1) for:
+  - `ip_allow.config`
+  - `parent.config`
+  - `remap.config`
 
 ## [4.1.0] - 2020-04-23
 ### Added

docs/source/admin/quick_howto/content_invalidation.rst

@@ -18,11 +18,11 @@
 ****************************
 Forcing Content Invalidation
 ****************************
-Invalidating content on the CDN is sometimes necessary when the :term:`origin` was mis-configured and something is cached in the CDN  that needs to be removed.
+Invalidating content on the CDN is sometimes necessary when the :term:`Origin` was mis-configured and something is cached in the CDN  that needs to be removed.
 
 .. impl-detail:: Given the size of a typical Traffic Control CDN and the amount of content that can be cached in it, removing the content from all the caches may take a long time. To speed up content invalidation, Traffic Control does not try to remove the content from the caches, but it makes the content inaccessible using the `regex_revalidate plugin for Apache Traffic Server <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/regex_revalidate.en.html>`_. This forces a "re-validation" of the content.
 
-.. Note:: This method forces :term:`cache servers` to "re-validate" content, so in order to work properly the :term:`origin` needs to support revalidation according to section 13 of :rfc:`2616`.
+.. Note:: This method forces :term:`cache servers` to "re-validate" content, so in order to work properly the :term:`Origin` needs to support revalidation according to section 13 of :rfc:`2616`.
 
 To invalidate content for a specific :term:`Delivery Service`, follow these steps:
 
@@ -42,7 +42,7 @@ To invalidate content for a specific :term:`Delivery Service`, follow these step
 
 		Select 'Manage Invalidation Requests'
 
-#. Click/tap on the :guilabel:`+` button to open the submission form for a new content invalidation. Fill out this form. The "Path Regex" field should be a `PCRE <http://www.pcre.org/>`_-compatible regular expression that matches all content that must be invalidated - and should **not** match any content that must *not* be invalidated. "TTL (hours)" specifies the number of hours for which the invalidation should remain active. Best practice is to set this to the same as the content's cache lifetime (typically set in the :term:`origin`'s ``Cache-Control`` response header).
+#. Click/tap on the :guilabel:`+` button to open the submission form for a new content invalidation. Fill out this form. The "Path Regex" field should be a `PCRE <http://www.pcre.org/>`_-compatible regular expression that matches all content that must be invalidated - and should **not** match any content that must *not* be invalidated. "TTL (hours)" specifies the number of hours for which the invalidation should remain active. Best practice is to set this to the same as the content's cache lifetime (typically set in the :term:`Origin`'s ``Cache-Control`` response header).
 
 	.. figure:: content_invalidation/03.png
 		:align: center

docs/source/admin/quick_howto/oauth_login.rst

@@ -26,7 +26,7 @@ An opt-in configuration for SSO using OAuth is supported and can be configured t
 
 .. Note:: The ``POST`` from the API to the OAuth provider to exchange the code for a token expects the response to have the token in JSON format with `access_token` as the desired field (and can include other fields).  It also supports a response with just the token itself as the body.  Further development work will need to be done to allow other resposne forms or other response fields.
 
-.. Note:: Users must exist in both Traffic Ops as well as in the OAuth provider's system.  The user's rights are defined by the :term:`role` assigned to the user.
+.. Note:: Users must exist in both Traffic Ops as well as in the OAuth provider's system.  The user's rights are defined by the :term:`Role` assigned to the user.
 
 To configure OAuth login:
 

docs/source/admin/quick_howto/server_capabililty.rst

@@ -18,9 +18,9 @@
 **************************
 Manage Server Capabilities
 **************************
-Server capabilities are designed to enable users with the Operations or Admin :term:`Role` to control the flow of :term:`delivery service` traffic through only the :term:`cache servers` (:term:`Edge` or :term:`Mid`) that have the required capabilities. For example, :term:`delivery services` designed to serve large binary files should only have requests routed to :term:`cache servers` with sufficient disk cache. Currently, this can be controlled at the :term:`Edge-tier` where system operators can explicitly assign only :term:`Edge-tier caches` with sufficient disk cache to the :term:`delivery service`. However, operators do not have control of :term:`Mid-tier cache` assignments and cannot dictate which :term:`Mid-tier caches` are qualified to serve these large binary files. This will cause a problem if a :term:`Mid-tier cache` with insufficient disk cache is asked to serve the :term:`delivery services` large binary files.
+Server capabilities are designed to enable users with the Operations or Admin :term:`Role` to control the flow of :term:`Delivery Service` traffic through only the :term:`cache servers` (:term:`Edge` or :term:`Mid`) that have the required capabilities. For example, :term:`Delivery Services` designed to serve large binary files should only have requests routed to :term:`cache servers` with sufficient disk cache. Currently, this can be controlled at the :term:`Edge-tier` where system operators can explicitly assign only :term:`Edge-tier caches` with sufficient disk cache to the :term:`Delivery Service`. However, operators do not have control of :term:`Mid-tier cache` assignments and cannot dictate which :term:`Mid-tier caches` are qualified to serve these large binary files. This will cause a problem if a :term:`Mid-tier cache` with insufficient disk cache is asked to serve the :term:`Delivery Services`' large binary files.
 
-A list of the server capabilities can be found under :menuselection:`Configure --> Server Capabilities`. Users with a higher-level :term:`role` ("operations" or "admin") can create or delete server capabilities. Server capabilities can only be deleted if they are not currently being used by a :term:`cache server` or required by a :term:`delivery service`.
+A list of the server capabilities can be found under :menuselection:`Configure --> Server Capabilities`. Users with a higher-level :term:`Role` ("operations" or "admin") can create or delete server capabilities. Server capabilities can only be deleted if they are not currently being used by a :term:`cache server` or required by a :term:`Delivery Service`.
 
 .. figure:: server_capability/server_caps_table.png
 	:align: center
@@ -44,12 +44,12 @@ Users with the Operations or Admin :term:`Role` can associate one or more server
 
 Manage delivery service required server capabilities
 ====================================================
-Users with the Operations or Admin :term:`Role` can associate one or more required server capabilities with a :term:`delivery service` by navigating to a :term:`delivery service` via :menuselection:`Services --> Delivery Services` and using the context menu for the :term:`delivery services` table and selecting :menuselection:`Manage Required Server Capabilities` or by navigating to :menuselection:`Services --> Delivery Services --> Delivery Service --> More --> Manage Required Server Capabilities`.
+Users with the Operations or Admin :term:`Role` can associate one or more required server capabilities with a :term:`Delivery Service` by navigating to a :term:`Delivery Service` via :menuselection:`Services --> Delivery Services` and using the context menu for the :term:`Delivery Services` table and selecting :menuselection:`Manage Required Server Capabilities` or by navigating to :menuselection:`Services --> Delivery Services --> Delivery Service --> More --> Manage Required Server Capabilities`.
 
-Adding a required server capability to a :term:`delivery service` will ensure two things:
+Adding a required server capability to a :term:`Delivery Service` will ensure two things:
 
-1. Only :term:`Edge-tier caches` with the required capability can be assigned to the :term:`delivery service`
-2. Only :term:`Mid-tier caches` with the required capability will handle requests of the :term:`delivery service` (if applicable)
+1. Only :term:`Edge-tier caches` with the required capability can be assigned to the :term:`Delivery Service`
+2. Only :term:`Mid-tier caches` with the required capability will handle requests of the :term:`Delivery Service` (if applicable)
 
 .. figure:: server_capability/ds_server_caps_table.png
 	:align: center

docs/source/admin/traffic_portal/usingtrafficportal.rst

@@ -418,33 +418,33 @@ Server management includes the ability to (where applicable):
 
 Origins
 -------
-A table of all :term:`origins`. These are automatically created for the :term:`origins` served by :term:`Delivery Services` throughout all CDNs, but additional ones can be created at will. The table has the following columns:
+A table of all :term:`Origins`. These are automatically created for the :term:`Origins` served by :term:`Delivery Services` throughout all CDNs, but additional ones can be created at will. The table has the following columns:
 
-:Name:             The name of the :term:`origin`. If this :term:`origin` was created automatically for a :term:`Delivery Service`, this will be the :ref:`ds-xmlid` of that :term:`Delivery Service`.
-:Tenant:           The name of the :term:`Tenant` that owns this :term:`origin` - this is not necessarily the same as the :term:`Tenant` that owns the :term:`Delivery Service` to which this :term:`origin` belongs.
-:Primary:          Either ``true`` to indicate that this is the "primary" :term:`origin` for the :term:`Delivery Service` to which it is assigned, or ``false`` otherwise.
-:Delivery Service: The :ref:`ds-xmlid` of the :term:`Delivery Service` to which this :term:`origin` is assigned.
-:FQDN:             The :abbr:`FQDN (Fully Qualified Domain Name)` of the :term:`origin server`.
-:IPv4 Address:     The :term:`origin`'s IPv4 address, if configured.
-:IPv6 Address:     The :term:`origin`'s IPv6 address, if configured.
-:Protocol:         The protocol this :term:`origin` uses to serve content. One of
+:Name:             The name of the :term:`Origin`. If this :term:`Origin` was created automatically for a :term:`Delivery Service`, this will be the :ref:`ds-xmlid` of that :term:`Delivery Service`.
+:Tenant:           The name of the :term:`Tenant` that owns this :term:`Origin` - this is not necessarily the same as the :term:`Tenant` that owns the :term:`Delivery Service` to which this :term:`Origin` belongs.
+:Primary:          Either ``true`` to indicate that this is the "primary" :term:`Origin` for the :term:`Delivery Service` to which it is assigned, or ``false`` otherwise.
+:Delivery Service: The :ref:`ds-xmlid` of the :term:`Delivery Service` to which this :term:`Origin` is assigned.
+:FQDN:             The :abbr:`FQDN (Fully Qualified Domain Name)` of the :term:`Origin`.
+:IPv4 Address:     The :term:`Origin`'s IPv4 address, if configured.
+:IPv6 Address:     The :term:`Origin`'s IPv6 address, if configured.
+:Protocol:         The protocol this :term:`Origin` uses to serve content. One of
 
 	- http
 	- https
 
-:Port: The port on which the :term:`origin server` listens for incoming HTTP(S) requests.
+:Port: The port on which the :term:`Origin` listens for incoming HTTP(S) requests.
 
-	.. note:: If this field appears blank in the table, it means that a default was chosen for the :term:`origin` based on its Protocol - ``80`` for "http", ``443`` for "https".
+	.. note:: If this field appears blank in the table, it means that a default was chosen for the :term:`Origin` based on its Protocol - ``80`` for "http", ``443`` for "https".
 
-:Coordinate: The name of the geographic coordinate pair that defines the physical location of this :term:`origin server`. :term:`Origins` created for :term:`Delivery Services` automatically will **not** have associated Coordinates. This can be rectified on the details pages for said :term:`origins`
-:Cachegroup: The :ref:`Name of the Cache Group <cache-group-name>` to which this :term:`origin` belongs, if any.
-:Profile:    The :ref:`profile-name` of a :term:`Profile` used by this :term:`origin`.
+:Coordinate: The name of the geographic coordinate pair that defines the physical location of this :term:`Origin`. :term:`Origins` created for :term:`Delivery Services` automatically will **not** have associated Coordinates. This can be rectified on the details pages for said :term:`Origins`
+:Cachegroup: The :ref:`Name of the Cache Group <cache-group-name>` to which this :term:`Origin` belongs, if any.
+:Profile:    The :ref:`profile-name` of a :term:`Profile` used by this :term:`Origin`.
 
 :term:`Origin` management includes the ability to (where applicable):
 
-- create a new :term:`origin`
-- update an existing :term:`origin`
-- delete an existing :term:`origin`
+- create a new :term:`Origin`
+- update an existing :term:`Origin`
+- delete an existing :term:`Origin`
 
 .. _tp-configure-profiles:
 
@@ -740,7 +740,7 @@ User management includes the ability to (where applicable):
 - update an existing user
 - view :term:`Delivery Services` visible to a user
 
-.. Note:: If OAuth is enabled, the username must exist both here as well as with the OAuth provider. A user's rights are defined by the :term:`role` assigned to the user in Traffic Ops. Creating/deleting a user here will update the user's :term:`role` but the user needs to be created/deleted with the OAuth provider as well.
+.. Note:: If OAuth is enabled, the username must exist both here as well as with the OAuth provider. A user's rights are defined by the :term:`Role` assigned to the user in Traffic Ops. Creating/deleting a user here will update the user's :term:`Role` but the user needs to be created/deleted with the OAuth provider as well.
 
 Tenants
 -------

docs/source/admin/traffic_router.rst

@@ -211,7 +211,7 @@ Much of a Traffic Router's configuration can be obtained through the :term:`Para
 	| deepcoveragezone.polling.url            | CRConfig.json                | The location (URL) where a :term:`Deep Coverage Zone Map` may be found.                                                               |
 	+-----------------------------------------+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 	| client.steering.forced.diversity        | CRConfig.json                | When this :term:`Parameter` exists and is exactly "true", it enables the "Client Steering Forced Diversity" feature to diversify      |
-	|                                         |                              | CLIENT_STEERING results by including more unique :term:`Edge-Tier Cache Servers` in the response to the client's request.             |
+	|                                         |                              | CLIENT_STEERING results by including more unique :term:`Edge-tier cache servers` in the response to the client's request.             |
 	+-----------------------------------------+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 	| tld.soa.expire                          | CRConfig.json                | The value for the "expire" field the Traffic Router DNS Server will respond with on :abbr:`SOA (Start of Authority)` records.         |
 	+-----------------------------------------+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+

docs/source/api/index.rst

@@ -102,6 +102,17 @@ Object
 ``undefined``
 	No ``response`` object is present in the response payload. Unless the format is otherwise noted, this means that there should be no field list in the "Response Structure" subsection.
 
+Summary
+-------
+The top-level ``summary`` object is used to provide summary statistics about object collections. In general the use of ``summary`` is left to be defined by API endpoints (subject to some restrictions). When an endpoint uses the ``summary`` object, its fields will be explained in a subsection of the "Response Structure" named "Summary Fields".
+
+The following, reserved properties of ``summary`` are guaranteed to always have their herein-described meaning.
+
+.. _reserved-summary-fields:
+
+``count``
+	``count`` contains an unsigned integer that defines the total number of results that could possibly be returned given the non-pagination query parameters supplied by the client.
+
 Using API Endpoints
 ===================
 #. Authenticate with valid Traffic Control user account credentials (the same used by Traffic Portal).

docs/source/api/v1/cdns_name_snapshot.rst

@@ -116,7 +116,7 @@ Response Structure
 
 		.. seealso:: :ref:`health-proto`
 
-:contentServers: An object containing keys which are the (short) hostnames of the :term:`Edge-Tier cache servers` in the CDN; the values corresponding to those keys are routing information for said servers
+:contentServers: An object containing keys which are the (short) hostnames of the :term:`Edge-tier cache servers` in the CDN; the values corresponding to those keys are routing information for said servers
 
 	:cacheGroup:       A string that is the :ref:`cache-group-name` of the :term:`Cache Group` to which the server belongs
 	:deliveryServices: An object containing keys which are the names of :term:`Delivery Services` to which this :term:`cache server` is assigned; the values corresponding to those keys are arrays of :abbr:`FQDNs (Fully Qualified Domain Names)` that resolve to this :term:`cache server`
@@ -186,9 +186,9 @@ Response Structure
 		:shuffled: A string containing a boolean that tells whether the :term:`cache servers` chosen for content dispersion are chosen randomly or based on a consistent hash of the request URL; one of:
 
 			"false"
-				:term:`Cache servers` will be chosen consistently
+				:term:`cache servers` will be chosen consistently
 			"true"
-				:term:`Cache servers` will be chosen at random
+				:term:`cache servers` will be chosen at random
 
 	:domains:             An array of domains served by this :term:`Delivery Service`
 	:ecsEnabled:          A string containing a boolean from :ref:`ds-ecs` that tells whether EDNS0 client subnet is enabled on this :term:`Delivery Service`; one of: