Projekti

Yleinen

Profile

Wiki » Tekninen dokumentaatio »

Yleisohje SIP2-laitteen kytkemiseksi Kohaan (lainaus/palautus/omatoimiautomaatit)

Kun on tehty hankintapäätös uudesta hienosta SIP2-laitteesta, on tarpeen ruveta miettimään miten laite oikeastaan saadaan toimimaan Kohan kanssa.
Tässä dokumentissa kuvataan mitä toimenpiteitä kirjaston henkilökunnan tulee tehdä, mitä asioita automaatin lisäämiseen oikeastaan liittyy ja kenen vastuulla mitkäkin asiat ovat.
Lisäksi automaatin toimittajat voivat toimittaa esitietolomakkeen, johon vastaukset löytyvät toivottavasti tästä dokumentista, sekä mahdollisen asennusohjeistuksen, joka täydentää tässä manittuja asioita.

0. Kirjaston vastuu uuden automaatin hankinnassa ja käyttönotossa

Koha-Suomi tarjoaa palvelua lukuisille kunnille. Kunnat ovat kukin järjestäneet tuen eri ICT -osa-alueille hyvinkin eri tavoin. Kuntien sisällä vastuu on jakautunut monille eri henkilöille ja nämä henkilöt vaihtuvat.
Paras osaaminen siitä kelle mikäkin työ kuuluu (ja millä tavalla palvelupyyntö pitää esittää) löytyy automaatin tilaavalta kirjastolta.

Tästä syystä seuraavat vastuut kuuluvat kirjastoille:
  • vastuu eri sidosryhmien välisen kommunikaation hoitamisesta
  • vastuuu tässä dokumentissa listattujen eri työvaiheiden toteutumisen valvonnasta
  • vastuu työvaiheiden valmistumisten ilmoittamisesta seuraavalle toimijalle. Esimerkiksi, kun kaikki on valmista, ilmoitettava automaatin toimittajalle että voi tulla asentamaan.

Tämä voi joistakuista tuntua haastavalta ja voi nousta esiin kysymyksiä, että osaanko minä?
Ei huolta, moni muukin on Suomessa ratkaissut juuri näitä samoja ongelmia. Muiden Koha-kimppojen pääkäyttäjiltä saa ja pitääkin kysyä neuvoja ja vinkkejä, ja yhteistä dokumentaatiota täydentää siltä usin kun puutteitä löytyy.

Koha-Suomen kantava tavoite on mahdollistaa kirjastoja kasvamaan ja kehittymään. Se toteutuu parhaiten kun kirjastot ottavat itse vahvan roolin omien tietoteknisten asioidensa hoitamisessa.

1. Valmistelut kirjaston päässä

Nämä tarkastukset on tehtävä manuaalisesti kirjastossa ennen kuin automaatin asentaja tulee asentamaan SIP2-laitetta.

Valitse sopiva paikka

Automaatti asennetaan johonkin kalusteeseen tai seinään tai muuhun rakenteeseen.
Valitse paikka etukäteen ja huolehdi että automaatin asentajan on mahdollista suorittaa asentaminen ilman häiriöitä.
Tarvittaessa tilaa kalusteet etukäteen, raivaa pöydälle paikka valmiiksi, poista julisteet seinältä, jne.

Huolehdi kirjastossa että automaatille on esteetön pääsy, hyvä opas esteettömyyteen:
Irish-National-IT-Accessibility-Guidelines-Public-Access-Terminals

Automaatin fyysisistä tarpeista huolehtiminen

Automaatit ovat aika vaatimattomia, mutta eivät valitettavasti tule toimeen pelkällä rakkaudella.

Automaatin asennuspaikkaan on oltava mahdollista saada verkkoyhteys (ATK-pistoke, Data-pistoke, Ethernet/Rj45/Cat5/Cat6) vetämällä lähimmästä ATK-pistokkeesta lähiverkkokaapeli automaattiin.
Huomioitavaa on että kaapelin vetäminen on rumaa ja roikkuvat ja/tai kulkuteillä olevat kaapelit ovat aina kompastumisriski. Mitä lähempänä automaatti on ATK-pistoketta, sitä parempi.
Periaatteessa on myös mahdollista käyttää langatonta verkkoa automaattien kanssa, mutta jostain syystä näin ei ole haluttu toimia. Kaapeli on toki aina luotettavampi ja turvallisempi ratkaisu.

