Update API Verzija 3
Detektovanje promene IP adrese
Da bi odredio da li je ažuriranje potrebno, klijent mora imati pouzdan metod detekcije svoje aktuelne IP adrese radi poređenja sa adresom prethodne promene. Postoje dva metoda:
Interni metod
Klijent može da odredi (samostalno ili na osnovu unosa korisnika) da je direktno povezan sa Internetom. Uređaj bi trebalo da ima javnu IP adresu, u kom slučaju je optimalno rešenje u pribavljanju tog podatka od samog operativnog sistema.
Web IP Detekcija (CheckIP)
Klijent može takođe ustanoviti (automatski ili na osnovu unosa korisnika) da nije direktno povezan sa Internetom, pri čemu je mrežnom interfejsu dodeljena privatna IP adresa (obično iz RFC 1918 opsega 10/8, 172.16/12, 192.168/16). U ovom slučaju, optimalni metod je upotreba web IP detekcije.
Za ove potrebe Dyn.rs nudi CheckIP servis koji mogu koristiti svi klijenti koji rade sa našim sistemom.
Update Zahtevi
Nakon detekcije promene IP adrese ili izmene konfiguracije od strane korisnika, klijent bi trebalo da izvrši ažuriranje. Ažuriranje se vrši putem standardizovanih i unapred definisanih HTTP zahteva. Sistem će uzvratiti odgovorom u čijem telu će biti odgovarajući povratni kod, koji bi klijent trebalo da analizira.
HTTP Zahtev
Server: | dyn.rs |
---|---|
URI: | /v3/update |
Metodi: | GET, POST |
HTTP Portovi: | 80, 8245 |
HTTPS Port: | 443 |
Zahtevi se mogu slati preko HTTP ili (TLS enkripcija) HTTPS protokola (preporučljivo).
Sve zahteve treba slati koristeći hostname servera dyn.rs
. Fiksno definisanje IP adrese u u kodu nije
prihvatljivo jer se taj podatak može u svakom trenutku izmeniti.
Naš interfejs za ažuriranje "sluša" na portovima 80
i 8245
za HTTP, i 443
za
HTTPS.
Port 8245
se može koristiti za zaobilaženje transparentnih HTTP proxy uređaja. Za uspešnu operaciju
ažuriranja nije potrebno otvarati bilo koji ulazni port (ili dozvoljavati dolazni ICMP saobraćaj).
Primeri
Ovi primeri su prikazani samo u cilju boljeg razumevanja procesa ažuriranja.
Autentifikacija u URL adresi
Za web čitače ili softverske alatke (fetch, curl, lwp-request) koji mogu da parsiraju autentifikacionu sekciju u okviru URL-a.
https://{username}:{password}@dyn.rs/v3/update?hostname={hostname}&myip={IP Address}
Curl primer u komandnoj liniji
curl -ks -u {username}:{password} "https://dyn.rs/v3/update/?hostname={hostname}&myip={IP Address}"
HTTP GET Zahtev
Kompletan HTTP zahtev bi trebalo da izgleda kao što sledi. Obratite pažnju na to da postoji minimalni skup zaglavlja. Zahtev treba završiti slanjem jedne prazne linije.
base-64-authorization treba zameniti sa Base64 enkodiranim stringom username:password .
GET /v3/update?hostname=yourhostname&myip=ipaddress HTTP/1.0 Host: dyn.rs Authorization: Basic base-64-authorization User-Agent: Company - Device - Version Number
NApominjemo da su i GET i POST zahtevi dozvoljeni i da će biti ravnopravno procesirani.
Parametri
Polje | Opis | Dodatne informacije |
---|---|---|
hostname |
Spisak imena hostova koje treba ažurirati (maksimalno 5), odvojenih zarezom. Ovo je obavezan parametar. | Svaki host će biti ažuriran istom informacijom o IP adresi, nakon ćega će biti vraćen jedinstvenipovratni kod.
Na primer, ako je vaše korisničko ime hostname=johndoe.dyn.rs or hostname=- or hostname=Da ažurirate sva tri hosta odjednom sa istom IP adresom, možete navesti hostove na sledeće načine: hostname=johndoe.dyn.rs,home.johndoe.dyn.rs,work.johndoe.dyn.rs or hostname=-,home,work or hostname=,home,work
Obratite pažnju na zarez na početku, koji odvaja prazan string za vaš primarni host.
|
myip |
IPv4 or IPv6 adresa za ažuriranje. | Ako ovaj parametar nije naveden, biće iskorišćena najadekvatnija IP adresa koju server može da odredi (neki proxy sistemi prosleđuju IP adresu u zaglavlju, što naš server detektuje). U slučaju da format IP adrese navedene u zahtevu nije valudan, podatak će biti ignorisan i zamenjen adresom sa koje zahtev dolazi. |
Povratni kodovi
Pri slanju zahteva za ažuriranje , odgovor servera je jedan od kratkih povratnih kodova opisanih u nastavku, nakon koga sledi jedan prazan ili TAB karakter, a u nastavku, do kraja linije, odgovarajuća opisna poruka. U slučaju greške, klijent bi trebalo da prikaže opisnu poruku korisniku. Svi povratni kodovi se vraćaju u telu HTTP odgovora, uz odgovarajući HTTP kod u zaglavlju koji indikuje uspeh (2xx), grešku sa strane klijenta (4xx) ili grešku na serveru (5xx)..
Kod ažuriranja više hostova istim zahtevom, vraća se samo jedan finalni povratni kod. Povratni kodovi koji označavaju neuspeh vezan sa korisničkim nalogom ili serverom se takođe vraćaju samo jednom.
Tipovi zahteva i odgovora
Uspešan zahtev
Postoji samo jedan povratni kod koji označava uspešno ažuriranje. Kod good
znači da je
ažuriranje uspešno izvršeno i da je IP adresa na sistemu izmenjena.
Zahtevi bez izmene
Kod nochg
označava uspešno procesiran zahtev, ali da IP adresa nije izmenjena jer je
identična sa već postojećom. Jedina situacija kada je ovo prihvatljivo je tokom inicijalizacije klijenta, kada se,
zavisno od implementacije, može desiti da je prethodna IP adresa klijentu nepoznata. Takođe, korisnicima može biti
na raspolaganju opcija za forsirano ažuriranje, za potrebe provere autentifikacije i funkcionalnosti ažuriranja.
Kako je ovo vrlo redak slučaj, učestala pojava nochg
koda će prouzrokovati blokadu
hosta sa koga zahtevi dolaze. Korisnicima ne bi trebalo omogućiti da koriste forsirano ažuriranje previše često.
Malo je verovatno da klijent spreči korisnika u ovome, pa je preporuka da u samom softverskom kodu budu
implementirana ograničenja koja sprečavaju prečesto vraćanje nochg
koda.
Fatalne greške
Svaki neuspešan zahtev je fatalnog tipa, što znači da će i naredni zahtevi neuspešni ukoliko korisnik ne preduzme neku akciju i koriguje nepravilnosti u konfiguraciji. Zbog toga bi bilo poželjno da na osnovu detektovane greške klijent obustavi dalji rad dok korisnik ne koriguje konfiguraciju i ručno reaktivira funkciju ažuriranja.
Pored toga, pošto zahtev može biti neuspešan iz više razloga, klijent bi trebalo da prikaže korisniku da je operacija neuspešna i šta je razlog. Nekoliko sugestija:
- Prikaz poruke na displeju rutera (ukoliko ga ima)
- Prikaz poruke u prozoru samog Dyn Update klijenta ili kroz sistem notifikacija operativnog sistema
- Generisanje Email poruke sa greškom i slanje na adresu koju korisnik definiše
Mnoge od ovih grešaka su uzrokovane pogrešnom konfiguracijom klijenta ili razlikama u konfiguraciji klijenta i korisničkog naloga na Dyn.rs sistemu. U svakom slučaju, klijent treba da zaustavi proces ažuriranja dok se problem ne otkloni. Automatsko nastavljanje s neuspešnim pokušajima u ovakvim slučajevima se smatra zloupotrebom servisa i može prouzrokovati blokadu klijenta..
Greške vezane za korisnički nalog
Sledeći kodovi znače da klijent nije konfigurisan u skladu sa korisničkim nalogom. Ovi kodovi se vraćaju samo jednom. Klijent treba da zaustavi proces ažuriranja dok se problem ne otkloni.
badauth |
Korisničko ime ili lozinka nisu ispravni. |
---|---|
noaccess |
Korisnički nalog je suspendovan. |
Update Complete
Sledeći kodovi označavaju uspešno izvršenu operaciju.
good |
Ažuriranje uspešno, nova IP adresa postavljena. |
---|---|
nochg |
Zahtev primljen i procesiran, izmena nije bila potrebna. Ponovljeni zahtevi sa
|
Za potrebe potvrde, good
i nochg
kodovi u nastavku linije imaju IP adresu kojom se zapis ažurira.
Greške vezane za host
Sledeći kdovi ukazuju na problem sa imenom hosta. Klijent treba da zaustavi proces ažuriranja dok se problem ne otkloni.
notfqdn |
Dato ime hosta se ne može razrešiti u puno FQDN ime *.hostname.dyn.rs. |
---|---|
nohost |
Dato ime hosta ne postoji na korisničkom nalogu (ili nije aktivno). |
numhost |
Previše hostova (preko 5) definisano u jednom zahtevu. |
abuse |
Zahtev je blokiran zbog evidentirane zloupotrebe. |
Greške vezane za klijent (user-agent)
badagent |
User-Agent zaglavlje nije uključeno u zahtev ili HTTP metod nije dozvoljen (preporučljivo je koristiti GET metod). |
---|---|
good 127.0.0.1 |
Ovaj kod indicira uspešno ažuriranje samo kada je adresa |
Greške na strani servera
Sledeći kodovi označavaju greške na serveru za koje je potrebna intervencija naših administratora. Klijent treba da prekine redovan rad i obavesti korisnika da kontaktira našu tehničku podršku. Redovan rad se ne sme nastaviti u narednih 30 minuta ili dok korisnik ne potvrdi da je problem otklonjen.
dnserr |
Greška u radu sa DNS serverima |
---|---|
911 |
Sistemski problem ili planirani radovi na održavanju sistema. |