Manuál pro FredClient konzoli a knihovnu fred

FredClient

Vzniklo: 11. 7.2006; Revize: 18. 8.2006; 1. 9.2006; 4. 9.2006; 14. 9.2006; 27. 9.2006; 1.11.2006; 7.11.2006; 17.1.2007; 24.11.2017;


Obsah

Co je FredClient:
1. Licence
2. Požadavky na systém a instalace
3. Popis jednotlivých programů, parametry a konfigurační soubor
Parametry při spuštění (OPTIONS)
Konfigurační soubor
4. Program fred_client
Zobrazení helpu
EPP příkazy
Syntaxe zadávání paramerů příkazu
Společný parametr cltrid (Client transaction ID)
Žádná hodnota / Prázdná hodnota
Žádná hodnota: NULL
Prázdná hodnota: '', ""
Interaktivní mód vkládání parametrů
Příkazy relace (session)
5. Skripty fred_create.py a fred_sender.py
6. Integrace klienta do PHP kódu
7. Grafická nadstavba v Qt4.
8. Knihovna fred a popis API
Online dokumentace:
Příklady práce s knihovnou
9. Verze klienta 2.9 - Korespondenční adresa v kontaktu
Příkaz create_contact
API create_contact
Příkaz update_contact
API update_contact
Příkaz info_contact
API info_contact

Co je FredClient:

FredClient je sada scriptů v jazyce Python postavených na fred knihovně a určených ke komunikaci s EPP serverem.

Sada obsahuje EPP konzoli a skripty určené pro použití v shellu.

Kapitola 1. Licence

Licence je v souboru fred/LICENSE.

Kapitola 2. Požadavky na systém a instalace

Pokyny k instalaci jsou v souboru INSTALL.

Kapitola 3. Popis jednotlivých programů, parametry a konfigurační soubor

Dostupné skripty jsou následující:

fred_client - EPP konzole, komunikuje s EPP serverem
fred_create.py - Vytvoří zdrojový EPP XML příkaz
fred_sender.py - Odešle soubor na EPP server

Parametry při spuštění (OPTIONS)

Skripty se dají spouštět s parametry. Jaké parametry lze použít zjistíte zadáním parametru --help nebo -?:

    $ fred_client --help
    $ fred_client -?

Použití: fred_client [parametry...]

Hlavní parametry:
  -?, --help       Zobrazit tuto nápovědu a skončit
  -V, --version    Zobrazit verzi programu a skončit
  -l LANGUAGE, --lang=LANGUAGE
                   Nastavení jazykové verze
  -v LEVEL, --verbose=LEVEL
                   Nastavení módu výpisu
                   0 - zobrazit jen XML odpověď od EPP serveru
                   1 - normální výstup
                   2 - zobrazit více detailů
                   3 - zobrazit více detailů a XML zdroje
  -x, --no_validate
                   Deaktivovat XML validaci na straně klienta

Parametry pro spojení:
  -f CONFIG, --config=CONFIG
                   Načtení konfigurace ze souboru
  -s SESSION, --session=SESSION
                   Použít session z konfiguračního souboru

  -h HOSTNAME, --host=HOSTNAME
                   Fred server host
  -p PORT, --port=PORT\n"
                   Server port (default: 700)
  -u USERNAME, --user=USERNAME
                   Přihlásit se jako uživatel
  -w PASSWORD, --password=PASSWORD
                   Přihlásit se s heslem
  -c CERTIFICATE --cert=CERTIFICATE
                   Pro spojení použít SSL certifikát
  -k PRIVATEKEY --privkey=PRIVATEKEY
                   Pro spojení použít SSL privátní klíč

  -n, --nologin
                   Deaktivovat automatické spojení se serverem po startu
  -d COMMAND, --command=COMMAND
                   Odeslat příkaz na server a skončit
  -o OUTPUT_TYPE, --output=OUTPUT_TYPE
                   Zobrazit výstup jako text (default), html, xml, php (Pozor! Jen pro testování!)
  -q,  --qt
                   Spustit klienta v Qt4 GUI (Pozor! Jen pro testování!)

Speciální parametry, které se v helpu nezobrazují:
   -r, --cltrid    --cltrid=mycID_%04d
                   Definice vlastního clTrID s přidáním čísla příkazu

Konfigurační soubor

Konfigurační soubor slouží k uložení různých nastavení klienta tak, aby při každém spuštění byly hodnoty takové, jaké je potřebujete mít. Například se zde definují jména a umístění souborů s certifikáty, adresa serveru, na který se má klient připojit, verze schemat a další nastavení.

Konfigurační soubor se implicitně hledá nejdříve v home uživatele (~/.fred_client.conf), který skript spustil. Pokud tam není nalezen, hledá se v adresáři etc/fred (/etc/fred/fred_client.conf). Na POSIX systémech je to /etc/fred, v MS Windows to je v adresáři nastaveném v proměnné $ALLUSERSPROFILE. Přepínačem --config=filepath (nebo -f filepath) je možné konfigurační soubor načíst z libovolného souboru.

Pro založení nového konfiguračního souboru je k dispozici příklad fred_client.conf.sample. Tento příklad můžete použít jako základ pro váš konfigurační soubor. V příkladu jsou pro definici plné cesty k souborům použity proměnné, které slouží jako hodnoty, které lze vložit do jiných položek v dané sekci.

Proměnné se zapisují ve tvaru %(název proměnné)s. Například:

   %(dir)s

V tomto příkladu je definována proměnná jménem dir. Ta musí být v dané sekci také definována:

   dir = /home/username/certificates

Pak se takovýto zápis

   %(dir)s/private_key.pem

po načtení konfiguračního souboru rozvine na:

   /home/username/certificates/private_key.pem

Tato metoda umožňuje mít plnou adresu k souborům na jednom místě a doplňovat k ní jen jméno potřebného souboru. Pokud se vám ale tento způsob zdá příliš složitý, tak proměnné používat nemusíte a v příslušných položkách zadejte místo proměnné vždy adresu celou.

V příkladu konfiguračního souboru se takto musí nastavit dvě cesty: Jedna k certifikátům (pro dva soubory) a druhá ke schematům.

