How to Install Elastic Search

📚 Why Elasticsearch + Unicode Matters

Traditional search engines struggle with:

• Diacritics (e.g., زبر، زیر)

• Word variations

• Complex scripts like Arabic and Urdu

Elasticsearch, combined with the ICU analyzer, solves this by:

• Normalizing Unicode text

• Ignoring diacritics

• Improving tokenization for non-Latin scripts

👉 Result: Users can search “اسلام”, “الإسلام”, or even slightly misspelled variants and still get accurate results.

---

⚙️ Step 1: Install Elasticsearch

Install Java (Prerequisite)

sudo apt update
sudo apt install openjdk-11-jdk -y

Install Elasticsearch (Compatible Version)

wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-7.17.0-amd64.deb
sudo dpkg -i elasticsearch-7.17.0-amd64.deb

---

🌐 Step 2: Configure Elasticsearch

Edit configuration:

sudo nano /etc/elasticsearch/elasticsearch.yml

Add:

cluster.name: koha-cluster
node.name: koha-node-1
network.host: 127.0.0.1
http.port: 9200

---

🌍 Step 3: Enable Unicode Support (ICU Plugin)

This is the most critical step for multilingual libraries.

sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo systemctl restart elasticsearch

🔍 Why ICU?

The ICU plugin enables:

• Unicode normalization

• Proper handling of Arabic/Urdu morphology

• Diacritics-insensitive search

---

🔗 Step 4: Connect Koha with Elasticsearch

Install integration package:

sudo apt install koha-elasticsearch -y

Enable Elasticsearch in Koha:

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

Add:

elasticsearch: 1

---

🧠 Step 5: Configure Unicode Analyzer in Koha

Edit mapping file:

/etc/koha/sites/library/elasticsearch/mappings/biblios.yaml

Add a custom analyzer:

analyzer:
  my_unicode_analyzer:
    type: custom
    tokenizer: standard
    filter: [lowercase, icu_normalizer]

---

🔄 Step 6: Rebuild Index

sudo koha-elasticsearch --rebuild -v -f library

This step ensures all bibliographic records are indexed with Unicode support.

---

⚡ Step 7: Enable Plack for High Performance

Koha without Plack reloads Perl for every request—this slows everything down.

With Plack:

• Faster OPAC

• Reduced server load

• Persistent processes

Install Plack

sudo apt install libplack-perl -y

Enable Plack

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

Add:

plack: 1

---

🔧 Step 8: Configure Plack Workers

Edit:

/etc/koha/sites/library/koha-conf.xml

Add:

<plack_workers>5</plack_workers>

---

▶️ Step 9: Start Plack

sudo koha-plack --enable library
sudo koha-plack --start library

Restart everything:

sudo systemctl restart apache2
sudo systemctl restart elasticsearch
sudo koha-plack --restart library

---

🧪 Testing Your Setup

Try searching in OPAC:

• اسلام

• القرآن

• Hadith / حدیث

✔ Expected results:

• Diacritics ignored

• Variants matched

• Faster response

---

⚠️ Common Issues & Solutions

Elasticsearch not responding

curl http://localhost:9200

Unicode search not working

• Check ICU plugin installation

• Rebuild index

Plack not running

sudo koha-plack --status library

---

📈 Performance Optimization Tips

• Set Elasticsearch memory:

/etc/elasticsearch/jvm.options

-Xms1g
-Xmx1g

• Use 4–8 Plack workers depending on RAM

• Schedule regular indexing for large catalogs

---

🔬 Advanced Enhancements

Take your Koha to the next level:

• Synonym filters for Islamic terminology

• Autocomplete using edge-ngram

• Authority control integration

• Relevance ranking (boost title fields)

---

📖 Conclusion

By integrating Elasticsearch with Unicode support and enabling Plack, your Koha becomes:

• Multilingual

• Faster

• More intelligent

This setup is especially critical for institutions dealing with Islamic studies, Arabic, and Urdu collections, where traditional search fails to deliver precision.

---

📚 Further Reading (For Deeper Understanding)

• Multilingual Information Retrieval Systems

• Unicode Normalization and ICU Standards

• Elasticsearch Indexing & Ranking Algorithms

• Koha Architecture (Zebra vs Elasticsearch)

• PSGI/Plack Performance Engineering

---

📑 References

• Koha Community Documentation (Elasticsearch Integration)

• Elasticsearch Official Documentation (Analysis Plugins)

• Unicode ICU Documentation

