Other APIs and protocols

SIP2

SIP2 (Session Initiation Protocol) è un protocollo per la comunicazione tra sistemi.

In Koha, il SIP2 è usato per la comunicazione tra macchine di Self-Check (autoprestito) SC e il sistema di Circolazione Automatica (noto anche come ACS, che è poi il server stesso di Koha).

Le comunicazioni SIP2 sono richieste e risposte.

Le macchine di autoprestito sono “tonte” e spediscono richieste al server Koha che esegue una certa logica per dare una risposta alla macchina, che la passa all’utente.

Avvertimento

Security notice regarding using SIP2 service: To ensure that your SIP2 traffic is secure as it passes over the internet you need to make sure that you are using a VPN or stunnel.

Impostare SIP2

Se hai installato Koha usando Debian, allora SIP2 è facile da installare, seguendo questi passi:

1. In your terminal (in the root Koha directory) write in: sudo koha-enable-sip <instancename>

2. Now you need to configure the SIP2 settings, to do this you need to edit the SIPconfig.xml file which exists in the /etc/koha/sites/<instancename>/ directory. You will need to edit this file as root because it contains passwords (to do so write ‘sudo’ at the start of your command).

es. sudo vi /etc/koha/sites/<instancename>/SIPconfig.xml

Nota

Nota importante: ci sono tre aree di interesse nel file SIPconfig.xml. Sono: service, account e institution.

Servizio

2.1 modificare il valore della porta nella parte superiore del file SIPconfig.xml (identificato con il numero 1 nella schermata sottostante), che abbia ha lo stesso indirizzo IP come più in basso nel file di SIPconfig.xml identificato da 2.

Nota

Assicurarsi che i valori di due porta non hanno lo stesso numero di porta, dato che non si può avere la stessa porta per due diversi servizi. Quando si decide il numero di porta usare un numero elevato (cioè sopra 1000) perché tutte le porte sotto 1000 richiedono permessi di root.

Account

The account(s) you define in the SIPconfig.xml file are simply account(s) permitted to use the SIP2 service i.e. you’re defining who can send and receive SIP2 commands.

Avvertimento

Le informazioni di account che scrivi qui devono essere presenti anche nel database di Koha, cioè è necessario creare un utente nell’interfaccia staff di Koha con lo stesso nome utente e password (assicurandosi di assegnare le autorizzazioni di circolazione) come quello indicato in SIPconfig.xml.

Nota

Si raccomanda di registrare in Koha solo accounts con permesso di circolazione.

La ragione per cui vogliamo che gli utenti SIP2 abbiano solo autorizzazione alla circolazione piuttosto che essere superlibrarian è quello di ridurre l’accesso a SIP2 ai dati non confidenziali nel caso in cui il sistema venga compromesso.

Se l’ACS o l’SC venissero compromessi, avere gli utenti SIP2 con i soli permessi della circolazione consente all’intruso di poter accedere solo ai dati utente solo attraverso il terminale e non con l’interfaccia web (cosa che sarebbe possibile con il privilegio di superlibrarian). Si tratta di proteggere i dati dei tuoi utenti.

Definizioni dei valori dell’account:

1. Login id: È lo username dell’account. - Modificarlo opportumanente

2. Password: Account password - Modificare opportunamente

3. Delimiter: il tipo di delimitatore per le informazioni dell’account - Lasciare il default

4. error-detect - Leave as default

5. Istituzione: Questo è il branchcode della biblioteca a cui l’utente appartiene. Nota: Questa istituzione deve essere definita ulteriormente nell’area istituzione del file SIPconfig.xml e deve esistere anche nel database di Koha. cioè è necessario creare una biblioteca con la stessa branchcode nell’interfaccia staff di Koha.

6. encoding: Questo è lo standard usato per codificare i dati dell’account

7. Terminator: Questo deve corrispondere al valore di terminator del server SIP2. - Modificare questa opzione se si conosce il valore di terminator del server SIP2.

It is also possible to add custom patron attributes to SIP2 profiles using the format such as:

<patron_attribute field=»XX» code=»CODE1» /> <patron_attribute field=»XY» code=»CODE2» /> <patron_attribute field=»XZ» code=»CODE3» />

Istituzione

