Configuration Files
aMule stores its configuration, data, and runtime files in a dedicated directory. Most of these files are compatible with or equivalent to eMule's files. Not all files exist at all times — many are created on demand.
This page is a catalogue: what each file is, what it is for, and where to find it. The only files meant to be edited by hand are amule.conf and remote.conf. For the on-disk format of the non-editable files (binary layouts, byte tables, parsing scripts), each entry links to the File Formats reference in the Developer Guide.
Platform paths
| Platform | Directory |
|---|---|
| Windows | %APPDATA%\aMule\ |
| macOS | ~/Library/Application Support/aMule/ |
| Linux / Unix / BSD | ~/.aMule/ |
On macOS, whenever this reference writes ~/.aMule/, it means ~/Library/Application Support/aMule/.
These are aMule's configuration paths. For the download directories (Incoming, Temporary, and shared folders), see Directories.
To back up aMule or move it to a new computer, copy this whole directory. See Backup and Restore.
Portable configuration (running from a USB drive)
If a directory named config exists next to the aMule executable (in its working directory) and already contains an amule.conf, aMule reads and writes its configuration there instead of the platform path above. This makes it possible to run a fully self-contained, portable aMule — for example from a USB drive — without touching the host machine's user profile.
All files at a glance
| File | Description |
|---|---|
amule.conf | Main configuration — stores all user preferences |
amule.conf.bak | Automatic backup of amule.conf (written on shutdown) |
amule.conf.backup | Backup of amule.conf, written only when started with --reset-config |
remote.conf | Configuration for remote tools (amulegui, amulecmd, amuleweb). amuleapi does not utilize this file. |
preferences.dat | Stores the userhash and config file version |
preferencesKad.dat | Stores the client IP and Kademlia ClientID |
cryptkey.dat | 384-bit RSA private key for Secure User Identification |
amuleapi.conf | Configuration for the amuleapi daemon (REST API and Web UI) |
amuleapi-passwords | Shared admin/guest credential store for amuleapi |
amuleapi-jwt-secret | Auto-generated JWT signing secret for amuleapi sessions |
amuleapi-ec-token | One-off EC login token dropped when aMule auto-starts amuleapi |
amuleapi-static/ | Installed Web UI assets served by amuleapi |
server.met | eD2k server list (IP, port, name, statistics) |
server.met.bak | Automatic backup of server.met |
server_auto.met | Temporary file holding a server list during auto-update (deleted after merge) |
staticservers.dat | Static eD2k servers that override server.met entries |
addresses.dat | URLs to download server.met updates from |
nodes.dat | Known Kademlia contacts for network bootstrap |
known.met | Hash cache for shared files (avoids rehashing) |
known2_64.met | Verified AICH hashes for shared files (large file support) |
clients.met | Credit ledger: bytes uploaded/downloaded per peer |
clients.met.bak | Automatic backup of clients.met |
emfriends.met | Friends list with last known IP, port, and timestamps |
statistics.dat | Lifetime traffic totals (cumulative bytes uploaded/downloaded) |
canceled.met | Hashes of cancelled downloads (highlights them in search results) |
searchhistory.dat | Past search terms (search history of the GUI) |
StoredSearches.met | Results of the searches still open at exit, restored on the next start |
shareddir.dat | Union of all shared directories (regenerated automatically) |
shareddir-explicit.dat | Non-recursive shared directory roots (user-added) |
shareddir-recursive.dat | Recursive shared directory roots (contents shared including subdirectories) |
ipfilter.dat | IP range block/allow list (auto-updated) |
ipfilter_static.dat | Static IP range overrides (never modified by aMule) |
ED2KLinks | One-way interface for adding downloads to aMule |
amulesig.dat | aMule status signature for external apps (17-line format) |
onlinesig.dat | eMule-compatible 2-line status signature |
muleLock | PID file that prevents two simultaneous aMule instances |
muleLockRGUI | PID file for the Remote GUI (amulegui) instance |
geoip.mmdb | GeoIP country database for IP2Country flags (auto-updated) |
logfile | Log of the current aMule session |
logfile.bak | Log of the previous aMule session |
remotelogfile | Log written by amulegui (Remote GUI) for its own session |
lastversion | History of the 10 most recently launched aMule versions |
last_version_check | Latest release info fetched from GitHub (Releases API JSON) |
last_version | Rename destination of a successful version-check download |
last_version_notified | Release version muted with Don't ask again in the new-version dialog |
key_index.dat | Kademlia keyword data this client publishes to the network |
src_index.dat | Kademlia source data this client publishes to the network |
load_index.dat | Kademlia client keyIDs and last-seen timestamps |
casrc | CAS image/HTML generation configuration |
aMule-online-sign.html | CAS-generated HTML status page |
aMule-online-sign.png | CAS-generated PNG status image |
*.part | In-progress download data (in Temp/) |
*.part.met | Download metadata: hashes, verified chunks, tags (in Temp/) |
*.part.met.bak | Recovery backup of *.part.met (previous version, kept on each save) |
*.part.met.tmp | Write-in-progress temp (renamed to .met on success) |
*.part.met.seeds | Up to 10 sources for rare files (in Temp/) |
Configuration files
amule.conf
Location: ~/.aMule/amule.conf
This is aMule's main configuration file. It stores virtually all user preferences set through the Preferences dialog — connection limits, directories, interface settings, and more. The format is a standard Windows-style INI file. It is read on startup and written on exit.
amule.conf.bak is an automatic backup: on a clean shutdown aMule copies the current amule.conf to amule.conf.bak, so the previous session's configuration is always available.
A separate amule.conf.backup is written only when aMule is started with the --reset-config option: the existing configuration is renamed to amule.conf.backup before being reset to default values.
See the amule.conf reference for the complete key reference and a full example file.
remote.conf
Location: ~/.aMule/remote.conf
Configuration file for the remote tools — the Remote GUI (amulegui), amulecmd, and amuleweb. It stores the External Connections host, port, and password, plus tool-specific settings. The format is a standard INI file.
See the remote.conf reference for the complete key reference and a full example file.
preferences.dat
Location: ~/.aMule/preferences.dat
In early eMule versions this file stored all user configuration. In current aMule it stores only two fields: the configuration file version and the userhash — a 128-bit value that uniquely identifies your client on the eD2k network (used for credit tracking and Secure User Identification).
This file is not meant to be edited by hand. For its binary layout, see the preferences.dat format reference.
preferencesKad.dat
Location: ~/.aMule/preferencesKad.dat
Stores the client's IP address and its Kademlia ClientID. Both are used to identify the client on the Kad network.
For its binary layout, see the preferencesKad.dat format reference.
cryptkey.dat
Location: ~/.aMule/cryptkey.dat
Contains the client's 384-bit RSA private key, used for Secure User Identification. This key is unique to each client and is generated automatically the first time aMule runs.
This file contains your private key. Never share it. If it is compromised, anyone can impersonate your client on the eD2k network.
Keep a backup of this file together with preferences.dat: the credits other clients have granted you are tied to both, and losing cryptkey.dat loses them. See Backup and Restore.
For its storage format, see the cryptkey.dat format reference.
amuleapi files
The amuleapi daemon (REST API and Web UI) keeps its own configuration and credential files in the aMule config directory, alongside amule.conf.
amuleapi.conf
Location: ~/.aMule/amuleapi.conf
amuleapi's configuration file, in standard INI format. It has four sections: [Server] (bind address, HTTP port, CORS, static-asset root), [EC] (how it reaches the aMule core over External Connections), [Auth] (login rate-limiting), and [Streaming]. It is created with defaults on first run. This is the only config file amuleapi reads — it does not use remote.conf.
See the amuleapi.conf reference for the complete key reference and a full example file.
amuleapi-passwords
Location: ~/.aMule/amuleapi-passwords
Shared credential store for the amuleapi admin and guest accounts. Each password is kept as a salted PBKDF2-HMAC-SHA256 record in PHC string format (pbkdf2-sha256$<iters>$<salt-hex>$<hash-hex>); an empty value means the role is unset. The file is created with mode 0600. It is written by amuleapi, amuled and the monolithic amule — but not by amulegui, which pushes password changes to the core over EC instead. A legacy bare-MD5 record is still accepted and is rewritten to PBKDF2 after the next successful login.
To set or change these passwords, see Changing Passwords on the amuleapi page.
This file holds your amuleapi login credentials. Keep its 0600 permissions; on POSIX systems amuleapi refuses to start if amuleapi.conf, amuleapi-jwt-secret or amuleapi-passwords has any group or other permission bit set.
amuleapi-jwt-secret
Location: ~/.aMule/amuleapi-jwt-secret
Signing secret for the JWT session tokens amuleapi issues. It is auto-generated as 32 random bytes (stored as hex) on first launch, with mode 0600. Delete the file and restart amuleapi to rotate the secret, which invalidates all existing sessions.
amuleapi-ec-token
Location: ~/.aMule/amuleapi-ec-token
A one-off External Connections login token. When aMule auto-starts amuleapi as a child process, it writes this short-lived token (mode 0600) so the child can authenticate without a stored EC password. amuleapi reads and deletes it immediately, and aMule also removes it after a short deadline. It normally exists only for a moment.
amuleapi-static/
Location: installed with aMule (for example /usr/share/amule/amuleapi-static/), not in the config directory.
Directory holding the built Web UI assets that amuleapi serves. When the [Server]/StaticRoot key in amuleapi.conf is empty (the default), amuleapi auto-discovers this folder — next to its executable, inside the macOS app bundle, or in the shared-data directory. If no assets are found, the REST API still works but / returns 404.
Network data files
server.met
Location: ~/.aMule/server.met
Binary database of known eD2k servers. Each entry records the server's IP address, TCP port, name, description, ping time, failure count, user count, and capability flags. The format is compatible with eMule's server.met. Servers listed in staticservers.dat override matching entries here. server.met.bak is an automatic backup. During an automatic server-list update, the downloaded list is written to server_auto.met first, then merged into server.met and deleted on success.
Obtaining server.met online
A current server.met can be downloaded on first run, when the local list is empty, or when all known servers are unreachable:
| URL | Notes |
|---|---|
https://upd.emule-security.org/server.met | Default URL configured in aMule; maintained by the eMule Security project |
https://shortypower.org/server.met | Aggregated server list |
These are third-party services unaffiliated with the aMule project. Their availability may change over time.
Enter a URL in the Networks → eD2k tab to download immediately, or set Ed2kServersUrl in amule.conf for automatic updates at startup.
For the complete binary format and tag reference, see the server.met reference.
staticservers.dat
Location: ~/.aMule/staticservers.dat
A text file listing eD2k servers that should always be treated as static servers. When aMule loads, entries from this file override matching entries in server.met. This file is never modified by aMule.
For its line format, see the staticservers.dat format reference.
addresses.dat
Location: ~/.aMule/addresses.dat
A plain-text list of URLs from which aMule downloads server.met files on startup (if the Auto-update server list at startup preference is enabled). The downloaded lists are merged into ~/.aMule/server.met.
For its format, see the addresses.dat format reference.
nodes.dat
Location: ~/.aMule/nodes.dat
Binary file storing known Kademlia contacts used to bootstrap the Kad network on startup.
Obtaining nodes.dat online
A fresh nodes.dat is useful on first run, when the local file is missing, or when it has become too stale to bootstrap into Kad:
| URL | Notes |
|---|---|
https://upd.emule-security.org/nodes.dat | Default URL configured in aMule; maintained by the eMule Security project |
This is a third-party service unaffiliated with the aMule project. Its availability may change over time.
Enter a URL in the Networks → Kad tab to download immediately, or set KadNodesUrl in amule.conf for automatic updates. Once connected to Kad, aMule keeps nodes.dat up to date automatically.
For the complete binary format, see the nodes.dat reference.
known.met
Location: ~/.aMule/known.met
Binary file that caches the hashes, names, sizes, modification dates, priorities, and notes of shared files. This prevents aMule from having to rehash every shared file each time it starts — a significant time saving for large files.
For its format, see the known.met format reference.
known2_64.met
Location: ~/.aMule/known2_64.met
Binary file that stores the verified AICH hashes of shared files. Supports large files (64-bit sizes). This is the successor to the deprecated known2.met.
For more detail, see the known2_64.met format reference.
clients.met
Location: ~/.aMule/clients.met
Binary credit ledger: for every peer you have exchanged data with, it records the bytes uploaded and downloaded, used to compute the credits that influence your position in other clients' upload queues. clients.met.bak is an automatic backup.
See the clients.met reference for the complete binary format.
emfriends.met
Location: ~/.aMule/emfriends.met
Binary file storing your friends list: each entry keeps a friend's userhash, last known IP, port, and timestamps.
See the emfriends.met reference for the complete binary format.
canceled.met
Location: ~/.aMule/canceled.met
Binary file storing the MD4 hashes of all downloads the user has cancelled. When a file appears in a search result but its hash is listed here, aMule marks it with a distinct colour to indicate it was previously cancelled.
For its format, see the canceled.met format reference.
statistics.dat
Location: ~/.aMule/statistics.dat
Small binary file storing aMule's lifetime traffic totals — the cumulative number of bytes ever uploaded and downloaded across all sessions.
For its format, see the statistics.dat format reference.
Shared files
shareddir.dat, shareddir-explicit.dat, shareddir-recursive.dat
aMule uses three related files to track shared directories. For how to configure shared directories from the GUI, see Directories.
| File | Purpose |
|---|---|
shareddir-explicit.dat | Canonical. Non-recursive roots: only the immediate files in each listed directory are shared (subdirectories are not included). |
shareddir-recursive.dat | Canonical. Recursive roots: aMule expands each listed directory to include all subdirectories. |
shareddir.dat | Derived. Union of the expanded contents of the two canonical files. aMule regenerates this file automatically on every save. External tools that only know shareddir.dat (e.g. old scripts or older aMule versions) can still read it. |
When aMule starts and neither shareddir-explicit.dat nor shareddir-recursive.dat exists (fresh install or migration from an older version), all entries in shareddir.dat are loaded as explicit (non-recursive) shares. This is the safe default for migration.
For the shared file format, see the shared directory files reference.
IP filter files
The IP filter blocks all traffic to and from a configurable list of IP addresses and ranges: blocked IPs cannot upload to you or download from you. The list is read from the two files below. aMule's ipfilter.dat is 100% compatible with eMule's. To enable and tune the filter, see Preferences → Security → IP-Filtering.
ipfilter.dat
Location: ~/.aMule/ipfilter.dat
Text file containing IP ranges that aMule should block or allow. aMule can auto-update this file by downloading a new one from a configurable URL. During the download, the new data is written to ipfilter.download first, then renamed to ipfilter.dat on success. The downloaded file may be a ZIP archive; aMule decompresses it automatically and accepts any of the entries named ipfilter.dat, guardian.p2p, or guarding.p2p (the PeerGuardian list filenames). For how to enable and tune the filter, see Preferences → Security → IP-Filtering; for the line format, see the ipfilter format reference.
If the local file cannot be loaded and Use system-wide ipfilter.dat if available (IPFilterSystem) is enabled, aMule falls back to a system-wide ipfilter.dat (on Linux, typically /usr/share/amule/ipfilter.dat). This lets a package manager or cron job maintain a shared file, so aMule does not have to re-download a large list at every startup.
Obtaining ipfilter.dat online
| URL | Notes |
|---|---|
https://upd.emule-security.org/ipfilter.zip | Maintained by the eMule Security project; distributed as a ZIP archive that aMule decompresses automatically |
This is a third-party service unaffiliated with the aMule project. Its availability may change over time.
Configure the URL via the IPFilterURL key in amule.conf:
[eMule]
IPFilterURL=https://upd.emule-security.org/ipfilter.zip
ipfilter_static.dat
Location: ~/.aMule/ipfilter_static.dat
Same purpose as ipfilter.dat, but with two important differences: its entries override conflicting entries in ipfilter.dat, and aMule never modifies it. Use it for custom IP ranges that must survive auto-updates.
For its format (identical to ipfilter.dat) and the default comment block aMule writes, see the ipfilter format reference.
Always-filtered ranges (hard-coded)
In addition to the ranges loaded from the files above, aMule always blocks the reserved IP ranges defined by RFC 3330. These are reserved, special-use, or non-routable addresses that should never appear as eD2k peers. This list is compiled into aMule and cannot be disabled by any preference:
0.0.0.0/8 "This" Network [RFC1700]
39.0.0.0/8 Reserved but subject to allocation [RFC1797]
127.0.0.0/8 Loopback [RFC1700]
128.0.0.0/16 Reserved but subject to allocation
169.254.0.0/16 Link Local
191.255.0.0/16 Reserved but subject to allocation
192.0.0.0/24 Reserved but subject to allocation
192.0.2.0/24 Test-Net
192.88.99.0/24 6to4 Relay Anycast [RFC3068]
198.18.0.0/15 Network Interconnect Benchmarking [RFC2544]
223.255.255.0/24 Reserved but subject to allocation
224.0.0.0/4 Multicast [RFC3171]
240.0.0.0/4 Reserved for Future Use [RFC1700]
Separately, the private LAN ranges below are blocked only when Always filter LAN IPs (FilterLanIPs, in amule.conf) is enabled, which is the default:
10.0.0.0/8 Private-Use Networks [RFC1918]
172.16.0.0/12 Private-Use Networks [RFC1918]
192.168.0.0/16 Private-Use Networks [RFC1918]
Status and interface files
ED2KLinks
Location: ~/.aMule/ED2KLinks
A plain-text interface for sending commands to a running aMule instance. As soon as aMule detects that this file exists, it reads it, processes each entry, and deletes the file. The interface is one-directional (write-only from the user's perspective). It is used by aMule itself to hand links clicked in a browser or passed on the command line to the running instance, and by the ed2k command-line tool.
For its format, see the ED2KLinks format reference.
amulesig.dat
Location: ~/.aMule/amulesig.dat
aMule's native status signature file: a 17-line text file that external applications (such as the cas tool) read to display the client's current status. See the amulesig.dat reference for details.
onlinesig.dat
Location: ~/.aMule/onlinesig.dat
eMule-compatible 2-line status file. aMule generates it for compatibility with eMule utilities. The native aMule status file is amulesig.dat, which carries far more information.
For its format, see the onlinesig.dat format reference.
muleLock
Location: ~/.aMule/muleLock
Plain-text file containing the PID of the currently running aMule process. It is created when aMule starts and deleted when aMule exits normally.
On startup, aMule checks whether muleLock exists. If it does, aMule reads the PID and checks whether a process with that PID is currently running. If one is found, aMule refuses to start, preventing two simultaneous instances for the same user.
aMule does not verify that the running process is actually another aMule. Any process with the stored PID will block startup. If muleLock is left behind after a crash, delete it manually before restarting aMule.
The Remote GUI (amulegui) uses its own lock file, muleLockRGUI, with the same mechanism, so a local aMule instance and the Remote GUI do not block each other.
geoip.mmdb
Location: ~/.aMule/geoip.mmdb
Country database in MaxMind DB format (.mmdb), used by IP2Country to show the country flag of clients and servers. aMule downloads it from the selected provider (DB-IP by default) and keeps it up to date, so it normally needs no manual handling; see IP2Country → The database file to install one by hand.
While an update is downloading, aMule writes geoip.mmdb.download and renames it to geoip.mmdb once it is complete. A leftover .download file after a failed update can be deleted.
searchhistory.dat
Location: ~/.aMule/searchhistory.dat
Plain-text list of the last 100 search terms, one per line, newest first. The GUI rewrites it after every search and reads it to fill the Name drop-down of the Searches window. In amulegui it is written in the remote GUI's own configuration directory; amuled does not create it. It is only used while Remember search history is enabled (SearchHistoryEnabled in amule.conf); disabling the option leaves the file in place, and Clear Search History deletes it.
StoredSearches.met
Location: ~/.aMule/StoredSearches.met
Binary file with the results of the searches still open when the core (amule or amuled) shuts down — at most the 20 most recent searches and 5000 results each; "View Files" listings are not saved. The core reads it on the next start to reopen those searches (see Saved Searches). It is written only while Remember search history is enabled; with the option disabled, the file is deleted on the next start.
Log files
logfile
Location: ~/.aMule/logfile
Plain-text log of the current aMule session, capturing all messages, warnings, and errors reported during operation. When a new session starts, the previous logfile is renamed to logfile.bak and a fresh one is created. Each line is prefixed with a YYYY-MM-DD HH:MM:SS: timestamp.
The amulegui writes its own separate log to ~/.aMule/remotelogfile, in the same format but recording only events from the GUI process.
Version tracking files
lastversion
Location: ~/.aMule/lastversion
Plain-text file recording the last 10 aMule versions launched on this machine, in reverse chronological order (most recent first), one version string per line. aMule uses it to detect version upgrades and show first-run messages. When an 11th version is added, the oldest entry is dropped.
last_version_check
Location: ~/.aMule/last_version_check
File holding the response of aMule's update check. aMule queries the GitHub Releases API (https://api.github.com/repos/amule-org/amule/releases/latest) and stores the returned JSON here; it then extracts the tag_name field and compares it with the running version to notify the user of updates. On a successful download the file is renamed to last_version.
This replaces the legacy single-line lastversion text file that was fetched from SourceForge, which has been unmaintained since the project moved to GitHub.
last_version_notified
Location: ~/.aMule/last_version_notified
Single-line plain-text file holding the release version for which the user ticked Don't ask again in the New version available dialog. aMule does not show the dialog for that version again, but a newer release shows it once more. The file is written only when the checkbox is ticked; delete it to be reminded of the muted version again.
Kademlia index files
key_index.dat, src_index.dat and load_index.dat
Location: ~/.aMule/key_index.dat, ~/.aMule/src_index.dat, ~/.aMule/load_index.dat
Binary files that store the Kademlia network index data this client maintains as a node of the Kad network:
key_index.dat— keyword index: the keywords this client publishes so other clients can search for files through it.src_index.dat— source index: the sources (which clients hold which files) this client publishes.load_index.dat— keyIDs of known Kademlia clients with their last-seen dates, used to gauge network load.
All three are internal to the Kad implementation and are not intended for manual editing.
For more detail, see the Kad index files format reference.
CAS files
casrc, aMule-online-sign.html, aMule-online-sign.png
Files used by the cas status-image tool: casrc is its configuration, and aMule-online-sign.html / aMule-online-sign.png are the HTML and PNG status outputs it generates. See the cas / wxcas documentation for details.
Temporary download files
*.part, *.part.met and related
Each in-progress download in the Temp/ directory is represented by a group of files: *.part (the partial data), *.part.met (metadata: hashes, verified chunks, tags), *.part.met.bak (recovery backup of *.part.met), *.part.met.tmp (short-lived write-in-progress temp), and *.part.met.seeds (up to 10 sources for rare files).
See the Temporary download files reference for the complete formats.
Deprecated files
These files are no longer created by current aMule versions but may be present in older installations.
| File | Replaced by | Deprecated since |
|---|---|---|
~/.eMule/ | ~/.aMule/amule.conf | aMule 2.0.0 |
~/.aMule/aMule.tmpl | ~/.aMule/webserver/ (skin directory) | aMule 2.0.0 |
~/.aMule/known2.met | ~/.aMule/known2_64.met (large-file support) | — |
~/.aMule/muleconn | ~/.aMule/muleLock | aMule 2.1.0 |
~/.aMule/server_met.old | (backup of server.met, no longer written) | — |
~/.aMule/GeoIP.dat | ~/.aMule/geoip.mmdb (MaxMind DB format) | aMule 3.0.0 |
~/.aMule/GeoLite2-Country.mmdb | ~/.aMule/geoip.mmdb (renamed automatically) | aMule 3.0.1 |