• PSGI/Plack Perl Framework Guides

---

If you want, I can also prepare:

• A fully optimized Urdu/Arabic biblios.yaml file

• A ready-to-deploy Koha DevOps script

• Or a research paper-style write-up for publication

How to Fix “Connection Refused” Error in PuTTY While Accessing a Virtual Machine

Abstract

When attempting to access a virtual machine using PuTTY, users often encounter the error “Network error: Connection refused.” This issue indicates that the target system is reachable, but the SSH service is either not running or not accepting connections on the specified port. This blog provides a clear, practical, and technically grounded guide to diagnose and resolve the problem effectively.

---

Introduction

Secure remote access is a fundamental requirement in modern system administration. Tools like PuTTY allow users to connect to Linux-based virtual machines using the SSH protocol. However, connection errors can interrupt workflows, especially in environments such as Koha library systems or cloud-based servers.

One of the most common issues is:

PuTTY Fatal Error: Network error: Connection refused

Understanding the root cause is essential for resolving it quickly.

---

What Does “Connection Refused” Mean?

This error occurs when:

• Your system successfully reaches the server’s IP address

• But the server rejects the connection request on the specified port

Technically, this means:

• No service (like SSH) is listening on that port

• Or a firewall is actively blocking the connection

---

Step-by-Step Troubleshooting Guide

1. Verify SSH Service Status

The most common cause is that the SSH service is not running.

Log in to your VM locally (or via console) and run:

sudo systemctl status ssh

If inactive, start it:

sudo systemctl start ssh
sudo systemctl enable ssh

If SSH is not installed:

sudo apt update
sudo apt install openssh-server

---

2. Confirm SSH Port Configuration

SSH runs on port 22 by default, but it may be changed for security reasons.

Check configuration:

sudo nano /etc/ssh/sshd_config

Look for:

Port 22

If the port is different (e.g., 2222), update PuTTY accordingly.

---

3. Check Firewall Settings

On Ubuntu (UFW):

sudo ufw status

Allow SSH if needed:

sudo ufw allow 22
sudo ufw reload

A blocked port will prevent SSH connections even if the service is running.

---

4. Ensure SSH Port is Listening

Run:

ss -tulnp | grep :22

Expected output:

LISTEN 0 128 0.0.0.0:22

If no output appears, SSH is not active.

---

5. Test Connectivity from Client Machine

From your local computer:

ping 10.40.3.125
telnet 10.40.3.125 22

Interpretation:

• Ping works → Network is fine

• Telnet fails → SSH service issue

---

6. Check Virtual Machine Network Configuration

If using VMware or VirtualBox:

• NAT mode may restrict access

• Switch to Bridged Adapter for direct network access

This is a frequent issue in local virtual environments.

---

7. Restart SSH Service

After changes:

sudo systemctl restart ssh

---

8. Reconnect Using PuTTY

In PuTTY:

• Host Name: 10.40.3.125

• Port: 22 (or custom)

• Connection Type: SSH

Click Open and log in.

---

Practical Insight: Why This Happens in Koha Environments

In systems like Koha (as seen in your case running on port 8080):

• Web interface works → server is active

• SSH fails → service not enabled or blocked

This often occurs in:

• Fresh installations

• Minimal Linux setups

• Security-hardened environments

---

Security Considerations

• Prefer key-based authentication over passwords

• Restrict SSH access using firewall rules

• Disable root login in production

• Consider changing the default SSH port

---

Conclusion

The “Connection refused” error is not a network failure but a service-level issue. By systematically verifying SSH service status, port configuration, firewall rules, and VM networking, the problem can be resolved efficiently. Mastering these diagnostics is essential for anyone working with virtual machines, especially in research, library systems, and cloud environments.

---

Suggested Further Reading

To deepen your understanding, explore:

• SSH Key-Based Authentication and Security

• Linux System Services (systemctl)

• Firewall Management (UFW and iptables)

• Virtual Machine Networking (NAT vs Bridged)

• Remote Server Administration Best Practices

• Koha System Deployment and Server Configuration

---

References

1. Barrett, D. J., Silverman, R. E., & Byrnes, R. G. SSH, The Secure Shell: The Definitive Guide. O’Reilly Media.

2. Nemeth, E., Snyder, G., & Hein, T. UNIX and Linux System Administration Handbook. Pearson.

3. Ubuntu Documentation. OpenSSH Server Guide.

4. Ylonen, T., & Lonvick, C. (2006). The Secure Shell (SSH) Protocol Architecture. RFC 4251.

