Other APIs and protocols

SIP2

SIP2 (Session Initiation Protocol) est un protocole de communication entre appareils.

Dans le contexte de Koha, SIP2 est utilisé pour la communication entre les bornes d’auto-prêt et le Système Automatisé de Circulation (ACS qui dans ce cas-ci est le serveur qui roule Koha).

Les communications SIP2 consistent en requêtes et réponses.

Les bornes d’auto-prêt sont « stupides » en ce sens qu’elles envoient des requêtes au serveur Koha qui exécute une logique de traitement pour déterminer le résultat qui est renvoyé en tant que message à la borne d’auto-prêt qui relaie ce message à l’utilisateur.

Avertissement

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.

Mise en place de SIP2

Si vous avez installé Koha avec les paquets Debian, la mise en place de SIP2 se fait aisément. Veuillez simplement suivre les étapes suivantes :

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).

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

Note

Note importante : Il y a trois zones dans le fichier SIPconfig.xml que vous devez modifier. Elles sont : service, account et institution.

Service

2.1 Changez la valeur du port vers le début du fichier SIPconfig.xml (identifié par le numéro 1 dans la capture d’écran), pour qu’il ait la même adresse IP que plus loin dans le fichier SIPconfig.xml, identifiée par le numéro 2.

Note

Assurez-vous que les deux valeurs n’ont pas le même numéro de port puisqu’un même port ne peut servir à deux services différents. Lorsque vous décidez du numéro de port à assigner, assurez-vous que ce soit un nombre élevé (c’est à dire plus élevé que 1000) parce que tous les ports sous 1000 requièrent les permissions 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.

Avertissement

Les informations de compte que vous inscrivez ici doivent également exister dans la base de données de Koha, c’est-à-dire que vous devez créer un adhérent dans l’interface professionnelle de Koha avec le même identifiant et mot de passe (sans oublier de lui assigner les permissions de circulation) que le compte d’utilisateur que vous notez dans le fichier SIPconfig.xml.

Note

Il est fortement recommandé de n’inscrire que des utilisateurs Koha avec les permissions de circulation.

La raison pour laquelle nous recommandons que les utilisateurs SIP2 n’aient que les permissions de circulation plutôt que les permissions de superbibliothécaire est afin de réduire l’accès des utilisateurs SIP2 aux informations confidentielles des adhérents, dans le cas où le système serait compromis.

Si le ACS ou la borne d’auto-prêt était compromis, le fait que les utilisateurs SIP2 n’aient que les permissions de circulation signifie que l’intrus ne pourrait accéder aux données des adhérents que par le terminal plutôt que par l’interface web (qui n’est accessible qu’avec les permissions de superbibliothécaire). Il s’agit simplement de protection pour vos adhérents.

Définition des valeurs de compte :

1. Login id : Ceci est l’identifiant du compte. - Modifiez-le en conséquence

2. Password : Le mot de passe du compte - Modifiez-le en conséquence

3. Delimiter : Il s’agit du type de délimiteur pour l’information du compte - Laissez tel quel

4. error-detect - Leave as default

5. Institution : Il s’agit du branchcode de la bibliothèque d’appartenance de l’utilisateur. NOTE : Cette institution doit être définie plut loin dans la section institution du fichier SIPconfig.xml et doit également exister dans la base de données de Koha. Vous devez donc créer un site avec le même branchcode dans l’interface professionnelle de Koha.

6. encoding : Il s’agit du standard utilisé pour encoder les données du compte

7. Terminator : Doit correspondre au caractère d’arrêt du serveur SIP2. - Modifiez-le si vous connaissez le caractère d’arrêt du serveur 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 » />

Institution

Les informations d’organisation que vous définissez ici doivent correspondre à un site créé dans l’interface professionnelle de Koha.

Avertissement

Vous devez vous assurer que toutes les organisations auxquelles des comptes d’utilisateurs ont été assignés précédemment dans le fichier SIPconfig.xml sont aussi définies dans la section institution du même fichier.

Définitions des valeurs d’institution :

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

2. Implementation : Définit le code qui sera envoyé. - Laissez tel quel

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>

Note

