Home / Documentation

wumpus_ docs

Everything you need to know about deploying, configuring, and mastering the Wumpus desktop search engine on Linux systems.

The Hunt for Wumpus

An international organization, dedicated to the pursuit of knowledge and the unraveling of mysteries, embarked on a digital expedition. Their mission: to find the elusive Wumpus, not a creature of flesh and blood, but a legendary anomaly whispered about in the deepest corners of the internet. They deployed sophisticated algorithms, scoured forgotten forums, and deciphered encrypted messages, all in the hope of pinpointing the Wumpus's digital footprint in the vast expanse of cyberspace.

01 Overview

Wumpus is a high-performance desktop search engine designed for Linux environments. Built from the ground up for speed and efficiency, it provides real-time file system indexing and instant full-text search across millions of documents.

100M+

Files indexed

<50ms

Search latency

GPL

Open source license

02 Prerequisites

Before installing Wumpus, ensure your system meets the following requirements:

System Requirements

Operating System: Linux kernel 2.6 or newer (Ubuntu, Debian, Fedora, Arch, etc.)
Compiler: GCC/G++ (for building from source)
Memory: 256 MB RAM minimum (1 GB+ recommended for large collections)
Disk: Proportional to your file collection size

03 Installation

Follow these steps to compile and install Wumpus from source:

terminal

# Download the latest release
wget https://stefan.buettcher.org/cs/wumpus/wumpus-2011-11-10.tar.gz

# Extract the archive
tar xzf wumpus-2011-11-10.tar.gz
cd wumpus

# Build from source
./configure && make

# Install system-wide (optional)
sudo make install

Kernel Patch Required

For real-time file system monitoring, you'll need to apply the fschange kernel patch. See the Kernel Patch section for details.

04 First Run

After installation, you're ready to index your first directory and run a search query:

terminal

# Index your home directory
wumpus index --path ~/Documents

# Run your first search
wumpus search "project proposal"

# Search with filters
wumpus search "budget report" --type pdf --after 2024-01-01

# View index statistics
wumpus stats

You're all set!

Wumpus will now automatically monitor your indexed directories and update the search index in real-time. No manual re-indexing required.

05 Indexing Engine

The Wumpus indexing engine uses an inverted index data structure to map terms to their locations across your file system. This enables sub-millisecond lookups even on collections with millions of files.

Incremental Updates

Only changed files are re-indexed. No full rebuilds needed when documents are added, modified, or deleted.

Scalable Architecture

Tested on collections with hundreds of gigabytes and millions of documents. Handles enterprise workloads effortlessly.

Supported File Types

.txt

.pdf

.doc

.html

.xml

.csv

.json

.log

06 Search Interface

Wumpus provides both a command-line interface and a built-in web server for interactive searches:

CLI Search

# Basic search
wumpus search "search query"

# Boolean operators
wumpus search "error AND timeout"
wumpus search "config OR configuration"

# Phrase search
wumpus search "exact phrase match"

# Filter by file type
wumpus search "deploy" --type log

# Filter by date range
wumpus search "report" --after 2024-01-01 --before 2024-12-31

Web Interface

Start the built-in web server for a browser-based search experience:

# Start web server on default port 8080
wumpus serve

# Custom port
wumpus serve --port 3000

# Then open in browser
# http://localhost:8080

07 Configuration

Wumpus is configured through a simple key-value configuration file. Here are the most important settings:

wumpus.conf

# Wumpus Configuration File

# Database location
index.path=/var/lib/wumpus/database

# Directories to monitor
index.watch=/home/user/Documents
index.watch=/home/user/Projects

# Update interval (seconds)
index.interval=5

# Multi-user mode
server.multiuser=true

# Memory allocation (MB)
index.memory=512

# Exclude patterns
index.exclude=*.tmp
index.exclude=*.cache
index.exclude=node_modules/**

08 CLI Reference

Complete command reference for the Wumpus command-line interface:

Command	Description
wumpus index	Index a directory
wumpus search	Search indexed files
wumpus serve	Start web interface
wumpus stats	Show index statistics
wumpus status	Check daemon status
wumpus help	Show help message

09 Multi-User Mode

Wumpus supports concurrent access from multiple users on shared servers. Enable multi-user mode to allow team-wide file search:

# Enable multi-user mode in config
server.multiuser=true
server.port=8080

# Each user gets their own search session
# Index is shared across all users
# No performance degradation with concurrent queries

Pro Tip

For shared environments with 10+ users, increase the index.memory setting to ensure optimal performance.

10 Performance Tuning

Optimize Wumpus for your specific workload with these tuning recommendations:

Small Collections (<10GB)

index.memory=256 | index.interval=5

Medium Collections (10-100GB)

index.memory=512 | index.interval=3

Large Collections (100GB+)

index.memory=1024 | index.interval=1 | index.compress=true

11 Troubleshooting

Common issues and their solutions:

x Build fails with "zlib.h not found"

# Ubuntu/Debian
sudo apt install zlib1g-dev

# Fedora/RHEL
sudo dnf install zlib-devel

x Index is slow or unresponsive

Increase memory allocation in your config file and ensure sufficient disk I/O bandwidth.

x Permission denied errors

Run with sudo or add your user to the wumpus group: sudo usermod -aG wumpus $USER

12 Kernel Patch: fschange

Advanced: Requires Kernel Recompilation

The fschange patch modifies the Linux kernel. Only proceed if you're comfortable with kernel development and have a backup system available.

fschange is a kernel patch that enables recursive file system monitoring at the block level. Unlike inotify, it captures all changes including metadata updates, making it ideal for real-time search indexing.

Setup Guide

# Clone the fschange patch
git clone https://github.com/stefanbuettcher/fschange.git

# Apply to your kernel source
cd /usr/src/linux
patch -p1 < ../fschange/fschange.patch

# Recompile kernel
make menuconfig
make -j$(nproc)
sudo make modules_install install

Configuration

After applying the patch, configure Wumpus to use fschange for real-time monitoring:

# Enable fschange in wumpus config
index.backend=fschange
index.watch=/home
index.watch=/var/www
index.recursive=true

13 FAQ

How much disk space does the index require?

The index typically requires 10-30% of the total size of indexed files. For example, indexing 100GB of text files will create an index of approximately 10-30GB, depending on file types and compression settings.

Can I use Wumpus on macOS?

Wumpus primarily targets Linux. While the 2011 release contains experimental macOS support, full functionality (especially real-time indexing via fschange) is Linux-only. For macOS, consider alternatives like Spotlight or Recoll.

Is Wumpus still maintained?

The last official release was in November 2011. While not actively developed, Wumpus remains fully functional and is still used in academic research for information retrieval experiments. The codebase is stable and well-tested.

14 Community

Connect with other Wumpus users and developers:

Email Support

[email protected]

GitHub

View source code and report issues