---

Enhancing Koha OPAC: Display Item Types with Icons (Koha 25.11 Guide)

If you're using Koha 25.11 and want to improve your OPAC interface, one powerful customization is displaying item types (Book, Thesis, Article, etc.) with icons alongside each bibliographic record.

This improves usability and gives your OPAC a more modern, professional look.

In this guide, we’ll walk through a complete, working solution to achieve this.

---

🚀 Why Display Item Types?

By default, Koha OPAC may not clearly highlight the type of material in search results. Adding item types helps users quickly identify:

• 📘 Books

• 🎓 Theses

• 📰 Articles

• 📜 Manuscripts

• 📖 Periodicals

---

🔍 Understanding the Data

Koha stores item types in two places:

• Database (itemtypes table) → codes like BK, THES

• MARC field 942$c → often contains descriptions like Books, Thesis

⚠️ Important:
XSLT reads MARC data, so you must match values like:

Books (not BK)

---

🛠️ Step 1: Add Icon Files

Create a folder for item type icons:

/usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/images/itemtypes/

Add your icon images:

book.png
thesis.png
article.png
manuscript.png
periodical.png
default.png

---

🧩 Step 2: Modify XSLT File

Open the OPAC XSLT file:

/usr/share/koha/opac/htdocs/opac-tmpl/bootstrap/en/xslt/MARC21slim2OPACResults.xsl

Inside the template:

<xsl:template match="record">

Insert the following code where you want the item type to appear (usually near the title):

<!-- ===== ITEM TYPE WITH ICON START ===== -->

<xsl:variable name="itype" select="normalize-space(marc:datafield[@tag='942']/marc:subfield[@code='c'])"/>

<span class="itemtype-label">

    <xsl:choose>

        <xsl:when test="$itype='Books'">
            <img src="/opac-tmpl/bootstrap/images/itemtypes/book.png" class="itemtype-icon"/>
            Book
        </xsl:when>

        <xsl:when test="$itype='Thesis'">
            <img src="/opac-tmpl/bootstrap/images/itemtypes/thesis.png" class="itemtype-icon"/>
            Thesis
        </xsl:when>

        <xsl:when test="$itype='Articles'">
            <img src="/opac-tmpl/bootstrap/images/itemtypes/article.png" class="itemtype-icon"/>
            Article
        </xsl:when>

        <xsl:when test="$itype='Manuscript'">
            <img src="/opac-tmpl/bootstrap/images/itemtypes/manuscript.png" class="itemtype-icon"/>
            Manuscript
        </xsl:when>

        <xsl:when test="$itype='Periodicals'">
            <img src="/opac-tmpl/bootstrap/images/itemtypes/periodical.png" class="itemtype-icon"/>
            Periodical
        </xsl:when>

        <xsl:otherwise>
            <img src="/opac-tmpl/bootstrap/images/itemtypes/default.png" class="itemtype-icon"/>
            <xsl:value-of select="$itype"/>
        </xsl:otherwise>

    </xsl:choose>

</span>

<!-- ===== ITEM TYPE WITH ICON END ===== -->

---

🎨 Step 3: Add Styling

Go to:

Koha → Administration → System Preferences → OPACUserCSS

Add:

.itemtype-label {
    display: inline-flex;
    align-items: center;
    gap: 6px;
    background: #f1f5f9;
    padding: 4px 8px;
    border-radius: 6px;
    font-size: 12px;
    font-weight: 600;
}

.itemtype-icon {
    width: 18px;
    height: 18px;
}

---

🔄 Step 4: Restart Services

Run:

sudo systemctl restart koha-common
sudo systemctl restart apache2

Then refresh your browser (Ctrl + F5).

---

🎯 Final Result

Your OPAC search results will now display clean, visual item types like:

• 📘 Book

• 🎓 Thesis

• 📰 Article

• 📜 Manuscript

• 📖 Periodical

Each with a matching icon and label.

---

⚠️ Troubleshooting

Icons not showing?

• Check file path:

/opac-tmpl/bootstrap/images/itemtypes/book.png

• Test in browser:

http://your-koha/opac-tmpl/bootstrap/images/itemtypes/book.png

---

Wrong item type showing?

• Verify MARC field:

942$c

• Ensure values match exactly:

Books, Thesis, Articles, Manuscript, Periodicals

---

💡 Pro Tips

• Use SVG icons for better quality

• Keep icon sizes consistent

