/jackal

An XMPP server written in Go (Golang).

Primary LanguageGoGNU General Public License v3.0GPL-3.0

jackal

An XMPP server written in Go.

This repository is a fork of ortuman/jackal making it available for SCION/QUIC. Refer to the original repository for general usage.

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 (BadgerDB, MySQL 5.7+, MariaDB 10.2+, PostgreSQL 9.5+)
  • Cross-platform (OS X, Linux)

Installing

Getting Started

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

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

This will retrieve the code and install the jackal server application into your $GOPATH/bin path.

By default the application will try to read server configuration from /etc/jackal/jackal.yml file, but alternatively you can specify a custom configuration path from command line.

$ jackal --config=$GOPATH/src/github.com/ortuman/jackal/example.jackal.yml

MySQL database creation

Grant right to a dedicated 'jackal' user (replace password with your desired password).

echo "CREATE USER IF NOT EXISTS 'jackal'@'localhost' IDENTIFIED BY 'password';" | mysql -h localhost -u root -p
echo "GRANT ALL ON jackal.* TO 'jackal'@'localhost';" | mysql -h localhost -u root -p

Create 'jackal' database (using previously created password).

echo "CREATE DATABASE jackal;" | mysql -h localhost -u jackal -p

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

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

Load database schema into the database.

mysql -h localhost -D jackal -u jackal -p < mysql.up.sql

Your database is now ready to connect with jackal.

Using PostgreSQL

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;

Run the postgres script file to create database schema. In jackal's root directory run:

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!

Push notifications

Support for XEP-0357: Push Notifications is not yet available in jackal.

However there's a chance to forward offline messages to some external service by configuring offline module as follows:

  mod_offline:
    queue_size: 2500
    gateway:
      type: http
      auth: a-secret-token-here
      pass: http://127.0.0.1:6666

Each time a message is sent to an offline user a POST http request to the pass URL is made, using the specified Authorization header and including the message stanza into the request body.

Run jackal in Docker

Set up jackal in the cloud in under 5 minutes with zero knowledge of Golang or Linux shell using our jackal Docker image.

$ docker pull ortuman/jackal
$ docker run --name jackal -p 5222:5222 ortuman/jackal

Supported Specifications

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 GNU General Public License, Version 3.0. See LICENSE for the full license text.

Contact

If you have any suggestion or question:

Miguel Ángel Ortuño, JID: ortuman@jackal.im, email: ortuman@pm.me

SCION Specifics (new in this fork)

SCION config

In .yml configuration file, you can provide different options for the incoming SCION connections:

  • addr: SCION address where the server is listening for incoming connections (if "localhost", jackal determines the SCION localhost on startup)
  • port: Port listening for incoming SCION connections (default is 52690)
  • keep_alive: Time after which the unresponsive connection is broken.
  • cert_path: Absolute path to the certificate used in creating QUIC connection (can be the same as the certificate used in c2s IP connection)
  • priv_key_path: Private key corresponding to the certificate, also used in creating QUIC connection

Install MySQL

sudo apt-get install mysql-server
mysql_secure_installation

Name resolution

In the router/hosts section of the .yml file, replace the "name" entry with your server name. Make sure that this name resolves over DNS to a valid IP address where the server will be accepting client requests. Also, specify the paths to the TLS private key and certificate in the tls section, as well as in the scion_transport section. Finally, your hostname specified in the router/hosts section needs to resolve to a valid SCION address on the specified RAINS server. SCION address where the RAINS server is running needs to be specified in the config file at ~/go/src/github.com/scionproto/scion/gen/rains.cfg. Simply put the address of the RAINS server together with the port inside this file. NOTE: when building jackal, both SCION and IP address mappings from /etc/hosts file will be loaded.

Connect to jackal

Once you have the config file setup correctly, together with the MySQL database, valid certificates and the DNS and RAINS entries, you can run your jackal server.

./jackal -c example.jackal.yml

Notes for local testing

To be used only when playing with jackal.

User registration

Since some XMPP clients do not support in-band registration (e.g. Profanity), users need to be created manually. So far, the only way is to manually add them into the MySQL database created previously. For example:

mysql -h localhost -u jackal -p
use jackal;
insert into users (`username`, `password`, `last_presence`, `last_presence_at`, `updated_at`, `created_at`) values ('user1', 'asdf', '<presence from="user1@localhost/profanity" to="user1@localhost" type="unavailable"/>', '2019-04-19 18:42:58', '2019-04-19 18:42:58', '2019-04-19 18:42:58');

Generating self-signed certificates

If you need to create self-signed certificates, you might find this post useful.