From 9feb8acb2827eb2b8f62ff74bf3994ec337c4713 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Eckl=2C=20M=C3=A1t=C3=A9?= <ecklm@sch.bme.hu>
Date: Thu, 24 Dec 2015 16:43:54 +0100
Subject: [PATCH] =?UTF-8?q?Tutorial=20aka=20felhaszn=C3=A1l=C3=B3i=20dokum?=
 =?UTF-8?q?ent=C3=A1ci=C3=B3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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       | 137 ++++++++++++++++++++++++++++++++++++++++++++++++
 conf_example.py |   6 ++-
 2 files changed, 141 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index e69de29..4bc197e 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,137 @@
+# 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
+```
+
diff --git a/conf_example.py b/conf_example.py
index 8427f8a..5edad2f 100644
--- a/conf_example.py
+++ b/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.
+
-- 
GitLab