V konfiguračním souboru se nachází sekce connect, kde jsou uloženy cesty k certifikátům a informace o serveru. Také tam jsou další hodnoty například username a password. Pokud se tyto hodnoty v konfiguračním souboru nacházejí, tak je příkaz login použije jako parametry příkazu, které mu nebyly zadány.

Sekcí connect může být v konfiguračním souboru více. Která z nich se při startu použije se nastaví pomocí parametru -s --session. Například si vytvoříte sekci [connect_myeppserver] tu pak aktivujete:

    $ fred_client --session=myeppserver     (nebo -s myeppserver)

    [connect_myeppserver]
    dir=/test/certificates
    host = myeppserver.cz
    ssl_cert = %(dir)s/cert.pem
    ssl_key  = %(dir)s/key.pem
    username = myusername
    password = mypassword

V sekci session jsou tato nastavení:

  • poll_autoack = on/off

    Při on se po odeslání příkazu poll req automaticky pošle i poll ack.

  • confirm_send_commands = on/off

    Všechny editační příkazy (create, delete, update, ...) vyžadují v konzoli pozvrzení před odesláním na server. Tuto funkci lze vypnout/zapnout.

  • validate = on/off

    K validaci se používá externí program xmllint. Validaci lze vypnout a dokumnety se tak na server posílají bez ověření platnosti formátu.

  • schema = /installdir/schemas/all-1.0.xsd

    Soubor, ve kterém má validátor hledat schemata, podle kterých dokumenty ověřuje.

  • colors = on/off

    Výstup na terminál může být barevný, pokud to terminál umožňuje.

  • escaped_input = on/off

    Pokud je vstup escapovaný (<example&test>), nastavte tuto hodnotu na on.

  • verbose = 1/2/3

    Úroveň výpisu 1 - stručná, 2 - celá, 3 - celá + XML zdrojové dokumenty.

  • lang = en/cs

    Jazyková verze. Pokud není zadána žádná hodnota, tak se bere nastavení z proměnné LANG prostředí OS. Dostupné jsou zatím jen angličtina a čeština. Jazykovou verzi můžete také nastavit i pomocí parametru při spuštění skriptu.

  • null_value = NULL

    Nastavení zástupce pro hodnotu nic (Nil), která vyjadřuje žádnou hodnotu. Defaultně je nastaveno NULL. Tuto hodnotu používáme, když chceme přeskočit některý z parametrů příkazu. Zadání NULL znamená, že jsme nezadali žádnou hodnotu na rozdíl od '' nebo "", kdy jsme zadali hodnotu nulové délky.

    Formát hodnoty NULL: Zástupce může být libovolný, ale nesmí obsahovat spojovník (-), mezery a kulaté závorky.

    Více se o této hodnotě dozvíte v části Žádná hodnota / Prázdná hodnota

  • skip_value = SKIP

    Speciální hodnota umožňující vynechat XML element v EPP dokumentu. Zavedeno pro testovací účely. Aktuálně lze tuto hodnotu použít pouze na element <clTRID>. Výchozí hodnota je nastavena na SKIP.

    Výchozí EPP dokument:

            REG-FRED_A@localhost> credit_info
    
            <?xml version="1.0"?>
            <epp>
                <fred:creditInfo/>
                <fred:clTRID>zhte004#11-08-12at09:00:27</fred:clTRID>
            </epp>
            

    Při použití hodnoty SKIP:

            REG-FRED_A@localhost> credit_info SKIP
    
            <?xml version="1.0"?>
            <epp>
                <fred:creditInfo/>
            </epp>
            

    Formát hodnoty SKIP: Zástupce může být libovolný, ale nesmí obsahovat spojovník (-), mezery a kulaté závorky.

    Popis elementu clTRID: Společný parametr cltrid (Client transaction ID)

  • cltrid = myid%04d

    Vlastní hodnota cltrID - Client client transaction ID. Symbol %d je nahrazen číslem příkazu. Hodnota mezi % a d zarovnává číslo na čtyři číslice (doplní se nula).

  • reconnect = no

    V případě, že se během komunikace spojení přeruší, se klient pokusí spojení znovu navázat. Tímto zápisem se funkce automatického navázání spojení vypne.

V sekci connect jsou tato nastavení:

  • dir = cesta k adresáři s certifikáty

    Tato hodnota nahrazuje zástupce %(dir)s ve všech položkách dané sekce. V našem případě je v ní uložena cesta k certifikátům.

  • ssl_cert = jméno certifikátu

    Název souboru s certifikátem. Před ním je uveden zástupce adresáře dir, který je nahrazen hodnotou definovanou v této sekci.

  • ssl_key = jméno privátního klíče

    Název souboru s privátním klíčem. Před ním je uveden zástupce adresáře dir, který je nahrazen hodnotou definovanou v této sekci.

  • host = jméno_serveru

    Název serveru, ke kterému se má klient připojit.

  • port = číslo_portu

    Číslo portu serveru. Pokud není zadán, použije se default 700.

  • username = uživatelské jméno

    Uživatelské jméno potřebné k přihlášení do systému.

  • password = heslo

    Heslo potřebné k přihlášení do systému.

  • timeout = čas čekání na odpověď ve vteřinách

    Nastavení timeoutu říká socketu jak dlouho má čekat na odpověď ze serveru. Pokud do uvedené doby odpověď nepřijde, je spojení považováno za přerušené. Defaultně je nastaveno 10 vteřin. Pozor! V MS Windows se může u timeoutu vyskytnout bug, který způsobí, že se spojení nenaváže. V takovém případě nastavte timeout na nulu: timeout = 0

  • socket = IPv4/IPv6

    Nastavení typu soketu na IPv4 nebo IPv6. Pokud není tato hodnota zadána, tak se použije typ soketu, který nabízí server.

  • schema_version_[name] = 1.0

    Individuální nastavení verze schemat pro objekty contact, nsset, domain, enum, fred a epp.

  • nologin = on/off

    Klient se ihned po spuštění pokusí spojit se serverem a zalogovat se. Tuto funkci je možné vypnout nastavením nologin = off.

Kapitola 4. Program fred_client

fred_client je konzole, která komunikuje s EPP serverem. Konzoli spustíte příkazem:

    $ fred_client

