KServer Etäohjaus 1 (5) KServer Etäohjaus Spesifikaatio asiakaspuolen toteutuksille Palvelimen toteutuksen ollessa versio 1.0, spesifikaation versio 1.0.0. 2009, Riku Eskelinen/ KServer Software Development <software@kserver.dy.fi> Julkaisu 13.05.2009.
KServer Etäohjaus 2 (5) Yleistä KServer Etäohjaus tarjoaa tavan hallita useita Linux -järjestelmiä keskitetysti ja tehokkaasti yksinkertaisen hallintatoteutuksen kanssa. Tarkoituksena on, että KServer Etäohjaus on vain alusta toiminnalle asiakasohjelmien tarjotessa varsinaisen toteutuksen. Tämä spesifikaatio kattaa vain nk. normaalien asiakkaiden toiminnan. Esim. käyttäjien ja tietokoneiden lisääminen ei kuulu palvelimen asiakasrajapintaan, joten sitä ei ole tässä määritelty. Toiminnot Dataa siirretään palvelimelle ja palvelimelta neljällä tapaa: Komentojonon vastaanottaminen palvelimelta (get): Asiakas saa kaikki suorittamattomat komentojononsa palvelimelta suorittamista varten. Lokin siirto palvelimelle (give): Kun asiakas on suorittanut palvelimelta saamansa komentojonon, sen tulisi palauttaa komentojonon palauttama data (sekä syöte- että virhevirrasta) lokitiedostona palvelimelle. Komentojonon siirtäminen palvelimelle (put): Asiakas siirtää järjestelmään haluamansa komentojonon, jonka toinen (tai sama) asiakas voi noutaa palvelimelta. Lokin vastaanottaminen palvelimelta (take): Asiakas vastaanottaa vastaanottamattomat lokit tutkimista varten. Komentojonon vastaanottaminen Asiakas lähettää palvelimelle GET-pyynnön seuraavilla muuttujilla: do=get kertoo palvelimelle, että kyseessä on komentojonon vastaanottamistoimenpide. user=käyttäjänimi, jossa käyttäjänimi on käyttäjänimi jolla on joko superkäyttäjän oikeudet tai käyttöoikeus tietokoneeseen. pass=md5hash, jossa md5hash on käyttäjän salasana muutettuna MD5-tarkistussummaksi. mach=kone, jossa kone on halutun tietokoneen nimi. mapa=salasana, jossa salasana on tietokoneen salasana muutettuna MD5-muotoon. Superkäyttäjät eivät tarvitse tällaista salasanaa. evrytin=1, jos halutaan palvelimen palauttavan myös jo suoritetut komentojonot. On asiakkaan tehtävä valita palautetusta listasta suoritettavat komentojonot. Palvelin palauttaa tämän jälkeen joko virheen tai komentojonot seuraavalla muotoilulla: # ----- # ** KServer Etäohjaus ** # ** Puran alle komentojonoa numero 1: ** komentojono 1 tulee tähän # ** Purettiin ylle komentojono numero 1, siirryn seuraavaan... ** # ----- # ** KServer Etäohjaus ** # ** Puran alle komentojonoa numero 2: ** komentojono 2 tulee tähän # ** Purettiin ylle komentojono numero 2, siirryn seuraavaan... ** Jne... # Kaikki komentojonot purettu, valmis. Kiitos, että käytit KServer Etäohjausta! Asiakkaan tulee tallentaa komentojono ja suorittaa se heti tai myöhemmin. Asiakas voi tehdä haluamaansa
KServer Etäohjaus 3 (5) erottelua tiedostoista haluamallaan tavalla, mutta se ei saa luottaa palvelimen merkintöihin, sillä komentojonon lähettäneen asiakkaan tiedostoon ei tehdä mitään tarkistuksia. Lokitiedoston palautus Suoritettuaan komentojonon, asiakas palauttaa jonon tuottamat syötteet palvelimelle POST-pyynnöllä seuraavilla muuttujilla: do=give kertoo palvelimelle, että kyseessä on lokitiedoston lähettämistoimenpide. user=käyttäjänimi, jossa käyttäjänimi on käyttäjänimi jolla on joko superkäyttäjän oikeudet tai käyttöoikeus tietokoneeseen. pass=md5hash, jossa md5hash on käyttäjän salasana muutettuna MD5-tarkistussummaksi. mach=kone, jossa kone on halutun tietokoneen nimi. mapa=salasana, jossa salasana on tietokoneen salasana muutettuna MD5-muotoon. Superkäyttäjät eivät tarvitse tällaista salasanaa. file=@tiedosto, jossa @tiedosto on syötteeseen lisätty tiedosto. Palvelin ei käsittele tiedoston MIMEtyyppiä tai tiedostonimeä, ja se nimetään automaattisesti yhteentörmäysten välttämiseksi. Palvelin palauttaa joko tyhjän vastauksen onnistuneesta siirrosta tai virheen epäonnistuessaan. Komentojonon siirto palvelimelle Kuten lokitiedoston palautuksessa, mutta do-muuttujan arvoksi on annettava put. Lokitiedoston vastaanottaminen Kuten komentojonon vastaanottamisessa, mutta do-muuttujan arvoksi on annettava take. Palvelin palauttaa joko virheen tai lokitiedostot seuraavalla muotoilulla: SS: ** KServer Etäohjaus ** SS: ** Puran alle lokia numero 1, tallennettu 10.5.2009 23:03:17: ** lokitiedoston 1 sisältö SS: ** Purettiin ylle loki numero 1, siirryn seuraavaan... ** SS: ** KServer Etäohjaus ** SS: ** Puran alle lokia numero 2, tallennettu 12.5.2009 22:57:35: ** lokitiedoston 2 sisältö SS: ** Purettiin ylle loki numero 2, siirryn seuraavaan... ** SS: Kaikki lokit purettu, valmis. Kiitos, että käytit KServer Etäohjausta! Asiakas voi tehdä haluamaansa erottelua tiedostoista haluamallaan tavalla, mutta se ei saa luottaa palvelimen merkintöihin, sillä lokin lähettäneen asiakkaan tiedostoon ei tehdä mitään tarkistuksia. Virheet Palvelin palauttaa virheet aina viimeisenä rivinä ilman lopettavaa rivinvaihtoa (\n). Asiakkaan tulee huolehtia virheen näyttämisestä käyttäjälle. Asiakas voi olettaa, että kaikki viimeiset rivinvaihdottomat rivit, jotka ovat viisi merkkiä (tavua) pitkiä, ovat virhekoodeja. Virhekoodit ovat muodossa Exxxx, jossa xxxx on virheen numero. Alla luettelo virhekoodeista palvelintoteutuksen tässä vaiheessa. Jos asiakas ei tunnista virhettä, sen tulee kohdella sitä samoin kuin virhettä E9999. Virhekoodi Selitys Virhealue
KServer Etäohjaus 4 (5) E0001 E0002 E0003 E0004 E0005 E0006 E0007 E0008 E0009 E0010 E0011 E0012 Asiakas ei lähettänyt mitään pyyntöä do-muuttujassa. Asiakkaan tulee liittää jokin spesifikaation mukainen pyyntö jokaiseen palvelimelle lähettämässään kyselyssä Virheellinen pyyntö. Asiakkaan pitää lähettää jokin kelvollinen pyyntö do-muuttujassa. Palvelin ei voinut yhdistää tietokantapalvelimeen. Asiakas voi esim. yrittää kolmesti uudelleen 30 sekunnin välein, ja sitten keskeyttää. Palvelin ei voinut valita tietokantaa. Toiminta sama kuin yllä, vaikkakin tämä on todennäköisemmin palvelimen asetusongelma. Käyttäjän yrittää tunnistautua väärällä käyttäjällä tai salasanalla. Asiakkaan tulee välittää salasana jo valmiiksi MD5-muodossa, ja huomauttaa käyttäjälle, että myös käyttäjänimessä isoilla ja pienillä kirjaimilla on eroa (sekä tietenkin itse huolehtia että kaikki merkit ovat käytettävissä). Asiakas on määritellyt tietokoneen, jota ei löydy tietokannasta. Asiakkaan tulee huomauttaa käyttäjälle, että myös järjestelmien nimissä isoilla ja pienillä kirjaimilla on eroa. Asiakas on palauttanut väärän salasanan tietokoneelle. Kuten aiemminkin, myös tässä isoilla ja pienillä kirjaimilla on eroa. Superkäyttäjät eivät tarvitse tätä salasanaa. Asiakas on palauttanut tietoja, jotka ovat muuten oikein, mutta käyttäjä ei ole superkäyttäjä, eikä kyseisen tietokoneen käyttäjätiedoissa ole mainintaa annetusta käyttäjästä. Yhtään komentojonoa ei tarvinnut palauttaa. Asiakkaan tulee käsitellä asia sopivalla tavalla. Komentojonoa ei ole tai sitä ei voida lukea. Tämä virhe tarkoittaa, että palvelimen talletuskansiosta on kadonnut tai poistettu tiedostoja, tai niiden oikeudet ovat väärät. Jos mahdollista, tällöin asiasta pitäisi huomauttaa palvelimen ylläpitäjää. Asiakkaan tulisi ilmoittaa tämä yleisenä palvelinvirheenä. Komentojonoa ei voitu merkitä luetuksi. Tämä on todennäköisimmin ongelma palvelimen tietokantatoteutuksessa (esim. MySQLtoimintahäiriö), ja asiakkaan tulisi yrittää pyyntöä uudelleen. Yhtään lokia ei tarvinnut palauttaa. Sama asiakkaan käytös kuin E0009:ssä. Kyselyt (Asiakas) Kyselyt (Asiakas) Komentojonot Tiedostojärjestelmä Lokit E0013 Sama kuin E0010, nyt vain lokitiedostojen osalta. Tiedostojärjestelmä E0014 Sama kuin E0011, nyt vain lokitiedostojen osalta. E0015 E0016 E0017 Asiakas on jättänyt tiedostonlähettämispyynnöstään tiedoston pois, tai se on väärän nimisellä muuttujalla. Asiakkaan tulisi jo ennen lähetystä tarkistaa, että käyttäjä on todella lähettämässä jotain, jotta tähän virheeseen ei jouduttaisi. Palvelimen vastaanottaessa tiedostoa tapahtui virhe, esim. tiedonsiirto katkesi tai suurin sallittu koko saavutettiin. Asiakkaan tulisi yrittää uudelleen kerran ja sen jälkeen heittää virhettä käyttäjälle. Palvelimelle lähetetty tiedosto oli tyhjä (kooltaan 0 tavua), joten tiedoston tallentaminen keskeytettiin. Asiakkaan tulisi varmistaa Vastaanotto (Asiakas) Vastaanotto (Palvelin/Asiakas) Vastaanotto (Asiakas)
KServer Etäohjaus 5 (5) E0018 E0019 E0020 E0021 ennen lähetystä, että tiedostossa on sisältöä. Vastaanotettu tiedosto ei ole vastaanotettu tiedosto. Tämä viittaisi harvinaiseen (joskin mahdolliseen) yhteentörmäykseen tai muuhun ongelmaan palvelimella. Asiakkaan tulisi yrittää uudelleen 30 sekunnin kuluttua. Palvelintoteutuksen sisäiselta nelinumeroistajalta loppuivat numerot kesken. Tämä harvinainen ongelma korjaantuu yleensä seuraavalla sekunnilla, kun uusi 10000 numeron pinkka otetaan käyttöön, joten asiakkaan tulisi yrittää uudelleen sekunnin kuluttua. Palvelin ei voinut tallentaa vastaanotettua tiedostoa kansioon, sillä tiedoston siirtämisessä kansiosta toiseen tapahtui virhe. Todennäköisesti virhe ei korjaannu itsellään, joten asiakkaan tulisi keskeyttää pyyntö ja ilmoittaa palvelimella olevan virhetilanne. Komentojonoa ei voitu tallentaa tietokantaan, koska tapahtui virhe. Asiakkaan tulisi yrittää hetken kuluttua uudelleen ainakin kolmesti, ja sitten peruuttaa. Vastaanotto Sisäinen Tiedostojärjestelmä E0022 Sama kuin E0021, mutta tällä kertaa lokitiedostojen osalta. E9999 Tuntematon virhe tai muu ongelma. On asiakkaan määriteltävissä, miten kyseisestä virheestä toivutaan. Muu (Muu) Asiakas voi käyttää omissa virhekoodeissaan virheitä E9000-E9899 (kaikkiaan 900 virhekoodia). Muotoiluohje lokitiedostoille: Asiakkaan olisi hyvä joskaan tätä ei vaadita muotoilla palauttamansa lokitiedostot niin, että jokainen rivi alkaa statuskuvauksella (kts. lista alla), jota seuraa ajetun ohjelman nimi ja sitten tuloste. Rivit tulee lopettaa UNIX-rivinvaihtoon (\n). Malli: XX: yyyyyy: kuvaus Jossa XX on statuskuvaus: SS: palvelimen tuottama ilmoitus, vain palvelimen käyttöön DD: virheenkorjaustietoja NN: tietoja WW: varoitus EE: virhe!!: virhe, johon kaaduttiin yyyyyy on suoritetun prosessin nimi ja kuvaus on prosessin palauttaman tulosteen sisältö. Asiakas voi näyttää vain haluamansa rivit olettaen että muotoiluohjetta on noudatettu. On kuitenkin suositeltavaa, että rivit, jotka eivät sisällä edellä mainittuja statuskuvaustietoja, näytetään aina. Asiakas voi kuitenkin toteuttaa lokin katselun haluamallaan tavalla, mutta se ei saa antaa virheilmoitusta käyttäjälle, jos lokia ei ole muotoiltu ohjeen mukaisesti.