6. EPP client workflow

Registrars communicate with the registry through FRED’s registrar interface, which is based on the EPP and which the registrars use as clients.

There are 3 options for using the registrar interface:

  • command-line Python client fred/eppic,

  • client Python API library fred/utils/epplib,

  • registrar’s custom client built on the raw EPP.

Although these three options vary in syntax, they have the same workflow, since they all talk to the same EPP server. This chapter describes the general workflow, which is independent from the syntax, while giving you hints about the syntax.

Of course, correct syntax is a necessary condition for the commands to be carried out.

Each EPP command allows you to append your own client transaction identifier.

Note

This chapter assumes that the client is a regular registrar (not the system registrar).

Where to get detailed help with syntax

The CLI client has an embedded command help. It also allows you to enter the commands in an interactive mode by filling in command parameters one by one, or enter the parameters by their names. See Additional EPPIC abilities.

Python API methods have the same names as CLI client commands, they differ in parameter syntax and order. You may view the API reference by starting the pydoc server pydoc -p 8080 from the command line and then opening http://localhost:8080 in a browser.

The EPP syntax itself is described in detail in the EPP Reference Manual. This chapter will provide you with links to specific EPP-commands as you read on.

6.1. Connecting to the server

The client must:

  • create a secure socket using a public certificate and private key,

  • connect via the socket to the EPP server using a hostname and port,

  • once connected, start reading data coming from the EPP server.

When you use the raw EPP, you need to find your own way of connecting to the EPP server, whereas the client programs will do it for you, all you need to do is supply connection settings in a configuration file.

Detailed requirements for transfer over TCP are in RFC 5734.

6.2. Getting service information

Once the client is connected to the server, the first data it receives contains the greeting.

What might interest you in the greeting (xpath:/epp/greeting/):

  • protocol version (svcMenu/version),

  • service languages provided (svcMenu/lang),

  • namespaces of managed objects (svcMenu/objURI),

  • namespaces of service extensions (svcExtension/extURI),

  • description of the data collection policy (dcp).

You actually need the first four items to establish a session.

To get the greeting, you just need to connect to the EPP server or send a hello.

6.3. Establishing a session (login)

This is the first command you must issue.

To login, you send the login command (display help / see the reference) with a username, password and, eventually, other session settings, such as the interface language.

The CLI client can use configuration settings to login automatically when it is launched. It requests use of all namespaces automatically.

Once you are logged in, you may start issuing other commands.

6.4. Registering domains & other objects

In a nutshell, if you’re a newcomer without previous records, you must proceed with registrations in this order:

  1. Login, before you begin.

  2. Check that an object can be registered.

  3. Create a contact.

  4. Optionally, create an nsset (using a contact).

  5. Optionally, create a keyset (using a contact).

  6. Create a domain (using a contact, and optionally an nsset and keyset).

6.4.1. Check domain names and handles

When registering a new object of any type, you need to name it with a unique identifier – a domain name or a handle. In case of domain names, the holders choose them for themselves of course. But for the other objects, it is you who names them. To make sure that a domain name or handle can be registered, use a check command according to the object type:

The command will tell you not only whether an object has not been registered yet, but also whether the name/handle has correct syntax and is acceptable by the Registry.

Formats for domain names and handles are properly described in the chapter Common object attributes (EPP Reference).

You may also check several objects of the same type with one call, because the commands accept multiple parameters.

6.4.2. Create a contact

To register a domain name, you must first record personal information, to which the domain name will be linked. Personal information is recorded using contact objects, which hold information about people (or organizations) in various roles, such as the domain holder or a technician responsible for domain’s name servers. (More about the roles of contacts in the Registry.)

A contact is registered using the command create-contact (display help) / contact:create (see the reference) and required parameters.

Note

Setting contact disclosure preference (disclose flags) requires special attention as described in Policies & rules of disclosure.

  • auth-info is generated on demand by the send-authinfo-contact command. For more information, see AuthInfo TTL.

If you omit:

  • disclose, the server sets disclose flags to defaults according to the disclosure policy,

  • other optional parameters, they are left unset.

6.4.3. Create a nsset OPTIONAL

To have the future domain included in the zone, you need to have some name servers recorded in the Registry as well. Name servers are recorded using nsset objects.

A nsset is registered using the command create-nsset (display help) / nsset:create (see the reference) and required parameters.

  • auth-info is generated on demand by the send-authinfo-nsset command. For more information, see AuthInfo TTL.

If you omit:

  • reportlevel, the server sets it to the default (see also Technical checks),

  • other optional parameters, they are left unset.

6.4.4. Create a keyset OPTIONAL

To have the future domain secured, you need to have some DNSSEC keys recorded in the Registry as well. The DNSSEC keys are recorded using keyset objects.

A keyset is registered using the command create-keyset (display help) / keyset:create (see the reference) and required parameters.

  • auth-info is generated on demand by the send-authinfo-keyset command. For more information, see AuthInfo TTL.

If you omit:

  • dnskey, it will be left empty and the linked domains still will not be secured.

6.4.5. Create a domain

Now, you’re ready to actually register a domain name. Domain names are recorded using domain objects.