Pokud máte v konfiguračním souboru správně nadefinovánu cestu k certifikátům a uložené login a heslo, tak můžete jednoduše zadat login a tím se spojíte s EPP serverem. Konzole se ukončuje příkazem "quit" nebo jen krátce "q".

Zobrazení helpu

Jaké příkazy máte k dispozici zjistíte zadáním příkazu "help" (nebo h, ?).

    FredClient verze n.n.n Zadejte "help", "license" nebo "credits" pro zobrazení více informací.
    > help

Help vypíše dvě části nápovědy:

1) Dostupné EPP příkazy
2) Příkazy relace (session) pro nastavení vnitřních proměnných konzole

EPP příkazy

Všechny EPP příkazy (kromě hello), mají své parametry. Jaké parametry to jsou a v jakém pořadí se zadávají naleznete v helpu daného příkazu. Help příkazu si zobrazíte zadáním "help příkaz" nebo zkráceně "h příkaz" nebo také "? příkaz". Například když chcete znát parametry příkazu login, zadáte: "help login".

Příklad:

> help login
> ?login

Vypíšou se podrobnosti o jednotlivých parametrech daného příkazu. Samotný příkaz zadáte tak, že napíšete název příkazu a za ním jeho parametry:

> login username password

Syntaxe zadávání paramerů příkazu

Na zadání parametrů EPP příkazu jsou kladeny zvláštní požadavky, kvůli kterým byla zavedena speciální syntaxe. Parametry, na které není nutné použít tuto syntaxi nazýváme jednoduché hodnoty. To jsou hodnoty, ve kterých se nevyskytuje mezera a ani to nejsou seznamy. Například:

username password

Parametry jsou odděleny mezerou nebo mohou být odděleny i více mezerami.

Syntaxe obsahuje tyto prvky:

  • ' " uvozovky (jednoduché nebo dvojité)
  • ( ) závorky
  • - spojovník (divis) a = (rovná se)
  • . tečka
  • [] hranaté závorky

Popis jednotlivých prvků:

  • Uvozovky ' " řeší požadavek na zadání hodnoty, která obsahuje mezery nebo čárku "," nebo znak = (rovná se). Taková hodnota se uzavře do uvozovek. Je jedno jestli jednoduchých nebo dvojitých. Uvnitř uvozovek se pak mohou nacházet libovolné znaky včetně závorek, spojovníku a dalších uvozovek. Pokud to jsou ale uvozovky shodné s těmi, které jsou použity na uzavření textu, tak se před ně musí dát zpětné lomítko \ (backslash):

    "text \"uvozovky\" text"

    Jinak mohou být bez něj:

    "text s 'jednoduchými' uvozovkami"

    nebo

    'text s "dvojtými" uvozovkami'

    nebo

    'text s rovnítkem = '
  • ( ) závorky se používají pro parametr, který může obsahovat seznam hodnot. Například parametr street v příkazu create_contact může být seznam až o třech položkách. Když chcete zadat jen jednu ulici, stačí zadat pouze:

    ulice1

    Program ví, že parametr má být seznam a tak tuto hodnotu vyhodnotí jako seznam s jednou položkou. Nemusíte tedy zadávat: (ulice1).

    Když chcete zadat více ulic, tak napíšete:

    (ulice1 ulice2 ulice3)

    Lze samozřejmě kombinovat se syntaxí s uvozovkami:

    ("ulice 1" "ulice 2" "ulice 3")

    Položky seznamu je možné kromě mezer oddělit i čárkou:

    (ulice1,ulice2,ulice3)
    (ulice1, ulice2, ulice3)
    ("ulice 1", "ulice 2", "ulice 3")
    

    Některé příkazy mají parametr typu seznam, který dále obsahuje další seznamy. Takový seznam také nazýváme jmenný prostor, protože obsahuje další položky, které lze definovat jménem. Ty mohou být jednoduché nebo to mohou být další seznamy. Je potřeba zadávat závorky tak, aby zápis odpovídal struktuře parametru. Strukturu zanořených seznamů zjistíte také z helpu příkazu. Každá úroveň je odsazena.

    Například příkaz update_contact obsahuje seznam chg, který dále obsahuje senzam postal_info, který obsahuje hodnoty name, org a ještě další seznam addr. Seznam addr obsahuje položky city, cc, street, atd. Takový seznam se zapíše asi takto:

    ((name, org, (street, city, pc, cc, sp)) voice, fax, ...)
    

    Porovnejte s příklady, které jsou uvedeny v helpu u každého příkazu.

  • - spojovník (divis) a = (rovná se). Parametry se musí zadávat ve stanoveném pořadí. Nejdříve se vždy zadávají povinné položky a pak nepovinné. Zadávání příkazu tedy můžete ukončit za posledním povinným parametrem. Pokud ale chcete zadat ještě nějaký nepovinný, který se shodou okolností nachází někde vzadu nebo na konci řady parametrů, museli byste zapsat i ty nepovinné parametry, které se nacházejí před ním, aby se zachovalo správné pořadí. To však není nutné pokud hodnotu zadáte pomocí pojmenovaného parametru.

    Pojmenovaný parametr je způsob, jak vložit hodnotu parametru mimo pořadí. Princip je ten, že se uvede jméno parametru, kterému hodnota patří. Toto jméno zjistíte z helpu příkazu. Pak jméno a hodnotu zadáte ve tvaru

    -jmeno hodnota
    

    Podle spojovníku na začátku slova parser pozná, že se jedná o jméno parametru. Za ním pak následuje hodnota. Tato syntaxe je volná v tom směru, že je možné zadat spojovníků více a mezi jménem a hodnotou může být rovnítko. Pak takový zápis vypadá takto:

    --jmeno = hodnota
    

    Hodnoty, které jsou definovány pomocí pojmenovaného parametru, stojí MIMO pořadí ostatních parametrů. To znamená, že mohou být uvedeny na kterékoliv pozici mezi parametry a hodnoty za nimi mají stále stejnou pozici, jako kdyby tam nic uvedeno nebylo (viz následující příklad).

    Například když si vypíšete help pro příkaz create_contact, tak předposlední parametr se jmenuje notify_email. Kromě povinných chcete zadat již pouze tuto hodnotu (povinných je prvních pět parametrů: ID, jméno, email, město a kód země). Pak zadáte:

    create_contact CID-ID jméno email@email město CZ --notify_email = muj@email.net
    

    Na pozici pojmenovaného parametru nezáleží:

    create_contact --notify_email = muj@email.net CID-ID jméno email@email město CZ
    

  • Tečka. Složitější případ nastane, když chcete definovat hodnotu, která se nachází v nějakém zanořeném seznamu, tj. seznamu v jiném seznamu. Pak se jednotlivá jména seznamů spojují pomocí tečky. Například:

    create_contact CID-ID jméno email@email město CZ --disclose.flag = y
    

  • [] hranaté závorky. V případě, že hodnota je položkou v seznamu, je možné zadat i index seznamu. Ten se zadává pomocí čísla v hranatých závorkách:

    create_nsset nssid:nsset1 ((ns1.domain.cz (217.31.207.130 217.31.207.129))) --dns.addr[1] = tato_hodnota_prepise_druhou_adresu_217.31.207.129 cid:regid
    

