amuleapi - Man Page

amuleapi [-h <host>] [-p <port>] [-P <password>] [--bind <address>] [--http-port <num>] [--config-dir <path>] [--amule-config-file <path>] [--log-file <path>] [--no-log-file] [--foreground]

amuleapi [--set-admin-pass <plain>]

amuleapi [--set-guest-pass <plain>]

amuleapi [--version]

amuleapi [--help]

amuleapi is a standalone HTTP daemon that exposes a versioned JSON REST API and a long-lived Server-Sent Events stream backed by a single amuled(1) instance over the EC protocol. It is intended to run alongside amuled (which it connects to as an EC client) and serves its HTTP surface on a separate port from amuleweb(1) - the two can run concurrently against the same daemon.

The wire contract for the REST API is documented at docs/api/REFERENCE.md; the SSE event catalog lives at docs/api/EVENTS.md. See docs/QUICKSTART-AMULEAPI.md for first-run setup notes.

[ -h <host>, --host=<host> ]

EC host to connect to (default: 127.0.0.1).

[ -p <port>, --port=<port> ]

EC port on the amuled instance (default: 4712).

[ -P <password>, --password=<password> ]

EC plaintext password (matches amuled's [ExternalConnect]/Password).

[ --bind=<address> ]

HTTP bind address (default: 127.0.0.1, overrides amuleapi.conf [Server]/BindAddress).

[ --http-port=<num> ]

HTTP listen port (default: 4713, overrides amuleapi.conf [Server]/Port).

[ --config-dir=<path> ]

Path to the amuleapi config dir. Defaults to the same per-platform aMule data directory that amuled uses (~/.aMule/ on Linux, ~/Library/Application Support/aMule/ on macOS, %APPDATA%\aMule\ on Windows). Creates the dir with mode 0700 if absent.

[ --amule-config-file=<path> ]

Read the EC host, port and password from an existing amule(1) / amuled(1) amule.conf, the same way amuleweb(1) does. This is how aMule auto-starts amuleapi (see Run amuleapi on startup in the GUI, or /AmuleApi/Enabled in amule.conf): amuled only stores the MD5-hashed EC password, so passing the config file lets amuleapi authenticate without a plaintext --password on the command line. Overrides --host / --port / --password.

[ --set-admin-pass=<plain> ]

Hash <plain> with MD5 and store it as the admin password in amuleapi-passwords (mode 0600), then exit. Does not start the HTTP server or connect to amuled.

[ --set-guest-pass=<plain> ]

Hash <plain> with MD5 and store it as the guest password in amuleapi-passwords (mode 0600), then exit.

[ --foreground ]

Stay in the foreground (default). aMule does not ship init-system units; if you need a system service wrapper, write a downstream unit that wraps the foreground command.

[ --log-file=<path> ]

Append a copy of all console output (both stdout and stderr) to <path> while still printing to the console. Enabled by default at <config-dir>/amuleapi.log, so a log is always available to attach to a bug report; pass this to use a different path. The file is opened in append mode and capped at 10 MiB: when a write would exceed the cap it is rotated to <path>.1 (replacing any previous one) and a fresh file is started, so on-disk usage stays bounded.

[ --no-log-file ]

Disable the log file entirely and print to the console only.

[ --version ]

Print version information and exit.

[ --help ]

Print a short usage description.

~/.aMule/amuleapi.conf

INI-style runtime config: [Server] (bind address, HTTP port, CORS allowlist), [EC] (outbound connection to amuled), [Auth] (login rate-limit knobs), [Streaming] (SSE event-bus ring capacity). The QUICKSTART document distributed with the source has the full reference.

~/.aMule/amuleapi-jwt-secret

32-byte HMAC signing key for issued tokens. Mode 0600. Auto-generated on first launch if absent. Deleting the file invalidates every previously-issued token.

~/.aMule/amuleapi-passwords

INI-style MD5-hashed admin + guest passwords. Mode 0600. Written via --set-admin-pass / --set-guest-pass.

Please report bugs either on our forum (https://github.com/amule-org/amule/discussions), or in our bugtracker (https://github.com/amule-org/amule/issues).

aMule and all of its related utilities are distributed under the GNU General Public License.

amule(1), amuled(1), amulecmd(1), amuleweb(1)

This manpage was written for the aMule project.