jackal

An XMPP server written in Go.

About

jackal is a free, open-source, high performance XMPP server which aims to be known for its stability, simple configuration and low resource consumption.

Features

jackal supports the following features:

• Customizable
• Enforced SSL/TLS
• Stream compression (zlib)
• Database connectivity for storing offline messages and user settings (PostgreSQL 9.5+)
• Clustering capabilities (ectd 3.4+)
• Expose prometheus metrics
• Cross-platform (OS X, Linux)

Installing

Getting Started

To start using jackal, install Go 1.16+ and run the following commands:

$ go get -d github.com/ortuman/jackal
$ cd $GOPATH/src/github.com/ortuman/jackal
$ make install installctl

This will fetch the code and install jackal and jackalctl binaries into your $GOPATH/bin path.

By default the application will try to locate service configuration at config.yaml, but alternatively you can specify a custom configuration path either through command line.

$ jackal --config=/your-custom-path/your-config.yaml

or environment variable:

$ env JACKAL_CONFIG_FILE=/your-custom-path/your-config.yaml jackal

PostgreSQL database creation

Create a user and a database for that user:

CREATE ROLE jackal WITH LOGIN PASSWORD 'password';
CREATE DATABASE jackal;
GRANT ALL PRIVILEGES ON DATABASE jackal TO jackal;

Download lastest version of the PostgreSQL schema from jackal Github repository.

wget https://raw.githubusercontent.com/ortuman/jackal/master/sql/postgres.up.psql

Run the postgres script file to create database schema:

psql --user jackal --password -f sql/postgres.up.psql

Configure jackal to use PostgreSQL by editing the configuration file:

storage:
  type: pgsql
  pgsql:
    host: 127.0.0.1:5432
    user: jackal
    password: password
    database: jackal

That's it!

Your database is now ready to connect with jackal.

Creating jackal user

After completing database setup you will have to register a new user to be able to login. To do so, you can use jackal command-line tool to create a new user proving name and password.

jackalctl user add <user>:<password>

Clustering

The purpose of clustering is to be able to use several servers for fault-tolerance and scalability.

Since jackal is a distributed system, it needs a distributed data store like etcd to share its state across the entire cluster.

To properly run jackal in clustering mode make sure to add a cluster section configuration in each of your service nodes.

Here's an example of how this section should look like:

cluster:
  etcd:
    endpoints:
      - http://<etcd-host1>:<etcd-port1>
      - http://<etcd-host2>:<etcd-port2>
      ...
  port: your-cluster-node-port # default is 14369

Note the defined port value will be used to perform cluster node communication, so make sure is reachable within your internal network.

Server extensibility

The purpose of the extensibility framework is to provide an interface between jackal server and third-party external modules, thus offering the possibility of extending the functionality of the service for particular use cases. Extensibility API is almost exclusively based on gRPC and its definition can be at jackal proto definitions repository.

Here's a list of all extendable server components:

• Components
• IQ handlers
• Event handlers
• Authenticators

Run jackal in Docker

The Docker deployment framework supports easy installation and configuration of jackal server.

You need to have Docker installed on your system before you can use a jackal Docker image. See Install Docker for instructions.

Download the jackal Docker image from the official Docker Hub library with this command:

docker pull ortuman/jackal:latest

Start a new jackal Docker container with custom configuration.

docker run --name=jackal \
   --mount type=bind,src=/path-on-host-machine/my-custom-config.yaml,dst=/jackal/config.yaml \
   -d ortuman/jackal:latest

Supported Specifications

• RFC 6120: XMPP CORE
• RFC 6121: XMPP IM
• XEP-0004: Data Forms 2.9
• XEP-0030: Service Discovery 2.5rc3
• XEP-0049: Private XML Storage 1.2
• XEP-0054: vcard-temp 1.2
• XEP-0092: Software Version 1.1
• XEP-0114: Jabber Component Protocol 1.6
• XEP-0115: Entity Capabilities 1.5.2
• XEP-0138: Stream Compression 2.0
• XEP-0160: Best Practices for Handling Offline Messages 1.0.1
• XEP-0190: Best Practice for Closing Idle Streams 1.1
• XEP-0199: XMPP Ping 2.0
• XEP-0220: Server Dialback 1.1.1
• XEP-0237: Roster Versioning 1.3
• XEP-0368: SRV records for XMPP over TLS 1.1.0

Join and Contribute

The jackal developer community is vital to improving jackal future releases.

Contributions of all kinds are welcome: reporting issues, updating documentation, fixing bugs, improving unit tests, sharing ideas, and any other tips that may help the jackal community.

Code of Conduct

Help us keep jackal open and inclusive. Please read and follow our Code of Conduct.

Licensing

jackal is licensed under the Apache 2 License. See LICENSE for the full license text.

Contact

If you have any suggestion or question:

Miguel Ángel Ortuño, JID: [email protected], email: [email protected]