Shrnutí:

Parametry zadávejte v pořadí, v jakém jsou vypsané v helpu.
Počet mezer mezi hodnotami může být libovolný.
Hodnoty s mezerami dejte do uvozovek.
Seznamy se definují pomocí závorek, položky seznamu můžou být odděleny čárkami.
Pokud je v seznamu jen jedna položka, nemusí se závorky zadávat.
Hodnoty mimo pořadí zadávejte pomocí pojmenovaného parametru.
Jména položek zanořených do více seznamů spojíte pomocí tečky.

Společný parametr cltrid (Client transaction ID)

Každý EPP příkaz, kromě příkazu hello, obsahuje tag <clTRID>. Ten je vždy jako poslední z parametrů a jmenuje se cltrid. Tato hodnota je identifikátor transakce. Ten si stanovuje klient a může být libovolný v rámci formátovacích pravidel definovaných ve schematech pro tuto hodnotu. Identifikátor je nepovinný a pokud není zadán, tak jej klient automaticky doplní.

Element <clTRID> lze potlačit speciální hodnotou SKIP.

Další možnost, jak zadat tento parametr je nadefinovat jej v konfiguračním souboru nebo při spuštění klienta v parametrech při spuštění (options).

Jednotlivé příkazy jsou v rámci relace číslovány. Pokud se v hodnotě cltrid vyskytne zástupce %d, je tento symbol nahrazen pořadovým číslem příkazu:

myCtrlID%d  - je zkonvertován na myCtrlID1, myCtrlID2, myCtrlID3, ...

Chcete-li aby pořadové číslo mělo vždy stejný počet číslic, je možné zadat:

myCtrlID%04d  - je zkonvertován na myCtrlID0001, myCtrlID0002, myCtrlID0003, ...

Žádná hodnota / Prázdná hodnota

Žádná hodnota: NULL

Výraz Žádná hodnota představuje hodnotu, kterou jste nezadali. Slouží nám k tomu, abychom mohli přeskakovat parametry, které nechceme zadávat. Je to alternativa k zadávání hodnot pomocí pojmenovaného parametru. Defaultě je zástupce žádné hodnoty nastaven na NULL.

Například, když v příkazu create_contact chcete kromě povinných parametrů uvést už jen telefonní číslo (parametr voice). Mezi posledním povinným parametrem pw a pořadovaným voice leží ještě další čtyři parametry: org, street, sp, cp. Místo nich zadáte "žádnou hodnotu" - pokud jste nenastavili jinak, tak NULL. Tím jste telefonní číslo umístili na správnou pozici v parametrech příkazu:

   create_contact CIDID01 'Jan Novak' info@mymail.cz 'Vinohradská 8' Praha 12000 CZ NULL NULL NULL mypassword +420.222745111

Uvedený příkaz nebude v XML struktuře vytvářet tagy pro hodnoty sp, mailing_addr, org:

    <contact:id>CID-ID01</contact:id>
        <contact:postalInfo>
            <contact:name>Jan Novak</contact:name>
            <contact:addr>
                <contact:street>Vinohradská 8</contact:street>
                <contact:city>Praha</contact:city>
                <contact:pc>12000</contact:pc>
                <contact:cc>CZ</contact:cc>
            </contact:addr>
        </contact:postalInfo>
    <contact:voice>+420.222745111</contact:voice>

V interaktivním módu zadávání parametrů zadáte žádnou hodnotu prostě tak, že jenom stisknete ENTER.

Definici žádné hodnoty lze v konzoli změnit příkazem null_value a také je možné si ji definovat v konfiguračním souboru.

Prázdná hodnota: '', ""

Výraz Prázdná hodnota představuje hodnotu, která je prázdná. Je to tedy text o nulové délce. Ten zapisujeme práznými uvozovkami '' nebo "". Tato hodnota nám slouží k tomu, abychom mohli zadávat hodnoty nulové délky. Rozdíl mezi práznou hodnotou a žádnou je v tom, že tato hodnota generuje tag v XML dokumentu. Protože je prázdná, tak daný XML tag bude také prázdný.

   create_contact CIDID01 'Jan Novak' info@mymail.cz 'Vinohradská 8' Praha 12000 CZ '' NULL '' mypassword +420.222745111

Příkaz vygeneruje XML, ve kterém budou u prázdných hodnot prázdné tagy (Organizace, Stát nebo kraj):

    <contact:id>CID-ID01</contact:id>
        <contact:postalInfo>
            <contact:name>Jan Novak</contact:name>
            <contact:org/>
            <contact:addr>
                <contact:street>Vinohradská 8</contact:street>
                <contact:city>Praha</contact:city>
                <contact:pc>12000</contact:pc>
                <contact:cc>CZ</contact:cc>
                <contact:sp/>
            </contact:addr>
        </contact:postalInfo>
    <contact:voice>+420.222745111</contact:voice>

V interaktivním módu zadávání parametru zadáme prázdnou hodnotu tak, že zapíšeme prázdné uvozovky '' nebo "".

Interaktivní mód vkládání parametrů

Interaktivní mód umožňuje zadávat hodnoty jednu za druhou, podle toho co prompt aktuálně požaduje. Tento způsob je vhodný zejména pokud nevíte přesně jak máte parametry zadat. Interaktivní mód se spouští pomocí vykřičníku, který se napíše před příkaz:

