++ed by:
ALEXBYK

1 PAUSE user
1 non-PAUSE user.

Patrick Mevzek

NAME

epp_client_se.pl - A command line client program using Net::DRI towards the .SE EPP registry.

DESCRIPTION

The client supports creation and maintainance of host, contact and domain objects for .SE. It supports transfer operations, as well as poll operation for the message queue.

It was developed for testing of the .SE extensions to Net::DRI, but can probably be used by users who are comfortable with a simple command line interfaces.

SYNOPSIS

Command line

perl epp_client_se.pl [Connect arguments] [Command arguments]

Arguments

Mandatory connect arguments
 -C: Client ID, your EPP registrar account name, typical regxxx,
     where xxx is a number
 -W: Account password, your EPP account password
 -S: Server name, the registry server
 -P: EPP server port
 -F: Path to pem certificate client certificate
 -w: Password for the pem file

As of version v3 of the .SE EPP server client certificate is mandatory.

Optional connect arguments
 -f: Log file. The Net::DRI raw XML exchange will be dumped to this file
 -L: Use SSL connection
Command arguments

The command argument specify the EPP operation to perform:

 -o: EPP object.
     One of contact, host, domain, message
 -c: EPP command.
     One of hello, create, update, info, delete, transfer, count,
     waiting, retrieve
 -p: EPP parameter argument string, in a format that can be eval'ed into
     a hash, se parameter string examples below.

About each EPP command sequence

Each command will be performed as follows:

 - Socket connect, session initiation, a greeting is returned
 - an EPP login, which will succeed if the connect arguments are correct,
   otherwise fail,
   a greeting is returned if login is OK
 - an EPP command, according to the specified command arguments
 - an EPP logout
 - Session termination

A simple connect and greeting test

Basic connect to an EPP server should give you a greeting back if successful. A simple connect to an EPP server and port:

Encrypted with SSL:

   openssl s_client -host <EPP server> -port <EPP port> -cert <Path to pem file> -key <Path to pem file>

About logging and filtering of the log output

Logging is useful for debugging purposes,

A client side log can be activated by -f option, like:

  '-f xx.log'

Tail on the log-file in a separate window is nice then. Even nicer is to filter the tail through the supplied xmlfilter.pl utility, which will wrap the raw XML to a pretty-printed dump.

The filters '-s' option will skip all the login/logout and greetings which otherwise will dominate the outpot.

  'tail -f xx.log | ./xmlfilter.pl -s'

About authInfo

Auth-info (pw) can be set and updated only for domain objects, and is needed only for a transfer.

EPP commands and arguments

Hello command

Hello

-c hello -o host -p "%p=()"

A greeting shall be returned.

Contact object commands

Contact create

A .SE contact can be one of two types, person, or organization. For each contact created, the type must be specified via the mandatory type extension.

1 Organization contact

-o contact -c create -p "%p=(id=>'testse0810-0001', name=>'Anders ANdersson', org=>'Exempel AB', street=>['Box 42','Exempelfatan 42'], city=>'Stockholm', pc=>'12345', cc=>'SE', voice=>'+46.12345678', fax=>'+46.12345679', email=>'test@test.se', auth=>{pw=>''}, orgno=>'[SE]551234-5678', vatno=>'SE551234567801', disclose=>{voice=>0, email=>0})"

3 Person contact

-o contact -c create -p "%p=(id=>'testse0811-0002', name=>'Anders Andersson', street=>['Exempelgatan 42'], city=>'Stockholm', pc=>'12345', cc=>'SE', voice=>'+46.12345678', fax=>'+46.12345679', email=>'test@test.se', auth=>{pw=>''}, orgno=>'[SE]640823-3234')"

Contact update

In this example, a role contact update is shown.

Contact update

-o contact -c update -p "%p=(srid=>'testse0811-0002', street=>['Exempelgatan 24'], city=>'Stockholm', pc=>'12354', fax=>'+46.12345679', email=>'test@test.se')"

Contact info

The 'srid' returned on a create is the same as the id when creating it. Lets do an info on this handle.

Info on an contact handle

-o contact -c info -p "%p=(srid=>'testse0811-0002')"

Contact check

Check on an contact handle

-o contact -c check -p "%p=(srid=>'testse0811-0002')"

Contact delete

Delete on an contact handle

-o contact -c delete -p "%p=(srid=>'testse0811-0002')"

Host object commands

Host create

1 Create an external name server

An external name server is a non .SE name server.

External name servers must be registered without any IP-addresses.

-o host -c create -p "%p=(name=>'ns1.example.com')"

2 A .SE name server can have up to 5 ipv4-addresses and up to 5 ipv6-addresses.

-o host -c create -p "%p=(name=>'ns1.test.se', v4=>'123.234.123.12')"

3 Multiple ip-addresses, pass them as an array