L’informazione di una istituzione che definisci qui deve coincidere con una biblioteca creata in Koha.

Avvertimento

È necessario accertarsi che tutte le istituzioni a cui vengono assegnati gli account ulteriormente nel file SIPconfig.xml siano definite anche nell’area istituzione dello stesso file.

Definizioni valori per l’istituzione:

1. Institution id: The branchcode of the library. - Modify this accordingly. Must be the same as created in Koha and the account area.

2. Implementazione: Definisce il codice che verrà eseguito. - Lasciare come default

3. Policy: Policy defines the permitted SIP2 commands allowed from SC’s in this institution. For example: renewal=”true” means that SC’s at that institution have permission to send renewal item SIP2 commands.

4. Starting SIP2 Simply write in the command: sudo koha-start-sip <instancename>

Nota

Ora hai un server SIP2 funzionante.

Nota

Optionally, you can configure sorting bin behavior, using the UseLocationAsAQInSIP and SIP2SortBinMapping system preferences.

Usando SIP2

SIP2 è un protocollo di comunicazione. I messaggi spediti via SIP2 sono richieste o risposte. L’SC spedisce richieste all’ACS che esegue una certa logica e restituisce un valore all’SC in un messaggio di risposta.

I messaggi di richiesta contengono argomenti, che sono valori di dati utilizzati dall’ACS nelle sue funzioni per eseguire il compito richiesto come rinnovare i prestiti.

Comandi SIP2

Se vuoi usare/testare SIP2 manualmente, dovrai scrivere e ricevere messaggi tramite il terminal Linux.

Per essere in grado di inviare e ricevere messaggi con il server SIP2 è necessario utilizzare telnet per aprire una connessione SIP2. È necessario specificare il numero di porta che si desidera telnet da utilizzare.

Per trovare queste informazioni vedere nell’area di servizio nella parte superiore del file SIPconfig.xml (cercare il numero di porta come indicato dalla freccia nella schermata qui sotto).

1. Scrivi sul terminale

   telnet localhost <portnumber>

   es. telnet localhost 8023

2. Now write in the username and password set in one of the accounts in the SIPconfig.xml file.

3. Ora che sei connesso al server SIP2, puoi scrivere e spedire comandi. La connessione al server SIP2 ha un timeout breve per cui se non hai finito di scrivere e ricevere comandi semplicemente scrivi:

   telnet localhost <portnumber>

   per resettare una connessione SIP2.

Comandi sintassi SIP2

Ogni comando SIP2 ha un prefisso di due caratteri numerici che definiscono cosa fa il comando.

ad esempio per ottenere informazioni su un utente si avvia il comando con il prefisso: 63. La risposta dal server ha anche un prefisso numerico corrispondente.

Sotto c’è un esempio di richiesta SIP2 di informazione di un utente (un account Koha con username “joe”, password “joes” e numero tessera “y76t5r43” è stato creato nello interfaccia di Koha).

Inoltre è stata creata una biblioteca con branchcode “WEL” che è anche definito nell’area istituzione del file SIPconfig.xml file):

Per cui il formato per questo messaggio SIP2 è:

Nota

Il valore di riepilogo è di 10 caratteri. Se si usa Y allora si sarà in grado di ottenere un riepilogo e più dettagliate informazioni di output.

The value in the <YYYYMMDD> <HHMMSS> is the current datetime, by leaving a 4 space gap between the YYYYMMDD and HHMMSS this indicates you want to use local time rather than UTC.

Nota

In questo manuale i codici a lettere nei diversi campi sono usati quando possibile per descrivere i campi del messaggio SIP2, per esempio AO <institutionid>.

Questi codici possono essere usati nei comandi SIP2 dal terminale Linux, ma non vanno riportate le <> parentesi uncinate, solo i valori tra <>.

Messaggi SIP2

Blocco utente

Usa il prefisso 01 del messaggio di richiesta e il prefisso 24 del messaggio di risposta.

Messaggio di richiesta:

Nota

Card retained is a single character field of either ‘Y’ or ‘N’ which tells the ACS that a card has been retained by the self checkout machine.

Messaggio di risposta:

Nota

<patronstatus> è una stringa di 14 caratteri. Il valore Y nella stringa indica vero. Ogni posizione nella stringa (a partire da 0) ha un valore (Y or N).

