Altre API e protocolli
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
Informazioni di sicurezza sul servizio SIP2: per assicurarsi che il traffico SIP2 in internet sia criptato devi usare una VPN o stunnel.
Impostare SIP2
Suggerimento
Helpful hints can be found on the Koha wiki:
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
L’account definito/i nel file SIPconfig.xml è semplicemente l’account autorizzato/i a utilizzare il servizio SIP2 cioè stai indicando chi può inviare e ricevere comandi SIP2.
Avvertimento
Account information that you write here must also exist in the Koha database i.e. you need to create a patron in the Koha staff interface with the same username, password (making sure to assign them the circulate permission) as the user account you write into the SIPconfig.xml file.
Nota
It is highly recommended that you only write in Koha user accounts with the circulate permission.
The reason we want SIP2 users to only have the circulate permission rather than the superlibrarian permission is to reduce the access SIP2 users have to confidential patron data in case the system was compromised.
If the ACS or the SC were compromised then having all SIP2 users only having the circulate permission means that an intruder would only be able to access patron data via the terminal rather than the web interface as well (which would be available with the superlibrarian permission). So it is simply a matter of protecting your users.
Definizioni dei valori dell’account:
Login id: È lo username dell’account. - Modificarlo opportumanente
Password: Account password - Modificare opportunamente
Delimiter: il tipo di delimitatore per le informazioni dell’account - Lasciare il default
error-detect - Leave as default
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.
encoding: Questo è lo standard usato per codificare i dati dell’account
Terminator: Questo deve corrispondere al valore di terminator del server SIP2. - Modificare questa opzione se si conosce il valore di terminator del server SIP2.
È anche possibile aggiungere attributi personalizzati utente ai profili SIP2 usando un formato del tipo:
<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.
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.
Usare 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).
Scrivi sul terminale
telnet localhost <portnumber>
es. telnet localhost 8023
Now write in the username and password set in one of the accounts in the SIPconfig.xml file.
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.
Il valore in <YYYYMMDD> <HHMMSS> è la data e ora corrente, e lasciando 4 spazi tra YYYYMMDD e HHMMSS si indica di usare il local time invece di 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
Se la copia viene magnetizzata allora il valore di <resensitize> deve essere Y altrimenti N. Magnetizzare copie riattiva l’antitaccheggio.
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:
Controllare che il numero di porta usato nel comando precedente sia il numero di porta scritto nel file SIPconfig.xml nella posizione indicata dal numero 1. cioè nell’esempio seguente se il numero di porta è 6001 il comando corretto sarebbe: telnet localhost 6001.
Verificare se qualsiasi userid è scritto più di una volta nel file SIPconfig.xml. L’ID utente (che è semplicemente il nome utente dell’utente Koha) deve essere univoco all’interno del file SIPconfig.xml. Se hai lo stesso ID utente più volte nel file SIPconfig.xml, farà sì che la connessione a SIP2 fallisca prima dell’autenticazione.
Check the account defined in the SIPconfig.xml file also exists in the Koha database with the same username, password and has the circulate permission. 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
Impostare LDAP () per Koha permette di conservare l’informazione di tutti gli utenti in un database centrale accessibile per autenticarsi in Koha e in altri server della tua istituzione.
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>/