> !update_nsset

Konzole vždy vypíše jméno parametru a čeká na zadání hodnoty. Pokud hodnotu nechcete zadat, tak prostě stisknete enter a hodnota se přeskočí. Interaktivní mód můžete kdykoliv zrušit stisknutím kláves Ctrl+C (C jako Cancel). Po zadání všech povinných parametrů, kdy už nechcete zadávat další nepovinné hodnoty, lze interaktivní režim dokončit stiknutím kláves Ctrl+D (D jako Done nebo Dokončit).

V případě zrušení interaktivního módu se žádný příkaz nesestaví a nic se na server neposílá. V případě dokončení módu se sestaví příkaz a na konzoli se vypíše tak, jako byste jej zadali přímo bez interaktivního režimu. Pak se příkaz odešle na server. V případě, že se jedná o editační příkaz a je zapnutá funkce potvrzování (confirm), tak se příkaz musí před odesláním na server ještě potvrdit:

REG-LRR@epp-test.ccreg.nic.cz> !update_nsset
Start interaktivního módu. Mód zrušíte stisknutím Ctrl+C. Příkaz dokončíte kombinací Ctrl+D.
NSSET ID [povinný]: nssid:id01
Přidat hodnoty / Seznam DNS[1/9] / Jmenný server [povinný jen je-li tato část zadána]: ns1.dns.cz
Přidat hodnoty / Seznam DNS[1/9] / Adresa serveru[1/oo] [nepovinný]: 217.31.207.130
Přidat hodnoty / Seznam DNS[1/9] / Adresa serveru[2/oo] [nepovinný]: 217.31.207.131
Přidat hodnoty / Seznam DNS[1/9] / Adresa serveru[3/oo] [nepovinný]:
Přidat hodnoty / Seznam DNS[2/9] / Jmenný server [nepovinný]:
Přidat hodnoty / Technický kontakt ID[1/oo] [nepovinný]: cid:myid01
Přidat hodnoty / Technický kontakt ID[2/oo] [nepovinný]:
Přidat hodnoty / Stav[1/6] [nepovinný]:
Interaktivní mód ukončen. [stiskněte Enter]
Příkaz k odeslání:
update_nsset nssid:id01 (((ns1.dns.cz (217.31.207.130, 217.31.207.131))) cid:myid01)
Opravdu chcete odeslat tento poříkaz na server? (y/N): y
nssid:id01 aktualizováno.
REG-LRR@epp-test.ccreg.nic.cz>
    

Příkazy relace (session)

Konzole má svá vnitřní nastavení, která můžete změnit přímo z promptu. K tomu slouží příkazy, které nazýváme příkazy relace. Nejsou to EPP příkazy a neslouží ke komunikaci se serverem. Jsou určeny z nastavení vnitřních proměnných konzole a nebo k zobrazení již nastavených hodnot. Takto nastavené hodnoty se neukládají. Jsou platné jen po dobu relace - spuštění konzole. S ukončením aplikace zanikají. Pokud chcete tato nastavení mít trvalá, musíte je nastavit v konfiguračním souboru.

Hodnoty se nastavují tak, že se zadá příkaz relace a za ním hodnota, která se má přiřadit:

> poll_autoack on

Pokud příkaz zadáte bez parametrů, tak se pouze vypíše aktuální stav nastavení.

> poll_autoack
poll_autoack je ON

Seznam příkazů relace:

> poll_autoack [on/off]

Pokud je tento přepínač ON, tak se po odeslání příkazu "poll req" automaticky odesílá i "poll ack". Tuhle funkci asi nejvíce oceníte, když budete mít na serveru hodně zpráv. Příkaz "poll req" zprávu ze serveru pouze zobrazí, ale pak se zpráva musí ze serveru odstranint příkazem "poll ack ID-zprávy". Při automatickém poll-ack se bude odstraňování provádět automaticky po zobrazení zprávy.

> escaped_input [on/off]

Pokud je vstup escapovaný (&lt;example&amp;test&gt;), nastavte tuto hodnotu na on.

> confirm [on/off]

U EPP editačních příkazů, které nějak mění hodnoty na serveru (create, upadte, delete, transfer, renew), se před odesláním požaduje potvrzení k odeslání. Přepínačem "confirm OFF" lze toto potvrzování vypnout.

> credits

Příkaz credits zobrazí text s informacemi o klientovi.

> help [příkaz]

Příkaz help zadaný bez parametru zobrazí seznam dostupných příkazů. Pokud se zadá i parametr příkaz, tak se zobrazí detaily zadaného příkazu. Stejný význam jako "help" mají i příkazy "h" a "?".

> lang [kód]

Příkazem lang se přepíná jazyková verze klienta a serveru. Pokud jste ale již zalogováni, tak je nutné se odlogovat a znovu zalogovat. Důvod je ten, že typ jazykové verze se serveru sděluje pouze pomocí příkazu "login". To je také druhá možnost, jak přepnout na jinou jazykovou verzi: login usename password cs V této verzi klienta i serveru jsou dostupné jen dva jazyky: en - angličtina; cs - čeština.

> license

Příkaz license zobrazí text licence klienta.

> quit

Příkaz quit odpojí klienta od serveru a ukončí aplikaci. Synonyma 'q' a 'exit' mají stejnou funkci.

> validate [on/off]

Tímto přepínačem zapnete nebo vypnete proces validace XML dokumentu. Validace je v této verzi realizována přes externí program xmllint. Pokud není v systému přítomen, tak nastavení ON nemá žádný efekt. Validace ověřuje platnost XML dokumentu podle EPP schemat a to jak v odchozích, tak i příchozích zprávách. Pokud není dokument validní, tak jej konzole na server neodešle. Nevalidní dokument vznikne například tím, že zadáte hodnotu, která neodpovídá konkrétnímu schématu. Například příliš krátké heslo. Konzole v této verzi obsah hodnot nijak neověřuje, pouze zjišťuje jestli byly zadány nebo ne.

> verbose [úrověň]