A domain is registered using the command create-domain (display help) / domain:create (see the reference) and required parameters.

  • auth-info is generated on demand by the send-authinfo-contact command. For more information, see AuthInfo TTL.

If you omit:

  • period, the server makes registration for the smallest period allowed,

  • other optional parameters, they are left unset.

Conditions for success

  • You must be granted access to the zone, in which you want to register the domain.

  • You must have credit, if the registry charges for domain creation.

6.4.6. Re-use

Of course, if you have previously recorded some contacts, nssets, or keysets, you may re-use them to register new domains, nssets, and keysets.

Beware, though, other registrars may link your objects to their objects, too. (This can happen when an object has been transferred.)

6.5. Listing objects

Recorded objects can be retrieved in the form of lists. This is done in two (or more) steps within separate requests.

The first request asks the server to prepare a list on its side. Use one of the commands starting with prep-* (display help) / a listing element (see the reference).

Note

The list preparation commands that do not accept parameters (such as prep-domains / fred:listDomains), will list only objects that you are designated to manage. The parametrized commands (such as prep-domains-by-contact / fred:domainsByContact) ignore who the designated registrar is.

The server responds with a total of prepared items.

A subsequent request orders the server to send a bulk of list items and it is to be called repeatedly until the server returns an empty list.

To retrieve the next bulk, use the command get-results (display help) / fred:getResults (see the reference) which does not require any parameters.

The server retains the remaining list items between these calls. Another prepare request resets the list.

Conditions for success

6.6. Getting object information

To view object details, use an info command according to the object type:

Conditions for success

  • You must be logged in.

  • The object must exist.

6.7. Renewing domains

To renew a domain, use the command renew-domain (display help) / domain:renew (see the reference) and required parameters.

If you don’t know its current expiration date, you can find out from the domain’s details – see Getting object information.

If you omit period, the server makes renewal for the smallest period allowed.

Conditions for success

  • You must be logged in.

  • The domain must exist.

  • The domain must not be marked for deletion (deleteCandidate status flag).

  • The domain must not be administratively blocked.

  • The domain must not be prohibited renewal.

  • You must have credit, if the registry charges for domain renewal.

6.8. Transferring objects

See the Object transfer concept for an explanation of how transfer works in general.

To proceed with a transfer request (and thus become the designated registrar of the object), use a transfer command according to the object type:

Conditions for success

  • You must be logged in.

  • The object must exist.

  • The AuthInfo must match.

  • The object must not be administratively blocked.

  • The object must not be prohibited transfers.

6.9. Updating objects

Generally, there are 3 “methods” for editing object details: add, rem (remove), and chg (change).

add and rem are used for editing attributes that can have multiple-child values, such as admin/tech contacts, name servers, or DNS keys. There is no difference between an omitted child (NULL) and a child that contains an empty string (''), both are interpreted as no change.

chg is used to edit single-child values, such as a domain owner, linked nsset, disclosure preference, or AuthInfo. If the child is omitted (NULL), it means that a change is not being requested, whereas when a child contains an empty string (''), it means that the old value shall be overwritten and thus left empty after the update.

To edit object details, use an update command according to the object type:

Note

Editing contact disclosure preference (disclose flags) requires special attention as described in Policies & rules of disclosure.

Conditions for success

  • You must be logged in.

  • The object must exist.

  • You must be designated to manage the object.

  • The object must not be administratively blocked.

  • The object must not be prohibited updates.

6.10. Deleting objects

To delete an object, use a delete command according to the object type:

Conditions for success

  • You must be logged in.

  • The object must exist.

  • You must be designated to manage the object.

  • The object must not be linked to (referenced by) other objects.

  • The object must not be administratively blocked.

  • The object must not be prohibited deletion.

6.11. Reading messages

The server generates service messages. Reading of the messages is done in two (or more) steps within separate requests.

To ask the server if it has any messages, use the command poll req (display help) / <poll op="req"/> (see the reference).

The server responds with the first message in the queue and the count of messages.

A subsequent request acknowledges that the message has been read and orders the server to remove it from the queue.

To acknowledge, use the command poll ack (display help) / <poll op="ack"/> (see the reference) with the message identifier.

To read the next message(s), just repeat the process.

You must be logged in to read your messages.

6.12. Reading credit

Just use the command credit-info (display help) / fred:creditInfo (see the reference), which does not require any parameters.

You must be logged in.

6.13. Ending a session (logout)

Just use the logout command (display help / see the reference), which does not require any parameters.

Then your client may close the connection (it times out anyway).

If you want to logout, disconnect and quit, you may use exit.

6.14. Additional EPPIC abilities

This section describes additional abilities of the CLI client. All these abilities can be used from the running client.

Note

This guide doesn’t describe all features, only highlights. For all eppic features, see the documentation contained with the program fred/eppic.

6.14.1. Display command help

To show available FRED client commands, type help.

To show help for a specific command, type help <command> (e.g. help update-contact) or ? <command> (e.g. ? create-domain).

6.14.2. Parameter usage

FRED client accepts positional and named parameters. Use help commands to display parameter information.

6.14.3. View raw EPP messages

If you need to read the xml-formatted communication, in addition to the default output, the CLI client can display the raw xml data sent to and received from the server. Input can be read from a file.