-o host -c create -p "%p=(name=>'ns2.test.se', v4=>['123.234.123.12','129.123.23.23'])"

4 A .SE name server with ipv6 address as well

-o host -c create -p "%p=(name=>'ns3.test.se', v4=>['123.234.123.12','129.123.23.23'], v6=>['2001:700:1:0:215:f2ff:fe3e:fe65'])"

Host info

1 Info on a sponsored host object

-o host -c info -p "%p=(name=>'ns1.test.se')"

2 info on a host object sponsored (owned) by another registrar

It is possible to query hosts sponsored by other registrars.

-o host -c info -p "%p=(name=>'ns2.test2.se')"

Host check

Check to see whether a host name is available or registered

-o host -c check -p "%p=(name=>'ns1.test.se')"

Host delete

Delete a host

-o host -c delete -p "%p=(name=>'ns1.test.se')"

Host update

1 First create a host with no ip-addressest.

-o host -c create -p "%p=(name=>'ns4.test.se')"

2 Do an info to verify

-o host -c info -p "%p=(name=>'ns4.test.se')"

3 Now, change/update it
 - 1 new ipv4-addresses are added

-o host -c update -p "%p=(name=>'ns4.test.se', ipset=>{add=>{v4=>['123.234.123.100']}})"

4 Do an info to verify

-o host -c info -p "%p=(name=>'ns4.test.se')"

5 Now, change/update it again
 - 1 new ipv4-address are added
 - 1 old ipv4-address is removed

-o host -c update -p "%p=(name=>'ns4.test.se', ipset=>{add=>{v4=>['123.234.123.101']}, del=>{v4=>['123.234.123.100']}})"

4 Do an info to verify

-o host -c info -p "%p=(name=>'ns4.test.se')"

5 Now, change/update it again
 - 1 new ipv6-address are added

-o host -c update -p "%p=(name=>'ns3.yask.se', ipset=>{add=>{v6=>['2001:698:a:e:208:2ff:fe15:b2e8']}})"

Domain object commands

Domain check

1 Check to see whether a domain name is available or registered

-o domain -c check -p "%p=(name=>'test.se')"

Domain info

1 Do an info on an existing domain

-o domain -c info -p "%p=(name=>'test.se')"

Domain create

Notes
  • on the domain create methods in Net::DRI

    A lot of domain create methods are offered by Net::DRI.

    The client uses one specific create method, namely the domain_create() with pure_create=1

    • domain_create() with pure_create=1

      This method assumes that the contacts handles and the nameservers listed are ALREADY created in the registry, and this is closest to .SE's datamodel. Hence, the client uses this method.

    • domain_create() without pure_create or with pure_create=0

      This is another method which is a very powerful Net::DRI method.

      This method will do the same as domain_create() with pure_create=1, but will also accept and handle full contacts and nameserver objects as parameters, meaning that it will check and create various objects as an integral part of the command.

      Support for this variant is not added to the client.

  • on the duration syntax

    The duration parameter must specify one year to be accepted in create, due to the period definition in lib/Net/DRI/DRD/SE.pm

    Duration syntax: 'duration=>{years=>1}' or 'duration=>{months=>12}'

1 Create a normal domain without nameservers

Create a single domain with a a registrant, a contact set with one type each, and and no name servers:

-o domain -c create -p "%p=(name=>'test.se', pw=>'', registrant=>'testse0810-0001', coset=>{tech=>'testse0810-0002', admin=>'testse0810-0002'}, duration=>{years=>1})"

2 Create a normal domain with nameservers

Create a single domain with a a registrant, a contact set with one type each, and and two name servers:

-o domain -c create -p "%p=(name=>'test2.se', pw=>'', registrant=>'testse0810-0001', coset=>{tech=>'testse0810-0002', admin=>'testse0810-0002'}, duration=>{years=>1}, nsset=>['ns1.test.se', 'ns2.test.se'])"

3 Create an IDN domain

Create a single IDN-domain with a duration of 12 months, a registrant, a contact set with one type each, and no name servers.

IDN domains are converted to the ACE-form (xn--...) by the client, and the ACE-form is passed as the domain name to the registry.

-o domain -c create -p "%p=(name=>'räksmörgås.se', pw=>'', registrant=>'testse0810-0001', coset=>{tech=>'testse0810-0002', admin=>'testse0810-0002'}, duration=>{years=>1})"

4 Create a domain with Secure DNS keys

Create a single domain with a a registrant, a contact set with one type each, and and two name servers and one Secure DNS Key:

-o domain -c create -p "%p=(name=>'test3.se', pw=>'', registrant=>'testse0810-0001', coset=>{tech=>'testse0810-0002', admin=>'testse0810-0002'}, duration=>{years=>1}, nsset=>['ns1.test.se', 'ns2.test.se'], secdns=>[{keyTag=>'12345',alg=>3,digestType=>2,digest=>'49FD46E6C4B45C55D4AC'}])"

