Manuál pro FredClient konzoli a knihovnu fred

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 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í:

V sekci connect jsou tato nastavení:

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:

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

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:

Popis jednotlivých prvků:

Shrnutí:

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, ...

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>
    

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á.

Ú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:

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.

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.

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']}, 
    }

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.