es. un Y in posizione 1 (il secondo valore nella stringa) indica che non sono concessi i privilegi di rinnovo all’account

Rientro copie

Usa il prefisso 09 del messaggio di richiesta (messaggi inviati a ACS e il prefisso 10 del messaggio di risposta (inviati a SC).

Messaggio di richiesta:

Nota

• <no block (Offline)> è ‘Y’ o ‘N’ che indica se la transazione è avvenuta offline. Le transazioni offline non sono supportate, per cui devi scrivere ‘N’ se stai testando questo messaggio manualmente.

• <transactiondate> un campo di 18 caratteri con formato: YYYYMMDDZZZZHHMMSS.

ZZZZ è la timezone, Se vuoi impostarlo a locale, usa 4 spazi, se vuoi impostarlo a UTC UTC (Coordinated Universal Time) scrivi 3 spazi e una Z.

Messaggio di risposta:

Nota

Tipi di allarme: 00: sconosciuto 01: prenotazione locale 02: prenotazione remota 03: trasferimento ILL 04: trasferimento 99: altro

If an item is resensitized then the value of <resensitize> should be Y otherwise it should be N. Rensensitizing items is done to ensure that if someone tries to steal the item they are detected.

Prestito copie

Usa il prefisso 11 del messaggio di richiesta e il prefisso 12 del messaggio di risposta. Ha una sintassi simile a quella del comando di restituzione visto prima, ma con prefissi diversi.

Prenotazione - Potrebbe non essere supportato su alcuni sistemi. Usa il prefisso 15 del messaggio di richiesta e il prefisso 16 del messaggio di risposta.

Messaggio di richiesta:

Nota

<holdmode> è un carattere. + indica di aggiungere una prenotazione, - indica di cancellarla e * indica di modificarla.

Messaggio di risposta:

Nota

• <ok> è un carattere numerico che può essere 0 (prenotazione non permessa o fallita) o 1 (prenotazione permessa e riuscita).

• <available> può essere Y o N. Y significa che la copia è attualmente in biblioteca, N significa che la copia è attualmente è in prestito o in prenotata.

Informazioni della copia: Usa il prefisso 17 del messaggio di richiesta e il prefisso 18 del messaggio di risposta

Messaggio di richiesta:

Nota

Si veda il comando restituzione copie (descritto sopra) per capire il valore di <xact_date>.

La password del terminale è opzionale.

Messaggio di risposta:

Modifica stato della copia - Usa il prefisso 19 del messaggio di richiesta e il prefisso 20 del messaggio di risposta

Messaggio di richiesta:

Nota

<itemproperties> non è un valore di lunghezza fissa, e puoi opzionalmente indicare valori come dimensione della copia e questi valori verranno conservati copia per copia nel database di Koha.

Messaggio di risposta:

Nota

<itempropertiesok> è 0 o 1. 1 indica che il valore <itemproperties> definito nel messaggio di aggiornamento dello stato della copia è stato conservato correttamente nel database di Koha.

Stato utente

Usa il prefisso 23 del messaggio di richiesta e il prefisso 24 del messaggio di risposta.

Messaggio di richiesta:

Messaggio di risposta:

Nota

Il valore mostrato per <patronvalidity> è Y (valido) e N (non valido). Il valore in <YYYYMMDD> < HHMMSS> è la data/ora corrente.

Il motivo dello spazio tra i due valori è indicare che si vuole usare il local time invece di UTC.

Attivazione utente - Non ancora supportata. Usa il prefisso 25 del messaggio di richiesta e il prefisso 26 del messaggio di risposta

Nota

Questo comando annulla quello di blocco dell’utente.

Messaggio di richiesta:

Messaggio di risposta:

Rinnovo - Usa il prefisso 29 del messaggio di richiesta e il prefisso 30 del messaggio di risposta

Messaggio di richiesta:

Nota

• <thirdpartyallowed> è Y o N. Se Y, terze parti possono rinnovare le copie.

• <noblock> è Y o N. Se Y, la copia è stata prestata/restituita quando l’ACD era offline.

• <nbduedate> è la data della transazione di prestito/restituzione quando il sistema ACS era offline.

• <feeacknowledged> è Y o N. Indica se l’utente accetta il costo associato con la copia che sta rinnovando.

Messaggio di risposta:

Nota

• <ok> è 0 o 1. Il valore 1 indica rinnovo avvenuto, 0 indica rinnovo fallito.

• <renewalok> è Y o N. La logica per impostare il valore di <renewalok> è: Y si usa quando la copia è già prestata all’utente e deve essere smagnetizzata e quindi rinnovata, mentre N si usa quando la copia non è già prestata all’utente e non deve essere rinnovata.

In altre parole non permettere all’utente di rinnovare ciò che non ha in prestito.

• <magneticmedia> Y (per sì), N (per no), o U (per sconosciuto).

• <mediatype> è di tre cifre. Per una lista dei valori vedi: http://multimedia.3m.com/mws/media/355361O/sip2-protocol.pdf

Fine sessione

Usa il prefisso 35 del messaggio di richiesta e il prefisso 36 del messaggio di risposta

Messaggio di richiesta:

Messaggio di risposta:

Nota

<success_or_failure> è Y per ok o N per ko.

Tassa pagata - Potrebbe non essere ancora implementata. Usa il prefisso 37 del messaggio di richiesta e il prefisso 38 del messaggio di risposta

Messaggio di richiesta:

Nota

• <feetype> è un numero di due cifre tra 01 e 99. Per vedere una lista dei tipi di costi vai a http://multimedia.3m.com/mws/media/355361O/sip2-protocol.pdf

• <paymenttype> sono due cifre da 00 a 99. 00 è contante, 01 è Visa, 02 è carta di credito.

• <currencytype> è una stringa di 3 caratteri che identifica la valuta per il pagamento delle multe.

Messaggio di risposta:

Nota

<paymentaccepted> è Y (pagamento accettato) o N (pagamento non accettato).

Informazioni utente

Usa il prefisso 63 del messaggio di richiesta e il prefisso 64 del messaggio di risposta

Messaggio di richiesta:

Messaggio di risposta:

Nota

<valid patron> è Y per valido e N per non valido.

Nota

<hold itemcount><overdueitemcount><chargeditemscount><fienitemscount><recallitemscount><unavaliableholdscount> sono tutti di 4 caratteri numerici.

Rinnova tutto

This uses the request message prefix of 65 and the response message prefix of 66.

Messaggio di richiesta:

Messaggio di risposta:

Nota

• <renewedcount> è un valore di 4 cifre che indica il numero delle copie rinnovate.

• <unrenewedcount> ha lo stesso formato di <renewedcount> ma indica il numero di copie non rinnovate.

Login

Usa il prefisso 93 del messaggio di richiesta e il prefisso 94 del messaggio di risposta.

Messaggio di richiesta:

Nota

<UIDalgorithm> e <PWDalgorithm> sono lunghi un carattere e indicano il tipo di algoritmo da usare per criptare loginuserid e loginpassword.

Il valore 0 indica che questi valori non saranno criptati.

Messaggio di risposta: 941 login ok. 940 login fallito [connessione chiusa dal server remoto.]

Rispedisci

Così viene chiesto al sistema ricevente di rispedire l’ultimo messaggio.

SC -> ACS rispedire la richiesta è 97

ACS -> SC rispedire la richiesta è 96

Status di ACS e SC

Questo ha il prefisso di richiesta 99 e il prefisso di risposta di 98.

Messaggio di richiesta:

Nota

Lo status code è uno di questi 3 valori. * 0: SC è ok * 1: SC ha finito la carta * 2: SC è in spegnimento. max print width è un valore lungo 3 caratteri che indica il numero di caratteri che il client può stampare. Protocol version è lungo 4 caratteri e ha il formato x.xx

Messaggio di risposta:

Nota

Se la risposta è “96”, il messaggio di richiesta è non valido/non compreso.

Risoluzione problemi con SIP2

Impossibile connettersi all’host usando il comando telnet localhost <portnumber>

le 3 soluzioni da tentare per questo problema sono:

1. Check the portnumber your writing in the above command is the port number written in the SIPconfig.xml file at the location indicated by the number 1. i.e. in the below example because the portnumber is 6001 the correct command would be: telnet localhost 6001.

2. Check if any userid is written more than once in the SIPconfig.xml file. The userid (which is simply the username of the Koha user) needs to be unique within the SIPconfig.xml file. If you have the same userid multiple times in your SIPconfig.xml file this will cause the connection to SIP2 to fail before you get a chance to authenticate.

3. Check the account defined in the SIPconfig.xml file also exists in the Koha database with the same username, password and has circulate permissions. If you have dropped and recreated the Koha database after creating the patron account in the Koha staff interface and the SIPconfig.xml file then that patron account will not exist in the Koha database and so you will need to recreate them in the Koha staff interface.

Per vedere il log di SIP2 vai alla directory: /var/log/koha/<instancename>

Poi vedi i log sip-error.log e sip-output.log che riportano informazioni più precise sugli errori di SIP2.

• cat sip-error.log

• cat sip-output.log

Link utili per i comandi SIP2

http://multimedia.3m.com/mws/media/355361O/sip2-protocol.pdf

LDAP

Setting up LDAP (Lightweight Directory Access Protocol) for Koha allows you to store all user information in a central database which is accessed both by your organisation’s Koha instance and for users to authenticate on other existing systems.

LDAP è un protocollo per trovare file sulle reti e per l’autenticazione.

LDAP configurations are powerful allowing you to customise how Koha and LDAP interact. LDAP can be configured so that new accounts created in LDAP can be synced down into the Koha database, additionally updates to the LDAP user account are synced down to the Koha database.

Comunque Koha non può sincronizzare i dati sul server LDAP, cioè il traffico verso Koha dal server LDAP è in sola lettura.

Auth_By_Bind è 1 se un sistema Microsoft Windows Active Directory è usato nel database LDAP.

Prima di procedere alla configurazione di LDAP, ti servono le seguenti informazioni/azioni da parte della tua istituzione

• L’organizzazione dovrà aprire una porta per permettere l’accesso al loro AD dal server.

• Informazione per accedere al server AD (IP address/hostname, port, SSL info)

• Informazioni sulla configurazione del server AD (sono rilevanti OUs, DCs, i formati CN relativi agli usernames)

• Mappatura tra campi AD e campi Koha, inclusi i default

• Valori di default per quanto non fornito da AD (categorycode, branchcode per esempio)

• Per autenticare un utente facciamo un bind come sembra essere comune per AD oppure usiamo un nostro login e poi controlliamo ? Se usiamo la seconda opzione abbiamo bisogno dei dettagli di come fare log on

• I nomi utente esistenti in Koha corrispondono ai nomi utente che useremo per cercarli in AD? Se è così, bene. Se così non fosse, come verranno trattati utenti duplicati?

Passi per configurare LDAP per la tua istanza di Koha

1 sul terminale Linux andare alla directory contenente il file koha-conf.xml che può stare in: * /etc/koha/sites/<instance-name>/ OR * /etc/koha/

2 Apri il file koha-conf.xml con i permessi di root: sudo vi koha-conf.xml

3 Andare alla linea che contiene ‘<useldapserver>0</useldapserver>’ e cambiarlo in: <useldapserver>1</useldapserver>

4 Then in the next line below write in the LDAP configurations below:

      <ldapserver id="<ldapserverid>">

      <hostname><hostname></hostname>

      <base>dc=<domaincontroller>,dc=<domaincontroller></base>

      <user>cn=<nameofuser>, dc=<domaincontroller>,dc=<domaincontroller></user> <!--This is the username of user account with permissions to query the LDAP server -->

      <pass><password></pass> <!-- This is password of the user account with permissions to query the LDAP server-->

      <replicate><either0or1></replicate> <!-- add new users from LDAP to Koha database -->

<welcome><either0or1></welcome> <!-- send new users the welcome email when added via replicate -->

      <update><either0or1></update> <!-- update existing users in Koha database -->

      <auth_by_bind><either0or1></auth_by_bind> <!-- set to 1 to authenticate by binding instead of password comparison, e.g., to use Active Directory -->

      <principal_name><principalname></principal_name> <!-- optional, for     auth_by_bind: a printf format to make userPrincipalName from koha userid        -->

      <mapping> <!-- match koha SQL field names to your LDAP record field names-->

      <firstname is="givenname"></firstname>

      <surname is="sn"></surname>

      <address is="postaladdress"></address>

      <city is="l">Athens, OH</city>    <!-- Athens,OH is the default value for
      city of all users logging into Koha -->

      <zipcode is="postalcode"></zipcode>

      <branchcode is="branch">Central</branchcode>

      <userid is="uid"></userid>

      <password is="userpassword"></password>

      <email is="mail"></email>

      <categorycode is="employeetype">EM</categorycode>

      <phone is="telephonenumber"></phone>

      </mapping>

      </ldapserver>

Salva ed esci dal file koha-conf.xml

6 Controlla che la connessione LDAP funzioni scrivendo:

ldapsearch -H ldaps://host.name -s base -x -w «» -d 1

Nota

Nota sull’hostname. Hostname può essere un nome alfanumerico o può essere l’indirizzo IP del server LDAP (è opzionale indicare il numero di porta). Per impostazione predefinita il numero di porta predefinito per ldaps è 636, mentre il numero di porta predefinito per ldap è 389

Nota

Note about the replicate and update fields The replicate LDAP config field for LDAP in the koha-conf.xml file allow the Koha database to be added to with a new borrower account whenever a user logs into Koha (either the staff client or OPAC) with their LDAP username and password (assuming the same username and password does not already exist in the Koha database).

Il campo update LDAP consente di sincronizzare le informazioni utente del database LDAP con Koha. Per esempio. se qualcuno si sposa e il cognome cambia, il nuovo cognome deve essere aggiornato solo nel database LDAP esistente e verrà automaticamente sincronizzato con il database Koha, se la configurazione del campo update è impostata su 1.

Riguardo ai campi di mappatura (i campi evidenziati inverde) <city is=»l»>Athens, OH</city>

Il nome di colonna a sinistra (in giallo) è il nome della colonna nel database LDAP.

Il nome della colonna all’interno di virgolette (evidenziata in color magenta) è il nome della colonna nel database di Koha. Nota: Questo può essere riempito con qualsiasi valore se non esiste alcun nome di colonna equivalente nel database Koha come esiste nel database LDAP.

Il valore evidenziato in ciano è il valore predefinito per le colonne specificate di Koha e LDAP. Così nell’esempio sopra tutti i record utente nel database di Koha e LDAP per impostazione predefinita avrà il valore di città di “Atene, OH”.

Esempi delle configurazioni LDAP:

<useldapserver>1</useldapserver><!-- see C4::Auth_with_ldap for extra configs you must add if you want to turn this on -->

<ldapserver id="ldapserver" listenref="ldapserver">

<hostname>ldaps://example.co.au</hostname>

<base>ou=employees,dc=companya,dc=com,dc=au</base>

<user></user> <!-- DN, if not anonymous -->

<pass></pass> <!-- password, if not anonymous -->

<auth_by_bind>1</auth_by_bind>

<replicate>1</replicate> <!-- add new users from LDAP to Koha database -->

<update>0</update> <!-- update existing users in Koha database -->

<principal_name>ou=employees,dc=companya,dc=com,dc=au</principal_name>

<mapping>

<userid       is="uid"            ></userid>

<cardnumber   is="uid"            ></cardnumber>

<email        is="mail"           ></email>

<surname      is="sn"             ></surname>

<firstname    is="givenname"      ></firstname>

<categorycode is="1">EM</categorycode>

<branchcode   is="1">SYD</branchcode>

</mapping>

</ldapserver>

I valori nell’area di mappatura non sono sempre gli stessi, dipendono da come è fatto il sistema LDAP della tua istituzione. Per esempio alcune istituzioni non usano <userid> ma ogni utente è identificato dal campo <email>; quindi <userid> non viene scritto.

Risoluzione problemi con LDAP

La stampa del log degli errori di LDAP dipende da diversi fattori:

Se Plack non viene disattivato, gli errori LDAP vengono visualizzati nel file plack-error log. Se Plack è disattivato, gli errori di LDAP vanno nel file opac-error.log (se l’utente accede in OPAC) o nel file intranet-error.log (se l’utente si collega all’interfaccia staff). Questi tre file di log sono accessibili nella seguente directory:

/var/log/koha/<instance>/