Vous avez maintenant un serveur SIP2 opérationnel.

Note

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

Utiliser SIP2

SIP2 est un protocole de communication. Les messages envoyés en SIP2 sont soit des requêtes ou des répondes. Les bornes d’auto-prêt envoient des messages de requête au système automatisé de circulation qui effectuera un traitement logique et renverra le résultat à la borne d’auto-prêt en tant que message de réponse.

Le message de requête contient des arguments qui sont des données utilisées par le système automatisé de circulation dans ses fonctions pour exécuter la tâche requise comme renouveler des exemplaires.

Commandes SIP2

Si vous souhaitez utiliser ou tester SIP2 manuellement, vous devrez écrire et recevoir des messages à travers le terminal de Linux.

Pour envoyer et recevoir des messages du serveur SIP2 vous devez utiliser telnet pour ouvrir une connexion SIP2. Vous devez spécifier le numéro de port que telnet doit utiliser.

Vous trouverez cette information au début du fichier SIPconfig.xml (cherchez le numéro de port, tel qu’indiqué par une flèche dans la capture d’écran ci-dessous).

1. Écrivez dans le terminal

   telnet localhost <portnumber>

   par exemple telnet localhost 8023

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

3. Vous êtez maintenant connecté au serveur SIP2 et vous pouvez commencer à écrire et envoyer des commandes de requête. La connexion au serveur SIP2 arrive rapidement au bout de son délai, donc si vous n’avez pas terminé d’écrire et de recevoir des commandes, écrivez :

   telnet localhost <portnumber>

   pour redémarrer la connexion SIP2.

Syntaxe de commande SIP2

Chaque commande SIP2 a un préfixe de 2 chiffres qui définit ce que la commande fait.

Par exemple, pour avoir de l’information à propos d’un adhérent, vous commencez votre commande par le préfixe 63. La réponse du serveur aura un préfixe numérique correspondant.

Vous trouverez ci-dessous un exemple de message de requête pour avoir des information d’adhérent (dans cet exemple, une fiche d’adhérent a été créée dans l’interface professionnelle de Koha avec l’identifiant « joe », le mot de passe « joes » et le numéro de carte « y76t5r43 »).

De plus, un site avec le branchcode « WEL » a été créé dans l’interface professionnelle de Koha et est également défini dans la section institution du fichier SIPconfig.xml) :

Le format de ce message de requête SIP2 est :

Note

La valeur summary est une valeur de 10 caractères. Si Y est inscrit comme valeur summary vous pourrez obtenir un sommaire ainsi que des informations plus détaillées comme résultat.

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.

Note

Dans ce manuel, dans la mesure du possible, les codes alphabétiques pour les champs sont utilisés dans la description des champs des messages SIP2, par exemple AO<institutionid>.

Ces codes alphabétiques peuvent être écrits dans les commandes SIP2 dans le terminal Linux, mais lorsque vous substituez des valeurs (valeurs entre <>), assurez-vous de ne pas écrire les chevrons <>.

Messages SIP2 :

Bloquer un adhérent

Ceci utilise le préfixe 01 pour les messages de requêtes et 24 pour les messages de réponses.

Message de requête :

Note

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.

Message de réponse :

Note

<patronstatus> est une valeur de 14 caractères. La valeur Y dans la chaîne veut dire vrai. Chaque position dans cette chaîne (commençant par 0) a une seule valeur correspondante (Y ou N) dans la chaîne.

par exemple, un Y à la position 1 (la deuxième valeur de la chaîne) signifie que les privilèges de renouvellement de l’adhérent sont refusés.

Retourner des documents

Ceci utilise le préfixe 09 pour le message de requête (message envoyé au système automatisé de circulation) et le préfixe 10 pour le message de réponse (message envoyé à la borne d’auto-prêt).

Message de requête :

Note

• <no block (Offline)> est un champ d’un seul caractère, soit « Y » ou « N », qui indique si la transaction est exécutée hors-ligne. Comme les transactions hors-ligne ne sont pas supportées, vous devez écrire « N » si vous testez ce message manuellement.

• <transactiondate> est un champ de date de 18 caractères au format : AAAAMMJJZZZZHHMMSS.