Klient zobrazuje různé informace. Ty jsou rozděleny do úrovní detailů. První úroveň zobrazování (základní) je určena pro běžného uživatele a vypisuje nezbytné minimum informací, které jsou k práci nutné. Pro zvídavé uživatele je zacílena druhá úroveň, která vypisuje všechna dostupná hlášení, která se během komunikace vyskytla. Třetí úroveň zobrazuje ještě navíc XML zdrojové dokumenty, které si klient se serverem předává.

Úrovně výpisu detailů:
1 - stručná (default)
2 - všechno
3 - všechno a XML zdroje.

Úroveň výpisu lze nastavit i při spuštění příkazového řádku. Viz konfigurační soubor.

> fetch_from_info typ_příkazu [ne-do-příkazové-řádky]

Funkce fetch_from_info umožňuje vytvořit příkaz z hodnot, které byly načteny z jednoho z příkazů typu info v předchozím kroku. To je například užitečné, když chcete vytvořit nový záznam s velmi podobnými údaji, jaké jsou již v nějakém zzáznamu použity. Platné typy příkazů, které můžete pomocí fetch_from_info vytvořit jsou: create, update, delete.

Například, když chcete vytvořit create_contact, proveďte tyto tři kroky:

1. Načtěte hodnoty: info_contact CID-ID
2. Vytvořte příkaz: fetch_from_info create
3. Upravte příkaz jak potřebujete a pak jej odešlete na server.

Pokud váš terminál podporuje vkládání textu do příkazové řádky (Unix), bude vytvořený příkaz vložen přímo do něj. Chcete-li příkaz místo do příkazové řádky zobrazit jen na výstup, zadejte parametr noprompt (nebo jen n).

Pokud váš terminál vkládání do promptu nepodporuje (Windows), bude příkaz zobrazen normálně na výstupu a musíte si jej do příkazové řádky zkopírovat nebo přepsat.

Kapitola 5. Skripty fred_create.py a fred_sender.py

Skripty fred_create.py a fred_sender.py jsou určeny pro použití v shell batchi. fred_create.py přijímá parametry se standardního vstupu a vygeneruje XML EPP dokument na standardní výstup. Například:

    $ python fred_create.py info_domain nic.cz
    $ echo -en "check_domain nic.cz\ninfo_domain nic.cz" | ./fred_create.py
    $ cat file-with-commands.txt | ./fred_create.py

<?xml version='1.0' encoding....

Pokud nastane nějaká chyba, tak vrací XML s chybovým hlášením:

    $ python fred_create.py inxo_domain nic.cz

<?xml encoding='utf-8'?><errors>inxo_domain nic.cz: Neznámý příkaz!</errors>

fred_sender.py odesílá dokumenty na server. Skript se automaticky zaloguje, pak předá dokument, zobrazí odpověď a odloguje se a ukončí. Pro správné zalogovájní je nutné mít správně nastaven konfigurační soubor.

Skript může odesílat dokumenty dvěma způsoby:

1. dokumenty se uloží do souboru a skriptu se předají jména souborů. Skript je pak odesílá v uvedeném pořadí. Například:

    $ ./fred_create.py check_domain cosi.cz nic.cz > doc1.xml
    $ ./fred_create.py info_domain nic.cz > doc2.xml
    $ ./fred_sender.py doc1.xml doc2.xml

2. PIPE - Zřetězením příkazů create a sender. Například:

    $ ./fred_create.py check_domain cosi.cz nic.cz | ./fred_sender.py
    $ echo -en "check_domain nic.cz\ninfo_domain nic.cz" | ./fred_create.py | ./fred_sender.py

Kapitola 6. Integrace klienta do PHP kódu

Pozor! Rozšíření klienta o podporu PHP je v této verzi ve vývojovém a testovacím stádiu. Finální řešení se může od tohoto vývojového ještě lišit.

Součástí distribuce klienta je i ukázkový PHP skript, který demonstruje, jak lze klienta začlenit do PHP: doc/client_example.php. V příkladu je nutné správně nastavit cestu ke klientovi $exec_path (pokud ten nebyl nainstalován standardním způsobem a systém jej nenalezne). Proměnou $php_module_name se nastavuje přesměrování do souboru a $command_options umožňují přidat další parametry, jsou-li třeba.

Popis začlenění klienta:

Klient fred_client lze spustit i tak, že se mu v parametrech na příkazové řádce zadá příkaz, který má vykonat -d --command. V takovém případě se nespouští konzole, ale klient funguje jako batch. Stejně jako kombinace skriptů fred_create.py a fred_sender.py. Klient pouze zadaný příkaz provede, zobrazí výstup a ukončí se. Přihlášení a odhlášení (login, logout) proběhnou automaticky a na výstup se nevypisují. Pro správné přihlášení je proto potřebné mít nastavený konfigurační soubor nebo vše definovat na příkazové řádce.

Přepínačem --output -o upravíme výstup do požadovaného formátu. Pokud chceme v prohlížeči hodnoty pouze zobrazit, můžeme zadat typ HTML: --output=html. Chceme-li data dále zpracovávat PHP skriptem, nastavíme typ PHP: --output=php.

Shrnutí metody použití klienta v PHP:

V PHP se klient spustí jako externí program například funkcí passthru().
V parametrech se nastaví mód výpisu na PHP: --output=php
Výstup klienta se přesměruje do adresáře s právy zápisu: ... > /cache/output.php
Výsledný kód se vloží do stránky required_once('/cache/output.php') a tím jsou hodnoty PHP skriptu dostupné.

Proměnné z PHP výstupu

$fred_error_create_name = 'poll'; // jméno neplatného příkazu
$fred_error_create_value = 'op: Value "xxx" is not allowed. Valid is: (req, ack)'; // popis chyby, která se objevila při vytváření příkazu.
$fred_client_notes = array(); // seznam hlášení, které se generuje během komunikace
$fred_client_errors = array(); // seznam chyb, které vznikly během komunikce
$fred_encoding = 'utf-8'; // kódování textu
$fred_code = 1000; // návratový kód odpovědi
$fred_command = 'domain:info'; // název odeslaného příkazu
$fred_reason = 'Command completed successfully'; // popis návratového kódu
$fred_reason_errors = array(); // detaily hodnot, které způsobily navrácení kódu s chybou
$fred_labels = array(); // seznam popisků hodnot
$fred_data = array(); // seznam hodnot
$fred_source_command = '<?xml ... >'; zdrojový XML dokument příkazu generuje se jen ve verbose 3).
$fred_source_answer = '<?xml ... >'; zdrojový XML dokument odpovědi, generuje se jen ve verbose 3).

