How to Enable the Z39.50 Server in Koha

Koha includes a built-in Z39.50 server that allows other library systems and Interlibrary Loan (ILL) networks to discover your catalog and request items from you as a potential lender. This server is disabled by default and requires a small configuration change to activate.

If your ILL network has told you that your Z39.50 connection is invalid or that your library cannot be found as a lender, this guide is for you.

What Is the Koha Z39.50 Server?

When Koha is installed, it runs a Zebra search daemon that powers its internal catalog search. Zebra can also expose a public Z39.50 endpoint that external systems can query. This is separate from the Z39.50 client used for copy cataloging — this is the server side, which lets others search your catalog.

Common use cases:

• ILL networks (e.g., ILLIAD, Tipasa, RapidILL) discovering your holdings
• Other libraries importing records from your catalog
• Union catalogs aggregating your holdings

Prerequisites

• Root/sudo access to the Koha server
• Koha installed via the official Debian/Ubuntu packages (koha-common)
• The instance name of your Koha installation (run koha-list if unsure)

Step 1: Find Your Instance Name

SSH into your server and run:

koha-list

This returns the name of your Koha instance (e.g. library). You will use this in the commands below.

Step 2: Back Up koha-conf.xml

Always back up before editing:

sudo cp /etc/koha/sites/INSTANCE/koha-conf.xml \
        /etc/koha/sites/INSTANCE/koha-conf.xml.bak

Replace INSTANCE with your instance name from Step 1.

Step 3: Edit koha-conf.xml

Open the file in a text editor:

sudo nano /etc/koha/sites/INSTANCE/koha-conf.xml

There are three comment blocks to uncomment. Find each one and remove the surrounding <!-- and --> markers.

3a. Uncomment the Listen Directive

Find this block near the top of the file (around line 8–10):

<!--
<listen id="publicserver" >tcp:@:</listen>
-->

Change it to (note: also add the port 2100):

<listen id="publicserver">tcp:@:2100</listen>

3b. Uncomment the Server Block

Find this block under the PUBLICSERVER’S BIBLIOGRAPHIC RECORDS comment (around line 149):

<!--
<server id="publicserver"  listenref="publicserver">
    <directory>/var/lib/koha/INSTANCE/biblios</directory>
    ...
</server>

Remove the <!-- at the start and the --> at the end to uncomment the entire block.

3c. Uncomment the Serverinfo Block

The <serverinfo> and closing --> are part of the same comment block as the server section above. After removing the outer <!-- / -->, the serverinfo tag will also be active:

<serverinfo id="publicserver">
    <ccl2rpn>/etc/koha/zebradb/ccl.properties</ccl2rpn>
    <user>kohauser</user>
    <password>YOURPASSWORD</password>
</serverinfo>

Note: The password here is the internal Zebra authentication credential, not a patron password. It is set during installation and does not need to be changed.

Step 4: Restart the Zebra Daemon

Apply the configuration change by restarting the Zebra service:

sudo koha-zebra --restart INSTANCE

Verify it is running and listening on port 2100:

sudo koha-zebra --status INSTANCE
ss -tlnp | grep 2100

You should see output similar to:

LISTEN   *:2100   *:*   users:(("zebrasrv", ...))

Step 5: Open Port 2100 in Your Firewall

The Zebra daemon is now listening, but your server’s firewall must allow inbound traffic on TCP port 2100.

On AWS (Security Group)

1. Go to EC2 → Security Groups in the AWS Console
2. Find the security group attached to your Koha instance
3. Click Edit inbound rules → Add rule
4. Set: Type = Custom TCP, Port = 2100, Source = 0.0.0.0/0 (or restrict to your ILL network’s IP range)
5. Click Save rules

On a Linux Server (iptables / ufw)

UFW:

sudo ufw allow 2100/tcp

iptables:

sudo iptables -A INPUT -p tcp --dport 2100 -j ACCEPT

On-premise / Hosted

Contact your hosting provider or network administrator and ask them to open TCP port 2100 for inbound traffic.

Step 6: Verify the Connection

The preferred method is yaz-client, which performs a full Z39.50 handshake — not just a TCP check. Install it if needed:

sudo apt install yaz      # Debian/Ubuntu

Then connect:

yaz-client YOUR-SERVER-HOSTNAME:2100/biblios

For example:

yaz-client library.example.com:2100/biblios

A successful connection looks like:

Connecting...OK.
Sent initrequest.
Connection accepted by v3 target.
ID     : 81
Name   : Zebra Information Server/GFS/YAZ
Version: 2.2.7/5.34.0
Options: search present delSet scan sort namedResultSets

Type quit to exit. If you see “Connection accepted” your Z39.50 server is fully working.

Alternative — quick TCP-only check:

nc -zv YOUR-SERVER-HOSTNAME 2100

This only verifies the port is reachable, not that Z39.50 is responding correctly. Always use yaz-client for a definitive test.

Provide Coordinates to Your ILL Network

Once verified, give your ILL network the following details:

Troubleshooting

Port 2100 not listening after restart

Check the Zebra error log for XML parse errors:

sudo tail -50 /var/log/koha/INSTANCE/zebra-error.log

A common cause is a malformed koha-conf.xml after editing. Restore from backup and try again:

sudo cp /etc/koha/sites/INSTANCE/koha-conf.xml.bak \
        /etc/koha/sites/INSTANCE/koha-conf.xml
sudo koha-zebra --restart INSTANCE

Connection times out but port is open

Ensure Zebra is binding to all interfaces (*:2100) rather than localhost only. Check by running:

ss -tlnp | grep 2100

If you see 127.0.0.1:2100 instead of *:2100, verify the listen directive reads tcp:@:2100 (not tcp:localhost:2100).

ILL network still can’t find the library

• Confirm the hostname resolves correctly from outside your network
• Verify the database name is exactly biblios (case-sensitive)
• Ask the ILL network to clear any cached entry and re-test

Important Note for KohaSupport Managed Instances

If you are on a KohaSupport managed subscription, contact our support team to enable the Z39.50 server on your behalf. We will handle the configuration and firewall changes, and provide you with the correct connection coordinates to share with your ILL network.

Related Articles

• How to Add a Z39.50 Server for Copy Cataloging
• What is Z39.50 and Why is it Important?
• Interlibrary Loan in Koha