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:
- 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
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.
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.
Now you are connected to the SIP2 server you can start writing and sending request commands. The connection to the SIP2 server does time out fast so if haven’t finished writing and receiving commands simply write in: telnet localhost <portnumber> to restart the SIP2 connection.
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).
Additionally a library with the branchcode of ‘WEL’ has been created in the Koha staff interface and is also defined in the institution area of the 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
Alert type could have one of several values: 00 : Unknown
01: local hold
02: remote hold
03: ILL Transfer
04: transfer
99: Other
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:
Item status update: This uses the request message prefix of 19 and the response message prefix of 20
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
The value displayed for <patronvalidity> is Y (valid) and N (invalid). The value in the <YYYYMMDD> < HHMMSS> is the current date/time.
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:
Renew: This uses the request message prefix of 29 and the response message prefix of 30
Messaggio di richiesta:
Nota
<thirdpartyallowed> is a single character value which is either Y or N. If it is Y then third parties can renew items.
<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> is a 3 alphanumeric character long value identifying the currency the fee was paid in.
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.
Response message: 941 is a successful login
940 is an unsuccessful login
[connection closed by foreign host.] is a unsuccessful login
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
The status code is one of 3 values. - 0: SC is ok
1: SC is out of paper
2: SC is shutting down
max print width is a 3 character long value which is the integer number of characters the client can print
Protocol version is a 4 character value in the format 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 In Linux terminal navigate to the directory containing the koha-conf.xml file which will either be 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
Note about hostname:
Hostname can either be a alphanumerical name or it can be the LDAP server IP address (its optional to write port number).
By default the ldaps default port number is 636, whilst ldap default port number is 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).
Whereas the update LDAP config field (in the same file allows) allows for user information in the LDAP database to be synced down to the Koha database.
e.g. if someone gets married and their surname changes then the new surname only needs to be updated in the existing LDAP database and that will be synced down to the Koha database automatically if the update configuration is set to 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:
If plack is not disabled then LDAP errors are displayed in the plack-error.log file. If plack is disabled then the location that LDAP errors are printed to is either the opac-error.log file (if the user is logging into the OPAC) or the intranet-error.log file (if the user is logging into the staff client) All of these three log files are accessible in the following directory:
/var/log/koha/<instance>/