ZZZZ indique le fuseau horaire, si vous souhaitez utiliser votre fuseau horaire local, vous devez laisser 4 espaces, mais si vous voulez utiliser UTC (Temps Universel Coordonné), vous devez alors laisser 3 espaces vides et un Z.

Message de réponse :

Note

Alert type could have one of several values: 00 : Unknown 01: local hold 02: remote hold 03: ILL Transfer 04: transfer 99: Other

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.

Checkout items

This uses the request message prefix of 11 and the response message prefix of 12. It has similar syntax to the check-in command, outlined above except the prefixes are different.

Hold – May not yet be supported on some systems. This has a request message numerical prefix of 15 and a response message prefix of 16.

Message de requête :

Note

<holdmode> is a single character value. + means add a hold, - means delete a hold and * means change a hold.

Message de réponse :

Note

• <ok> is a single length value which is either 0 (for hold is not permitted or was not successful) or 1 (for hold is permitted and was successful).

• <available> is a single length value which is either Y or N. Y means the item is currently in the library, whilst N means the item is currently on loan/someone else has created a hold on the item.

Item information: This uses the request command prefix of 17, and the response command prefix of 18

Message de requête :

Note

See the check-in items command (described above) to find out what the <xact_date> value is.

The terminal password is optional.

Message de réponse :

Item status update This uses the request message prefix of 19 and the response message prefix of 20

Message de requête :

Note

<itemproperties> is not a fixed length value, and you can optionally write in values such as item size and these values will be stored in the Koha database for the item.

Message de réponse :

Note

<itempropertiesok> is a single length character value which is either 0 or 1. 1 identifies that the <itemproperties> value defined in the item status update request message was successfully stored in the Koha database.

Patron status

This uses the request message prefix 23 and the response message prefix of 24.

Message de requête :

Message de réponse :

Note

The value displayed for <patronvalidity> is Y (valid) and N (invalid) The value in the <YYYYMMDD> < HHMMSS> is the current date/time.

The reason for the gap between the two values is to define that you want to use localtime rather than UTC.

Patron enable - This is not yet supported. This uses the request message prefix of 25 and the response message prefix of 26

Note

This command undoes the block patron command.

Message de requête :

Message de réponse :

Renew This uses the request message prefix of 29 and the response message prefix of 30

Message de requête :

Note

• <thirdpartyallowed> is a single character value which is either Y or N. If it is Y then third parties can renew items.

• <noblock> is a single character value which is either Y or N. If it is Y then this means that the item was checkin/out when the ACS was offline.

• <nbduedate> is the transaction date of checkin/checkout when the ACS was offline.

• <feeacknowledged> is a single character value which is either Y or N. This indicates if the user accepts the fee associated with the item they are renewing.

Message de réponse :

Note

• <ok> is a single character value which is either 0 or 1. A value of 1 means the item was successfully renewed, 0 means item was not successfully renewed.

• <renewalok> is a single character value which is either Y or N. The logic for the setting of the value of <renewalok> is Y is set when the item is already checkout by the user and so it should be desensitized thereby renewing it, whereas N is set if the item is not already checkout to the patron and so it should not be renewed.

In other words don’t let patrons renew books when they are not currently checked out to them.

• <magneticmedia> is a single character value which is either Y (for yes), N ( for no), or U (for unknown).

• <mediatype> is a three numerical character long value. For a list of the values go to: http://multimedia.3m.com/mws/media/355361O/sip2-protocol.pdf

End session

This uses the request message prefix of 35 and the response message prefix of 36

Message de requête :

Message de réponse :

Note

<success_or_failure> is either Y for success or N for failure.

Fee Paid – May not be implemented yet. This uses a request message prefix of 37 and a response message prefix of 38

Message de requête :

Note

• <feetype> is a two numerical character value which is between 01 and 99. To see a list of fee type values go to http://multimedia.3m.com/mws/media/355361O/sip2-protocol.pdf

• <paymenttype> is a two character numerical value between 00 and 99. 00 is cash, 01 is Visa, and 02 is credit card.