• Avoid hardcoding too many conditions — keep it maintainable

---

🎉 Conclusion

With just a small XSLT customization, you can significantly enhance the user experience of your Koha OPAC. Clear item type labels and icons make browsing faster, easier, and more visually appealing.

---

🚀 What’s Next?

You can further enhance your OPAC by:

• Adding filters by item type

• Grouping results (Books / Theses / Journals)

• Customizing the detail page layout

---

If you need help with advanced customization, feel free to explore further or extend this implementation.

Happy customizing! 🎯

Mastering Metadata Cleanup in MarcEdit

Cleaning metadata in MarcEdit is a systematic process. It typically begins by "breaking" a .mrc (binary) file into the mnemonic .mrk (text) format, performing batch edits, and then compiling it back into .mrc.

1. Batch Deleting Unwanted Fields

To remove entire tags (like local 9XX fields or vendor-specific 655 tags) across your entire file:

• Path: Tools > Add/Delete Field (Shortcut: F7)
• Example: Removing all 949 local call number fields.
• Action: Enter 949 in the Field box and click Delete Field.

Pro Tip: Use the Preview button first. It’s the best way to ensure you aren't accidentally deleting essential data.

2. Targeted Subfield Editing

Use this when you need to change data within a field, such as stripping proxy prefixes from URLs or fixing punctuation.

Path: Tools > Edit Subfield Data (Shortcut: F9)

Goal	Field / Subfield	Field Data	Replace With
Remove "Electronic book" from 655	655 / a	Electronic book.	(Leave Empty)
Update Proxy Prefix in 856	856 / u	oldproxy.com/	newproxy.com/
Add trailing period to 245	245 / a	([^.])\s*$	$1. (Check Regex)

3. Updating Indicators

Indicators control how data is indexed. A common task is fixing the second indicator in the 245 field to account for "The" or "A".

• Path: Tools > Edit Indicators (Shortcut: F8)
• Example: Changing 050 \4 (Local LC Call Number) to 050 00 (LC assigned by LC).

4. Modernizing with the RDA Helper

The RDA Helper automates the transition from AACR2 to modern RDA standards.

• Path: Tools > RDA Helper
• What it does:
  • Adds 336 (Content), 337 (Media), and 338 (Carrier) fields.
  • Converts abbreviations (e.g., "p." to "pages").
  • Removes the 245 $h [electronic resource] GMD.

5. Global Find/Replace & Regex

For general text cleaning (like fixing typos or removing specific phrases), use Edit > Replace (Ctrl+H). For complex patterns, enable Use Regular Expressions.

Regex Example: To find cases where a subfield $b is missing a leading space, search for ([^\s])\$b and replace with $1 $b.

---

Once your edits are complete, navigate to File > Compile File to save your work back into the .mrc format for your ILS.

Display in OPAC of Different datatypes

⚠️

Diagnosis: Your Koha is defaulting to "text" because the Item Type Codes in your MARC (952$y) do not match the codes in your Koha Administration.

Solution 1: Define Item Types in Koha Admin

Go to Koha Administration → Item types and create these entries exactly as they appear in your MARC data:

Code (Must match 952$y)	Description	Suggested Icon
BK	Book	bridge/book.gif
ARTICLE	Journal Article	bridge/periodical.gif
THESIS	Research Thesis	bridge/thesis.gif
BIBLIO	Bibliographic Entry	bridge/reference.gif

Solution 2: Adjust MARC Leader (LDR) for Theses

If an item is missing, Koha looks at Position 06 of the Leader. To differentiate theses from standard books:

• Books/Articles: Set Position 06 to a (Language material).
• Theses/Manuscripts: Change Position 06 to t (Manuscript language material).

MarcEdit Fix: Click the LDR field → Type of Record → Select "t-Manuscript language material".

Solution 3: Enable XSLT System Preferences

Ensure your system is configured to show icons in the OPAC:

1. Search for DisplayOPACiconsXSLT → Set to Show.
2. Search for OPACNoItemTypeImages → Set to Show (this enables images).

Solution 4: Collection Codes (CCODE)

To see "Sirah Hub" or "SNK Bibliography" clearly next to the item type, add Collection Codes:

1. Go to Admin → Authorized values → CCODE.
2. Add values: SIRAH (Sirah Research Hub) and SNK (Sher Nowrooz Khan).
3. Add the tag to your MARC: =952 \\$8SNK

Standardizing these administrative settings ensures your scholarly Hub is visually organized and professional for researchers.

