Repository files navigation

An XMPP server written in Go.

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

jackal supports the following features:

• Customizable
• Enforced SSL/TLS
• Stream compression (zlib)
• Database connectivity for storing offline messages and user settings (PostgreSQL 9.5+, BoltDB)
• Caching (Redis 6.2+)
• Clustering capabilities (etcd 3.4+)
• Exposeprometheus metrics
• Cross-platform (OS X, Linux)

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

$ git clone git@github.com:ortuman/jackal.git$cd jackal$ make install installctl

This will fetch the code and installjackal andjackalctl binaries into your$GOPATH/bin path.

By default the application will try to locate service configuration atconfig.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

To make it easy to install jackal via Helm in Kubernetes a chart has been included into this repository.

After customizing your ownvalues.yaml file run the following command to install and configure all required components underjackal namespace.

sh ./helm/scripts/install.sh<your_custom_values>.yaml

In turn, an active chart can be updated by running the upgrade script as follows:

sh ./helm/scripts/upgrade.sh<your_custom_values>.yaml

On the other hand, you can also remove the jackal chart from your Kubernetes cluster by running the uninstall script:

sh ./helm/scripts/uninstall.sh

Create a user and a database for that user:

CREATE ROLE jackal WITH LOGIN PASSWORD'password';CREATEDATABASEjackal;GRANT ALL PRIVILEGESON DATABASE jackal TO jackal;

Download lastest version of thePostgreSQL 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:pgsqlpgsql:host:127.0.0.1:5432user:jackalpassword:passworddatabase:jackal

That's it!

Your database is now ready to connect with jackal.

After completing database setup and startingjackal service you'll have to register a new user to be able to login. To do so, you can usejackal command-line tool to create a new user proving name and password.

make installctl&& jackalctl user add<user>:<password>

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

Sincejackal is a distributed system, it needs a distributed data store likeetcd to share its state across the entire cluster.

To properly runjackal in clustering mode make sure to add acluster section configuration in each of your service nodes.

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

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

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

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.ExtensibilitygRPC API proto files can be found at jackalproto definitions repository.

• Authenticators
• Components

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. SeeInstall 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 \   -p"5222:5222" \   -p"15280:15280"\# used by jackalctl   -d ortuman/jackal:latest

Alternatively, and with the purpose of facilitating service mounting, you can make use ofdocker-compose as follows:

docker-compose -f dockerfiles/docker-compose.yml up

This command will spin up ajackal server along with its dependencies on a docker network and start listening for incoming connections on port5222.

Once up and running, don't forget toregister one or more users usingjackalctl.

• RFC 6120: XMPP CORE
• RFC 6121: XMPP IM
• XEP-0004: Data Forms2.9
• XEP-0012: Last Activity2.0
• XEP-0030: Service Discovery2.5rc3
• XEP-0049: Private XML Storage1.2
• XEP-0054: vcard-temp1.2
• XEP-0059: Result Set Management1.0
• XEP-0092: Software Version1.1
• XEP-0114: Jabber Component Protocol1.6
• XEP-0115: Entity Capabilities1.5.2
• XEP-0122: Data Forms Validation1.0.2
• XEP-0138: Stream Compression2.0
• XEP-0160: Best Practices for Handling Offline Messages1.0.1
• XEP-0190: Best Practice for Closing Idle Streams1.1
• XEP-0191: Blocking Command1.3
• XEP-0198: Stream Management1.6
• XEP-0199: XMPP Ping2.0
• XEP-0202: Entity Time2.0
• XEP-0220: Server Dialback1.1.1
• XEP-0237: Roster Versioning1.3
• XEP-0280: Message Carbons0.13.3
• XEP-0297: Stanza Forwarding1.0
• XEP-0313: Message Archive Management1.0.1
• XEP-0368: SRV records for XMPP over TLS1.1.0

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

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

jackal is licensed under the Apache 2 License. SeeLICENSE for the fulllicense text.

If you have any suggestion or question:

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