ejabberd API library in Go and multi-platform command-line tool
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd/ejabberd rename generic command to call Sep 29, 2016
.codeclimate.yml Update .codeclimate.yml Dec 20, 2017
.gitignore Expand gitignore file list Jul 17, 2016
README.md Add example for generic command calls Sep 29, 2016
TODO.org Refactor to merge code for OAuthToken handling Jul 29, 2016
api.go Refactor error management + user_resources call Jul 31, 2016
client.go Add support for generic commands + refactor Jul 31, 2016
client_test.go Without mock, example cannot work as test Jul 31, 2016
doc.go
helpers.go Do not export PrepareScope anymore Jul 29, 2016
helpers_test.go Fix code after joinURL renaming Jul 29, 2016
jid.go Refactor Jul 26, 2016
jid_test.go
oauth_token.go Do not export PrepareScope anymore Jul 29, 2016
url.go Add missing file Jul 29, 2016

README.md

ejabberd API library and command-line tool

Build Status Coverage Status

This tool is composed of two components:

  • A command-line tool to interact with ejabberd through ReST API calls from the command-line, from any server type or desktop (Linux, OSX, Windows).
  • An implementation of ejabberd API client library in Go. It can be used to interact with ejabberd from backend applications developed in Go programming language.

Installation

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 get -v github.com/processone/ejabberd-api/cmd/ejabberd

Once the get completes, you should find your new ejabberd (or ejabberd.exe) executable sitting inside $GOPATH/bin/.

To update ejabberd API’s dependencies, use go get with the -u option.

go get -v -u github.com/processone/ejabberd-api/cmd/ejabberd

Configuring ejabberd OAuth API

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:

  1. 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
  2. You can then configure the OAuth commands you want to expose. Check commands_admin_access to make sure ACL for passing commands as admins are set properly:

    commands_admin_access:
      - allow:
        - user: "admin@localhost"
    commands:
      - add_commands: [user, admin, open]
    # Tokens are valid for a year as default:
    oauth_expire: 31536000
    oauth_access: all
  3. Finally, make sure the modules, you need to use the command from are enabled, for example:

    modules:
      mod_admin_extra: {}

ejabberd command-line tool

ejabberd command-line tool allow interacting ejabberd with ejabberd ReST API. It relies on OAuth tokens and scope to define the command the user will be allowed to call.

Usage

  1. Generating an OAuth token:

    To use 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.

  2. Calling ejabberd API from the command-line, using your token file. For example:

    ejabberd stats registeredusers
  3. You can also try to call any availale command thanks to the generic call command. Do not forget -a parameter for commands that requires admin rights. For example:

    cat unregister.json 
    {"user":"test1", "host":"localhost"}
    
    ejabberd call --name unregister -a --data-file=unregister.json

Generating Bash/ZSH completion

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

Available commands

  • token: Get OAuth token. This is needed before calling others commands.
  • stats: Retrieve some stats from ejabberd.

OAuth Token file format

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:

  • access_token: Actual token value.
  • endpoint: Base URL.
  • jid: JID for which user the token was generated.
  • scope: OAuth scope for which the token was generated.
  • expiration: Expiration date for the token.

For example:

{"access_token":"AaQTb0PUZqeZhFKYoaTQBb4KKkCTAolE",
 "endpoint":"http://localhost:5281/",
 "jid":"admin@localhost",
 "scope":"ejabberd:admin",
 "expiration":"2017-07-23T13:53:08.326421575+02:00"}

Development

Local build

go build -o ejabberd cmd/ejabberd/main.go

Running tests

You can run tests from repository clone with command:

go test -race -v ./.