Code Monkey home page Code Monkey logo

ejabberd-api's Introduction

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

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 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
  3. Finally, make sure to enable the modules that provide the commands you want to use, for example:

    modules:
      mod_admin_extra: {}

ejabberd command-line tool

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.

Usage

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

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

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.

To get a full list of commands and their options:

ejabberd --help-long

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

ejabberd-api's People

Contributors

mremond avatar badlop avatar dependabot[bot] avatar rincewindshat avatar

Stargazers

Alexandre Ferreira avatar Prawee Wongsa avatar Oussama Rouabah avatar maccn avatar  avatar Amir .DEV avatar  avatar Marcus S. Abildskov avatar Rafik NACCACHE avatar Vishwas Puri avatar AJEET SINGH avatar  avatar oldtree avatar perestoronin avatar STYLIANOS IORDANIS avatar Dmytro Chornyi avatar  avatar Lee Jae-yeol avatar necmi acikyol avatar Mohamed Abida avatar Samuel Berthe avatar Dmitrii D avatar Sakib Sami avatar  avatar

Watchers

Sébastien Luquet avatar Paweł Chmielowski avatar  avatar  avatar Neustradamus avatar Zbyszek Żółkiewski avatar mayulu avatar Jérôme Sautret avatar James Cloos avatar Alexey Shchepin avatar  avatar  avatar  avatar

ejabberd-api's Issues

Cannot compile with go 1.18 or newer

How to reproduce:

e.g. with Docker:

ARG GO_VSN='1.18'
FROM docker.io/golang:${GO_VSN}-alpine AS build
RUN go install github.com/processone/ejabberd-api/cmd/ejabberd@latest

Error msg:

/go # go install github.com/processone/ejabberd-api/cmd/ejabberd@latest
go: downloading github.com/processone/ejabberd-api v0.0.0-20210707155731-b02bcbec4fa9
go: finding module for package gopkg.in/alecthomas/kingpin.v2
go: downloading gopkg.in/alecthomas/kingpin.v2 v2.3.2
go: found gopkg.in/alecthomas/kingpin.v2 in gopkg.in/alecthomas/kingpin.v2 v2.3.2
go: github.com/processone/ejabberd-api/cmd/ejabberd imports
        gopkg.in/alecthomas/kingpin.v2: gopkg.in/alecthomas/[email protected]: parsing go.mod:
        module declares its path as: github.com/alecthomas/kingpin/v2
                but was required as: gopkg.in/alecthomas/kingpin.v2

go vsn 1.17 works

ARG GO_VSN='1.17'
FROM docker.io/golang:${GO_VSN}-alpine AS build
RUN go get -v github.com/processone/ejabberd-api/cmd/ejabberd

Output:

/go # go get -v github.com/processone/ejabberd-api/cmd/ejabberd
go: downloading github.com/processone/ejabberd-api v0.0.0-20210707155731-b02bcbec4fa9
go: downloading gopkg.in/alecthomas/kingpin.v2 v2.3.2
get "gopkg.in/alecthomas/kingpin.v2": found meta tag vcs.metaImport{Prefix:"gopkg.in/alecthomas/kingpin.v2", VCS:"git", RepoRoot:"https://gopkg.in/alecthomas/kingpin.v2"} at //gopkg.in/alecthomas/kingpin.v2?go-get=1
go: downloading gopkg.in/alecthomas/kingpin.v2 v2.2.6
go: downloading github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751
go: downloading github.com/alecthomas/units v0.0.0-20211218093645-b94a6e3cc137
go get: installing executables with 'go get' in module mode is deprecated.
        Use 'go install pkg@version' instead.
        For more information, see https://golang.org/doc/go-get-install-deprecation
        or run 'go help get' or 'go help install'.
github.com/alecthomas/units
github.com/alecthomas/template/parse
github.com/processone/ejabberd-api
github.com/alecthomas/template
gopkg.in/alecthomas/kingpin.v2
github.com/processone/ejabberd-api/cmd/ejabberd
/go # ./bin/ejabberd 
usage: ejabberd [<flags>] <command> [<args> ...]

A command-line front-end for ejabberd server API.

cannot unmarshal number into Go value of type ejabberd.Stats

  1. run ejabberd23.10
  2. register zlr@localhost zlr
  3. go install -v github.com/processone/ejabberd-api/cmd/ejabberd@master
  4. generate token :
    ./ejabberd token -j zlr@localhost -p zlr -s ejabberd:admin
  5. try the api
    ./ejabberd stats registeredusers
  6. error occured:
    ejabberd: error: stats error "registeredusers": Error 99: json: cannot unmarshal number into Go value of type ejabberd.Stats

Add LICENSE

Godoc doesn't work since there doesn't seem to be a LICENSE file for this project

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.