Toistaiseksi vielä, kunnes langaton sähkönsiirto on ratkaistu, automaatti tarvitsee ainakin yhden verkkovirtapistokkeen. Automaatin paikanvalinnassa samat säännöt pätevät verkkovirtakaapelin vetämiseen automaatille kuin lähiverkkokaapelin vetämisessä (yllä).

2. Tarkasta että verkkoyhteys pelaa

Automaateilta tyypillisesti on tarve päästä julkiseen internetiin huoltoyhteyksiä ja päivityksiä varten.
Tämän lisäksi automaatin on tarpeen kommunikoida SIP2-serverin kanssa.

Ohessa kuvataan kuka toimittaa mitäkin tietoja ja kuka vastaa mistäkin asioista.
Kirjasto vastaa eri sidosryhmien kanssa kommunikaatiosta ja valvoo eri osa-alueiden hoitamisen.

SIP2-serverin ylläpitäjä (yleensä Koha-Suomi Oy) kertoo SIP2-serveristä seuraavat tiedot:

  • IP-osoite
  • verkkoliikenteen portti (eli ihan vaan portti)
  • käyttäjätunnus
  • salakala
  • muita SIP2-serverin ja SIP2-laitteen välisiä tarkempia ei-verkkoliikenteen kannalta oleellisia asioita, kuten merkistäkoodaus, sanoman lopetusmerkki, yms. asioita mitä vuonna 1993 alkunsa saaneen protokollan kanssa toimeentulo vaatii.

Nämä tiedot pitää toimittaa esitietona automaatin asentajalle.

Lisäksi SIP2-serverin ylläpitäjä lisää Kohaan automaatille asiakastietueen, asiakaslajiltaan "automaatti" ja sille vaaditut käyttöoikeudet.
Kohassanne pitäisi olla erillinen asiakaslaji, jonka alla on käyttäjätilit kaikille eri automaateille/rajapinnoille/muille automatisoiduille asioille.

Paikallinen IT-tuki huolehtii:

  • valitsemastanne ATK-pistokkeesta voidaan muodostaa yhteys SIP2-serveriin. Tekevät tarvittaessa palomuuriavaukset ja muut verkkoliikenneasetukset.
    • Tätä varten he tarvitsevat SIP2-serverin IP-osoitteen ja portin, sekä ATK-portin tunnisteen. Tyypillisesti siinä ATK-pistokkeessa on joku lyhyt tunniste, jos se puuttuu sitten vain kuvaatte parhaanne mukaan mitä ATK-pistoketta tarkoitetaan.
  • antaa automaatille kiinteän sisäverkon IP-osoitteen, eli siis automaatin IP-osoitteen, jonka automaatin asentaja tarvitsee esitietona.
  • Sallii automaatille pääsyn julkiseen internetiin

Koha-palvelimen fyysisestä palvelintilasta vastaava hosting-palveluntarjoaja huolehtii:

  • Paikallisen IT-tuen määrittämästä IP-osoitteesta pääsee SIP2-serverin IP-osoitteeseen ja porttiin. Tarvittaessa tekevät palomuuriavaukset ja muut verkkoliikenneasetukset.
    • Tätä varten he tarvitsevat SIP2-serverin IP-osoitteen ja portin.

Automaatin asentajan tarpeet

Automaatin toimittaja tyypillisesti esiasentaa verkkoasetukset automaattiin ennen asennusta.

He tarvitsevat kaikki yllä mainitut tiedot mitä paikallinen IT-tukipalveluntarjoaja, sekä SIP2-serverin ylläpitäjä toimittaa.
Lisäksi mahdollisia lisätietoja heidän oman esitietokaavakkeensa mukaan.

Varmuuden välttämisen estäminen

