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 (supplied with the FRED),

  • client Python API library (supplied with the FRED),

  • 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 FRED-client 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 by the server. 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 an 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 by the server. 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 by the server. 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 by the server. 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.

If you want to request and acknowledge a message at once in the fred-client, you may use poll_autoack on to enable this feature. With autoack on, the client will send poll request and then automatically poll acknowledge the read message.

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 the fred-client at once, you may use quit.

6.14. Additional FRED-client 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 fred-client features, see the documentation contained with the program.

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. Use named parameters

Command parameters can also be entered by their names, so that you don’t have to watch their order and you don’t have to spell out all NULLs and empty lists.

For example, let’s say you want to change the notify email of a contact. Using positional parameters, you would have to enter:

> update_contact CID01 (() NULL NULL NULL NULL () NULL () notify@joe.name)

With named parameters, you can enter just this instead:

> update_contact CID01 --chg.notify_email=notify@joe.name

Use command help to find out how the composite parameters are structured, e.g.:

REG-FRED-A@epp.nic.cz> help update_nsset
...

OPTIONS:
  id (required)            NSSET ID
  add                      Add values
    dns                    List of DNS (list with max 9 items)
      name (required)      Name server
      addr                 Server address (unbounded list)
    tech                   Technical contact ID (unbounded list)
  rem                      Remove values
    name                   Name server (list with max 9 items)
    tech                   Technical contact ID (unbounded list)
  auth_info                Password required by server to authorize the transfer
  reportlevel              Report range level (0 - 10; higher = more detailed)
  cltrid                   Client transaction ID
...

If the parameter is indented, you must chain it with parent structures using dots, e.g. to add a DNS host name, you will need --add.dns.name:

> update_nsset ID01 --add.dns.name=ns2.domain.cz --add.dns.addr=217.31.207.130 --rem.name=(ns.2domain.cz)

Tip

Recommended for small modifications of one or two object attributes which would have to be entered at the end of a long parameter list.

6.14.3. Use interactive mode

The interactive mode can be used as a “composer” for complex commands.

To enter parameters of a command interactively, prefix the command with an exclamation mark ! <command> (e.g. ! update_contact) and don’t append any parameters yet. After you press Enter, you are prompted for the first paramater, then for the second, and so on.

Example
REG-FRED-A@epp.nic.cz> !update_domain
Interactive input mode started. Press Ctrl+C to abort or Ctrl+D to finish command.
Domain name [required]: mydomain.cz
Add administrative contact ID[1/oo] [optional]: CID02
Add administrative contact ID[2/oo] [optional]:
Remove administrative contact ID[1/oo] [optional]:
Remove temporary contact ID[1/oo] [optional]:
Change values / NSSET ID [optional]: NID-SET
Change values / KEYSET ID [optional]:
Change values / Registrant ID [optional]:
Change values / Password required by server to authorize the transfer [optional]:
Validation expires at [optional]:
Include ENUM domain into ENUM dictionary (y,n) [optional]:
Client transaction ID [optional]:

Interactive input completed. [Press Enter]

Tip

Recommended for big or complicated object modifications.

6.14.4. Confirm commands before sending

Before a command is sent to the server, the CLI client may request a special confirmation, just to give you one more chance to double-check that you’re really requesting what you mean.

When enabled, the CLI client will prompt for confirmation as follows:

Command to issue:
update_domain mydomain.cz CID02 () () (NID-SET)
Do you really want to send this command to the server? (y/N): y

To enable confirmation, type confirm on. To disable it, type confirm off.

6.14.5. View raw EPP messages

The CLI client allows you to read the XML-formatted communication. You can either increase the verbosity to level 3 with verbose 3 and then you will see the XML messages for requests and replies each time.

Or if you need to see the XML only occasionally, you may use raw-command to display the last composed request, or raw-answer to display the last received reply.