Příklad dat:

$fred_labels['domain:name'] = 'Domain name';
$fred_data['domain:name'] = 'domena.cz';
$fred_labels['domain:roid'] = 'Repository object ID';
$fred_data['domain:roid'] = 'D0000000174-CZ';
$fred_labels['domain:crID'] = 'Created by';
$fred_data['domain:crID'] = 'REG-LRR';
$fred_labels['domain:clID'] = 'Designated registrar';
$fred_data['domain:clID'] = 'REG-LRR';
$fred_labels['domain:crDate'] = 'Created on';
$fred_data['domain:crDate'] = '2006-10-31T16:51:56+01:00';
$fred_labels['domain:exDate'] = 'Expiration date';
$fred_data['domain:exDate'] = '2009-10-31T01:00:00+01:00';
$fred_labels['domain:renew'] = 'Last renew on';

Kapitola 7. Grafická nadstavba v Qt4.

Popis grafické nadstavby klienta je v samostatném souboru README_QT4.

Kapitola 8. Knihovna fred a popis API

Knihovna "fred" vám umoňuje implmentovat API rozhraní do vašich aplikací. Knihova i jednotlivé funkce obsahují komentáře, podle kterých se můžete při implementaci řídit. V části __init__.py naleznete i ukázky kódu.

Online dokumentace:

Pokud si chcete projít jednotlivé třídy a funkce knihovny, tak k tomu můžete využít generátor dokumentace pydoc, který je standardní součástí pythonu. Generátor má několik módů činnosti. Popis naleznete v helpu pydoc. Pokud jako parametr zadáte název souboru nebo modulu, tak se dokumentace zobrazuje ve stylu manuálové stránky:

    $ pydoc fred

Chcete-li generátor spustit, jako HTML server, tak zadejte na příkazové řádce příkaz:

    $ pydoc -p 8080

Pokud se server nespustí, tak zkuste:

    $ python `which pydoc` -p 8080

Tím jste spustili webový server, který generuje strany dokumentace přímo ze zdrojových souborů. Parametr -p udává na jakém portu je server spuštěn. Číslo portu můžete zadat jakékoliv jiné. Nyní si otevřete prohlížeč a zadejte adresu: http://localhost:8080/. Otevře se strana, na které v části ../site-packages naleznete odkaz na fred (package).

Pokud jste skripty neinstalovali, ale jen nakopírovali, nebo pokud se chcete podívat i na skripty pracující s knihovnou fred, tak celý proces spuštění udělejte stejně, ale s tím rozdílem, že pydoc spustíte z adresáře, kde máte tyto skripty uložené. Pak se v helpu zobrazí i ony:

    $ cd FredClient-n.n.n
    $ pydoc -p 8080

Server ukončíte stiskem Ctrl+C.

Příklady práce s knihovnou

Import knihovny provedete příkazem:

    >>> import fred

Instanci EPP klienta vytvoříte:

    >>> epp = fred.Client()

Ještě musíte načíst config, aby knihovna našla certifikát:

    >>> epp.load_config()

Chcete-li načíst jinou session - analogicky k parametru --session, tak zadejte:

    >>> epp.load_config('my-sessison-name')

Pak již můžete navázat spojení funkcí login:

    >>> retval = epp.login("username","password")

Každá funkce (EPP příkazu) vrací tuto "retval" hodnotu, která je typu dict a ve tvaru:

    {'reason': u'Text of answer reason',
     'code': 1000,
     'command': 'command_name',
     'errors': []
     'data': {'key': 'value' [,'next-key':'next-value']},
    }

Klíč "reason" (str) je vyrozumění serveru o stavu odpovědi.
Klíč "code" (int) je číslo, které definuje typ chyby. Číslo 1000 znamená OK - vše vpořádku.
Klíč "command" (str) je název příkazu, na který se odpověď vztahuje (který odpověď vyvolal).
Klíč "errors" (list) je seznam chyb, které server nalezl.
Klíč "data" (dict) je slovník s hodnotami individuálními pro každý jednotlivý příkaz.

Příklad: Když jsou vstupní data:

    name = 'jmeno'
    addr = (1,2,3)
    tech = ('ok',)
    stat = ''

...tak se vytvoří takovýto slovník 'data':

    {'name': 'jmeno',
     'addr':['1','2','3']
     'tech':'ok'           # tady je type str a stat chybí
    }

...ale ve finální verzi by to mělo být takto:

    {'name': 'jmeno',
     'addr':['1','2','3']
     'tech':['ok',]
     'stat':''
    }

Návratovou hodnotu "retval" není nutné odchytávat, ukládá se do interní proměnné a lze ji kdykoliv zobrazit funkcí print_answer():

    >>> epp.print_answer()

nebo testovat jakoukoliv hodnotu v retval pomocí funkce is_val():

    >>> epp.is_val('reason')
    u'Text of answer reason'

Každé volání další funkce EPP příkazu samozřejmě předchozí "retval" přepíše, takže uvedené dvě funkce pracují vždy jen s poslední návratovou hodnotou. Pokud chcete návratovou hodnotu testovat nebo zobrazit později, tak si ji uložte a pak ji předejte funkcím:

    >>> epp.print_answer(my_retval)
    >>> epp.is_val('reason', my_retval)

Funkci is_val() je možno zadat bez parametru. V takovém případě defaultně vrací hodnotu klíče "code":

   >>> epp.is_val()
    1000

Pokud chcete zjistit hodnotu v jakékoliv vnořené části slovníku, tak zadejte parametr jako cestu - seznam jmen (klíčů) slovníku:

    >>> epp.is_val(('data','next-key'))
    next-value

V případě, že daný klíč neexistuje, vrací funkce hodnotu None.

    >>> epp.is_val(('data','any-key'))
    None

Pokud se vyskytne nějaká chyba při přenosu nebo jiná, která zablokuje funkčnost, tak se generuje výjimka FredError.

Kapitola 9. Verze klienta 2.9 - Korespondenční adresa v kontaktu

