NAME¶

amuleapi - the aMule REST API + Server-Sent Events daemon

SYNOPSIS¶

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

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

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

amuleapi [--version]

amuleapi [--help]

DESCRIPTION¶

amuleapi serves a JSON REST API and a live event stream for a running amuled(1), so other programs can control aMule over HTTP. It connects to amuled the same way amulecmd(1) does, and listens on its own port, so it can run at the same time as amuleweb(1).

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.

OPTIONS¶

[ -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).

[ --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.

[ --disable-ec-encryption ]

Do not encrypt the link to amuled(1). Encryption is on by default whenever the remote aMule supports it. Turning it off lets anyone watching the connection read and alter everything after the login. Same as Encryption=0 in amuleapi.conf.

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

Set the admin password to <plain>, storing it salted and stretched in amuleapi-passwords (mode 0600), then exit. Does not start the HTTP server or connect to amuled. A stored password cannot be read back, only replaced.

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

Set the guest password to <plain>, storing it the same way, then exit. An empty <plain> clears the guest password, which is how guest access is turned off.

[ --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> ]

Write a copy of the console output to <path>. On by default at <config-dir>/amuleapi.log, so there is always a log to attach to a bug report; use this to put it somewhere else. It is capped at 10 MiB and rotated to <path>.1, so it cannot grow without bound. Each line starts with the local date and time, on the console as well as in the file.

[ --no-log-file ]

Disable the log file entirely and print to the console only, still timestamped.

[ --version ]

Print version information and exit.

[ --help ]

Print a short usage description.

FILES¶

~/.aMule/amuleapi.conf

Settings file: HTTP address and port, the connection to amuled, login rate limits and event-stream sizing. The QUICKSTART document shipped with the source has the full reference.

~/.aMule/amuleapi-jwt-secret

Key used to sign login tokens. Created on first launch. Deleting it signs out everyone.

~/.aMule/amuleapi-passwords

The admin and guest passwords, stored so they cannot be read back, only replaced. This is the only place they are kept. Set them with --set-admin-pass / --set-guest-pass, from the REST API, or from the Remote Controls preferences in amule(1). A change applies at the next login and signs out anyone already logged in.

~/.aMule/amuleapi-ec-token

Short-lived login token, written by amule(1) / amuled(1) when they start amuleapi themselves. Created fresh each time, read once and deleted straight away, so an auto-started amuleapi needs no EC password of its own. Started by hand, amuleapi finds no token and uses [EC]/Password from amuleapi.conf instead. There is no --password option: a password given on the command line is visible to every local user through ps(1).

REPORTING BUGS¶

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).

COPYRIGHT¶

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

SEE ALSO¶

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

AUTHOR¶

This manpage was written for the aMule project.