• <currencytype> is a 3 alphanumeric character long value identifying the currency the fee paid was in.

Message de réponse :

Note

<paymentaccepted> is a single alphanumeric character long value which is either Y (payment has been accepted) or N (payment has not been accepted).

Patron information

This uses the request message prefix of 63 and the response message prefix of 64

Message de requête :

Message de réponse :

Note

<valid patron> is Y for valid and N for not valid.

Note

<hold itemcount><overdueitemcount><chargeditemscount><fienitemscount><recallitemscount><unavaliableholdscount> are all 4 numerical character long values.

Renew all

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

Message de requête :

Message de réponse :

Note

• <renewedcount> is a 4 numerical character long value denoting the number of items that were renewed.

• <unrenewedcount>, has the same format as the <renewedcount> but it denotes the number of items not renewed.

Login

This uses the request message prefix of 93, and the response message prefix of 94.

Message de requête :

Note

<UIDalgorithm> and <PWDalgorithm> are one character long values indicating the type of algorithm to use to encrypt the loginuserid and loginpassword respectively.

Writing in the value of 0 means these values will not be encrypted.

Response message: 941 is a successful login. 940 is an unsuccessful login [connection closed by foreign host.] is a unsuccessful login

Resend

This requests the receiving device to resend its last message.

SC -> ACS resend request is 97

ACS -> SC resend request is 96

Status of the ACS and SC

This has the request message prefix of 99 and the response message prefix of 98.

Message de requête :

Note

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

Message de réponse :

Note

If you get the response message ‘96’ this means that the request message is not valid/understood.

Troubleshooting SIP2

Can’t connect to remote host when writing in the command telnet localhost <portnumber>

3 solutions for this issue to try are:

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.

To access the SIP2 logs in your Koha home directory navigate to the following directory: /var/log/koha/<instancename>

Then view the output of the sip-error.log and the sip-output.log files which give more detailed information about the SIP2 error.

• cat sip-error.log

• cat sip-output.log

Useful links on SIP2 commands:

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 is a protocol used for file discovery over networks and network authentication.

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.

However Koha cannot sync data up to the LDAP server, thus the data traffic when using LDAP is only one directional.

Auth_By_Bind is set to 1 where a Microsoft Windows Active Directory system is in use in the LDAP database.

Before going through the steps to configure LDAP you will need the following information/actions from the organisation

• The organisation will need to open a port to allow access to their AD from the server.

• Information on the access to the AD server (IP address/hostname, port, SSL info)

• Information on the configuration of the AD server (relevant OUs, DCs, CN formats relative to usernames)

• Mapping between AD fields and Koha fields, including defaults

• Default values for things not provided by AD (categorycode, branchcode for example)

• To authenticate a user do we bind as them (seems to be common for AD) or do we use an account and login with that and then check? If the latter, we’ll need details of how to log in

• Do the existing usernames in Koha match the usernames that we’ll be using to look them up in AD? If so, good. If not, how will we deal with duplicate users?

Steps to set up LDAP with your Koha instance

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 Open the koha-conf.xml file with root permissions: sudo vi koha-conf.xml

3 Scroll down to the line containing ‘<useldapserver>0</useldapserver>’ and change it to: <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>

5 Save and exit the koha-conf.xml file

6 Check the LDAP connection works by writing in:

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

Note

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

Note

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.

About the mapping fields (the fields highlighted green) <city is= »l »>Athens, OH</city>

The left hand column name (highlighted yellow) is the name of the column in the LDAP database.

The column name inside quote marks (highlighted pink) is the name of the column in the Koha database. NOTE: This can be filled with any value if there is no equivalent column name in the Koha database as exists in the LDAP database.

The value highlighted cyan is the default value for the specified Koha and LDAP columns. So in the above example all user records in the Koha and LDAP databases will by default have the city value of ‘Athens, OH’.

Example of the LDAP configurations:

<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>

The values in the mapping area are not always the same, and it depends on what is in your organisations LDAP database. For example some organisations do not use <userid> instead each user is only identified by the <email> field and so no <userid> is written.

Troubleshooting LDAP

The log that LDAP errors are printed to depends on several factors:

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>/