You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@trafficcontrol.apache.org by GitBox <gi...@apache.org> on 2021/01/21 00:52:55 UTC
[GitHub] [trafficcontrol] srijeet0406 opened a new pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
srijeet0406 opened a new pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450
<!--
************ STOP!! ************
If this Pull Request is intended to fix a security vulnerability, DO NOT submit it! Instead, contact
the Apache Software Foundation Security Team at security@trafficcontrol.apache.org and follow the
guidelines at https://www.apache.org/security/ regarding vulnerability disclosure.
-->
## What does this PR (Pull Request) do?
<!-- Explain the changes you made here. If this fixes an Issue, identify it by
replacing the text in the checkbox item with the Issue number e.g.
- [x] This PR fixes #9001 OR is not related to any Issue
^ This will automatically close Issue number 9001 when the Pull Request is
merged (The '#' is important).
Be sure you check the box properly, see the "The following criteria are ALL
met by this PR" section for details.
-->
- [x] This PR fixes #5316 <!-- You can check for an issue here: https://github.com/apache/trafficcontrol/issues -->
## Which Traffic Control components are affected by this PR?
<!-- Please delete all components from this list that are NOT affected by this
Pull Request. Also, feel free to add the name of a tool or script that is
affected but not on the list.
Additionally, if this Pull Request does NOT affect documentation, please
explain why documentation is not required. -->
- Documentation
- Traffic Ops
- Traffic Portal
- CI tests
## What is the best way to verify this PR?
<!-- Please include here ALL the steps necessary to test your Pull Request. If
it includes tests (and most should), outline here the steps needed to run the
tests. If not, lay out the manual testing procedure and please explain why
tests are unnecessary for this Pull Request. -->
## If this is a bug fix, what versions of Traffic Control are affected?
<!-- If this PR fixes a bug, please list here all of the affected versions - to
the best of your knowledge. It's also pretty helpful to include a commit hash
of where 'master' is at the time this PR is opened (if it affects master),
because what 'master' means will change over time. For example, if this PR
fixes a bug that's present in master (at commit hash '1df853c8'), in v4.0.0,
and in the current 4.0.1 Release candidate (e.g. RC1), then this list would
look like:
- master (1df853c8)
- 4.0.0
- 4.0.1 (RC1)
If you don't know what other versions might have this bug, AND don't know how
to find the commit hash of 'master', then feel free to leave this section
blank (or, preferably, delete it entirely).
-->
## The following criteria are ALL met by this PR
<!-- Check the boxes to signify that the associated statement is true. To
"check a box", replace the space inside of the square brackets with an 'x'.
e.g.
- [ x] <- Wrong
- [x ] <- Wrong
- [] <- Wrong
- [*] <- Wrong
- [x] <- Correct!
-->
- [x] This PR includes tests
- [x] This PR includes documentation
- [x] This PR includes an update to CHANGELOG.md
- [x] This PR includes any and all required license headers
- [x] This PR **DOES NOT FIX A SERIOUS SECURITY VULNERABILITY** (see [the Apache Software Foundation's security guidelines](https://www.apache.org/security/) for details)
## Additional Information
<!-- If you would like to include any additional information on the PR for
potential reviewers please put it here.
Some examples of this would be:
- Before and after screenshots/gifs of the Traffic Portal if it is affected
- Links to other dependent Pull Requests
- References to relevant context (e.g. new/updates to dependent libraries,
mailing list records, blueprints)
Feel free to leave this section blank (or, preferably, delete it entirely).
-->
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] srijeet0406 commented on a change in pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
srijeet0406 commented on a change in pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#discussion_r564708310
##########
File path: traffic_portal/app/src/common/modules/table/servers/TableServersController.js
##########
@@ -220,7 +220,7 @@ var TableServersController = function(tableName, servers, filter, $scope, $state
},
{
headerName: "Router Port Name",
- field: "routerPortName",
+ field: "routerPort",
Review comment:
yeah I think I changed it to `routerPortName` in my latest commit
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
ocket8888 commented on a change in pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#discussion_r563971707
##########
File path: docs/source/api/v3/about.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-about:
+.. _to-api-v3-v3-about:
Review comment:
This one apparently already had a `-v3-` segment, so now it's got two
##########
File path: docs/source/api/v3/ping.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-ping:
+.. _to-api-v3-v3-ping:
Review comment:
Same as above RE: two`v3` segments
##########
File path: docs/source/api/v3/federations_all.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-federations-all:
+.. _to-api-v3-v3-federations-all:
Review comment:
Same as above RE: two`v3` segments
##########
File path: docs/source/api/v3/servers.rst
##########
@@ -39,7 +39,7 @@ Request Structure
| cachegroupName | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-name` |
+----------------+----------+-------------------------------------------------------------------------------------------------------------------+
| dsId | no | Return only those servers assigned to the :term:`Delivery Service` identified by this integral, unique identifier.|
- | | | If the Delivery Service has a :term:`Topology` assigned to it, the :ref:`to-api-servers` endpoint will return |
+ | | | If the Delivery Service has a :term:`Topology` assigned to it, the :ref:`to-api-v3-servers` endpoint will return |
Review comment:
Malformed table
##########
File path: docs/source/api/v3/steering.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-steering:
+.. _to-api-v3-v3-steering:
Review comment:
Same as above RE: two`v3` segments
##########
File path: docs/source/api/v3/deliveryservice_requests_id_assign.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-deliveryservice_requests-id-assign:
+.. _to-api-v3-v3-deliveryservice_requests-id-assign:
Review comment:
Same as above RE: two`v3` segments
##########
File path: docs/source/api/v3/cdns_dnsseckeys_generate.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-cdns-dnsseckeys-generate:
+.. _to-api-v3-v3-cdns-dnsseckeys-generate:
Review comment:
same as above RE: double-segment.
##########
File path: docs/source/api/v3/deliveryservice_requests_id_status.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-deliveryservice_requests-id-status:
+.. _to-api-v3-v3-deliveryservice_requests-id-status:
Review comment:
Same as above RE: two`v3` segments
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] srijeet0406 commented on a change in pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
srijeet0406 commented on a change in pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#discussion_r562951019
##########
File path: traffic_ops/app/db/migrations/2021011500000000_update_interfaces_multiple_routers.sql
##########
@@ -0,0 +1,53 @@
+/*
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
+-- +goose Up
+-- SQL in section 'Up' is executed when this migration is applied
+ALTER TABLE interface ADD COLUMN router_host_name text DEFAULT '';
+ALTER TABLE interface ADD COLUMN router_port text DEFAULT '';
Review comment:
Checked with Jeff Howell, and he suggested keeping it as a string. I changed the name to be `router_port_name` though.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] srijeet0406 commented on a change in pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
srijeet0406 commented on a change in pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#discussion_r564145131
##########
File path: traffic_portal/app/src/common/modules/table/servers/TableServersController.js
##########
@@ -220,7 +220,7 @@ var TableServersController = function(tableName, servers, filter, $scope, $state
},
{
headerName: "Router Port Name",
- field: "routerPortName",
+ field: "routerPort",
Review comment:
I'm a UI rookie, but isn't the field `interfaceName` working in the same way? It comes from the `interface` struct inside the `server` struct, as do `routerHostName` and `routerPortName`.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
ocket8888 commented on a change in pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#discussion_r564696022
##########
File path: traffic_portal/app/src/common/modules/table/servers/TableServersController.js
##########
@@ -220,7 +220,7 @@ var TableServersController = function(tableName, servers, filter, $scope, $state
},
{
headerName: "Router Port Name",
- field: "routerPortName",
+ field: "routerPort",
Review comment:
Yeah, I guess we don't actually need to remove it. It's fair enough to represent the router that's used for the IP addresses that we're adding to it.
But I still think the name is wrong. The property name that gets added from `toLegacyIPInfo` looks like `routerPortName`, so that'd need to be the name of the field to display it properly.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] srijeet0406 commented on a change in pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
srijeet0406 commented on a change in pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#discussion_r565751139
##########
File path: traffic_portal/app/src/common/modules/form/server/form.server.tpl.html
##########
@@ -268,6 +253,15 @@ <h6>Deprecated</h6>
<label for="{{inf.name}}-max-bandwidth" ng-class="{'has-error': hasError(serverForm[inf.name+'-max-bandwidth'])}">Maximum Bandwidth</label>
<input id="{{inf.name}}-max-bandwidth" ng-model="inf.maxBandwidth" ng-class="{'has-error': hasError(serverForm[inf.name+'-max-bandwidth'])}" min="0" type="number" name="{{inf.name}}-max-bandwidth"/>
<small class="input-error" ng-show="hasPropertyError(serverForm[inf.name+'-max-bandwidth'], 'min')">Cannot be negative</small>
+ <label for="{{inf.name}}-router-hostname" ng-class="{'has-error': hasError(serverForm[inf.name+'-router-hostname'])}">Router Hostname</label>
+ <input id="{{inf.name}}-router-hostname" ng-model="inf.routerHostName" ng-class="{'has-error': hasError(serverForm[inf.name+'-router-hostname'])}" type="text" name="{{inf.name}}-router-hostname" maxlength="256" pattern="\S*"/>
+ <small class="input-error" ng-show="hasPropertyError(serverForm[inf.name+'-router-hostname'], 'maxlength')">Too long</small>
+ <small class="input-error" ng-show="hasPropertyError(serverForm[inf.name+'-router-hostname'], 'pattern')">No Spaces</small>
+ <label for="{{inf.name}}-router-portname" ng-class="{'has-error': hasError(serverForm[inf.name+'-router-portname'])}">Router Port Name</label>
+ <input id="{{inf.name}}-router-portname" ng-model="inf.routerPortName" ng-class="{'has-error': hasError(serverForm[inf.name+'-router-portname'])}" type="text" name="{{inf.name}}-router-portname" maxlength="256" pattern="\S*"/>
+ <small class="input-error" ng-show="hasPropertyError(serverForm[inf.name+'-router-port'], 'maxlength')">Too long</small>
+ <small class="input-error" ng-show="hasPropertyError(serverForm[inf.name+'-router-port'], 'pattern')">No Spaces</small>
Review comment:
aah yeah, copy paste error. Fixed now
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
ocket8888 commented on a change in pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#discussion_r564037261
##########
File path: lib/go-tc/servers.go
##########
@@ -63,12 +72,22 @@ type ServersV1Response struct {
type ServerDetailV11 struct {
ServerDetail
LegacyInterfaceDetails
+ RouterHostName *string `json:"routerHostName" db:"router_host_name"`
+ RouterPortName *string `json:"routerPortName" db:"router_port_name"`
}
// ServerDetailV30 is the details for a server for API v3
type ServerDetailV30 struct {
ServerDetail
ServerInterfaces *[]ServerInterfaceInfo `json:"interfaces"`
+ RouterHostName *string `json:"routerHostName" db:"router_host_name"`
+ RouterPortName *string `json:"routerPortName" db:"router_port_name"`
+}
+
+// ServerDetailV40 is the details for a server for API v4
+type ServerDetailV40 struct {
+ ServerDetail
+ ServerInterfaces *[]ServerInterfaceInfoV40 `json:"interfaces"`
Review comment:
Does this need to be a pointer? Slices are already reference types so you can already do
```go
type Foo {
Slice []int
}
a := Foo{Slice: nil}
```
##########
File path: lib/go-tc/servers.go
##########
@@ -99,6 +124,13 @@ type ServerInterfaceInfo struct {
Name string `json:"name" db:"name"`
}
+// ServerInterfaceInfoV40 is the data associated with a V40 server's interface.
+type ServerInterfaceInfoV40 struct {
+ ServerInterfaceInfo
+ RouterHostName string `json:"routerHostName" db:"router_host_name"`
+ RouterPortName string `json:"routerPortName" db:"router_port_name"`
Review comment:
The database and the existing API implementation for these server fields allows them to be null - if they're still allowed to be `null` then these need to be pointers, otherwise we need to enforce that these can't be null in the database, because that could cause TO to return data that can't be used in subsequent requests.
Honestly I don't really care which, just make sure existing data is `COALESCE`'d if you go the db constraint route
##########
File path: traffic_portal/app/src/common/modules/table/servers/TableServersController.js
##########
@@ -220,7 +220,7 @@ var TableServersController = function(tableName, servers, filter, $scope, $state
},
{
headerName: "Router Port Name",
- field: "routerPortName",
+ field: "routerPort",
Review comment:
This field won't work anymore, since there's no field on the input data named `routerPort` (or `routerPortName`). I think we may just have to remove it.
##########
File path: docs/source/api/v4/servers.rst
##########
@@ -0,0 +1,522 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers:
+
+***********
+``servers``
+***********
+
+``GET``
+=======
+Retrieves properties of all servers across all CDNs.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +================+==========+===================================================================================================================+
+ | cachegroup | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | cachegroupName | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-name` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | dsId | no | Return only those servers assigned to the :term:`Delivery Service` identified by this integral, unique identifier.|
+ | | | If the Delivery Service has a :term:`Topology` assigned to it, the :ref:`to-api-servers` endpoint will return |
+ | | | each server whose :term:`Cache Group` is associated with a :term:`Topology Node` of that Topology and has the |
+ | | | :term:`Server Capabilities` that are |
+ | | | :term:`required by the Delivery Service <Delivery Service required capabilities>` but excluding |
+ | | | :term:`Origin Servers` that are not assigned to the Delivery Service. For more information, see |
+ | | | :ref:`multi-site-origin-qht`. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | hostName | no | Return only those servers that have this (short) hostname |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | id | no | Return only the server with this integral, unique identifier |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | profileId | no | Return only those servers that are using the :term:`Profile` that has this :ref:`profile-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | status | no | Return only those servers with this status - see :ref:`health-proto` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only servers of this :term:`Type` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | topology | no | Return only servers who belong to cachegroups assigned to the :term:`Topology` identified by this name |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | sortOrder | no | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | limit | no | Choose the maximum number of results to return |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | offset | no | The number of results to skip before beginning to return results. Must use in conjunction with limit |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | page | no | Return the n\ :sup:`th` page of results, where "n" is the value of this parameter, pages are ``limit`` long and |
+ | | | the first page is 1. If ``offset`` was defined, this query parameter has no effect. ``limit`` must be defined to |
+ | | | make use of ``page``. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/4.0/servers?hostName=mid HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
Review comment:
This is still indented with spaces instead of tab characters.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
ocket8888 commented on a change in pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#discussion_r563971707
##########
File path: docs/source/api/v3/about.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-about:
+.. _to-api-v3-v3-about:
Review comment:
This one apparently already had a `-v3-` segment, so now it's got two
##########
File path: docs/source/api/v3/ping.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-ping:
+.. _to-api-v3-v3-ping:
Review comment:
Same as above RE: two`v3` segments
##########
File path: docs/source/api/v3/federations_all.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-federations-all:
+.. _to-api-v3-v3-federations-all:
Review comment:
Same as above RE: two`v3` segments
##########
File path: docs/source/api/v3/servers.rst
##########
@@ -39,7 +39,7 @@ Request Structure
| cachegroupName | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-name` |
+----------------+----------+-------------------------------------------------------------------------------------------------------------------+
| dsId | no | Return only those servers assigned to the :term:`Delivery Service` identified by this integral, unique identifier.|
- | | | If the Delivery Service has a :term:`Topology` assigned to it, the :ref:`to-api-servers` endpoint will return |
+ | | | If the Delivery Service has a :term:`Topology` assigned to it, the :ref:`to-api-v3-servers` endpoint will return |
Review comment:
Malformed table
##########
File path: docs/source/api/v3/steering.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-steering:
+.. _to-api-v3-v3-steering:
Review comment:
Same as above RE: two`v3` segments
##########
File path: docs/source/api/v3/deliveryservice_requests_id_assign.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-deliveryservice_requests-id-assign:
+.. _to-api-v3-v3-deliveryservice_requests-id-assign:
Review comment:
Same as above RE: two`v3` segments
##########
File path: docs/source/api/v3/cdns_dnsseckeys_generate.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-cdns-dnsseckeys-generate:
+.. _to-api-v3-v3-cdns-dnsseckeys-generate:
Review comment:
same as above RE: double-segment.
##########
File path: docs/source/api/v3/deliveryservice_requests_id_status.rst
##########
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-v3-deliveryservice_requests-id-status:
+.. _to-api-v3-v3-deliveryservice_requests-id-status:
Review comment:
Same as above RE: two`v3` segments
##########
File path: lib/go-tc/servers.go
##########
@@ -63,12 +72,22 @@ type ServersV1Response struct {
type ServerDetailV11 struct {
ServerDetail
LegacyInterfaceDetails
+ RouterHostName *string `json:"routerHostName" db:"router_host_name"`
+ RouterPortName *string `json:"routerPortName" db:"router_port_name"`
}
// ServerDetailV30 is the details for a server for API v3
type ServerDetailV30 struct {
ServerDetail
ServerInterfaces *[]ServerInterfaceInfo `json:"interfaces"`
+ RouterHostName *string `json:"routerHostName" db:"router_host_name"`
+ RouterPortName *string `json:"routerPortName" db:"router_port_name"`
+}
+
+// ServerDetailV40 is the details for a server for API v4
+type ServerDetailV40 struct {
+ ServerDetail
+ ServerInterfaces *[]ServerInterfaceInfoV40 `json:"interfaces"`
Review comment:
Does this need to be a pointer? Slices are already reference types so you can already do
```go
type Foo {
Slice []int
}
a := Foo{Slice: nil}
```
##########
File path: lib/go-tc/servers.go
##########
@@ -99,6 +124,13 @@ type ServerInterfaceInfo struct {
Name string `json:"name" db:"name"`
}
+// ServerInterfaceInfoV40 is the data associated with a V40 server's interface.
+type ServerInterfaceInfoV40 struct {
+ ServerInterfaceInfo
+ RouterHostName string `json:"routerHostName" db:"router_host_name"`
+ RouterPortName string `json:"routerPortName" db:"router_port_name"`
Review comment:
The database and the existing API implementation for these server fields allows them to be null - if they're still allowed to be `null` then these need to be pointers, otherwise we need to enforce that these can't be null in the database, because that could cause TO to return data that can't be used in subsequent requests.
Honestly I don't really care which, just make sure existing data is `COALESCE`'d if you go the db constraint route
##########
File path: traffic_portal/app/src/common/modules/table/servers/TableServersController.js
##########
@@ -220,7 +220,7 @@ var TableServersController = function(tableName, servers, filter, $scope, $state
},
{
headerName: "Router Port Name",
- field: "routerPortName",
+ field: "routerPort",
Review comment:
This field won't work anymore, since there's no field on the input data named `routerPort` (or `routerPortName`). I think we may just have to remove it.
##########
File path: docs/source/api/v4/servers.rst
##########
@@ -0,0 +1,522 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers:
+
+***********
+``servers``
+***********
+
+``GET``
+=======
+Retrieves properties of all servers across all CDNs.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +================+==========+===================================================================================================================+
+ | cachegroup | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | cachegroupName | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-name` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | dsId | no | Return only those servers assigned to the :term:`Delivery Service` identified by this integral, unique identifier.|
+ | | | If the Delivery Service has a :term:`Topology` assigned to it, the :ref:`to-api-servers` endpoint will return |
+ | | | each server whose :term:`Cache Group` is associated with a :term:`Topology Node` of that Topology and has the |
+ | | | :term:`Server Capabilities` that are |
+ | | | :term:`required by the Delivery Service <Delivery Service required capabilities>` but excluding |
+ | | | :term:`Origin Servers` that are not assigned to the Delivery Service. For more information, see |
+ | | | :ref:`multi-site-origin-qht`. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | hostName | no | Return only those servers that have this (short) hostname |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | id | no | Return only the server with this integral, unique identifier |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | profileId | no | Return only those servers that are using the :term:`Profile` that has this :ref:`profile-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | status | no | Return only those servers with this status - see :ref:`health-proto` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only servers of this :term:`Type` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | topology | no | Return only servers who belong to cachegroups assigned to the :term:`Topology` identified by this name |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | sortOrder | no | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | limit | no | Choose the maximum number of results to return |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | offset | no | The number of results to skip before beginning to return results. Must use in conjunction with limit |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | page | no | Return the n\ :sup:`th` page of results, where "n" is the value of this parameter, pages are ``limit`` long and |
+ | | | the first page is 1. If ``offset`` was defined, this query parameter has no effect. ``limit`` must be defined to |
+ | | | make use of ``page``. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/4.0/servers?hostName=mid HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
Review comment:
This is still indented with spaces instead of tab characters.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
ocket8888 commented on a change in pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#discussion_r562839032
##########
File path: docs/source/api/v4/servers.rst
##########
@@ -0,0 +1,522 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers:
+
+***********
+``servers``
+***********
+
+``GET``
+=======
+Retrieves properties of all servers across all CDNs.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +================+==========+===================================================================================================================+
+ | cachegroup | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | cachegroupName | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-name` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | dsId | no | Return only those servers assigned to the :term:`Delivery Service` identified by this integral, unique identifier.|
+ | | | If the Delivery Service has a :term:`Topology` assigned to it, the :ref:`to-api-servers` endpoint will return |
+ | | | each server whose :term:`Cache Group` is associated with a :term:`Topology Node` of that Topology and has the |
+ | | | :term:`Server Capabilities` that are |
+ | | | :term:`required by the Delivery Service <Delivery Service required capabilities>` but excluding |
+ | | | :term:`Origin Servers` that are not assigned to the Delivery Service. For more information, see |
+ | | | :ref:`multi-site-origin-qht`. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | hostName | no | Return only those servers that have this (short) hostname |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | id | no | Return only the server with this integral, unique identifier |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | profileId | no | Return only those servers that are using the :term:`Profile` that has this :ref:`profile-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | status | no | Return only those servers with this status - see :ref:`health-proto` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only servers of this :term:`Type` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | topology | no | Return only servers who belong to cachegroups assigned to the :term:`Topology` identified by this name |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | sortOrder | no | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | limit | no | Choose the maximum number of results to return |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | offset | no | The number of results to skip before beginning to return results. Must use in conjunction with limit |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | page | no | Return the n\ :sup:`th` page of results, where "n" is the value of this parameter, pages are ``limit`` long and |
+ | | | the first page is 1. If ``offset`` was defined, this query parameter has no effect. ``limit`` must be defined to |
+ | | | make use of ``page``. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/4.0/servers?hostName=mid HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
Review comment:
This doesn't match the indentation level of the other properties of `:interfaces:` - also, indent using tabs, not spaces.
##########
File path: docs/source/api/v4/servers.rst
##########
@@ -0,0 +1,522 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers:
+
+***********
+``servers``
+***********
+
+``GET``
+=======
+Retrieves properties of all servers across all CDNs.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +================+==========+===================================================================================================================+
+ | cachegroup | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | cachegroupName | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-name` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | dsId | no | Return only those servers assigned to the :term:`Delivery Service` identified by this integral, unique identifier.|
+ | | | If the Delivery Service has a :term:`Topology` assigned to it, the :ref:`to-api-servers` endpoint will return |
+ | | | each server whose :term:`Cache Group` is associated with a :term:`Topology Node` of that Topology and has the |
+ | | | :term:`Server Capabilities` that are |
+ | | | :term:`required by the Delivery Service <Delivery Service required capabilities>` but excluding |
+ | | | :term:`Origin Servers` that are not assigned to the Delivery Service. For more information, see |
+ | | | :ref:`multi-site-origin-qht`. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | hostName | no | Return only those servers that have this (short) hostname |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | id | no | Return only the server with this integral, unique identifier |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | profileId | no | Return only those servers that are using the :term:`Profile` that has this :ref:`profile-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | status | no | Return only those servers with this status - see :ref:`health-proto` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only servers of this :term:`Type` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | topology | no | Return only servers who belong to cachegroups assigned to the :term:`Topology` identified by this name |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | sortOrder | no | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | limit | no | Choose the maximum number of results to return |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | offset | no | The number of results to skip before beginning to return results. Must use in conjunction with limit |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | page | no | Return the n\ :sup:`th` page of results, where "n" is the value of this parameter, pages are ``limit`` long and |
+ | | | the first page is 1. If ``offset`` was defined, this query parameter has no effect. ``limit`` must be defined to |
+ | | | make use of ``page``. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/4.0/servers?hostName=mid HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:lastUpdated: The date and time at which this server description was last modified
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status
+:physLocation: The name of the physical location where the server resides
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profile: The :ref:`profile-name` of the :term:`Profile` used by this server
+:profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server
+:profileId: The :ref:`profile-id` the :term:`Profile` used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: A string indicating "server rack" location
+:status: The :term:`Status` of the server
+
+ .. seealso:: :ref:`health-proto`
+
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: The port on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:type: The name of the :term:`Type` of this server
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: The password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Content-Encoding: gzip
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 19 May 2020 17:06:25 GMT; Max-Age=3600; HttpOnly
+ Vary: Accept-Encoding
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 19 May 2020 16:06:25 GMT
+ Content-Length: 538
+
+ { "response": [{
+ "cachegroup": "CDN_in_a_Box_Mid",
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "domainName": "infra.ciab.test",
+ "guid": null,
+ "hostName": "mid",
+ "httpsPort": 443,
+ "id": 12,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "lastUpdated": "2020-05-19 14:49:39+00",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocation": "Apachecon North America 2018",
+ "physLocationId": 1,
+ "profile": "ATS_MID_TIER_CACHE",
+ "profileDesc": "Mid Cache - Apache Traffic Server",
+ "profileId": 10,
+ "rack": "",
+ "revalPending": false,
+ "status": "REPORTED",
+ "statusId": 3,
+ "tcpPort": 80,
+ "type": "MID",
+ "typeId": 12,
+ "updPending": false,
+ "xmppId": "",
+ "xmppPasswd": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "172.26.0.4/16",
+ "gateway": "172.26.0.1",
+ "serviceAddress": true
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": false,
+ "mtu": 1500,
+ "name": "eth0",
+ "routerHostName": "",
+ "routerPort": ""
Review comment:
The formatting here is a little wonky, but most importantly the content of a `code-block` must be associated with that `code-block` directive by being indent with a tab character; these lines start with spaces.
##########
File path: docs/source/api/v4/servers_id.rst
##########
@@ -0,0 +1,509 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers-id:
+
+******************
+``servers/{{ID}}``
+******************
+
+``PUT``
+=======
+Allow user to edit a server.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+---------------------------------------------+
+ | Name | Description |
+ +======+=============================================+
+ | ID | The integral, unique identifier of a server |
+ +------+---------------------------------------------+
+
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server shall belong
+:cdnId: The integral, unique identifier of the CDN to which the server shall belong
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:hostName: The (short) hostname of the server
+:httpsPort: An optional port number on which the server listens for incoming HTTPS connections/requests
+:iloIpAddress: An optional IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: An optional IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: An optional IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: An optional string containing the password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) <Role>`
+:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be necessary, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be necessary, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface. This unsigned integer must not be less than 1280.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: An optional string containing The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: An optional string containing The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profileId: The :ref:`profile-id` the :term:`Profile` that shall be used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: An optional string indicating "server rack" location
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: An optional port number on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: An optional password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/4.0/servers/14 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 599
+ Content-Type: application/json
+
+ {
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "domainName": "infra.ciab.test",
+ "hostName": "quest",
+ "httpsPort": 443,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ },
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": false
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "bond0",
+ "routerHostName": "",
+ "routerPort": "",
Review comment:
Indentation here is actually fine, but the formatting is still a little wonky since things don't line up
##########
File path: docs/source/api/v4/servers_id.rst
##########
@@ -0,0 +1,509 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers-id:
+
+******************
+``servers/{{ID}}``
+******************
+
+``PUT``
+=======
+Allow user to edit a server.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+---------------------------------------------+
+ | Name | Description |
+ +======+=============================================+
+ | ID | The integral, unique identifier of a server |
+ +------+---------------------------------------------+
+
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server shall belong
+:cdnId: The integral, unique identifier of the CDN to which the server shall belong
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:hostName: The (short) hostname of the server
+:httpsPort: An optional port number on which the server listens for incoming HTTPS connections/requests
+:iloIpAddress: An optional IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: An optional IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: An optional IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: An optional string containing the password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) <Role>`
+:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be necessary, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be necessary, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface. This unsigned integer must not be less than 1280.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: An optional string containing The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: An optional string containing The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profileId: The :ref:`profile-id` the :term:`Profile` that shall be used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: An optional string indicating "server rack" location
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: An optional port number on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: An optional password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/4.0/servers/14 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 599
+ Content-Type: application/json
+
+ {
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "domainName": "infra.ciab.test",
+ "hostName": "quest",
+ "httpsPort": 443,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ },
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": false
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "bond0",
+ "routerHostName": "",
+ "routerPort": "",
+ }
+ ],
+ "interfaceMtu": 1500,
+ "interfaceName": "eth0",
+ "ip6Address": "::1",
+ "ip6Gateway": "::2",
+ "ipAddress": "0.0.0.1",
+ "ipGateway": "0.0.0.2",
+ "ipNetmask": "255.255.255.0",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocationId": 1,
+ "profileId": 10,
+ "statusId": 3,
+ "tcpPort": 80,
+ "typeId": 12,
+ "updPending": false
+ }
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:lastUpdated: The date and time at which this server description was last modified
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status
+:physLocation: The name of the :term:`Physical Location` where the server resides
+:physLocationId: An integral, unique identifier for the :term:`Physical Location` where the server resides
+:profile: The :ref:`profile-name` of the :term:`Profile` used by this server
+:profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server
+:profileId: The :ref:`profile-id` the :term:`Profile` used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: A string indicating "server rack" location
+:status: The status of the server
+
+ .. seealso:: :ref:`health-proto`
+
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: The port on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:type: The name of the 'type' of this server
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: The password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Access-Control-Allow-Credentials: true
+ Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
+ Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
+ Access-Control-Allow-Origin: *
+ Content-Encoding: gzip
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 19 May 2020 17:46:33 GMT; Max-Age=3600; HttpOnly
+ Vary: Accept-Encoding
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 19 May 2020 16:46:33 GMT
+ Content-Length: 566
+
+ { "alerts": [
+ {
+ "text": "Server updated",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "cachegroup": "CDN_in_a_Box_Mid",
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "domainName": "infra.ciab.test",
+ "guid": null,
+ "hostName": "quest",
+ "httpsPort": 443,
+ "id": 14,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "lastUpdated": "2020-05-19 16:46:33+00",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocation": "Apachecon North America 2018",
+ "physLocationId": 1,
+ "profile": "ATS_MID_TIER_CACHE",
+ "profileDesc": "Mid Cache - Apache Traffic Server",
+ "profileId": 10,
+ "rack": null,
+ "revalPending": false,
+ "status": "REPORTED",
+ "statusId": 3,
+ "tcpPort": 80,
+ "type": "MID",
+ "typeId": 12,
+ "updPending": false,
+ "xmppId": null,
+ "xmppPasswd": null,
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ },
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": false
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "bond0",
+ "routerHostName": "",
+ "routerPort": ""
+ }
+ ]
+ }}
+
+``DELETE``
+==========
+Allow user to delete server through api.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+ .. versionchanged:: 3.0
+ In older versions of the API, this endpoint did not return a response object. It now returns a representation of the deleted server.
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+---------------------------------------------+
+ | Name | Description |
+ +======+=============================================+
+ | ID | The integral, unique identifier of a server |
+ +------+---------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ DELETE /api/3.0/servers/14 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belonged
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belonged
+:cdnId: The integral, unique identifier of the CDN to which the server belonged
+:cdnName: Name of the CDN to which the server belonged
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listened for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces that were in use by the server
+
+ :ipAddresses: A set of objects representing IP Addresses that were assigned to this network interface
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address".
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors would have considered the entire server unhealthy - which includes *all* configured network interfaces. If this was ``null``, it has the meaning "no limit". It had no effect if ``monitor`` was not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should have been monitored by Traffic Monitor for statistics and health consideration
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information was either not available or not applicable for this interface.
+ :name: The name of the interface. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
Review comment:
Same as above RE: indentation
##########
File path: traffic_ops/app/db/migrations/2021011500000000_update_interfaces_multiple_routers.sql
##########
@@ -0,0 +1,53 @@
+/*
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
+-- +goose Up
+-- SQL in section 'Up' is executed when this migration is applied
+ALTER TABLE interface ADD COLUMN router_host_name text DEFAULT '';
+ALTER TABLE interface ADD COLUMN router_port text DEFAULT '';
Review comment:
I know that this is currently a text field, but isn't it actually a literal port? If so, seems like it should be an integer
##########
File path: docs/source/api/v4/servers_details.rst
##########
@@ -0,0 +1,193 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers-details:
+
+*******************
+``servers/details``
+*******************
+Retrieves details of :ref:`tp-configure-servers`.
+
+
+``GET``
+=======
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+.. note:: On top of the response including the response key that is of type array it will also include the keys ``limit``, ``orderby``, and ``size``.
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +================+========================================+================================================================================================================================================================+
+ | hostName | Required if no physLocationID provided | Return only the servers with this (short) hostname. Capitalization of "hostName" is important. |
+ +----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | physLocationID | Required if no hostName provided | Return only servers with this integral, unique identifier for the physical location where the server resides. Capitalization of "physLocationID" is important. |
+ +----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/4.0/servers/details?hostName=edge HTTP/1.1
+ User-Agent: python-requests/2.22.0
+ Accept-Encoding: gzip, deflate
+ Accept: */*
+ Connection: keep-alive
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:limit: The maximum size of the ``response`` array, also indicative of the number of results per page using the pagination requested by the query parameters (if any) - this should be the same as the ``limit`` query parameter (if given)
+:orderby: A string that names the field by which the elements of the ``response`` array are ordered - should be the same as the ``orderby`` request query parameter (if given)
+:response: An array of objects, each of which represents the details of a given :ref:`Server <tp-configure-servers>`.
+
+ :cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+ :cdnName: Name of the CDN to which the server belongs
+ :deliveryservices: An array of integral, unique identifiers for :term:`Delivery Services` to which this server belongs
+ :domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+ :guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+ :hostName: The (short) hostname of the server
+ :httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+ :id: An integral, unique identifier for this server
+ :iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_
+ :iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_
+ :iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_
+ :iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+ :iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_
+ :interfaces: An array of interface and IP address information
+
+ :max_bandwidth: The maximum allowed bandwidth for this interface to be considered "healthy" by Traffic Monitor. This has no effect if `monitor` is not true. Values are in kb/s. The value `0` means "no limit".
+ :monitor: A boolean indicating if Traffic Monitor should monitor this interface
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` to configure for ``interfaceName``
+
+ .. seealso:: `The Wikipedia article on Maximum Transmission Unit <https://en.wikipedia.org/wiki/Maximum_transmission_unit>`_
+
+ :name: The network interface name used by the server.
+
+ :ipAddresses: An array of the IP address information for the interface
+
+ :address: The IPv4 or IPv6 address and subnet mask of the server - applicable for the interface ``name``
+ :gateway: The IPv4 or IPv6 gateway address of the server - applicable for the interface ``name``
+ :service_address: A boolean determining if content will be routed to the IP address
+
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface
Review comment:
mixing tabs and spaces for indentation here
##########
File path: lib/go-tc/servers.go
##########
@@ -495,6 +745,48 @@ type CommonServerProperties struct {
XMPPPasswd *string `json:"xmppPasswd" db:"xmpp_passwd"`
}
+// CommonServerPropertiesV40 is just the collection of properties which are
+// shared by all servers across API versions >= 4.0.
+type CommonServerPropertiesV40 struct {
Review comment:
I don't think this needs to be separate from the ServerV4 definition; instead I'd just remove the router fields from `CommonServerProperties` and add them to the older objects that still need them. The point of `CommonServerProperties` is just to not re-iterate properties shared by servers of all versions - but people are supposed to access those properties like `server.Prop` not `server.CommonServerProperties.Prop` so it's fine to change it as long as the overall Server structure isn't changed.
##########
File path: docs/source/api/v4/servers_details.rst
##########
@@ -0,0 +1,193 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers-details:
+
+*******************
+``servers/details``
+*******************
+Retrieves details of :ref:`tp-configure-servers`.
+
+
+``GET``
+=======
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+.. note:: On top of the response including the response key that is of type array it will also include the keys ``limit``, ``orderby``, and ``size``.
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +================+========================================+================================================================================================================================================================+
+ | hostName | Required if no physLocationID provided | Return only the servers with this (short) hostname. Capitalization of "hostName" is important. |
+ +----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | physLocationID | Required if no hostName provided | Return only servers with this integral, unique identifier for the physical location where the server resides. Capitalization of "physLocationID" is important. |
+ +----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/4.0/servers/details?hostName=edge HTTP/1.1
+ User-Agent: python-requests/2.22.0
+ Accept-Encoding: gzip, deflate
+ Accept: */*
+ Connection: keep-alive
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:limit: The maximum size of the ``response`` array, also indicative of the number of results per page using the pagination requested by the query parameters (if any) - this should be the same as the ``limit`` query parameter (if given)
+:orderby: A string that names the field by which the elements of the ``response`` array are ordered - should be the same as the ``orderby`` request query parameter (if given)
+:response: An array of objects, each of which represents the details of a given :ref:`Server <tp-configure-servers>`.
+
+ :cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+ :cdnName: Name of the CDN to which the server belongs
+ :deliveryservices: An array of integral, unique identifiers for :term:`Delivery Services` to which this server belongs
+ :domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+ :guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+ :hostName: The (short) hostname of the server
+ :httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+ :id: An integral, unique identifier for this server
+ :iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_
+ :iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_
+ :iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_
+ :iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+ :iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_
+ :interfaces: An array of interface and IP address information
+
+ :max_bandwidth: The maximum allowed bandwidth for this interface to be considered "healthy" by Traffic Monitor. This has no effect if `monitor` is not true. Values are in kb/s. The value `0` means "no limit".
+ :monitor: A boolean indicating if Traffic Monitor should monitor this interface
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` to configure for ``interfaceName``
+
+ .. seealso:: `The Wikipedia article on Maximum Transmission Unit <https://en.wikipedia.org/wiki/Maximum_transmission_unit>`_
+
+ :name: The network interface name used by the server.
+
+ :ipAddresses: An array of the IP address information for the interface
+
+ :address: The IPv4 or IPv6 address and subnet mask of the server - applicable for the interface ``name``
+ :gateway: The IPv4 or IPv6 gateway address of the server - applicable for the interface ``name``
+ :service_address: A boolean determining if content will be routed to the IP address
+
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface
+
+ :mgmtIpAddress: The IPv4 address of the server's management port
+ :mgmtIpGateway: The IPv4 gateway of the server's management port
+ :mgmtIpNetmask: The IPv4 subnet mask of the server's management port
+ :offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status
+ :physLocation: The name of the physical location where the server resides
+ :profile: The :ref:`profile-name` of the :term:`Profile` used by this server
+ :profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server
+ :rack: A string indicating "server rack" location
+ :status: The status of the server
+
+ .. seealso:: :ref:`health-proto`
+
+ :tcpPort: The port on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+ :type: The name of the 'type' of this server
+ :xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+ :xmppPasswd: The password used in XMPP communications with the server
+
+:size: The page number - if pagination was requested in the query parameters, else ``0`` to indicate no pagination - of the results represented by the ``response`` array. This is named "size" for legacy reasons
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Access-Control-Allow-Credentials: true
+ Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
+ Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
+ Access-Control-Allow-Origin: *
+ Content-Encoding: gzip
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 01:27:36 GMT; Max-Age=3600; HttpOnly
+ Whole-Content-Sha512: HW2F3CEpohNAvNlEDhUfXmtwpEka4dwUWFVUSSjW98aXiv10vI6ysRIcC2P9huabCz5fdHqY3tp0LR4ekwEHqw==
+ X-Server-Name: traffic_ops_golang/
+ Date: Mon, 24 Feb 2020 00:27:36 GMT
+ Content-Length: 493
+
+ {
+ "limit": 1000,
+ "orderby": "hostName",
+ "response": [
+ {
+ "cachegroup": "CDN_in_a_Box_Edge",
+ "cdnName": "CDN-in-a-Box",
+ "deliveryservices": [
+ 1
+ ],
+ "domainName": "infra.ciab.test",
+ "guid": null,
+ "hardwareInfo": null,
+ "hostName": "edge",
+ "httpsPort": 443,
+ "id": 5,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocation": "Apachecon North America 2018",
+ "profile": "ATS_EDGE_TIER_CACHE",
+ "profileDesc": "Edge Cache - Apache Traffic Server",
+ "rack": "",
+ "status": "REPORTED",
+ "tcpPort": 80,
+ "type": "EDGE",
+ "xmppId": "edge",
+ "xmppPasswd": "",
+ "interfaces": [
+ { "ipAddresses": [
+ {
+ "address": "172.16.239.100",
+ "gateway": "172.16.239.1",
+ "service_address": true
+ },
+ {
+ "address": "fc01:9400:1000:8::100",
+ "gateway": "fc01:9400:1000:8::1",
+ "service_address": true
+ }
+ ],
+ "max_bandwidth": 0,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "eth0",
+ "routerHostName": "",
+ "routerPort": ""
Review comment:
same as above RE: formatting and indentation
##########
File path: docs/source/api/v4/servers.rst
##########
@@ -0,0 +1,522 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers:
+
+***********
+``servers``
+***********
+
+``GET``
+=======
+Retrieves properties of all servers across all CDNs.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +================+==========+===================================================================================================================+
+ | cachegroup | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | cachegroupName | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-name` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | dsId | no | Return only those servers assigned to the :term:`Delivery Service` identified by this integral, unique identifier.|
+ | | | If the Delivery Service has a :term:`Topology` assigned to it, the :ref:`to-api-servers` endpoint will return |
+ | | | each server whose :term:`Cache Group` is associated with a :term:`Topology Node` of that Topology and has the |
+ | | | :term:`Server Capabilities` that are |
+ | | | :term:`required by the Delivery Service <Delivery Service required capabilities>` but excluding |
+ | | | :term:`Origin Servers` that are not assigned to the Delivery Service. For more information, see |
+ | | | :ref:`multi-site-origin-qht`. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | hostName | no | Return only those servers that have this (short) hostname |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | id | no | Return only the server with this integral, unique identifier |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | profileId | no | Return only those servers that are using the :term:`Profile` that has this :ref:`profile-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | status | no | Return only those servers with this status - see :ref:`health-proto` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only servers of this :term:`Type` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | topology | no | Return only servers who belong to cachegroups assigned to the :term:`Topology` identified by this name |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | sortOrder | no | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | limit | no | Choose the maximum number of results to return |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | offset | no | The number of results to skip before beginning to return results. Must use in conjunction with limit |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | page | no | Return the n\ :sup:`th` page of results, where "n" is the value of this parameter, pages are ``limit`` long and |
+ | | | the first page is 1. If ``offset`` was defined, this query parameter has no effect. ``limit`` must be defined to |
+ | | | make use of ``page``. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/4.0/servers?hostName=mid HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:lastUpdated: The date and time at which this server description was last modified
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status
+:physLocation: The name of the physical location where the server resides
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profile: The :ref:`profile-name` of the :term:`Profile` used by this server
+:profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server
+:profileId: The :ref:`profile-id` the :term:`Profile` used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: A string indicating "server rack" location
+:status: The :term:`Status` of the server
+
+ .. seealso:: :ref:`health-proto`
+
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: The port on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:type: The name of the :term:`Type` of this server
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: The password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Content-Encoding: gzip
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 19 May 2020 17:06:25 GMT; Max-Age=3600; HttpOnly
+ Vary: Accept-Encoding
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 19 May 2020 16:06:25 GMT
+ Content-Length: 538
+
+ { "response": [{
+ "cachegroup": "CDN_in_a_Box_Mid",
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "domainName": "infra.ciab.test",
+ "guid": null,
+ "hostName": "mid",
+ "httpsPort": 443,
+ "id": 12,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "lastUpdated": "2020-05-19 14:49:39+00",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocation": "Apachecon North America 2018",
+ "physLocationId": 1,
+ "profile": "ATS_MID_TIER_CACHE",
+ "profileDesc": "Mid Cache - Apache Traffic Server",
+ "profileId": 10,
+ "rack": "",
+ "revalPending": false,
+ "status": "REPORTED",
+ "statusId": 3,
+ "tcpPort": 80,
+ "type": "MID",
+ "typeId": 12,
+ "updPending": false,
+ "xmppId": "",
+ "xmppPasswd": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "172.26.0.4/16",
+ "gateway": "172.26.0.1",
+ "serviceAddress": true
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": false,
+ "mtu": 1500,
+ "name": "eth0",
+ "routerHostName": "",
+ "routerPort": ""
+ }
+ ]
+ }],
+ "summary": {
+ "count": 13
+ }}
+
+Summary Fields
+""""""""""""""
+The ``summary`` object returned by this method of this endpoint uses only the ``count`` :ref:`standard property <reserved-summary-fields>`.
+
+``POST``
+========
+Allows a user to create a new server.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server shall belong
+:cdnId: The integral, unique identifier of the CDN to which the server shall belong
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:hostName: The (short) hostname of the server
+:httpsPort: An optional port number on which the server listens for incoming HTTPS connections/requests
+:iloIpAddress: An optional IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: An optional IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: An optional IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: An optional string containing the password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be necessary, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be necessary, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
Review comment:
Same as above RE: indentation
##########
File path: docs/source/api/v4/servers.rst
##########
@@ -0,0 +1,522 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers:
+
+***********
+``servers``
+***********
+
+``GET``
+=======
+Retrieves properties of all servers across all CDNs.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +================+==========+===================================================================================================================+
+ | cachegroup | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | cachegroupName | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-name` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | dsId | no | Return only those servers assigned to the :term:`Delivery Service` identified by this integral, unique identifier.|
+ | | | If the Delivery Service has a :term:`Topology` assigned to it, the :ref:`to-api-servers` endpoint will return |
+ | | | each server whose :term:`Cache Group` is associated with a :term:`Topology Node` of that Topology and has the |
+ | | | :term:`Server Capabilities` that are |
+ | | | :term:`required by the Delivery Service <Delivery Service required capabilities>` but excluding |
+ | | | :term:`Origin Servers` that are not assigned to the Delivery Service. For more information, see |
+ | | | :ref:`multi-site-origin-qht`. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | hostName | no | Return only those servers that have this (short) hostname |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | id | no | Return only the server with this integral, unique identifier |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | profileId | no | Return only those servers that are using the :term:`Profile` that has this :ref:`profile-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | status | no | Return only those servers with this status - see :ref:`health-proto` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only servers of this :term:`Type` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | topology | no | Return only servers who belong to cachegroups assigned to the :term:`Topology` identified by this name |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | sortOrder | no | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | limit | no | Choose the maximum number of results to return |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | offset | no | The number of results to skip before beginning to return results. Must use in conjunction with limit |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | page | no | Return the n\ :sup:`th` page of results, where "n" is the value of this parameter, pages are ``limit`` long and |
+ | | | the first page is 1. If ``offset`` was defined, this query parameter has no effect. ``limit`` must be defined to |
+ | | | make use of ``page``. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/4.0/servers?hostName=mid HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:lastUpdated: The date and time at which this server description was last modified
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status
+:physLocation: The name of the physical location where the server resides
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profile: The :ref:`profile-name` of the :term:`Profile` used by this server
+:profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server
+:profileId: The :ref:`profile-id` the :term:`Profile` used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: A string indicating "server rack" location
+:status: The :term:`Status` of the server
+
+ .. seealso:: :ref:`health-proto`
+
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: The port on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:type: The name of the :term:`Type` of this server
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: The password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Content-Encoding: gzip
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 19 May 2020 17:06:25 GMT; Max-Age=3600; HttpOnly
+ Vary: Accept-Encoding
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 19 May 2020 16:06:25 GMT
+ Content-Length: 538
+
+ { "response": [{
+ "cachegroup": "CDN_in_a_Box_Mid",
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "domainName": "infra.ciab.test",
+ "guid": null,
+ "hostName": "mid",
+ "httpsPort": 443,
+ "id": 12,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "lastUpdated": "2020-05-19 14:49:39+00",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocation": "Apachecon North America 2018",
+ "physLocationId": 1,
+ "profile": "ATS_MID_TIER_CACHE",
+ "profileDesc": "Mid Cache - Apache Traffic Server",
+ "profileId": 10,
+ "rack": "",
+ "revalPending": false,
+ "status": "REPORTED",
+ "statusId": 3,
+ "tcpPort": 80,
+ "type": "MID",
+ "typeId": 12,
+ "updPending": false,
+ "xmppId": "",
+ "xmppPasswd": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "172.26.0.4/16",
+ "gateway": "172.26.0.1",
+ "serviceAddress": true
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": false,
+ "mtu": 1500,
+ "name": "eth0",
+ "routerHostName": "",
+ "routerPort": ""
+ }
+ ]
+ }],
+ "summary": {
+ "count": 13
+ }}
+
+Summary Fields
+""""""""""""""
+The ``summary`` object returned by this method of this endpoint uses only the ``count`` :ref:`standard property <reserved-summary-fields>`.
+
+``POST``
+========
+Allows a user to create a new server.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server shall belong
+:cdnId: The integral, unique identifier of the CDN to which the server shall belong
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:hostName: The (short) hostname of the server
+:httpsPort: An optional port number on which the server listens for incoming HTTPS connections/requests
+:iloIpAddress: An optional IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: An optional IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: An optional IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: An optional string containing the password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be necessary, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be necessary, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profileId: The :ref:`profile-id` the :term:`Profile` that shall be used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: An optional string indicating "server rack" location
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: An optional port number on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: An optional password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/3.0/servers HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 599
+ Content-Type: application/json
+
+ {
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "domainName": "infra.ciab.test",
+ "hostName": "test",
+ "httpsPort": 443,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ },
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": true
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "eth0",
+ "routerHostName": "",
+ "routerPort": ""
+ }
+ ],
+ "interfaceMtu": 1500,
+ "interfaceName": "eth0",
+ "ip6Address": "::1",
+ "ip6Gateway": "::2",
+ "ipAddress": "0.0.0.1",
+ "ipGateway": "0.0.0.2",
+ "ipNetmask": "255.255.255.0",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocationId": 1,
+ "profileId": 10,
+ "statusId": 3,
+ "tcpPort": 80,
+ "typeId": 12,
+ "updPending": false
+ }
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
Review comment:
same as above RE: indentation
##########
File path: docs/source/api/v4/servers_id.rst
##########
@@ -0,0 +1,509 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers-id:
+
+******************
+``servers/{{ID}}``
+******************
+
+``PUT``
+=======
+Allow user to edit a server.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+---------------------------------------------+
+ | Name | Description |
+ +======+=============================================+
+ | ID | The integral, unique identifier of a server |
+ +------+---------------------------------------------+
+
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server shall belong
+:cdnId: The integral, unique identifier of the CDN to which the server shall belong
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:hostName: The (short) hostname of the server
+:httpsPort: An optional port number on which the server listens for incoming HTTPS connections/requests
+:iloIpAddress: An optional IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: An optional IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: An optional IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: An optional string containing the password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) <Role>`
+:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be necessary, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be necessary, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface. This unsigned integer must not be less than 1280.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: An optional string containing The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: An optional string containing The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profileId: The :ref:`profile-id` the :term:`Profile` that shall be used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: An optional string indicating "server rack" location
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: An optional port number on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: An optional password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/4.0/servers/14 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 599
+ Content-Type: application/json
+
+ {
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "domainName": "infra.ciab.test",
+ "hostName": "quest",
+ "httpsPort": 443,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ },
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": false
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "bond0",
+ "routerHostName": "",
+ "routerPort": "",
+ }
+ ],
+ "interfaceMtu": 1500,
+ "interfaceName": "eth0",
+ "ip6Address": "::1",
+ "ip6Gateway": "::2",
+ "ipAddress": "0.0.0.1",
+ "ipGateway": "0.0.0.2",
+ "ipNetmask": "255.255.255.0",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocationId": 1,
+ "profileId": 10,
+ "statusId": 3,
+ "tcpPort": 80,
+ "typeId": 12,
+ "updPending": false
+ }
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:lastUpdated: The date and time at which this server description was last modified
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status
+:physLocation: The name of the :term:`Physical Location` where the server resides
+:physLocationId: An integral, unique identifier for the :term:`Physical Location` where the server resides
+:profile: The :ref:`profile-name` of the :term:`Profile` used by this server
+:profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server
+:profileId: The :ref:`profile-id` the :term:`Profile` used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: A string indicating "server rack" location
+:status: The status of the server
+
+ .. seealso:: :ref:`health-proto`
+
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: The port on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:type: The name of the 'type' of this server
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: The password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Access-Control-Allow-Credentials: true
+ Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
+ Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
+ Access-Control-Allow-Origin: *
+ Content-Encoding: gzip
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 19 May 2020 17:46:33 GMT; Max-Age=3600; HttpOnly
+ Vary: Accept-Encoding
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 19 May 2020 16:46:33 GMT
+ Content-Length: 566
+
+ { "alerts": [
+ {
+ "text": "Server updated",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "cachegroup": "CDN_in_a_Box_Mid",
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "domainName": "infra.ciab.test",
+ "guid": null,
+ "hostName": "quest",
+ "httpsPort": 443,
+ "id": 14,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "lastUpdated": "2020-05-19 16:46:33+00",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocation": "Apachecon North America 2018",
+ "physLocationId": 1,
+ "profile": "ATS_MID_TIER_CACHE",
+ "profileDesc": "Mid Cache - Apache Traffic Server",
+ "profileId": 10,
+ "rack": null,
+ "revalPending": false,
+ "status": "REPORTED",
+ "statusId": 3,
+ "tcpPort": 80,
+ "type": "MID",
+ "typeId": 12,
+ "updPending": false,
+ "xmppId": null,
+ "xmppPasswd": null,
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ },
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": false
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "bond0",
+ "routerHostName": "",
+ "routerPort": ""
Review comment:
Same as above RE: formatting
##########
File path: docs/source/api/v4/servers.rst
##########
@@ -0,0 +1,522 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers:
+
+***********
+``servers``
+***********
+
+``GET``
+=======
+Retrieves properties of all servers across all CDNs.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +================+==========+===================================================================================================================+
+ | cachegroup | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | cachegroupName | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-name` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | dsId | no | Return only those servers assigned to the :term:`Delivery Service` identified by this integral, unique identifier.|
+ | | | If the Delivery Service has a :term:`Topology` assigned to it, the :ref:`to-api-servers` endpoint will return |
+ | | | each server whose :term:`Cache Group` is associated with a :term:`Topology Node` of that Topology and has the |
+ | | | :term:`Server Capabilities` that are |
+ | | | :term:`required by the Delivery Service <Delivery Service required capabilities>` but excluding |
+ | | | :term:`Origin Servers` that are not assigned to the Delivery Service. For more information, see |
+ | | | :ref:`multi-site-origin-qht`. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | hostName | no | Return only those servers that have this (short) hostname |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | id | no | Return only the server with this integral, unique identifier |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | profileId | no | Return only those servers that are using the :term:`Profile` that has this :ref:`profile-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | status | no | Return only those servers with this status - see :ref:`health-proto` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only servers of this :term:`Type` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | topology | no | Return only servers who belong to cachegroups assigned to the :term:`Topology` identified by this name |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | sortOrder | no | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | limit | no | Choose the maximum number of results to return |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | offset | no | The number of results to skip before beginning to return results. Must use in conjunction with limit |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | page | no | Return the n\ :sup:`th` page of results, where "n" is the value of this parameter, pages are ``limit`` long and |
+ | | | the first page is 1. If ``offset`` was defined, this query parameter has no effect. ``limit`` must be defined to |
+ | | | make use of ``page``. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/4.0/servers?hostName=mid HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:lastUpdated: The date and time at which this server description was last modified
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status
+:physLocation: The name of the physical location where the server resides
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profile: The :ref:`profile-name` of the :term:`Profile` used by this server
+:profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server
+:profileId: The :ref:`profile-id` the :term:`Profile` used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: A string indicating "server rack" location
+:status: The :term:`Status` of the server
+
+ .. seealso:: :ref:`health-proto`
+
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: The port on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:type: The name of the :term:`Type` of this server
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: The password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Content-Encoding: gzip
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 19 May 2020 17:06:25 GMT; Max-Age=3600; HttpOnly
+ Vary: Accept-Encoding
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 19 May 2020 16:06:25 GMT
+ Content-Length: 538
+
+ { "response": [{
+ "cachegroup": "CDN_in_a_Box_Mid",
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "domainName": "infra.ciab.test",
+ "guid": null,
+ "hostName": "mid",
+ "httpsPort": 443,
+ "id": 12,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "lastUpdated": "2020-05-19 14:49:39+00",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocation": "Apachecon North America 2018",
+ "physLocationId": 1,
+ "profile": "ATS_MID_TIER_CACHE",
+ "profileDesc": "Mid Cache - Apache Traffic Server",
+ "profileId": 10,
+ "rack": "",
+ "revalPending": false,
+ "status": "REPORTED",
+ "statusId": 3,
+ "tcpPort": 80,
+ "type": "MID",
+ "typeId": 12,
+ "updPending": false,
+ "xmppId": "",
+ "xmppPasswd": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "172.26.0.4/16",
+ "gateway": "172.26.0.1",
+ "serviceAddress": true
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": false,
+ "mtu": 1500,
+ "name": "eth0",
+ "routerHostName": "",
+ "routerPort": ""
+ }
+ ]
+ }],
+ "summary": {
+ "count": 13
+ }}
+
+Summary Fields
+""""""""""""""
+The ``summary`` object returned by this method of this endpoint uses only the ``count`` :ref:`standard property <reserved-summary-fields>`.
+
+``POST``
+========
+Allows a user to create a new server.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server shall belong
+:cdnId: The integral, unique identifier of the CDN to which the server shall belong
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:hostName: The (short) hostname of the server
+:httpsPort: An optional port number on which the server listens for incoming HTTPS connections/requests
+:iloIpAddress: An optional IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: An optional IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: An optional IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: An optional string containing the password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be necessary, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be necessary, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profileId: The :ref:`profile-id` the :term:`Profile` that shall be used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: An optional string indicating "server rack" location
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: An optional port number on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: An optional password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/3.0/servers HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 599
+ Content-Type: application/json
+
+ {
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "domainName": "infra.ciab.test",
+ "hostName": "test",
+ "httpsPort": 443,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ },
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": true
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "eth0",
+ "routerHostName": "",
+ "routerPort": ""
Review comment:
same as above RE formatting and indentation
##########
File path: docs/source/api/v4/servers.rst
##########
@@ -0,0 +1,522 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers:
+
+***********
+``servers``
+***********
+
+``GET``
+=======
+Retrieves properties of all servers across all CDNs.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +================+==========+===================================================================================================================+
+ | cachegroup | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | cachegroupName | no | Return only those servers within the :term:`Cache Group` that has this :ref:`cache-group-name` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | dsId | no | Return only those servers assigned to the :term:`Delivery Service` identified by this integral, unique identifier.|
+ | | | If the Delivery Service has a :term:`Topology` assigned to it, the :ref:`to-api-servers` endpoint will return |
+ | | | each server whose :term:`Cache Group` is associated with a :term:`Topology Node` of that Topology and has the |
+ | | | :term:`Server Capabilities` that are |
+ | | | :term:`required by the Delivery Service <Delivery Service required capabilities>` but excluding |
+ | | | :term:`Origin Servers` that are not assigned to the Delivery Service. For more information, see |
+ | | | :ref:`multi-site-origin-qht`. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | hostName | no | Return only those servers that have this (short) hostname |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | id | no | Return only the server with this integral, unique identifier |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | profileId | no | Return only those servers that are using the :term:`Profile` that has this :ref:`profile-id` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | status | no | Return only those servers with this status - see :ref:`health-proto` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only servers of this :term:`Type` |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | topology | no | Return only servers who belong to cachegroups assigned to the :term:`Topology` identified by this name |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | sortOrder | no | Changes the order of sorting. Either ascending (default or "asc") or descending ("desc") |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | limit | no | Choose the maximum number of results to return |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | offset | no | The number of results to skip before beginning to return results. Must use in conjunction with limit |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | page | no | Return the n\ :sup:`th` page of results, where "n" is the value of this parameter, pages are ``limit`` long and |
+ | | | the first page is 1. If ``offset`` was defined, this query parameter has no effect. ``limit`` must be defined to |
+ | | | make use of ``page``. |
+ +----------------+----------+-------------------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/4.0/servers?hostName=mid HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:lastUpdated: The date and time at which this server description was last modified
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status
+:physLocation: The name of the physical location where the server resides
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profile: The :ref:`profile-name` of the :term:`Profile` used by this server
+:profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server
+:profileId: The :ref:`profile-id` the :term:`Profile` used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: A string indicating "server rack" location
+:status: The :term:`Status` of the server
+
+ .. seealso:: :ref:`health-proto`
+
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: The port on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:type: The name of the :term:`Type` of this server
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: The password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Content-Encoding: gzip
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 19 May 2020 17:06:25 GMT; Max-Age=3600; HttpOnly
+ Vary: Accept-Encoding
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 19 May 2020 16:06:25 GMT
+ Content-Length: 538
+
+ { "response": [{
+ "cachegroup": "CDN_in_a_Box_Mid",
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "domainName": "infra.ciab.test",
+ "guid": null,
+ "hostName": "mid",
+ "httpsPort": 443,
+ "id": 12,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "lastUpdated": "2020-05-19 14:49:39+00",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocation": "Apachecon North America 2018",
+ "physLocationId": 1,
+ "profile": "ATS_MID_TIER_CACHE",
+ "profileDesc": "Mid Cache - Apache Traffic Server",
+ "profileId": 10,
+ "rack": "",
+ "revalPending": false,
+ "status": "REPORTED",
+ "statusId": 3,
+ "tcpPort": 80,
+ "type": "MID",
+ "typeId": 12,
+ "updPending": false,
+ "xmppId": "",
+ "xmppPasswd": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "172.26.0.4/16",
+ "gateway": "172.26.0.1",
+ "serviceAddress": true
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": false,
+ "mtu": 1500,
+ "name": "eth0",
+ "routerHostName": "",
+ "routerPort": ""
+ }
+ ]
+ }],
+ "summary": {
+ "count": 13
+ }}
+
+Summary Fields
+""""""""""""""
+The ``summary`` object returned by this method of this endpoint uses only the ``count`` :ref:`standard property <reserved-summary-fields>`.
+
+``POST``
+========
+Allows a user to create a new server.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server shall belong
+:cdnId: The integral, unique identifier of the CDN to which the server shall belong
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:hostName: The (short) hostname of the server
+:httpsPort: An optional port number on which the server listens for incoming HTTPS connections/requests
+:iloIpAddress: An optional IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: An optional IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: An optional IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: An optional string containing the password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be necessary, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be necessary, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profileId: The :ref:`profile-id` the :term:`Profile` that shall be used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: An optional string indicating "server rack" location
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: An optional port number on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: An optional password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Request Example
+
+ POST /api/3.0/servers HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 599
+ Content-Type: application/json
+
+ {
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "domainName": "infra.ciab.test",
+ "hostName": "test",
+ "httpsPort": 443,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ },
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": true
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "eth0",
+ "routerHostName": "",
+ "routerPort": ""
+ }
+ ],
+ "interfaceMtu": 1500,
+ "interfaceName": "eth0",
+ "ip6Address": "::1",
+ "ip6Gateway": "::2",
+ "ipAddress": "0.0.0.1",
+ "ipGateway": "0.0.0.2",
+ "ipNetmask": "255.255.255.0",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocationId": 1,
+ "profileId": 10,
+ "statusId": 3,
+ "tcpPort": 80,
+ "typeId": 12,
+ "updPending": false
+ }
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:lastUpdated: The date and time at which this server description was last modified
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status
+:physLocation: The name of the :term:`Physical Location` where the server resides
+:physLocationId: An integral, unique identifier for the :term:`Physical Location` where the server resides
+:profile: The :ref:`profile-name` of the :term:`Profile` used by this server
+:profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server
+:profileId: The :ref:`profile-id` the :term:`Profile` used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: A string indicating "server rack" location
+:status: The status of the server
+
+ .. seealso:: :ref:`health-proto`
+
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: The port on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:type: The name of the 'type' of this server
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: The password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 201 Created
+ Content-Encoding: gzip
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 19 May 2020 17:34:40 GMT; Max-Age=3600; HttpOnly
+ Vary: Accept-Encoding
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 19 May 2020 16:34:40 GMT
+ Content-Length: 562
+
+ { "alerts": [
+ {
+ "text": "Server created",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "cachegroup": "CDN_in_a_Box_Mid",
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "domainName": "infra.ciab.test",
+ "guid": null,
+ "hostName": "test",
+ "httpsPort": 443,
+ "id": 14,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "lastUpdated": "2020-05-19 16:34:40+00",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocation": "Apachecon North America 2018",
+ "physLocationId": 1,
+ "profile": "ATS_MID_TIER_CACHE",
+ "profileDesc": "Mid Cache - Apache Traffic Server",
+ "profileId": 10,
+ "rack": null,
+ "revalPending": false,
+ "status": "REPORTED",
+ "statusId": 3,
+ "tcpPort": 80,
+ "type": "MID",
+ "typeId": 12,
+ "updPending": false,
+ "xmppId": null,
+ "xmppPasswd": null,
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ },
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": true
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "eth0",
+ "routerHostName": "",
+ "routerPort": ""
Review comment:
Same as above RE: formatting and indentation
##########
File path: docs/source/api/v4/servers_id.rst
##########
@@ -0,0 +1,509 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers-id:
+
+******************
+``servers/{{ID}}``
+******************
+
+``PUT``
+=======
+Allow user to edit a server.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+---------------------------------------------+
+ | Name | Description |
+ +======+=============================================+
+ | ID | The integral, unique identifier of a server |
+ +------+---------------------------------------------+
+
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server shall belong
+:cdnId: The integral, unique identifier of the CDN to which the server shall belong
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:hostName: The (short) hostname of the server
+:httpsPort: An optional port number on which the server listens for incoming HTTPS connections/requests
+:iloIpAddress: An optional IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: An optional IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: An optional IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: An optional string containing the password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) <Role>`
+:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be necessary, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be necessary, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface. This unsigned integer must not be less than 1280.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: An optional string containing The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: An optional string containing The human-readable name of the port used by the router responsible for reaching this server's interface.
Review comment:
Same as above RE: indentation
##########
File path: lib/go-tc/deliveryservice_servers.go
##########
@@ -105,14 +105,144 @@ type DSServerBase struct {
DeliveryServiceCapabilities []string `json:"-" db:"deliveryservice_capabilities"`
}
+// DSServerBaseV4 contains the base information for a Delivery Service Server.
+type DSServerBaseV4 struct {
+ Cachegroup *string `json:"cachegroup" db:"cachegroup"`
+ CachegroupID *int `json:"cachegroupId" db:"cachegroup_id"`
+ CDNID *int `json:"cdnId" db:"cdn_id"`
+ CDNName *string `json:"cdnName" db:"cdn_name"`
+ DeliveryServices *map[string][]string `json:"deliveryServices,omitempty"`
+ DomainName *string `json:"domainName" db:"domain_name"`
+ FQDN *string `json:"fqdn,omitempty"`
+ FqdnTime time.Time `json:"-"`
+ GUID *string `json:"guid" db:"guid"`
+ HostName *string `json:"hostName" db:"host_name"`
+ HTTPSPort *int `json:"httpsPort" db:"https_port"`
+ ID *int `json:"id" db:"id"`
+ ILOIPAddress *string `json:"iloIpAddress" db:"ilo_ip_address"`
+ ILOIPGateway *string `json:"iloIpGateway" db:"ilo_ip_gateway"`
+ ILOIPNetmask *string `json:"iloIpNetmask" db:"ilo_ip_netmask"`
+ ILOPassword *string `json:"iloPassword" db:"ilo_password"`
+ ILOUsername *string `json:"iloUsername" db:"ilo_username"`
+ LastUpdated *TimeNoMod `json:"lastUpdated" db:"last_updated"`
+ MgmtIPAddress *string `json:"mgmtIpAddress" db:"mgmt_ip_address"`
+ MgmtIPGateway *string `json:"mgmtIpGateway" db:"mgmt_ip_gateway"`
+ MgmtIPNetmask *string `json:"mgmtIpNetmask" db:"mgmt_ip_netmask"`
+ OfflineReason *string `json:"offlineReason" db:"offline_reason"`
+ PhysLocation *string `json:"physLocation" db:"phys_location"`
+ PhysLocationID *int `json:"physLocationId" db:"phys_location_id"`
+ Profile *string `json:"profile" db:"profile"`
+ ProfileDesc *string `json:"profileDesc" db:"profile_desc"`
+ ProfileID *int `json:"profileId" db:"profile_id"`
+ Rack *string `json:"rack" db:"rack"`
+ Status *string `json:"status" db:"status"`
+ StatusID *int `json:"statusId" db:"status_id"`
+ TCPPort *int `json:"tcpPort" db:"tcp_port"`
+ Type string `json:"type" db:"server_type"`
+ TypeID *int `json:"typeId" db:"server_type_id"`
+ UpdPending *bool `json:"updPending" db:"upd_pending"`
+ ServerCapabilities []string `json:"-" db:"server_capabilities"`
+ DeliveryServiceCapabilities []string `json:"-" db:"deliveryservice_capabilities"`
+}
+
// DSServerV11 contains the legacy format for a Delivery Service Server.
type DSServerV11 struct {
DSServerBase
LegacyInterfaceDetails
}
-// DSServer contains information for a Delivery Service Server.
-type DSServer struct {
+// DSServerV3 contains information for a Delivery Service Server.
+type DSServerV3 struct {
Review comment:
You can't get rid of DSServer because existing clients depend on it
##########
File path: docs/source/api/v4/servers_id.rst
##########
@@ -0,0 +1,509 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers-id:
+
+******************
+``servers/{{ID}}``
+******************
+
+``PUT``
+=======
+Allow user to edit a server.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+---------------------------------------------+
+ | Name | Description |
+ +======+=============================================+
+ | ID | The integral, unique identifier of a server |
+ +------+---------------------------------------------+
+
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server shall belong
+:cdnId: The integral, unique identifier of the CDN to which the server shall belong
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:hostName: The (short) hostname of the server
+:httpsPort: An optional port number on which the server listens for incoming HTTPS connections/requests
+:iloIpAddress: An optional IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: An optional IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: An optional IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: An optional string containing the password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) <Role>`
+:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be necessary, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be necessary, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface. This unsigned integer must not be less than 1280.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: An optional string containing The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: An optional string containing The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profileId: The :ref:`profile-id` the :term:`Profile` that shall be used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: An optional string indicating "server rack" location
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: An optional port number on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: An optional password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/4.0/servers/14 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 599
+ Content-Type: application/json
+
+ {
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "domainName": "infra.ciab.test",
+ "hostName": "quest",
+ "httpsPort": 443,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ },
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": false
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "bond0",
+ "routerHostName": "",
+ "routerPort": "",
+ }
+ ],
+ "interfaceMtu": 1500,
+ "interfaceName": "eth0",
+ "ip6Address": "::1",
+ "ip6Gateway": "::2",
+ "ipAddress": "0.0.0.1",
+ "ipGateway": "0.0.0.2",
+ "ipNetmask": "255.255.255.0",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocationId": 1,
+ "profileId": 10,
+ "statusId": 3,
+ "tcpPort": 80,
+ "typeId": 12,
+ "updPending": false
+ }
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
Review comment:
Same as above RE: indentation
##########
File path: traffic_ops/app/db/migrations/2021011500000000_update_interfaces_multiple_routers.sql
##########
@@ -0,0 +1,53 @@
+/*
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+*/
+
+-- +goose Up
+-- SQL in section 'Up' is executed when this migration is applied
+ALTER TABLE interface ADD COLUMN router_host_name text DEFAULT '';
+ALTER TABLE interface ADD COLUMN router_port text DEFAULT '';
+
+UPDATE interface
+SET router_host_name = CASE
+WHEN server.router_host_name IS NULL THEN ''
+ELSE interface.router_host_name || server.router_host_name
+END
Review comment:
This looks like it'll work fine, but for what it's worth it looks like you wanted a `COALESCE` here. Since you just created the router_port column of an interface, they can't already have any text, so this should be equivalent to
```sql
UPDATE interface
SET router_host_name = CASE
WHEN server.router_host_name IS NULL THEN ''
ELSE server.router_host_name
END
FROM server
WHERE server = server.id;
```
which, in turn, is equivalent to
```sql
UPDATE interface
SET router_host_name = COALESCE(server.router_host_name, '')
FROM server
WHERE server = server.id;
```
... but also, can't `interface.router_host_name` itself be NULL? Then maybe you don't need to check at all. If the intention was to make it NOT NULL then I think you missed a constraint.
##########
File path: docs/source/api/v4/servers_id.rst
##########
@@ -0,0 +1,509 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers-id:
+
+******************
+``servers/{{ID}}``
+******************
+
+``PUT``
+=======
+Allow user to edit a server.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+---------------------------------------------+
+ | Name | Description |
+ +======+=============================================+
+ | ID | The integral, unique identifier of a server |
+ +------+---------------------------------------------+
+
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server shall belong
+:cdnId: The integral, unique identifier of the CDN to which the server shall belong
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:hostName: The (short) hostname of the server
+:httpsPort: An optional port number on which the server listens for incoming HTTPS connections/requests
+:iloIpAddress: An optional IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: An optional IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: An optional IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: An optional string containing the password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) <Role>`
+:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be necessary, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be necessary, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface. This unsigned integer must not be less than 1280.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: An optional string containing The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: An optional string containing The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:physLocationId: An integral, unique identifier for the physical location where the server resides
+:profileId: The :ref:`profile-id` the :term:`Profile` that shall be used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: An optional string indicating "server rack" location
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: An optional port number on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: An optional password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Request Example
+
+ PUT /api/4.0/servers/14 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+ Content-Length: 599
+ Content-Type: application/json
+
+ {
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "domainName": "infra.ciab.test",
+ "hostName": "quest",
+ "httpsPort": 443,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ },
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": false
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "bond0",
+ "routerHostName": "",
+ "routerPort": "",
+ }
+ ],
+ "interfaceMtu": 1500,
+ "interfaceName": "eth0",
+ "ip6Address": "::1",
+ "ip6Gateway": "::2",
+ "ipAddress": "0.0.0.1",
+ "ipGateway": "0.0.0.2",
+ "ipNetmask": "255.255.255.0",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocationId": 1,
+ "profileId": 10,
+ "statusId": 3,
+ "tcpPort": 80,
+ "typeId": 12,
+ "updPending": false
+ }
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belongs
+:cdnId: The integral, unique identifier of the CDN to which the server belongs
+:cdnName: Name of the CDN to which the server belongs
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listens for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :abbr:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be present, but it is illegal for this set to be an empty collection.
+
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be present, but it is illegal for this set to be an empty collection.
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:lastUpdated: The date and time at which this server description was last modified
+:mgmtIpAddress: The IPv4 address of some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:offlineReason: A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status
+:physLocation: The name of the :term:`Physical Location` where the server resides
+:physLocationId: An integral, unique identifier for the :term:`Physical Location` where the server resides
+:profile: The :ref:`profile-name` of the :term:`Profile` used by this server
+:profileDesc: A :ref:`profile-description` of the :term:`Profile` used by this server
+:profileId: The :ref:`profile-id` the :term:`Profile` used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server has pending content invalidation/revalidation
+:rack: A string indicating "server rack" location
+:status: The status of the server
+
+ .. seealso:: :ref:`health-proto`
+
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: The port on which this server listens for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:type: The name of the 'type' of this server
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server has updates of some kind pending, typically to be acted upon by Traffic Ops ORT
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: The password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Access-Control-Allow-Credentials: true
+ Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
+ Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
+ Access-Control-Allow-Origin: *
+ Content-Encoding: gzip
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 19 May 2020 17:46:33 GMT; Max-Age=3600; HttpOnly
+ Vary: Accept-Encoding
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 19 May 2020 16:46:33 GMT
+ Content-Length: 566
+
+ { "alerts": [
+ {
+ "text": "Server updated",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "cachegroup": "CDN_in_a_Box_Mid",
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "domainName": "infra.ciab.test",
+ "guid": null,
+ "hostName": "quest",
+ "httpsPort": 443,
+ "id": 14,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "lastUpdated": "2020-05-19 16:46:33+00",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocation": "Apachecon North America 2018",
+ "physLocationId": 1,
+ "profile": "ATS_MID_TIER_CACHE",
+ "profileDesc": "Mid Cache - Apache Traffic Server",
+ "profileId": 10,
+ "rack": null,
+ "revalPending": false,
+ "status": "REPORTED",
+ "statusId": 3,
+ "tcpPort": 80,
+ "type": "MID",
+ "typeId": 12,
+ "updPending": false,
+ "xmppId": null,
+ "xmppPasswd": null,
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ },
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": false
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "bond0",
+ "routerHostName": "",
+ "routerPort": ""
+ }
+ ]
+ }}
+
+``DELETE``
+==========
+Allow user to delete server through api.
+
+:Auth. Required: Yes
+:Roles Required: "admin" or "operations"
+:Response Type: Object
+
+ .. versionchanged:: 3.0
+ In older versions of the API, this endpoint did not return a response object. It now returns a representation of the deleted server.
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +------+---------------------------------------------+
+ | Name | Description |
+ +======+=============================================+
+ | ID | The integral, unique identifier of a server |
+ +------+---------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ DELETE /api/3.0/servers/14 HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+:cachegroup: A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belonged
+:cachegroupId: An integer that is the :ref:`ID of the Cache Group <cache-group-id>` to which the server belonged
+:cdnId: The integral, unique identifier of the CDN to which the server belonged
+:cdnName: Name of the CDN to which the server belonged
+:domainName: The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+:guid: An identifier used to uniquely identify the server
+
+ .. note:: This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+:hostName: The (short) hostname of the server
+:httpsPort: The port on which the server listened for incoming HTTPS connections/requests
+:id: An integral, unique identifier for this server
+:iloIpAddress: The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpGateway: The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloIpNetmask: The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:iloPassword: The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [#ilo]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+:iloUsername: The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
+:interfaces: A set of the network interfaces that were in use by the server
+
+ :ipAddresses: A set of objects representing IP Addresses that were assigned to this network interface
+
+ :address: The actual IP address, including any mask as a CIDR-notation suffix
+ :gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
+ :serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address".
+
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors would have considered the entire server unhealthy - which includes *all* configured network interfaces. If this was ``null``, it has the meaning "no limit". It had no effect if ``monitor`` was not true for this interface.
+
+ .. seealso:: :ref:`health-proto`
+
+ :monitor: A boolean which describes whether or not this interface should have been monitored by Traffic Monitor for statistics and health consideration
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information was either not available or not applicable for this interface.
+ :name: The name of the interface. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: The human-readable name of the port used by the router responsible for reaching this server's interface.
+
+:lastUpdated: The date and time at which this server description was last modified
+:mgmtIpAddress: The IPv4 address of some network interface on the server that was used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server that was used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server that was used for 'management'
+
+ .. deprecated:: 3.0
+ This field is deprecated and will be removed in a future API version. Operators should migrate this data into the ``interfaces`` property of the server.
+
+:offlineReason: A user-entered reason why the server was in ADMIN_DOWN or OFFLINE status
+:physLocation: The name of the physical location where the server resided
+:physLocationId: An integral, unique identifier for the physical location where the server resided
+:profile: The :ref:`profile-name` of the :term:`Profile` which was used by this server
+:profileDesc: A :ref:`profile-description` of the :term:`Profile` which was used by this server
+:profileId: The :ref:`profile-id` the :term:`Profile` which was used by this server
+:revalPending: A boolean value which, if ``true`` indicates that this server had pending content invalidation/revalidation
+:rack: A string indicating "server rack" location
+:status: The :term:`Status` of the server
+
+ .. seealso:: :ref:`health-proto`
+
+:statusId: The integral, unique identifier of the status of this server
+
+ .. seealso:: :ref:`health-proto`
+
+:tcpPort: The port on which this server listened for incoming TCP connections
+
+ .. note:: This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+:type: The name of the :term:`Type` of this server
+:typeId: The integral, unique identifier of the 'type' of this server
+:updPending: A boolean value which, if ``true``, indicates that the server had updates of some kind pending, typically to be acted upon by Traffic Ops :term:`ORT`
+:xmppId: A system-generated UUID used to generate a server hashId for use in Traffic Router's consistent hashing algorithm. This value is set when a server is created and cannot be changed afterwards.
+:xmppPasswd: The password used in XMPP communications with the server
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Content-Encoding: gzip
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 19 May 2020 17:50:13 GMT; Max-Age=3600; HttpOnly
+ Vary: Accept-Encoding
+ X-Server-Name: traffic_ops_golang/
+ Date: Tue, 19 May 2020 16:50:13 GMT
+ Content-Length: 568
+
+ { "alerts": [
+ {
+ "text": "Server deleted",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "cachegroup": "CDN_in_a_Box_Mid",
+ "cachegroupId": 6,
+ "cdnId": 2,
+ "cdnName": "CDN-in-a-Box",
+ "domainName": "infra.ciab.test",
+ "guid": null,
+ "hostName": "quest",
+ "httpsPort": 443,
+ "id": 14,
+ "iloIpAddress": "",
+ "iloIpGateway": "",
+ "iloIpNetmask": "",
+ "iloPassword": "",
+ "iloUsername": "",
+ "lastUpdated": "2020-05-19 16:46:33+00",
+ "mgmtIpAddress": "",
+ "mgmtIpGateway": "",
+ "mgmtIpNetmask": "",
+ "offlineReason": "",
+ "physLocation": "Apachecon North America 2018",
+ "physLocationId": 1,
+ "profile": "ATS_MID_TIER_CACHE",
+ "profileDesc": "Mid Cache - Apache Traffic Server",
+ "profileId": 10,
+ "rack": null,
+ "revalPending": false,
+ "status": "REPORTED",
+ "statusId": 3,
+ "tcpPort": 80,
+ "type": "MID",
+ "typeId": 12,
+ "updPending": false,
+ "xmppId": null,
+ "xmppPasswd": null,
+ "interfaces": [
+ {
+ "ipAddresses": [
+ {
+ "address": "0.0.0.1/24",
+ "gateway": "0.0.0.2",
+ "serviceAddress": false
+ },
+ {
+ "address": "::1",
+ "gateway": "::2",
+ "serviceAddress": true
+ }
+ ],
+ "maxBandwidth": null,
+ "monitor": true,
+ "mtu": 1500,
+ "name": "bond0",
+ "routerHostName": "",
+ "routerPort": ""
Review comment:
same as above RE: formatting
##########
File path: lib/go-tc/servers.go
##########
@@ -71,6 +80,12 @@ type ServerDetailV30 struct {
ServerInterfaces *[]ServerInterfaceInfo `json:"interfaces"`
}
+// ServerDetailV40 is the details for a server for API v4
+type ServerDetailV40 struct {
Review comment:
Why not just have this one type declaration instead of a "base" and this combination?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] ocket8888 merged pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
ocket8888 merged pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] srijeet0406 commented on pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
srijeet0406 commented on pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#issuecomment-768797916
> Everything seems to be working fine. There are, unfortunately, more docs problems, though. These ones didn't get caught earlier because they're in those extra v4 copies you just made:
>
> * `cache_stats-get-request-example`
> * `deliveryservice_stats-get-request-example`
> * `response-structure`
>
> All appear in the v3 and v4 docs, making them duplicates. They aren't prefixed with `to-api` which is probably why they didn't get caught in the find/replace.
>
> Also, in `v3/deliveryserviceserver.rst` line 58 this label doesn't exist: `to-api-v3-response-structure`. I think it's supposed to be just `to-api-response-structure` - which is fine because it references the "Response Structure" section of the _main_ API docs page and therefore isn't versioned.
Good eye, I've fixed them now.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] ocket8888 commented on pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
ocket8888 commented on pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#issuecomment-769253788
GHA was experiencing an outage last night; I restarted all the jobs. Assuming they pass like they have before, it'll be good to merge.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
ocket8888 commented on a change in pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#discussion_r565700706
##########
File path: traffic_portal/app/src/common/modules/form/server/form.server.tpl.html
##########
@@ -268,6 +253,15 @@ <h6>Deprecated</h6>
<label for="{{inf.name}}-max-bandwidth" ng-class="{'has-error': hasError(serverForm[inf.name+'-max-bandwidth'])}">Maximum Bandwidth</label>
<input id="{{inf.name}}-max-bandwidth" ng-model="inf.maxBandwidth" ng-class="{'has-error': hasError(serverForm[inf.name+'-max-bandwidth'])}" min="0" type="number" name="{{inf.name}}-max-bandwidth"/>
<small class="input-error" ng-show="hasPropertyError(serverForm[inf.name+'-max-bandwidth'], 'min')">Cannot be negative</small>
+ <label for="{{inf.name}}-router-hostname" ng-class="{'has-error': hasError(serverForm[inf.name+'-router-hostname'])}">Router Hostname</label>
+ <input id="{{inf.name}}-router-hostname" ng-model="inf.routerHostName" ng-class="{'has-error': hasError(serverForm[inf.name+'-router-hostname'])}" type="text" name="{{inf.name}}-router-hostname" maxlength="256" pattern="\S*"/>
+ <small class="input-error" ng-show="hasPropertyError(serverForm[inf.name+'-router-hostname'], 'maxlength')">Too long</small>
+ <small class="input-error" ng-show="hasPropertyError(serverForm[inf.name+'-router-hostname'], 'pattern')">No Spaces</small>
+ <label for="{{inf.name}}-router-portname" ng-class="{'has-error': hasError(serverForm[inf.name+'-router-portname'])}">Router Port Name</label>
+ <input id="{{inf.name}}-router-portname" ng-model="inf.routerPortName" ng-class="{'has-error': hasError(serverForm[inf.name+'-router-portname'])}" type="text" name="{{inf.name}}-router-portname" maxlength="256" pattern="\S*"/>
+ <small class="input-error" ng-show="hasPropertyError(serverForm[inf.name+'-router-port'], 'maxlength')">Too long</small>
+ <small class="input-error" ng-show="hasPropertyError(serverForm[inf.name+'-router-port'], 'pattern')">No Spaces</small>
Review comment:
These errors aren't showing up when their conditions occur - I think it's because you're checking `inf.name+'router-port'` and the input's `id` is actually `{{inf.name}}-router-portname`
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
ocket8888 commented on a change in pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#discussion_r563027170
##########
File path: docs/source/api/v4/servers_id.rst
##########
@@ -49,21 +49,21 @@ Request Structure
:iloUsername: An optional string containing the user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [#ilo]_
:interfaces: A set of the network interfaces in use by the server. In most scenarios, only one will be necessary, but it is illegal for this set to be an empty collection.
- :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be necessary, but it is illegal for this set to be an empty collection.
+ :ipAddresses: A set of objects representing IP Addresses assigned to this network interface. In most scenarios, only one or two (usually one IPv4 address and one IPv6 address) will be necessary, but it is illegal for this set to be an empty collection.
:address: The actual IP address, including any mask as a CIDR-notation suffix
:gateway: Either the IP address of the network gateway for this address, or ``null`` to signify that no such gateway exists
:serviceAddress: A boolean that describes whether or not the server's main service is available at this IP address. When this property is ``true``, the IP address is referred to as a "service address". It is illegal for a server to not have at least one service address. It is also illegal for a server to have more than one service address of the same address family (i.e. more than one IPv4 service address and/or more than one IPv6 address). Finally, all service addresses for a server must be contained within one interface - which is therefore sometimes referred to as the "service interface" for the server.
- :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
+ :maxBandwidth: The maximum healthy bandwidth allowed for this interface. If bandwidth exceeds this limit, Traffic Monitors will consider the entire server unhealthy - which includes *all* configured network interfaces. If this is ``null``, it has the meaning "no limit". It has no effect if ``monitor`` is not true for this interface.
.. seealso:: :ref:`health-proto`
- :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
- :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface. This unsigned integer must not be less than 1280.
- :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
- :routerHostName: An optional string containing The human-readable name of the router responsible for reaching this server's interface.
- :routerPort: An optional string containing The human-readable name of the port used by the router responsible for reaching this server's interface.
+ :monitor: A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.
+ :mtu: The :abbr:`MTU (Maximum Transmission Unit)` of this interface. If it is ``null``, it may be assumed that the information is either not available or not applicable for this interface. This unsigned integer must not be less than 1280.
+ :name: The name of the interface. No two interfaces of the same server may share a name. It is the same as the network interface's device name on the server, e.g. ``eth0``.
+ :routerHostName: An optional string containing The human-readable name of the router responsible for reaching this server's interface.
+ :routerPort: An optional string containing The human-readable name of the port used by the router responsible for reaching this server's interface.
Review comment:
these are still indented with spaces instead of tabs
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [trafficcontrol] srijeet0406 commented on a change in pull request #5450: When adding multiple interfaces on a server, a router host and router description should also be created per interface
Posted by GitBox <gi...@apache.org>.
srijeet0406 commented on a change in pull request #5450:
URL: https://github.com/apache/trafficcontrol/pull/5450#discussion_r564145131
##########
File path: traffic_portal/app/src/common/modules/table/servers/TableServersController.js
##########
@@ -220,7 +220,7 @@ var TableServersController = function(tableName, servers, filter, $scope, $state
},
{
headerName: "Router Port Name",
- field: "routerPortName",
+ field: "routerPort",
Review comment:
I'm a UI rookie, but isn't the field `interfaceName` working in the same way? It comes from the `interface` struct inside the `server` struct, as do `routerHostName` and `routerPortName`.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org