Tutorial aka felhasználói dokumentáció

Csináltam egy kis tutorialt. A windowsos dolgok egy része még hiányzik belőle, illetve még meg kell nézni, hogy mac-re pl mennyire igazak, azok, amiket én linuxos fejjel leírtam.

README.md

+# Tartalom
+
+* Tartalom
+* A DDNS tipikus felhasználása
+* Ajánlott updater
+ * Python interpreter telepítése, kipróbálása
+  * Telepítés és futtatás Windowson
+  * Telepítés és futtatás UNIX alapú rendszereken
+* debian/ubuntu és leszármazottaik
+* fedora
+* archlinux
+ * Konfiguráció
+ * Futtatás, ütemezés Windowson
+  * Kézi futtatás, adatok ellenőrzése
+  * Ütemezés
+ * Futtatás, ütemezés UNIX-on
+  * Kézi futtatás, adatok ellenőrzése
+  * Ütemezés
+ * Parancssori paraméterek
+* API a rekordok frissítéséhez annak, aki saját kódot használna
+ * A kérésben megadandó értékek
+ * Egy példa
+
+# A DDNS tipikus felhasználása
+A Dinamikus DNS röviden DynDNS vagy DDNS lehetővé teszi, hogy egy dinamikus IP címmel rendelkező eszköz rögzített DNS névvel rendelkezzen.
+
+Mivel az IP cím ezen szolgáltatás felhasználóinál dinamikus, így a kiszolgálón szokás elévülési időt beállítani. Ez azt jelenti, hogyha egy frissítés után az elévülési időn belül nem küldünk újabb kérést, akkor a kiszolgáló nem fogja többé feloldani a domain nevet, csak a legközelebbi frissítés után fog ez újra megtörténni.
+Ez nálunk jelen beállítás szerint 30 nap.
+
+# Ajánlott updater
+A repóból letölthető Python nyelven írt szkript minden szükséges képességgel rendelkezik, ami egy egyszerű rekordfrissítéshez szükséges. Az egyszerűség és platformfüggetlenség kedvéért ez a szkript egyetlen frissítés után kilép és befejezi a futását. Az ütemezést a felhasználóra, vagy az operációs rendszerre bízzuk. Főleg az operációs rendszeren való ütemezés ajánlott (ehhez segítség lejjebb), illetve bizonyos gyakorisággal/áramszünetkor stb. publikus ip cím változhat, ekkor pedig nem ütemezett frissítés esetén a szerver elérhetetlenné válhat.
+
+## Python interpreter telepítése, kipróbálása
+A Python nyelven írt szkript minden elterjedt operációs rendszeren futtatható, ehhez az adott operációs rendszerre egy python2.7 (az updater 2.7-es verziót használ) interpreter telepítése szükséges. Ez Windowsra legegyszerűbben [itt (Windows x86(-64) MSI installer)](https://www.python.org/downloads/release/python-2711/) tölthető le. A linken UNIX alapú rendszerekhez is elérhető interpreter, de ezeken a rendszereken inkább ajánlott a disztribúció fejlesztője által karbantartott csomagrepóból telepíteni, azok általában rögtön telepítés után jól működnek.
+
+### Telepítés és futtatás Windowson
+Mielőtt leírjuk a telepítést és használatot Windowson, felhívjuk rá a figyelmet, hogy készült egy, a windows lelkületéhez közelebb álló frissítő is, ami az [alábbi linken érhető el](). Ezt igyekszünk ugyancsak naprakészen tartani.
+
+A Python honpapjáról (fenti link) letöltött telepítő egy tipikus next-next-finish telepítő. Egyetlen dologra kell figyelni telepítés közben: Ha jót akarunk magunknak, akkor a *Customize Python 2.7.x* menüpontban az *Add python.exe to Path* melletti értéket állítsuk *Will be installed on local hard drive*-ra. Ez azért szükséges, hogy ha esetleg valamikor parancssorból szeretnénk használni a python parancsot, akkor ne kelljen teljes elérési úttal beírni ahhoz, hogy elinduljon.
+
+A telepítés után, ha semmi mást nem változtattunk, akkor a *.py* kiterjesztésű fájlokat már dupla kattintásra, vagy parancssorból indításra pythonnal futtatja a rendszer. Ez részben jó, mert kattintásra is lehet majd futtatni az updatert, viszont cserébe nem látjuk, ha esetleg hibával tér vissza (erről még lesz szó). Emellett egy alap szerkesztő is felkerül, amivel kódszínezés mellett meg lehet nézni/szerkeszteni a kódot, illetve kitölteni a konfigurációs fájlt.
+
+### Telepítés és futtatás UNIX alapú rendszereken
+A UNIX alapú rendszerek többsége rendelkezik csomagdisztribúciós rendszerrel, így általában az ilyen alapvető komponenseket egyetlen parancs kiadásával lehet telepíteni, valamint ezeket rögtön ezután használni is lehet minden különösebb beállítás nélkül.
+
+Erre adunk pár példát:
+```bash
+# debian/ubuntu és leszármazottaik
+apt-get install python2.7
+
+# fedora
+dnf install python2.7
+
+# archlinux
+pacman -S python2.7
+```
+
+Ez után a python2.7 konzolban bármikor futtathatók python parancsok.
+
+**Fontos!** Telepítéskor érdemes mindenképpen python**2.7**-ként telepíteni simán *python* helyett, ugyanis néhány disztribúción a sima *python* már a python**3.5**-re utal.
+
+## Konfiguráció
+A repóban van egy conf_example.py nevű fájl, ami példaként szolgál a konfigurációs fájl kitöltésére. Ezt érdemes egy az egyben átmásolni conf.py névre (az updater ezt a fájlt fogja importálni), és itt a kommentben leírt magyarázatok alapján beírni a megfelelő adatokat.
+
+Aki nem szereti a parancssort, annak érdemes először is a LOG_FILE paramétert megadni, ugyanis kattintásra futtatáskor ugyan megjelenik egy konzol, de futás után rögtön be is zárul, így a frissítés kimenetele alig látható. LOG_FILE megadása esetén a kimenet kiíródik a megadott fájlba.
+
+## Futtatás, ütemezés Windowson
+
+### Kézi futtatás, adatok ellenőrzése
+
+### Ütemezés
+http://windows.microsoft.com/hu-hu/windows/schedule-task#1TC=windows-7
+
+## Futtatás, ütemezés UNIX-on
+
+### Kézi futtatás, adatok ellenőrzése
+Először egy kézi futtatással bizonyosodjunk meg arról, a megadott kofigurációs adatok helyesek-e. Ehez nyiss egy terminált, majd menj el abba a mappába, ahová letöltötted az updatert.
+
+Ahhoz, hogy futtatható legyen a szkript, engedényezni kell a futtatását. Ezután küldjünk egy validációs kérést.
+```bash
+cd /path/to/updater
+chmod +x update_i42_domain.py
+./update_i42_domain.py -v
+```
+Ha ez sikeres visszajelzést ad, akkor a konfigurációs fájlban megadott adatok helyesek.
+
+### Ütemezés
+UNIX-szerű rendszereken ilyen feladatok ütemezésére szolgál a cron. Ennek használata többféle lehet, most azt mutatjuk be, hogy tud a felhasználó a saját hatáskörében ütemezett feladatot megadni.
+Ennek működéséhez **futnia kell** a gépen egy cron daemonnak (pl *cronie*). Ez disztribúciófüggő, és nem feltétlenül fut alapértelmezetten, folytatás előtt nézz utána, hogy a saját disztribúciódhoz mit ajánlanak, és hogy hogy lehet elindítani/engedélyezni.
+
+Alapvetően a cron arra való, hogy egy-egy parancsot bizonyos időnként lefuttassunk. Ehhez a crontab-ban kell megadni az ütemezést egy megadott formátum szerint, majd utána a parancsot, amit futtatni szereténk.
+
+Ehhez a terminálban futtassuk a `crontab -e` parancsot, amire egy karakteres szövegszerkesztő fog megnyílni. Ide írjuk be például a következőt.
+```cron
+ * */1 * * * /path/to/updater/update_i42_domain.py
+```
+Ez óránként lefuttatja az updatert. Ezt az esetek többségében egy optimális értéknek tartjuk, ha nincs rá különösebb okod ne állítsd át.
+A túl gyakori kérések terhelésének elkerülése érdekében szerver oldalon erre korlátozás van beállítva, ha ezt túlléped, akkor esetleg olyan hibaüzeneteket kaphatsz, ami arra utal, hogy a szolgáltatás nem elérhető.
+
+Aki szeretné jobban személyre szabni a frissítési időt, vagy csak érdeklődik a crontab iránt, az olvasson utána a fájl formátumának [ezen a linken](https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man5/crontab.5.html#//apple_ref/doc/man/5/crontab), vagy terminálban a `man crontab` parancs kiadása után.
+
+## Parancssori paraméterek
+Az updaternek megadhatók a futást befolyásoló paraméterek parancssorban is. Ezek megismeréséhez `--help` kapcsolóval kell futtatni: `update_i42_domain.py --help`.
+
+**Figyelem!** A parancssori paraméterek magasabb prioritásúak, mint a konfigurációs fájlban megadott adatok.
+
+# API a rekordok frissítéséhez annak, aki saját kódot használna
+A frissítéshez egy POST kérést kell küldeni IP verziótól függően valamelyik címre.
+
+| Verzió	| Cím								|
+| --------	| ------------------------------	|
+| IPv4		| https://updaterv4.i42.hu:10053	|
+| IPv6		| https://updaterv6.i42.hu:10053	|
+
+Ezekhez a címekhez valid SSL cert tartozik.
+
+## A kérésben megadandó értékek
+| Név	 		| Érték																											| Megadása		|
+| ----------	| -----------------------------------------------------------------------------------------------------------	| ----------	|
+| prefix		| A rekord i42.hu előtti része. pl: az **val.ami**.i42.hu-ban a **val.ami**.									| Kötelező		|
+| token			| A honlapon generált token.																					| Kötelező		|
+| ip_address	| A beírandó ip cím. Ha nincs a kérésben, akkor a küldő publikus ip címe kerül beírásra.						| Opcionális	|
+| validate		| Nem tartozik hozzá érték. Ha meg van adva, akkor nem történik frissítés, csak a küldött adatok ellenőrzése.	| Opcionális	|
+
+Mivel ip_address paraméter megadása esetén a megadott érték kerül beírásra, így szükség esetén lehetséges IPv4-es kapcsolaton keresztül IPv6-os címet frissíteni.
+
+## Egy példa
+A következő kis szkript linux rendszeren elküld egy-egy kérést IPv4-en és IPv6-on is.
+
+```bash
+#! /bin/bash
+for x in 4 6
+do
+	curl -${x} https://updaterv${x}.i42.hu:10053 --data "token=my_token&prefix=my_prefix" && echo ""
+done
+```
+

conf_example.py

@@ -6,13 +6,14 @@
 """
 
 # Prefix, amit regisztráltál
+# Pl: valami.i42.hu-nál valami, x.valami.i42.hu-nál pedig x.valami
 MY_PREFIX = "" # az i42.hu domain hozzáfűzésre kerül
 
-# Token, amit regisztráltál
+# Token, amit a honlapon generáltál
 MY_TOKEN = ""
 
 # Az IP cím, amire frissíteni akarod a domain rekordod. Ha erről a gépről akarod használni, akkor hagyd el.
-# Ha nem muszáj ne használd!
+# Ha nem muszáj ne változtasd meg!
 # Ha nem változtatod meg, akkor az éppen aktuális publikus címed kerül beállításra
 MY_IP_V4 = "" # opcionális
 MY_IP_V6 = "" # szintén opcionális
@@ -28,3 +29,4 @@ UPDATE_IP_VERSION = 0
 # Ütemezett használat esetén érdemes ilyet megadni.
 # Ha üresen hagyod, minden a standard hibakimenetre fog íródni.
 LOG_FILE = "" # Lehetőleg teljes elérési utat használj.
+