Od verze 2.9 je možné v kontaktu editovat korespondenční adresu. Oproti předchozí verzi se změnilo zadávání údajů v příkazech create_contact a update_contact. Příkaz info_contact pak umí korespondenční adresu zobrazit.

Příkaz create_contact

V příkazu create_contact se korespondenční adresa zadává na konci příkazu, kromě transaction ID, to je vždy poslední (nepovinná) hodnota:

    create_contact CIDID02 'Jan Ban' info@mail.com 'Hlavní ulice' Praha 12000 CZ
        NULL NULL NULL NULL NULL () NULL () NULL (('Korespondenční ulice'
        'Korespondenční Město' 12001 CZ))
        

S pojmenovanými parametry se korespondenční adresa zadává například takto:

    create_contact CIDID02 'Jan Ban' info@mail.com Street Brno 123000 CZ
        --extensions.mailing_addr.street='Mailing street'
        --extensions.mailing_addr.city='Maling City'
        --extensions.mailing_addr.pc=12300 --extensions.mailing_addr.cc=CZ
        

API create_contact

Ve funkci create_contact byl přidán nový atribut extensions. Atribut je nepovinný:

    def create_contact(self, contact_id, name, email, street, city, pc, cc,
        sp=None, org=None, auth_info=None, voice=None, fax=None,
        disclose=None, vat=None, ident=None, notify_email=None, cltrid=None,
        extensions=None):
            

Korespondenční adresa se zadá například takto:

    ret = epp.create_contact("handle1", "My Name", "email@email.net",
        "Street", "City", "12300", "CZ", extensions={'mailing_addr': {
        'street': 'M. street', 'city': 'M. City', 'pc': '12301', 'cc': 'CZ'}})
            

Jsou li klíče v parametru extensions v nesprávném formátu, vyvolá se výjimka ClientUsageException.

Příkaz update_contact

V příkazu update_contact se korespondenční adresa upravuje nebo odebírá na konci příkazu:

    update_contact CIDID02 () ((('Update mailing street' City 12300 CZ State)))
        

Korespondenční adresu z kontaktu smažete zadáním mailing_addr hodnoty do parametru extensions.rem:

    update_contact CIDID01 () (() mailing_addr)
        

nebo

    update_contact CIDID01 --extensions.rem=mailing_addr
        

API update_contact

Ve funkci update_contact byl přidán nový atribut extensions. Atribut je nepovinný:

    def update_contact(self, contact_id, chg=None, cltrid=None,
        extensions=None):
            

Hodnota extensions obsahuje slovník s klíčem chg nebo s rem. Klíč chg aktualizuje korespondenční adresu kontaktu:

    ret = epp.update_contact("CIDID01", extensions={'chg': {'mailing_addr': {
            'street': 'M. street', 'city': 'M. City', 'pc': '12301', 'cc': 'CZ'
            }}})
            

Klíč rem korespondenční adresu z kontaktu odebere:

    ret = epp.update_contact("CIDID01", extensions={'rem': ['mailing_addr']})
            

Jsou li klíče v parametru extensions v nesprávném formátu, vyvolá se výjimka ClientUsageException.

Příkaz info_contact

Příkaz info_contact CIDID02 za hlavní adresou zobrazí také korespondenční adresu (je-li zadána):

Návratový kód:            1000
Důvod:                    Příkaz úspěšně proveden

Kontakt ID:               CIDID02
ID objektu v rep.:        C0000000007-CZ
Vytvořil:                 REG-FRED_A
Určený registrátor:       REG-FRED_A
Změnil:                   REG-FRED_A
Vytvořeno dne:            2017-11-22T09:49:17+01:00
Poslední změna dne:       2017-11-22T16:26:57+01:00
Jméno:                    Jan Ban
Název organizace:         Firma s.r.o.
Ulice:                    První ulice 1
                          Druhá ulice 2
                          Třetí 3
Město:                    Praha
Stát nebo kraj:           Praha 3 - Vinohrady
PSČ:                      12300
Kód země:                 CZ
Korespondenční adresa / Ulice: Korespondenční ulice 1234/14
Korespondenční adresa / Město: Korespondenční Město
Korespondenční adresa / PSČ: 12301
Korespondenční adresa / Kód země: CZ
Heslo pro transfer:       mypassword
Email:                    info@mail.com
Stav:                     ok - Objekt je bez omezení
Zveřejnit:                voice
                          fax
                          email
                          vat
                          ident
                          notify_email
                          addr
        

API info_contact

Ve funkci info_contact byly do slovníku odpovědi přidány nové atributy pro korespondenční adresu:

    ret = epp.info_contact("CIDID02")

    {'code': 1000,
     'command': u'contact:info',
     'data': {'contact:authInfo': u'mypassword',
      'contact:cc': u'CZ',
      'contact:city': u'Praha',
      'contact:clID': u'REG-FRED_A',
      'contact:crDate': u'2017-11-22T09:49:17+01:00',
      'contact:crID': u'REG-FRED_A',
      'contact:disclose': ['voice',
       'fax',
       'email',
       'vat',
       'ident',
       'notify_email',
       'addr'],
      'contact:email': u'info@mail.com',
      'contact:extension.mailingAddr.cc': u'CZ',
      'contact:extension.mailingAddr.city': u'Korespondenční Město',
      'contact:extension.mailingAddr.pc': u'12301',
      'contact:extension.mailingAddr.street': u'Korespondenční ulice 1234/14',
      'contact:hide': [],
      'contact:id': u'CIDID02',
      'contact:ident': u'',
      'contact:ident.type': u'',
      'contact:name': u'Jan Ban',
      'contact:notifyEmail': u'',
      'contact:org': u'Firma s.r.o.',
      'contact:pc': u'12300',
      'contact:roid': u'C0000000007-CZ',
      'contact:sp': u'Praha 3 - Vinohrady',
      'contact:status': u'Objekt je bez omezení',
      'contact:status.s': u'ok',
      'contact:street': [u'Prvn\xed ulice 1',
       u'Druh\xe1 ulice 2',
       u'T\u0159et\xed 3'],
      'contact:upDate': u'2017-11-22T16:26:57+01:00',
      'contact:upID': u'REG-FRED_A',
      'contact:vat': u''},
     'errors': [],
     'reason': u'Command completed successfully'}