HUOM! Tässä osiossa on aika teknisiä kohtia, jos tuntuu että nyt menee yli hilseen, etkä halua selvitellä asiaa enempää, käänny paikallisen IT-tukipalveluntarjoajasi puoleen. Voit toki myös painaa (menemään?) riskillä, mutta käytännössä on huomattu että kaikki mikä voi mennä vikaan, myös ennemmin tai myöhemmin menee vikaan.
Ennenkaikkea verkkoliikenneasioiden kanssa.
Automaatin asentaja ajettuaan autolla monta tuntia päästäkseen asentamaan automaattia, ei tule olemaan iloinen jos verkkoyhteyttä SIP2-serveriin ei saada muodostettua. Myöskin näiden verkkoliikenneasetusten säätäminen siinä hetken huumassa ei yleensä tule onnistumaan, sillä verkkoliikenneasiantuntijat ovat tyypillisesti ylityöllistettyjä ja ylistressaantuneita ja voi olla suuria vaikeuksia saada heihin yhteys "just nyt".

Kun kaikki nämä asiat on hoidettu ja jokaiselta toimijalta on tullut vahvistus että homma pelaa, käykää itse vielä kokeilemassa toimiiko verkkoyhteys.
Se on helpoiten testattu:

  • viemällä läppäri valitun ATK-pistokkeen äärelle
  • sammuttamalla läppärin langaton netti
  • kytkemällä läppäri verkkopiuhalla ATK-pistokkeeseen
  • mahdollisesti (kokeile ensin ilman), verkkoasetuksista riippuen, läppärille pitää väliaikaisesti asettaa paikallisen IT-tuen antama kiinteä IP-osoite
  • Pääsetkö osoitteeseen www.duckduckgo.com ? Jos pääset, verkko todennäköisesti toimii.

Kaikista suurin varmuus saavutetaan kun tarkastat vielä yksinkertaisella SIP2-viestillä vastaako SIP2-serveri oikeassa portissa ja oikeassa IP-osoitteessa.
Tämä onnistuu lähettämällä jollakin telnet-sovelluksella seuraavan viestin:

9300CNkivilahtio|COsalamana|CPJOE_JOE|

Vastauksena SIP2-serverin pitäisi vastata

941

Jos SIP2-serveri vastaa

940

Kannattaa vaihtaa automaatin käyttäjätunnus ja salasana SIP-serveriin ja SIP-laitteeseen :)

Ohessa esimerkki linux-komentokehotteesta:

kivilahtio@Vulcan:~$ telnet koha:n-SIP2-serverin-IP-osoite-tähän portti
Trying 13.37.13.37...
Connected to koha-boss-server.
Escape character is '^]'.
9300CNnoname|OSsala|CPJOE|
940
Connection closed by foreign host.

Puttyä voi käyttää Windowsissa telnet-yhteyden muodostamiseksi. Tai ehkä telnet -komentoa.
Linuxissa telnet on jo valmiiksi asennettuina.

Jos SIP2-liikenne kulkee stunnel-salauksen kautta, ei telnet:illä saa mitään vastausta SIP2-login viestiin (9300) ennenkuin stunnel-tunneli on muodostettu.
Kuitenkin yhteys SIP2-serverin porttiin voidaan muodostaa.
Telnet-istunto näyttää jotakuinkin tältä:

kivilahtio@hamk_koha_app1:~$ telnet 10.0.3.3 6001
Trying 10.0.3.3...
Connected to 10.0.3.3.
Escape character is '^]'.
9300CNnoname|OSsala|CPJOE|
Connection closed by foreign host.

Tämä kertoo, että palomuuri on auki, mutta ei varmenna toimiiko Kohan päässä SIP2-serveri oikein, tai onko siellä asetettu käyttäjätunnukset oikein.

