Contents
The management of name servers via the EPP Gateway allows for easy checking, creation, deleting, and updating of name servers.
1. Check Host availability
The EPP <check> command is used to determine if a name server host exists. It provides a hint that allows a client to anticipate the success or failure of provisioning, changing or deleting a name server host object.
Command request contain following element:
- <host:name> – fully qualified host name. Registrar is able to provide multiple <host:name> in a single request.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <command> <check> <host:check xmlns:host="urn:ietf:params:xml:ns:host-1.0"> <host:name>ns.example.st</host:name> <host:name>ns2.example.st</host:name> </host:check> </check> <clTRID>53cfd4d19d362</clTRID> </command> </epp> |
After successful command execution response will include all host names provided in request with attribute “avail” and value “0” or “1”. “0” mean that host cannot be created, “1” mean that host syntax is correct and can be created.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <response> <result code="1000"> <msg>Command completed successfully</msg> </result> <resData> <host:chkData xmlns:host="urn:ietf:params:xml:ns:host-1.0"> <host:cd> <host:name avail="1">ns.example.st</host:name> </host:cd> <host:cd> <host:name avail="0">ns2.example.st</host:name> <host:reason>In use</domain:reason> </host:cd> </host:chkData> </resData> <trID> <clTRID>53cfd4d19d362</clTRID> <svTRID>53cfd791edf71</svTRID> </trID> </response> </epp> |
2. Create Host
Name server hosts can be created using the <host:create> element. Child elements include:
- A <host:name> element that contains the fully qualified name of a host.
- Zero or more OPTIONAL <host:addr> elements that contain the IP addresses to be associated with the host.
- Each element MAY contain an “IP” attribute to identify the IP address format.
- Attribute value “v4” is used to denote an IPv4 address format.
- Attribute value “v6” is used to denote an IPv6 address format.
- If the “IP” attribute is not specified, “v4” is the default attribute value.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <command> <create> <host:create xmlns:host="urn:ietf:params:xml:ns:host-1.0"> <host:name>ns.example.st</host:name> <host:addr ip="v4">192.0.2.1</host:addr> </host:create> </create> <clTRID>53cfd4d19d362</clTRID> </command> </epp> |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <response> <result code="1000"> <msg>Command completed successfully</msg> </result> <resData> <host:creData xmlns:host="urn:ietf:params:xml:ns:host-1.0"> <host:name>ns.example.st</host:name> <host:crDate>2014-01-01T15:30:00+00:00</host:crDate> <host:exDate></host:exDate> </host:creData> </resData> <trID> <clTRID>53cfd4d19d362</clTRID> <svTRID>07f358c2-d79f-466d-8db4-ee18f69bbd7f</svTRID> </trID> </response> </epp> |
3. Query Host
The EPP <info> command is used to retrieve information associated with a host object.
Command request contain following element:
- <host:name> – fully qualified host name.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <command> <info> <host:info xmlns:host="urn:ietf:params:xml:ns:host-1.0"> <host:name>ns.example.st</host:name> </host:info> </info> <clTRID>53cfdb48878ce</clTRID> </command> </epp> |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <response> <result code="1000"> <msg>Command completed successfully</msg> </result> <resData> <host:infData xmlns:host="urn:ietf:params:xml:ns:host-1.0"> <host:name>ns.example.st</host:name> <host:roid>ST-53CFD74A93C66-STREGISTRY2-ST</host:roid> <host:status s="ok"></host:status> <host:addr ip="v4">192.0.2.1</host:addr> <host:clID>ABC123</host:clID> <host:crID>ABC123</host:crID> <host:crDate>2014-01-01T15:42:23+00:00</host:crDate> <host:upID>ABC123</host:upID> <host:upDate>2014-01-01T15:42:23+00:00</host:upDate> </host:infData> </resData> <trID> <clTRID>53cfdb48878ce</clTRID> <svTRID>47f35f87-bdb4-468d-a24f-7f95ba2245da</svTRID> </trID> </response> </epp> |
4. Update Host
The EPP <update> command for name sever hosts allows modification of attributes of a host object. The <update> command MUST contain a <host:update> element that identifies the host.
The <host:update> element contains the following child elements:
- A <host:name> element that contains full qualified name of the host to be updated.
- An OPTIONAL <host:add> element that contains attribute values to be added to the object.
- An OPTIONAL <host:rem> element that contains attribute values to be removed from the object.
- An OPTIONAL <host:chg> element that contains object attribute values to be changed.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <command> <update> <host:update xmlns:host="urn:ietf:params:xml:ns:host-1.0"> <host:name>ns.example.st</host:name> <host:add> <host:addr ip="v4">192.0.2.2</host:addr> </host:add> <host:rem> <host:addr ip="v4">192.0.2.1</host:addr> </host:rem> </host:update> </update> <clTRID>53cfdc64302a4</clTRID> </command> </epp> |
|
1 2 3 4 5 6 7 8 9 10 11 12 |
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <response> <result code="1000"> <msg>Command completed successfully</msg> </result> <trID> <clTRID>53cfdc64302a4</clTRID> <svTRID>9edd7a5b-5caa-4e4a-bd95-f33607280632</svTRID> </trID> </response> </epp> |
5. Delete Host
The <delete> command allows a client to delete a name server host object. In addition to the standard EPP command elements, the <delete> command MUST contain a <host:delete> that identifies the host.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <command> <delete> <host:delete xmlns:host="urn:ietf:params:xml:ns:host-1.0"> <host:name>ns.example.st</host:name> </host:delete> </delete> <clTRID>53cfd5c3b0d51</clTRID> </command> </epp> |
|
1 2 3 4 5 6 7 8 9 10 11 12 |
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <response> <result code="1000"> <msg>Command completed successfully</msg> </result> <trID> <clTRID>53cfd5c3b0d51</clTRID> <svTRID>0fd566c9-8ff5-4cfa-b14a-7f751106ab85</svTRID> </trID> </response> </epp> |
6. Host status codes
Same as for domain objects there is 2 different types of status codes: client and server codes. Client status codes are set by registrars. Server status codes are set by ST Registry and they take precedence over client codes.
The following are two tables containing 10 possible host object status codes, these tables will explain what each status means.
Server codes:
Status code Description ok This is the standard status for a domain, meaning it has no holds or restrictions. This status code is set and removed by ST Registry as other status values are added or removed. linked The host object has at least one active association with a domain object. Registrars are unable to delete such host object unless all associations between host object and domains will be destroyed. To find all domains with association to corresponding host object please refer to the manual – Collections. serverDeleteProhibited Any request to delete host object will be rejected by ST Registry. serverUpdateProhibited Any request to update host object (other than to remove this status) will be rejected by ST Registry. pendingCreate This status code indicates that a request to create host object has been received and is being processed. Status is removed when host object will be propagated to the root ST zone. pendingUpdate This status indicates that a request to update host object has been received and is being processed. Status is removed when host object updates will be propagated to the root ST zone. pendingTransfer This status indicates that a request to transfer the host object superordinate domain object has been received and is being processed. pendingDelete This status indicates that a request to delete host object has been received and is being processed. Status code is removed and host object completely deleted from ST Registry repository after changes propagated to the root ST zone.
7. Response codes
To simplify initial integration process, instead of general error messages, ST Registry provide different response messages for same response code depending from exception which generated corresponding response code. Below you can find list of all possible response codes and their messages for host related operations.
| Response code | Message |
| 1000 | Command completed successfully |
| 2003 | Missing host name |
| 2005 | Invalid host:name |
| 2005 | Invalid host:addr |
| 2203 | Operation not permitted |
| 2302 | Host already exists |
| 2302 | Host with name {hostaname} already exists |
| 2304 | Object status prohibits operation |
| 2305 | Host must be subordinate to one of the registrar domains |
