amuleapi(1)

NAME

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

SYNOPSIS

[-h <host>] [-p <port>]

DESCRIPTION

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.

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.

Always compress the link to amuled(1). By default amuleapi skips

compression when amuled's address is on the local network. Use this when that address is a VPN tunnel over a slow Internet link.

Set the admin password from stdin, then exit. Terminal input is hidden and

confirmed; redirected stdin supplies one UTF-8 line without confirmation. An empty admin password is rejected. EOF and input errors leave credentials unchanged. No HTTP server or EC connection is started.

As above for the guest password. An explicitly empty line disables guest access;

EOF does not. Choose exactly one password setter per invocation.

Read the existing EC password from stdin (hidden on a terminal, without

confirmation), write its MD5 digest to [EC]/PasswordMD5 in amuleapi.conf, remove the plaintext [EC]/Password key, and exit. Other settings are preserved; INI formatting and comments may change. Empty input is rejected.

[ --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. Prefer the stdin form: literal passwords can be exposed through process arguments and shell history.

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

For standalone use, set the EC password with --set-ec-pass-stdin, or copy its MD5 digest from [EC]/Password in remote.conf to [EC]/PasswordMD5 here. Plaintext [EC]/Password is also supported. Set only one: amuleapi refuses to start if both are nonempty or PasswordMD5 is not 32 hexadecimal characters. The digest logs in to amuled just like the password, so keep this file private.

~/.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-stdin / --set-guest-pass-stdin, 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]/PasswordMD5 (or plaintext [EC]/Password) from amuleapi.conf instead. There is no --password option: a password given on the command line is visible through ps(1) for the lifetime of the process, and can persist in shell history, service unit files and wrapper scripts.

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

AUTHOR

This manpage was written for the aMule project.