Domain delete

Delete domain is not suported by .SE.

Domain update

The domain name cannot be changed, otherwise all parameters may be changed.

1 Update (change) some domain attributes
 - set authInfo to 'abc'
 - add and del on all the multiple objects, coset and nsset, which may be
   arrays or scalars
 - delete all secude DNS keys

-o domain -c update -p "%p=(name=>'test.se', pw=>'abc', coset=>{add=>{tech=>['testse0810-0001'], admin=>['testse0810-0001']}, del=>{tech=>['testse0810-0002'], admin=>['testse0810-0002']}}, nsset=>{add=>['ns3.yask.se'], del=>'ns1.test.se'}, secdns=>{del=>[{keyTag=>'0'}]})"

2 Update of status flags

Update is the only command where the status flags can be set/changed. .SE only handles clientHold. The name is not intuative so to put the clientHold flag on, ie not to publish the domain - use the add command to set that the domain should NOT be published and request the domain to be published again by deleteing the status flag.

The flag values to use by the DRI user is the following (from Status.pm):

  my %s=('delete'   => 'clientDeleteProhibited',
         'renew'    => 'clientRenewProhibited',
         'update'   => 'clientUpdateProhibited',
         'transfer' => 'clientTransferProhibited',
         'publish'  => 'clientHold');

Example update to set a domain to NOT be published:

-o domain -c update -p "%p=(name=>'test.se', status=>{add=>['publish']})"

Example update to set a domain to be published:

-o domain -c update -p "%p=(name=>'test.se', status=>{del=>['publish']})"

DNS Secure

.SE suports the DNS secure extensions secDNS. The epp_client_se.pl can get/set/remove the keys for DNSsec. One extensions that .SE has added is that you can delete all keys by just sending a delete with keyTag 0. This will delete all keys.

1 Add a DNSsec key

Add a DNSsec key to a domain.

-o domain -c update -p "%p=(name=>'test.se', secdns=>{add=>[{keyTag=>'12346', alg=>3, digestType=>1, digest=>'49FD46E6C4B45C55D4DD'}]})"

2 Delete a DNSsec key

Delete a DNSsec key from a domain.

-o domain -c update -p "%p=(name=>'yask04.se', secdns=>{del=>[{keyTag=>'12345'}]})"

clientRelease

.SE has one extensions for clientDelete. is you set this it will remove the domain before its expiration date.

1 Set the clientDelete flag

- Update the domain and set the clientDelete flag to forece the domain to be removed

-o domain -c update -p "%p=(name=>'test.se', clientDelete=>1)"

2 Unset the clientDelete flag

- Update the domain and remove the clientDelete flag to not have the domain be removed

-o domain -c update -p "%p=(name=>'test.se', clientDelete=>0)"

Domain renew

1 Renew with parameters.

Duration has to be 12 months or 1 year for .SE. DRI requires curexpiry, which should match the expiry date of the domain being renewed:

-o domain -c renew -p "%p=(name=>'test.se', curexpiry=>'2008-12-11', duration=>{months=>12})"

Domain transfer commands

Domain transfers are used if the registrant wants to change his registrar. He must then ask the old registrar for the password and the old one has to set that. The the new registrars can do the transfer.

Domain transfer request

When the registrant knows the authInfo, he passes it to the new registrar, who can do a transfer containing the authInfo, and the transfer will be performed.

- The transfer must be authorized by the token.

-o domain -c transfer -p "%p=(name=>'test.se', pw=>'abc')"

If the password is correct, the domain should be transferred.

Polling the message queue

Poll messages

1 message_waiting()

This method performs a poll request and returns true if one or more messages are waiting in the queue.

-o message -c waiting -p "%p=()"

2 message_count()

This method performs a poll request and returns the 'msgQ count' value from the response, if any.

-o message -c count -p "%p=()"

3 message_retrieve()

This method performs a poll request, and with get_info() you can grab all the message details.

-o message -c retrieve -p "%p=()"

4 message_delete()

This is the poll ack message, which will remove message (with id=12) from the server message queue.

-o message -c delete -p "%p=(id=>12)"

COPYRIGHT

Copyright (c) 2008,2011 .SE, <http://www.iis.se<gt>, Jan Saell <jan@yask.se> All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

See the LICENSE file that comes with this distribution for more details.

AUTHOR

Jan Saell, <jan@yask.se>

5 POD Errors

The following errors were encountered while parsing the POD:

Around line 1672:

Non-ASCII character seen before =encoding in 'E<34>%p=(name=>'räksmörgås.se','. Assuming UTF-8

Around line 1737:

'=item' outside of any '=over'

Around line 1751:

You forgot a '=back' before '=head3'

You forgot a '=back' before '=head3'

Around line 1774:

'=item' outside of any '=over'

Around line 1782:

You forgot a '=back' before '=head2'