Marc Tags of Different Data Types

Koha 25.11 "Sirah Hub" Test Suite

MARC21 Record Samples for Multilingual & Scholarly Validation

1. Physical Book (Multi-Holding) Consolidation Test

=LDR 00000nam 2200000ia 4500 =001 hub-book-001 =020 \\$a9789694080123 =100 1\$aNomani, Shibli. =245 10$aSirat-un-Nabi /$cShibli Nomani. =260 \\$aLahore :$bReligious Publications,$c2010. =952 \\$aIRI$bIRI$pML100445-IRI$yBK$t1$o297.63 NOM =952 \\$aSSMK$bSSMK$p120684-SSMK$yBK$t1$o297.63 NOM

2. Journal Article (Analytical Entry) 773 Linking Test

=LDR 00000nab 2200000ia 4500 =001 hub-art-001 =100 1\$aAhmad, Zohaib. =245 10$aProphetic Diplomacy in the Medinan Period :$ba bibliometric review. =773 0\$tJournal of Islamic Thought and Civilization$gVol. 10, No. 2 (2025)$x2070-0326 =856 40$uhttps://define.pk/articles/prophetic-diplomacy.pdf$zFull Text PDF

3. Thesis/Dissertation 502 Academic Test

=LDR 00000nam 2200000ia 4500 =001 hub-thesis-001 =100 1\$aAhmed, Rauf. =245 10$aMapping Sirah Literature in Pakistan :$ba comparative study of digital repositories. =502 \\$bPh.D.$cInternational Islamic University, Islamabad$d2026.

4. Virtual Bibliographic Citation (SNK) 510 Citation Test

=LDR 00000nam 2200000ia 4500 =001 hub-snk-045 =100 1\$aHamidullah, Muhammad. =245 10$aThe Life and Work of the Prophet of Islam. =510 4\$aSher Nowrooz Khan, Bibliography of Sirah Literature$cEntry No. 45. =952 \\$aSNK_BIB$bSNK_BIB$pSNK-45$yBIBLIO$t1$oREF SNK-45

🔍 Validation Checklist

• The "Split" Display: Does "Nomani" show both IRI and SSMK availability in the OPAC results?
• Link Integrity: Is the "Full Text PDF" link in the Article record clickable?
• Note Visibility: Does the 510 tag appear clearly in the "Description" or "Notes" tab of the Hamidullah record?
• Virtual Branch: Verify that the SNK_BIB item is listed as "Not for Loan."

The SNK Bibliography Strategy

Integrating Historical Citations into the Modern Hub

Managing the Sher Nowrooz Khan (SNK) bibliography requires a shift in perspective. We are not just cataloging books; we are performing a Bibliometric Mapping of Sirah literature, acknowledging the history of its documentation.

1. The "Virtual Branch" Concept

In Koha, create a library code specifically for this bibliography: SNK_BIB. This allows you to track items that exist in the "world index" even if you don't physically own them yet.

• The Barcode: Use the Entry Number from the printed bibliography (e.g., SNK-124).
• The Status: Set these to a custom "Not for Loan" status: Bibliographic Citation Only.

2. Scholarly Acknowledgement (Tag 510)

To give Sher Nowrooz Khan proper "Academic Credit," use MARC Tag 510. This formally links the record to his scholarly work.

510 $a: Sher Nowrooz Khan, Bibliography of Sirah Literature
510 $c: Entry No. 124

Result: Users see a note stating: "This book is acknowledged/cited in Sher Nowrooz Khan's Bibliography."

Handling the 4 SNK Entry Types

Entry Type	Hub Action	Deduplication Strategy
Books	Create "Master Record"	Match by ISBN/Title. Merge physical holdings into one 510 tag.
Journal Articles	Create "Analytical Record"	Use 773 tag to link to the Journal title.
Theses	Create "Thesis Record"	Match by Author+Title. Use 502 tag for University info.
Library Holdings	Location Metadata	Add an item with the NLP branch code if SNK cites it there.

The "Ghost Duplicate" Solution

To prevent having a "Physical Record" (IRI) and a "Cited Record" (SNK) as two separate entries, use the MarcEdit Merge Tool:

1. Source: Your existing Koha records.
2. Merge File: The SNK Bibliography records.
3. Action: Tell MarcEdit to only add the 510 tag to the existing record instead of creating a new one.

This approach acknowledges that Sher Nowrooz Khan "found" these works before they were digitally available, adding immense historical value to your PhD research.