`servers`

`GET`

Retrieves properties of all servers across all CDNs.

Auth. Required: Yes
Roles Required: None
Response Type: Array

Request Structure

Table 215 Request Query Parameters
Name	Required	Description
cachegroup	no	Return only those servers within the Cache Group that has this ID
dsId	no	Return only those servers assigned to the Delivery Service identified by this integral, unique identifier
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 Profile that has this ID
status	no	Return only those servers with this status - see Health Protocol
type	no	Return only servers of this Type
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^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`.

#485 Request Example

GET /api/2.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 name of the Cache Group to which the server belongs
cachegroupId: An integer that is the ID of the Cache Group 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 FQDN
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 ILO service1
iloIpGateway: The IPv4 gateway address of the server’s ILO service1
iloIpNetmask: The IPv4 subnet mask of the server’s ILO service1
iloPassword: The password of the of the server’s ILO service user1 - displays as simply ****** if the currently logged-in user does not have the ‘admin’ or ‘operations’ Role(s)
iloUsername: The user name for the server’s ILO service1
interfaceMtu: The MTU configured on interfaceName
interfaceName: The name of the primary network interface used by the server
ip6Address: The IPv6 address and subnet mask of interfaceName
ip6IsService: A boolean value which if true indicates that the IPv6 address will be used for routing content.
ip6Gateway: The IPv6 address of the gateway used by interfaceName
ipAddress: The IPv4 address of interfaceName
ipIsService: A boolean value which if true indicates that the IPv4 address will be used for routing content.
ipGateway: The IPv4 address of the gateway used by interfaceName
ipNetmask: The IPv4 subnet mask used by interfaceName
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’
mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for ‘management’
mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for ‘management’
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 Name of the Profile used by this server
profileDesc: A Description of the Profile used by this server
profileId: The ID the 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
routerHostName: The human-readable name of the router responsible for reaching this server
routerPortName: The human-readable name of the port used by the router responsible for reaching this server
status: The Status of the server

See also

Health Protocol
statusId: The integral, unique identifier of the status of this server

See also

Health Protocol
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

#486 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-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: WyapQctUIhjzEALka5QbBiZRZ58Mlc6MJSwjBeGyJS2UzbL3W6lN/4kvAZtPrP4qMWQBWz6JjbF7Y5lNRASUmQ==
X-Server-Name: traffic_ops_golang/
Date: Mon, 10 Dec 2018 16:13:31 GMT
Content-Length: 939

{ "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": 10,
        "iloIpAddress": "",
        "iloIpGateway": "",
        "iloIpNetmask": "",
        "iloPassword": "",
        "iloUsername": "",
        "interfaceMtu": 1500,
        "interfaceName": "eth0",
        "ip6Address": "fc01:9400:1000:8::120",
        "ip6Gateway": "fc01:9400:1000:8::1",
        "ipAddress": "172.16.239.120",
        "ipGateway": "172.16.239.1",
        "ipNetmask": "255.255.255.0",
        "lastUpdated": "2018-12-05 18:45:05+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,
        "routerHostName": "",
        "routerPortName": "",
        "status": "REPORTED",
        "statusId": 3,
        "tcpPort": 80,
        "type": "MID",
        "typeId": 12,
        "updPending": false,
        "xmppId": "mid",
        "xmppPasswd": "",
        "ipIsService": true,
        "ip6IsService": true
    }
]}

`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 ID of the Cache Group 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 FQDN
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 ILO service1
iloIpGateway: An optional IPv4 gateway address of the server’s ILO service1
iloIpNetmask: An optional IPv4 subnet mask of the server’s ILO service1
iloPassword: An optional string containing the password of the of the server’s ILO service user1 - displays as simply ****** if the currently logged-in user does not have the ‘admin’ or ‘operations’ Role(s)
iloUsername: An optional string containing the user name for the server’s ILO service1
interfaceMtu: The MTU configured on interfaceName

Note

In virtually all cases this ought to be 1500. Further note that the only acceptable values are 1500 and 9000.
interfaceName: The name of the primary network interface used by the server
ip6Address: An optional IPv6 address and subnet mask of interfaceName
ip6IsService: An optional boolean value which if true indicates that the IPv6 address will be used for routing content. Defaults to true.
ip6Gateway: An optional IPv6 address of the gateway used by interfaceName
ipAddress: The IPv4 address of interfaceName
ipIsService: An optional boolean value which if true indicates that the IPv4 address will be used for routing content. Defaults to true.
ipGateway: The IPv4 address of the gateway used by interfaceName
ipNetmask: The IPv4 subnet mask used by interfaceName
mgmtIpAddress: An optional IPv4 address of some network interface on the server used for ‘management’
mgmtIpGateway: An optional IPv4 address of a gateway used by some network interface on the server used for ‘management’
mgmtIpNetmask: An optional IPv4 subnet mask used by some network interface on the server used for ‘management’
physLocationId: An integral, unique identifier for the physical location where the server resides
profileId: The ID the 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
routerHostName: An optional string containing the human-readable name of the router responsible for reaching this server
routerPortName: An optional string containing the human-readable name of the port used by the router responsible for reaching this server
statusId: The integral, unique identifier of the status of this server

