whois/ENVIRONMENT.md

WHOIS Project Environment Documentation

Project Overview

Project Name: mwhois - RFC 3912 compliant WHOIS server Working Directory: /root/whois Git Branch: master Last Updated: 2025-11-12

Infrastructure Migration Notice

CRITICAL: The original infrastructure at as60284.net has been DELETED and is NO LONGER AVAILABLE.

Previous Configuration (DEPRECATED)

• Previous remote: https://git.as60284.net/AXSY/whois.git
• Status: INFRASTRUCTURE DELETED - DO NOT USE

Current Configuration (ACTIVE)

• Primary Remote: git.photon.obnh.io (Production)
• Mirror Remote: git.proton.obr.sh (Disaster Recovery - automatic sync)
• User: olaf
• Organization: AXSY

Python Environment

Python Version

• Version: Python 3.12.10
• Location: /root/venv/bin/python3
• Note: System Python in global venv, no project-local venv

Dependencies

The project uses an embedded Python library:

• netaddr (included in /root/whois/netaddr/)
  • Purpose: IP address and network manipulation
  • License: Separate license included in netaddr folder
  • Status: Embedded for compatibility, updated when necessary

No Additional Dependencies

• No requirements.txt
• No pyproject.toml
• No Pipfile
• All dependencies are embedded or system-provided

Project Structure

/root/whois/
├── mwhoisd                 # Main WHOIS server (Python 3 script)
├── db/                     # Database directory
│   ├── ipv4/              # IPv4 address records
│   ├── domains/           # Domain name records
│   ├── as/                # AS number records
│   └── isd/               # ISD records
├── netaddr/               # Embedded netaddr library
├── add-as                 # Script to add AS records
├── add-as-batch           # Batch AS addition script
├── add-ip                 # Script to add IP ranges
├── add-ip-auto            # IP block wizard
├── add-ip-wind            # IP block wizard (ID instead of AS)
├── add-domain             # Domain addition script
├── add-isd                # ISD addition script
├── remove-as              # AS removal utility
├── check-axpo-as          # Axpo AS validation script
├── hwhois                 # Bash wrapper for custom whois queries
├── mwhois.log             # Server log file
├── README.txt             # Project documentation
├── LICENSE                # MIT License
├── NOTICE                 # Legal notices
└── .gitea-config.md       # Gitea instance configuration

Server Configuration

mwhoisd Configuration Variables (lines 8-11)

• LISTEN_ADDRESS: "::" (all IPv6 addresses, includes IPv4-mapped)
• LISTEN_PORT: 43 (standard WHOIS port)
• MAX_QUERY_SIZE: 128 bytes
• LOGFILE: /root/whois/mwhois.log

Runtime Requirements

• Must run as root to bind to port 43
• Requires write access to LOGFILE location
• Auto-creates db subdirectories on startup

Database Structure

Storage Format

• Filesystem-based storage (no external database)
• IPv4 records: db/ipv4/[IP]-[CIDR] (e.g., 10.0.0.0-8)
• Domain records: db/domains/[domain-name]
• AS records: db/as/[as-number]
• ISD records: db/isd/[isd-number]
• All records use CRLF line endings (RFC 3912 compliance)

Development Workflow

Running the Server

cd /root/whois
sudo ./mwhoisd  # Must run as root for port 43

Testing Queries

whois -h 127.0.0.1 10.0.0.1
whois -h 127.0.0.1 example.com
./hwhois [query]  # Uses local server

Adding Records

./add-ip          # Add IPv4 ranges
./add-ip-auto     # Interactive IP block wizard
./add-domain      # Add domain records
./add-as          # Add AS records
./add-as-batch    # Batch add AS records
./add-isd         # Add ISD records
./remove-as       # Remove AS records

Git Configuration

Remote Repositories

See .gitea-config.md for complete configuration details.

Primary (Production):

• URL: https://git.photon.obnh.io/AXSY/whois.git
• SSH: git@git.photon.obnh.io:AXSY/whois.git
• User: olaf
• Status: ACTIVE

Mirror (Disaster Recovery):

• URL: https://git.proton.obr.sh/axsy/whois.git
• SSH: git@git.proton.obr.sh:axsy/whois.git
• User: olaf
• Status: ACTIVE (automatic sync from primary)
• Note: Read-only mirror, all pushes go to primary

Git User Configuration

git config user.name "Olaf"
git config user.email "admin@obr.sh"

Project History

Recent Changes (from git log)

• 2025-11-12: Migration to new git infrastructure (photon.obnh.io)
• 2025-07-31: Last mwhois.log update
• 2025-06-27: Added remove-as utility
• 2025-06-10: Added AS 60284 removal
• 2025-06-03: SCION SSUN ISD76 allocations (Semax AG, Litecom AG)
• 2025-05-13: Initial migration from external repository

Key Features

• RFC 3912 compliant WHOIS server
• IPv4 address lookups
• Domain name lookups
• AS (Autonomous System) number lookups
• ISD (SCION Isolation Domain) lookups
• Filesystem-based storage
• Python 3 compatible (migrated from Python 2.7)

Continuation Instructions for User "olaf"

Environment Recreation

1. Clone repository:

   git clone git@git.photon.obnh.io:AXSY/whois.git
   cd whois
   

2. Verify Python version:

   python3 --version  # Should be 3.12+ or compatible
   

3. Set git configuration:

   git config user.name "Olaf"
   git config user.email "admin@obr.sh"
   

4. Verify remotes:

   git remote -v
   # Should show:
   # origin  git@git.photon.obnh.io:AXSY/whois.git (fetch)
   # origin  git@git.photon.obnh.io:AXSY/whois.git (push)
   # mirror  git@git.proton.obr.sh:axsy/whois.git (fetch)
   # mirror  git@git.proton.obr.sh:axsy/whois.git (push)
   

5. Test server:

   sudo ./mwhoisd  # Run as root
   # In another terminal:
   whois -h 127.0.0.1 10.0.0.1
   

Important Notes

• No virtual environment setup needed (uses system Python 3.12+)
• All dependencies are embedded (netaddr/)
• Server must run as root to bind port 43
• Database is filesystem-based in db/ directory
• All git operations should use primary remote (photon.obnh.io)
• Mirror (proton.obr.sh) syncs automatically, push only to primary

Maintenance

Backup Strategy

• Git repository: Automatically mirrored to git.proton.obr.sh
• Database: Located in db/ directory (committed to git)
• Logs: mwhois.log (committed selectively)

Monitoring

• Check mwhois.log for query logs and errors
• Monitor mwhoisd.out for server output
• Review mwhoisd.err for error messages

Contact & Support

• Primary Administrator: olaf (admin@obr.sh)
• Organization: AXSY
• Git Infrastructure: git.photon.obnh.io (primary)

License

MIT License - See LICENSE file for details Netaddr library has separate license in netaddr/ directory