This tool is composed of two components:
Both the library and the command-line tool can be installed from
source with go get
tool.
If you have go installed in your environment you can install
ejabberd
command-line tool with:
go install -v github.com/processone/ejabberd-api/cmd/ejabberd@master
Once the get completes, you should find your new ejabberd
(or ejabberd.exe
) executable sitting inside $GOPATH/bin/
.
Before being able to interact with ejabberd API, you need to configure ejabberd with OAuth support enabled. This is is documented in ejabberd OAuth support.
Here are example entries to check / change in your ejabberd configuration file:
Add a listener for OAuth and ReST API:
listen:
-
# Using a separate port for oauth and API to make it easy to protect it
# differently than BOSH and Websocket HTTP interface.
port: 5281
# oauth and API only listen on localhost interface for security reason
# You can set ip to 0.0.0.0 to open it widely, but be careful!
ip: 127.0.0.1
module: ejabberd_http
request_handlers:
/oauth: ejabberd_oauth
/api: mod_http_api
You can then configure the OAuth commands you want to expose. Check
api_permissions
to make sure ACL for passing commands as admins are set properly:
api_permissions:
"admin access":
who:
oauth:
scope: "ejabberd:admin"
access:
allow:
user: admin@localhost
what:
- "register"
- "change_password"
# Tokens are valid for a year as default:
oauth_expire: 31536000
oauth_access: all
Finally, make sure to enable the modules that provide the commands you want to use, for example:
modules:
mod_admin_extra: {}
The ejabberd
command-line tool allows you to interact with your ejabberd server
by using ejabberd's ReST API. It relies on OAuth tokens and scope to define the command
the user will be allowed to call.
Generating an OAuth token:
To use the ejabberd
command-line tool, you first need to generate an OAuth
token.
It can be done, for example, with the following command:
ejabberd token -j admin@localhost -p mypassword -s ejabberd:admin
This will generate a .ejabberd-oauth.json
file containing your
credentials. Keep the file secret, as it will grant access to command
available in the requested scope on your behalf.
Calling ejabberd API from the command-line, using your token file. For example:
ejabberd stats registeredusers
You can also try to call any available command thanks to the generic call
command. Do not forget -a
parameter for commands that requires admin rights. For example:
cat register.json
{"user":"test1", "host":"localhost", "password":"somePassW0rd"}
ejabberd call --name register -a --data-file=register.json
You can generate Bash completion with following command:
./ejabberd --completion-script-bash
You can generate ZSH completion with following command:
./ejabberd --completion-script-zsh
To be able to use completion for Bash, you can type or add in your
bash_profile
(or equivalent):
eval "$(ejabberd --completion-script-bash)"
For ZSH, you can use:
eval "$(ejabberd --completion-script-zsh)"
To get a full list of commands and their options:
ejabberd --help-long
As a default, the token is stored in a file called
./.ejabberd-oauth.json
when using the command token
and read from
the same file when you use any other commands.
Option -f file
will let you point to another file.
The file contains a JSON structure with the following fields:
For example:
{"access_token":"AaQTb0PUZqeZhFKYoaTQBb4KKkCTAolE",
"endpoint":"http://localhost:5281/",
"jid":"admin@localhost",
"scope":"ejabberd:admin",
"expiration":"2017-07-23T13:53:08.326421575+02:00"}
go build -o ejabberd cmd/ejabberd/main.go
You can run tests from repository clone with command:
go test -race -v ./.