Usein verkkolikkenne on suurin yksittäinen ongelman aiheuttaja ja ehdottomasti vaikein paikka selvitellä mistä ongelma johtuu. Tyypillisesti verkkolikkenneongelmat aiheuttavat ns. "silloin tällöin toimimista" tai hidastelua, vaikka Koha muuten toimisi normaalisti.
Myöskin häiriöt verkkoyhteyksissä voivat aiheuttaa SIP2-serverin tai SIP2-laitteen jumittumisen ja vaatia uudelleenkäynnistystä jompaankumpaan päähän.
Tilanne vaikeutuu entisestään kun verkkoliikenne kulkee monen eri organisaation tai monen eri verkon hallinnollisen alueen läpi, jolloin verkkoliikennesääntöjen poikkeuksia pitää tehdä yhteensä erittäin suuri määrä.

3. Verkkovirta

Ei ole myöskään itsestäänselvyys että tilaan asennettu verkkovirtapistoke toimisi.
Se on kuitenkin helppo testata, esimerkiksi kännykän laturilla.
Tarkasta lataako kännykkä akkuaan verkkovirtapistokkeen kautta.

4. Tyypillisimmät ongelmatilanteet

Ongelmia automaatin toiminnassa voivat aiheuttaa tyypillisesti seuraavat asiat (ei missään erityisessä järjestyksessä):

ATK-poistoketta ei ole kytketty mihinkään.

Siis fyysinen verkkokaapeli ei mene mihinkään tai "Joku kävi verkkoliikennetaululla tekemässä vähän kytkentöjä". Eli ongelma voi olla talojakomossa. Tästä vastaa paikallinen IT-tuki tai talotekniikka.

Palomuurisäännöt estävät verkkoliikenteen joko sisäänpäin SIP2-serverille, tai ulospäin automaatista kohti SIP2-serveriä.

Se kenen palomuurissa vika on, ei voi automaatin eikä SIP2-serverin päästä tietää, vaan sitä pitää etsiä verkon hallinnoijilta.

SIP2-serveri on vikaantunut tai konfiguraatiot ovat muuttunueet, ota yhteyttä Koha-Suomeen.

Tyypillinen ongelma Koha:n versiossa 3.16 on, että SIP2-serverin ja SIP2-laitteen (automaatti) välinen yhteys katkeaa, mutta jostain syystä yhteyden lopetusviesti ei tule SIP2-serverille. Tästä syystä SIP2-serveri luulee että yhteys on vielä aktiivinen ja pitää kiinni vanhasta yhteydestä automaattiin.
SIP2-servereillä on rajallinen määrä yhtäaikaisia worker-yhteyksiä mitä ne voivat ylläpitää, ja kun tarpeeksi monta ns. zombie-worker -yhteyttä jää roikkumaan, ei ole enää tilaa kaikille oikeille tarvittaville SIP2-automaatin yhteyksille. Jos samaa SIP2-serverin porttia käyttää useampi SIP2-laite, alkavat laitteet pikkuhiljaa satunnaisesti vikaantumaan, koska SIP2-serverillä ei ole enää vapaita workereitä kaikkien uusien yhteyksien vastaanottamiseen. Tällöin SIP2-serveri jää odottamaan että vanhat yhteydet katkeaisivat (vaikka eivät koskaan katkea), jotta ne niitä palvelevat workerit voivat siirtyä toisten yhteyksien palvelemiseen. Mitä enemmän yhteyksiä zombiutuu, sitä epävakaammin SIP2-laitteet toimivat.

Tätä ongelmaa voi lieventää/korjata vain SIP2-serverin ylläpitäjä:
  • lisäämällä workereitä SIP2-serverille
  • ajamalla yhdessä SIP2-serverin portissa vain yhtä tai muutamaa SIP2-laitetta. Tällöin on helpompi haarukoida mikä laite tarkalleen aiheuttaa yhteyksien zombiutumisen.
  • ajamalla koha-sip-watchdog -daemonia, joka tarkastaa muutaman minuutin välein että SIP2-serveri toimii oikein ja uudelleenkäynnistää SIP2-servereitä eri porteissa tarvittaessa.

SIP2-client on vikaantunut tai konfiguraatiot ovat muuttunueet, ota yhteyttä automaatin toimittajaan.

Onneksi automaatintoimittajien automaattien uusimmat ohjelmistoversiot ovat suht fiksuja ja selviytyvät erilaisista vikatilanteista sangen hyvin.

