AMULE.md

aMule Integration

aMuTorrent connects to aMule via the EC (External Connections) protocol, allowing you to search the ED2K/Kad network and manage downloads.

Requirements

• aMule (or amuled) with External Connections (EC) enabled
• EC password configured in aMule

aMule EC Setup

Before connecting aMuTorrent, you must enable External Connections in aMule:

1. Open aMule (or edit amuled configuration file)
2. Navigate to Preferences → Remote Controls → External Connections
3. Enable "Accept external connections"
4. Set an EC password (remember this for aMuTorrent configuration)
5. Note the EC port (default: 4712)
6. Optional: Configure allowed IP addresses for security

amuled Configuration

For headless setups using amuled, edit ~/.aMule/amule.conf:

[ExternalConnect]
AcceptExternalConnections=1
ECPassword=<md5_hash_of_your_password>
ECPort=4712

To generate the MD5 hash of your password:

echo -n "your_password" | md5sum | cut -d ' ' -f 1

Configuration

Via Settings UI

1. Go to Settings in aMuTorrent
2. Expand the aMule section
3. Enable aMule integration
4. Configure connection settings:
   • Host: aMule hostname or IP (e.g., localhost, amule, or host.docker.internal)
   • Port: EC port (default: 4712)
   • Password: Your EC password

Via Environment Variables

AMULE_ENABLED=true
AMULE_HOST=localhost
AMULE_PORT=4712
AMULE_PASSWORD=your_ec_password
AMULE_SHARED_FILES_RELOAD_INTERVAL_HOURS=3
AMULE_SHARED_DIR_DAT=/home/amule/.aMule/shareddir.dat

Via config.json

{
  "amule": {
    "enabled": true,
    "host": "localhost",
    "port": 4712,
    "password": "your_ec_password"
  }
}

Docker Compose Example

aMule on Host Machine

services:
  amutorrent:
    image: g0t3nks/amutorrent:latest
    environment:
      - AMULE_ENABLED=true
      - AMULE_HOST=host.docker.internal
      - AMULE_PORT=4712
      - AMULE_PASSWORD=your_password
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      # Optional: shared directory management (path to your aMule shareddir.dat)
      # - /path/to/.aMule/shareddir.dat:/home/amule/.aMule/shareddir.dat:rw
    ports:
      - "4000:4000"

aMule in Docker Container

services:
  amule:
    image: ngosang/amule:latest
    container_name: amule
    ports:
      - "4662:4662"
      - "4665:4665/udp"
      - "4672:4672/udp"
    environment:
      - PUID=1000
      - PGID=1000
      - GUI_PWD=your_password
      - WEBUI_PWD=your_password
      - INCOMING_DIR=/downloads
      - TEMP_DIR=/downloads/temp
    volumes:
      - ./data/aMule/config:/home/amule/.aMule
      - ./data/aMule/incoming:/downloads
      - ./data/aMule/temp:/downloads/temp
    restart: unless-stopped

  amutorrent:
    image: g0t3nks/amutorrent:latest
    environment:
      - AMULE_ENABLED=true
      - AMULE_HOST=amule
      - AMULE_PORT=4712
      - AMULE_PASSWORD=your_password
    volumes:
      # Download directories (optional): Required for moving/deleting files
      - ./data/aMule/incoming:/downloads
      # Shared directory management (optional): mount aMule's shareddir.dat
      - ./data/aMule/config/shareddir.dat:/home/amule/.aMule/shareddir.dat:rw
    ports:
      - "4000:4000"
    restart: unless-stopped

Categories

Categories created in aMuTorrent can be assigned to aMule downloads. When a category has a configured path:

1. New downloads with that category are saved to the category path
2. Existing downloads (active or completed) can be moved to their category path via the UI

Troubleshooting

Connection Failed

• Verify aMule is running and EC is enabled
• Check the EC password is correct (case-sensitive)
• Ensure the EC port (default 4712) is accessible
• Check firewall rules between aMuTorrent and aMule

Docker: Can't reach aMule on host

• Add extra_hosts to your docker-compose.yml:

  extra_hosts:
    - "host.docker.internal:host-gateway"

• Use host.docker.internal as the aMule host

Downloads Not Appearing

• Ensure aMule integration is enabled in Settings
• Check the aMuTorrent logs for connection errors
• Verify aMule has active downloads

Wrong Password Error

• EC passwords are case-sensitive
• For amuled, ensure the password in amule.conf is the MD5 hash
• For aMule GUI, use the plain text password you set

Connection Drops

• Check aMule's EC timeout settings
• Ensure aMule isn't being overloaded
• Check network stability between containers/hosts

---

Shared Directory Management (Experimental)

aMuTorrent can manage aMule's shareddir.dat file — the list of directories aMule shares on the ed2k/Kademlia network. The feature is available in the Shared Files view via the "Manage Shared Dirs" button.

How It Works

• The UI shows root directories only (subdirectories are auto-collapsed)
• When saving, aMuTorrent runs find -type d on each root to enumerate all subdirectories
• The expanded list is written to shareddir.dat and aMule reloads shared files
• The periodic auto-reload (configured via AMULE_SHARED_FILES_RELOAD_INTERVAL_HOURS) also rescans subdirectories automatically, picking up new folders

Configuration

Set the path to shareddir.dat via environment variable or directly in the UI:

AMULE_SHARED_DIR_DAT=/home/amule/.aMule/shareddir.dat

Or click "Manage Shared Dirs" in the Shared Files view and configure the path in the modal.

Docker Requirements

1. Mount the shareddir.dat file (or its parent directory) with write permissions — aMule sets shareddir.dat to read-only (444), so aMuTorrent needs to chmod it before writing:

   volumes:
     # Single file mount:
     - ./data/aMule/config/shareddir.dat:/home/amule/.aMule/shareddir.dat:rw
     # Or directory mount:
     # - ./data/aMule/config:/home/amule/.aMule:rw

2. Same UID — both the aMuTorrent and aMule containers must run with the same user ID (e.g., PUID=1000) so aMuTorrent can modify the read-only file.

3. Same mount paths — shared directories listed in shareddir.dat must be accessible at the same path in both containers. For example, if aMule sees /downloads, aMuTorrent must also have /downloads mounted.