`servers/{{ID}}`

`PUT`

Allow user to edit a server.

Auth. Required:: Yes
Roles Required:: “admin” or “operations”
Permissions Required:: SERVER:UPDATE, SERVER:READ, DELIVERY-SERVICE:READ, CDN:READ, PHYSICAL-LOCATION:READ, CACHE-GROUP:READ, TYPE:READ, PROFILE:READ
Response Type:: Object

Request Structure

Table 406 Request Path Parameters
Name	Description
ID	The integral, unique identifier of a server

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 service[1]

iloIpGateway:

An optional IPv4 gateway address of the server’s ILO service[1]

iloIpNetmask:

An optional IPv4 subnet mask of the server’s ILO service[1]

iloPassword:

An optional string containing the password of the of the server’s ILO service user[1] - displays as simply ****** if the currently logged-in user does not have the ‘admin’ or ‘operations’ Role(s) <Role>

iloUsername:

An optional string containing the user name for the server’s ILO service[1]

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.

See also

Health Protocol

monitor:

A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.

mtu:

The MTU 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.

routerPortName:

The human-readable name of the router responsible for reaching this server’s interface.

routerPortName:

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 since version 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 since version 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 since version 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

profileNames:

List of Name of the Profiles that shall be used by this server

rack:

An optional string indicating “server rack” location

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

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

#990 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": "",
            "routerPortName": ""
        }
    ],
    "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,
    "profileNames": ["ATS_MID_TIER_CACHE"],
    "statusId": 3,
    "tcpPort": 80,
    "typeId": 12
}

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

configUpdateTime:

The last time an update was requested for this server. This field defaults to standard epoch

configApplyTime:

The last time an update was applied for this server. This field defaults to standard epoch

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 service[1]

iloIpGateway:

The IPv4 gateway address of the server’s ILO service[1]

iloIpNetmask:

The IPv4 subnet mask of the server’s ILO service[1]

iloPassword:

The password of the of the server’s ILO service user[1] - 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 service[1]

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.

See also

Health Protocol

monitor:

A boolean which describes whether or not this interface should be monitored by Traffic Monitor for statistics and health consideration.

mtu:

The MTU 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.

routerPortName:

The human-readable name of the router responsible for reaching this server’s interface.

routerPortName:

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 since version 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 since version 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 since version 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

profileNames:

List of Name of the Profiles used by this server

revalPending:

A boolean value which, if true indicates that this server has pending content invalidation/revalidation

Deprecated since version 4.1: With the addition of revalUpdateTime and revalApplyTime, this field is superfluous as it is trivially calculated from those other properties. It has been removed in version 5.0 of the API.

revalUpdateTime:

The last time a content invalidation/revalidation request was submitted for this server. This field defaults to standard epoch

revalApplyTime:

The last time a content invalidation/revalidation request was applied by this server. This field defaults to standard epoch

rack:

A string indicating “server rack” location

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 Control Cache Config (t3c, formerly 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

#991 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",
    "configUpdateTime": "2022-02-28T15:44:15.895145-07:00",
    "configApplyTime": "2022-02-18T13:52:47.129174-07:00",
    "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,
    "profileNames": ["ATS_MID_TIER_CACHE"],
    "rack": null,
    "revalPending": false,
    "revalUpdateTime": "1969-12-31T17:00:00-07:00",
    "revalApplyTime": "1969-12-31T17:00:00-07:00",
    "status": "REPORTED",
    "statusId": 3,
    "tcpPort": 80,
    "type": "MID",
    "typeId": 12,
    "updPending": true,
    "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": "",
            "routerPortName": ""
        }
    ]
}}

`DELETE`

Allow user to delete server through api.

Auth. Required:: Yes
Roles Required:: “admin” or “operations”
Permissions Required:: SERVER:DELETE, SERVER:READ, DELIVERY-SERVICE:READ, CDN:READ, PHYSICAL-LOCATION:READ, CACHE-GROUP:READ, TYPE:READ, PROFILE:READ
Response Type:: Object

Changed in version 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 407 Request Path Parameters
Name	Description
ID	The integral, unique identifier of a server

#992 Request Example

DELETE /api/4.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 name of the Cache Group to which the server belonged

cachegroupId:

An integer that is the ID of the Cache Group 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

configUpdateTime:

The last time an update was requested for this server. This field defaults to standard epoch

configApplyTime:

The last time an update was applied for this server. This field defaults to standard epoch

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 listened for incoming HTTPS connections/requests

id:

An integral, unique identifier for this server

iloIpAddress:

The IPv4 address of the server’s ILO service[1]

iloIpGateway:

The IPv4 gateway address of the server’s ILO service[1]

iloIpNetmask:

The IPv4 subnet mask of the server’s ILO service[1]

iloPassword:

The password of the of the server’s ILO service user[1] - 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 service[1]

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.

See also

Health Protocol

monitor:

A boolean which describes whether or not this interface should have been monitored by Traffic Monitor for statistics and health consideration

mtu:

The MTU 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.

routerPortName:

The human-readable name of the router responsible for reaching this server’s interface.

routerPortName:

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 since version 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 since version 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 since version 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

profileNames:

List of Name of the Profiles which was used by this server

revalPending:

A boolean value which, if true indicates that this server has pending content invalidation/revalidation

Deprecated since version 4.1: With the addition of revalUpdateTime and revalApplyTime, this field is superfluous as it is trivially calculated from those other properties. It has been removed in version 5.0 of the API.

revalUpdateTime:

The last time a content invalidation/revalidation request was submitted for this server. This field defaults to standard epoch

revalApplyTime:

The last time a content invalidation/revalidation request was applied by this server. This field defaults to standard epoch

rack:

A string indicating “server rack” location

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 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 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 Control Cache Config (T3C, formerly 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

#993 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",
    "configUpdateTime": "1969-12-31T17:00:00-07:00",
    "configApplyTime": "1969-12-31T17:00:00-07:00",
    "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,
    "profileNames": ["ATS_MID_TIER_CACHE"],
    "rack": null,
    "revalPending": false,
    "revalUpdateTime": "1969-12-31T17:00:00-07:00",
    "revalApplyTime": "1969-12-31T17:00:00-07:00",
    "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": "",
            "routerPortName": ""
        }
    ]
}}

servers/{{ID}}

PUT

Request Structure

Response Structure

DELETE

Request Structure

Response Structure

`servers/{{ID}}`

`PUT`

`DELETE`