On kuitenkin mahdollista että esim laitevika estää SIP2-laitteen oikeamuotoisen toiminnan.

  • Tarkasta onko laite päällä
  • Auttaako uudelleenkäynnistys?

Ongelmanratkaisu

Paras tapa lähteä selvittelemään vikaa, on käydä läpi kappaleessa Varmuuden välttämisen estäminen esitetyt vaiheet ja soittaa Koha-Suomelle.

5. SIP2-yhteyden salaaminen stunnel4-ohjelmalla

SIP2-protokolla on vanha, eikä se ota kantaa yhteyden salaamiseksi. Helppo tapa suojata salaamaton SIP2-liikenne, on muodostaa yksinkertainen salattu putki SIP2-laitteen ja SIP2-serverin välille.

Tämä onistuu helposti esim. stunnel-työkalulla: https://www.stunnel.org/

HUOM! Tietoliikenneyhteyksien rakentaminen muuriavauksineen ja tunnelointeineen on palvelinpäässä konesalipalveluntarjoajan, kunnan tietotekniikasta vastaavan tahon sekä automaattitoimittajan välinen asia. Koha-Suomella ole mitään roolia siinä, vaan Koha-Suomi tarjoaa ainoastaan SIP2-rajapinnan automaatin kytkemistä varten. Tieteellisissä kirjastoissa järjestely voi olla toisenlainen.

Koha-palvelimelle stunnelin asentaminen

Hyvä ohje stunnel-putken muodostamiseksi: https://www.digitalocean.com/community/tutorials/how-to-encrypt-traffic-to-redis-with-stunnel-on-ubuntu-16-04#what-is-stunnel
Kirjoitushetkellä 16.10.2018 stunnelin versio 4 on tarjolla debian paketeista ja on todettu toimivan Windows-työasemaan asennettavan stunnel versio 5:n kanssa.

Windows-työasemalle stunnel:n käyttöönotto

Muodostaakseen yhteyden Koha:n SIP2-serveriä suojaavaan stunnel-serveriin, SIP2-laitteen työasemalla oleva stunnel-client pitää konfiguroida ja asettaa käynnistymään automaattisesti tietokonetta uudelleenkäynnistettäessä.

Stunnel-asennus

Lataa ohjelma stunnelin kotisivuilta https://www.stunnel.org/downloads.html
Tiedosto on muotoa

stunnel-5.49-win32-installer.exe

tai muu vastaava.

Asenna .exe-päätteinen ohjelma normaalisti.

Asennusohjelma tekee paikalliselle työasemalle oman SSL-varmenteen. Tätä varten työpöydälle tulee komentoriviterminaali. Syötä tähän parhaan osaamisesi mukaan jotkut tiedot, mutta kirjoitushetkellä 16.10.2018 näille tiedoille ei ole suurempaa käyttötarkoitusta tiedossa.

Älä käynnistä stunnel:ia asennuksen lopuksi.

Stunnel-clientin konfiguraatio

SSL varmenne/sertifikaatti

Client (eli paikallisen työaseman stunnel-ohjelma) tarvitsee stunnel-salausavaimen. Silloin kun salaukseen käytetään Kohan salausavainta, löytyy avain Koha-palvelimelta tyypillisesti polusta /etc/stunnel/koha-sip2.crt. Koha-Suomi kirjastoissa näin ei siis kuitenkaan toimita, vaan konesalipalveluntarjoaja toimittaa avaimen.

Tämä avain tallennetaan stunnel-konfiguraation viereen, tyypillisesti Windowsissa polkuun

C:\Users\Kirjasto\AppData\Local\stunnel\config
    C:\Users\Kirjasto\AppData\Local\stunnel\koha-sip2.crt

ja konfiguraatiossa määritellään mistä avain löytyy.

CAfile = C:\Users\Kirjasto\AppData\Local\stunnel\koha-sip2.crt

Salausavain tallennetaan SIP-laitteeseen selkokielisenä. On hyvä nimetä se jotenkin havainnollisesti, kuten

HAMK-Koha-SIP2-stunnel.crt