See also

Health Protocol
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

#487 Request Example

POST /api/2.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": "",
    "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,
    "routerHostName": "",
    "routerPortName": "",
    "statusId": 3,
    "tcpPort": 80,
    "typeId": 12,
    "updPending": false,
    "ipIsService": true,
    "ip6IsService": true
}

Response Structure

cachegroup: A string that is the name of the Cache Group to which the server belongs
cachegroupId: An integer that is the ID of the Cache Group 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 FQDN
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 ILO service1
iloIpGateway: The IPv4 gateway address of the server’s ILO service1
iloIpNetmask: The IPv4 subnet mask of the server’s ILO service1
iloPassword: The password of the of the server’s ILO service user1 - displays as simply ****** if the currently logged-in user does not have the ‘admin’ or ‘operations’ Role(s) <Role>
iloUsername: The user name for the server’s ILO service1
interfaceMtu: The MTU configured on interfaceName
interfaceName: The name of the primary network interface used by the server
ip6Address: The IPv6 address and subnet mask of interfaceName
ip6IsService: A boolean value which if true indicates that the IPv6 address will be used for routing content.
ip6Gateway: The IPv6 address of the gateway used by interfaceName
ipAddress: The IPv4 address of interfaceName
ipIsService: A boolean value which if true indicates that the IPv4 address will be used for routing content.
ipGateway: The IPv4 address of the gateway used by interfaceName
ipNetmask: The IPv4 subnet mask used by interfaceName
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’
mgmtIpGateway: The IPv4 address of a gateway used by some network interface on the server used for ‘management’
mgmtIpNetmask: The IPv4 subnet mask used by some network interface on the server used for ‘management’
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 Name of the Profile used by this server
profileDesc: A Description of the Profile used by this server
profileId: The ID the 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
routerHostName: The human-readable name of the router responsible for reaching this server
routerPortName: The human-readable name of the port used by the router responsible for reaching this server
status: The status of the server

See also

Health Protocol
statusId: The integral, unique identifier of the status of this server

See also

Health Protocol
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

#488 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-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: mcGmmu5ONDg3jmvlkItcw6jxiT1ecmePYujZfmKiZrn5ThKjsSadeJIynaeOK0XVUjHuYHdtdynSqxr2rdzEyA==
X-Server-Name: traffic_ops_golang/
Date: Mon, 10 Dec 2018 17:44:04 GMT
Content-Length: 850

{ "alerts": [
    {
        "text": "server was created.",
        "level": "success"
    }
],
"response": {
    "cachegroup": null,
    "cachegroupId": 6,
    "cdnId": 2,
    "cdnName": null,
    "domainName": "infra.ciab.test",
    "guid": null,
    "hostName": "test",
    "httpsPort": 443,
    "id": 13,
    "iloIpAddress": "",
    "iloIpGateway": "",
    "iloIpNetmask": "",
    "iloPassword": "",
    "iloUsername": "",
    "interfaceMtu": 1500,
    "interfaceName": "eth0",
    "ip6Address": "::1",
    "ip6Gateway": "::2",
    "ipAddress": "0.0.0.1",
    "ipGateway": "0.0.0.2",
    "ipNetmask": "255.255.255.0",
    "lastUpdated": "2018-12-10 17:44:04+00",
    "mgmtIpAddress": "",
    "mgmtIpGateway": "",
    "mgmtIpNetmask": "",
    "offlineReason": "",
    "physLocation": null,
    "physLocationId": 1,
    "profile": null,
    "profileDesc": null,
    "profileId": 10,
    "rack": null,
    "revalPending": null,
    "routerHostName": "",
    "routerPortName": "",
    "status": null,
    "statusId": 3,
    "tcpPort": 80,
    "type": "",
    "typeId": 12,
    "updPending": false,
    "xmppId": "test",
    "xmppPasswd": null,
    "ipIsService": true,
    "ip6IsService": true
}}

1(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15): For more information see the Wikipedia page on Lights-Out management.

servers

GET

Request Structure

Response Structure

POST

Request Structure

Response Structure

`servers`

`GET`

`POST`