Salausavain on suunnilleen tämän näköinen:

-----BEGIN CERTIFICATE-----
MIIDvDCCAqSgAwIBAgIJAKE24DWDyxuqMA0GCSqGSIb3DQEBCwUAMHMxCzAJBgNV
BAYTAkZJMREwDwYDVQQIDAhLb2hhbGFuZDEXMBUGA1UEBwwOSMODwqRtZWVub...
                 ...<monta riviä ohitettu>...
...Z0sqVdg0+uIcUNAARUqSU13CXsyXa3fkgoyKtUNkXJZ8CrIgPcCtNFABM3Y8m
BQ9E1HJPZERaeidzAnJL8oAZmxh1mqiLxOc1H2sPwTjOaNXn3Kqxq9UMtPxyBnFi
-----END CERTIFICATE-----
Muut konfiguraatiot

Clientille pitää konfiguroida Koha-palvelimen osoite ja portti, johon stunnel ottaa yhteyden.

Clientille pitää konfiguroida missä osoitteessa se vastaanottaa paikallisen SIP2-clientin yhteyttä.

stunnel-clientin konfigurointi

Kun edellä mainitut asiat on selvitetty, asetetaan stunnel-konfiguraatio käynnistä-valikon "stunnel currentUser"-valikon alla olevasta "Edit stunnel.conf"

Korvaa työpöydälle ponnahtavan tekstieditorissa olevan tiedoston sisältö tällä:

Esimerkkikonfiguraatio Windows-työaseman stunnel-clientille

Esimerkkikonfiguraatiossa on kuvattu mihin edellä selvitetyt tiedot pitää asettaa

Stunnel:in käynnistäminen

Käynnistä stunnel käynnistä-valikon pikakuvakkeesta "stunnel GUI Start".

Jos on ongelmia, voit käynnistää stunnelin myös komentorivikehotteeseen, jolloin pääset seuraamaan stunnel-clientin logia.

Stunnel-yhteyden testaaminen

Voit testata stunnel-yhteyttä esim Putty:llä.
Ota telnet-yhteys stunnel-clientin paikalliseen osoitteeseen ja porttiin:

accept = 127.0.0.1:34343

Muista asettaa Putty:n telnet-alavalikosta

Telnet negotiation mode = Passive

Tällöin Putty ei lähetä kummallisia telnet-loitsuja SIP2-serverille ja vaikeuta yhteyden testaamista.

Kun muodostat yhteyden SIP2-serveriin, Putty avaa tyhjän komentorivin. Kun syötät tähän mitä tahansa ja painat enter, yhteys katkeaa ponnahdusikkunan viestillä "Connection closed by remote host". Tässä vaiheessa tämä on normaalia ja todistaa, että yhteys stunnel-clientiin toimii.

SIP2-clientin uudelleenkonfigurointi

SIP2-clientille pitää asettaa stunnel-clientin konfiguraatioon asetetun

accept = 127.0.0.1:34343

tiedot. Eli SIP2-serverin osoite on esimerkissä 127.0.0.1 ja portti on 34343.

SIP2-client keskustelee käyttäen socket-yhteyttä. Tämä on relevantti vain jos yhteys ei muuten normaalisti lähde toimimaan.

Käynnistä SIP2-client uudestaan. Yhteys kirjastojärjestelmään muodostuu stunnel-tunnelia pitkin.

Stunnel:in automaattinen uudelleenkäynnistys

Stunnel-putken pitää olla käytössä ennenkuin SIP2-client voi ottaa sen kautta yhteyden SIP2-serveriin.

Automatisoi putken avaus tietokoneen uudelleenkäynnistyessä kopioimalla "stunnel GUI Start"-pikakuvake kännissä-valikon Startup-kansioon.

Testaa tämä käynnistämällä SIP2-clientin työasema uudestaan. SIP2-clientin pitäisi käynnistyä ja muodostaa yhteys SIP2-serveriin automaattisesti.

6. Toimet Kohassa (pääkäyttäjille ohjeita)

SIP2-käyttäjätunnusten käsittelyohje

Lisälukemista