jabber.el - an XMPP client for Emacs

Description

jabber.el is an XMPP client for Emacs. XMPP (also known as ‘Jabber’) is an IETF-standard federated instant messaging protocol.

To try it out, see the install instructions.

Why XMPP?

XMPP is the only instant messaging protocol which simultaneously -

1. has most features you expect from modern chat - offline messages, multi-device support, file transfer, message correction, A/V calls, end-to-end encryption, etc. (Excludes IRC, Tox, Briar, etc.)
2. is federated, rather than centralized. (Excludes WhatsApp, Discord, Telegram, Signal, …)
3. has highly efficient server implementations. A single XMPP server on a Raspberry Pi can serve thousands of users. (Excludes Matrix.)
4. has a rich ecosystem of FOSS clients and servers. (Excludes WhatsApp, Discord, Telegram, Signal, …)
5. is an established IETF standard. (Excludes Matrix, Tox, Telegram, Signal, …)
6. is governed and evolved by an open community of users and developers.
7. has outlasted all competition over 24 years. (Unless IRC counts.)

Differences from upstream

1. More features - XEP-0363: HTTP File Upload, XEP-0280: Message Carbons
2. Support for XEmacs and old Emacs versions has been dropped
3. The external dependency hexrgb.el has been replaced with color.el (which is part of Emacs)
4. The deprecated cl library has been replaced with cl-lib
5. Build system has been changed from Autotools to a Makefile
6. lexical-binding is used in all files
7. Lots of cleanup by addressing checkdoc and byte-compiler warnings - addition/improvement of docstrings, function/variable declarations, etc

Community

New resources

• project page
• chat: https://xmpp.link/#[email protected]?join (general Emacs and jabber.el talk)
• chat: https://xmpp.link/#[email protected]?join (jabber.el developement)

Old resources

• project page
• home page
• wiki page
• mailing list:
  • http://lists.sourceforge.net/lists/listinfo/emacs-jabber-general
  • http://dir.gmane.org/gmane.emacs.jabber.general
• chat: [email protected] and [email protected] (Russian, English)

Requirements

jabber.el requires GNU Emacs 27.1 or later.

Two required libraries, fsm.el and srv.el, are present in lisp/jabber-fallback-lib/.

Encrypted connections

Many Jabber servers require encrypted connections, and even if yours doesn’t it may be good idea. To get an encrypted connection, the most convenient option is to use GNU Emacs 24 with GnuTLS support compiled in. You can check whether you have that by typing:

M-: (gnutls-available-p)

If that commands shows t in the echo area, then you have working GnuTLS support. If it shows nil or signals an error, then you don’t.

Failing that, jabber.el will use the starttls.el library, which requires that the GnuTLS command line tool “gnutls-cli” is installed.

In Debian-based distributions, “gnutls-cli” is in the “gnutls-bin” package.

The above applies to STARTTLS connections, the most common way to encrypt a Jabber connection and the only one specified in the standards. STARTTLS connections start out unencrypted, but switch to encrypted after negotiation. jabber.el also supports connections that are encrypted from start. For this it uses the tls.el library, which requires either “gnutls-cli” or the OpenSSL command line tool “openssl” to be installed.

To use the latter form of encryption, customize jabber-account-list.

Note that only the connection from you to the server is encrypted; there is no guarantee of connections from your server to your contacts’ server being encrypted.

Usage

To connect to a Jabber server, type C-x C-j C-c (or equivalently M-x jabber-connect-all) and enter your JID. With prefix argument, register a new account. You can set your JID permanently with M-x jabber-customize.

Your roster is displayed in a buffer called *-jabber-*. To disconnect, type C-x C-j C-d or M-x jabber-disconnect.

You may want to use the menu bar to execute Jabber commands. To enable the Jabber menu, type M-x jabber-menu.

For a less terse description, read the enclosed manual.

For bug reports, help requests and other feedback, use the trackers and forums at the project page mentioned above.

Configuration

All available configuration options are described in the manual. This section only serves to point out the most important ones.

To change how you are notified about incoming events, type M-x customize-group RET jabber-alerts.

To activate logging of all chats, set jabber-history-enabled to t. By default, history will be saved in ~/.jabber_global_message_log; make sure that this file has appropriate permissions. Type M-x customize-group RET jabber-history for more options.

By default, jabber.el will send a confirmation when messages sent to you are delivered and displayed, and also send “contact is typing” notifications. To change this, type M-x customize-group RET jabber-events, and set the three jabber-events-confirm-* variables to nil.

By default, jabber.el logs all MUC presence announcements to the chat buffer. With the advent of mobile clients that frequently lose and regain network connectivity, the user left/joined messages can flood the chat. Customize jabber-muc-decorate-presence-patterns to hide or deemphasize presence announcements. See the manual for details (info “(jabber) Presence announcements”).

File transfer

This release of jabber.el contains support for file transfer. You may need to configure some variables to make it work; see the manual for details.

XMPP URIs

It is possible to make various web browsers pass links starting with “xmpp:” to jabber.el. In the ideal case, this works right after running “make install”. Otherwise, see the manual, section “XMPP URIs”.

Design

As a XMPP client, jabber.el is mostly just a face in the crowd, except that it uses buffers where GUI clients have windows. There is a roster buffer, and to chat with someone you open a chat buffer, and there are buffers for interaction with servers and services. Then again, jabber.el delivers excellent console performance and customizable hooks (if you have speech synthesizer software, hook it up to your presence alerts).

Troubleshooting

Common connection issues

When a connection fails, there is usually a message in the echo area describing the failure. If the echo area has already been cleared, check the *Messages* buffer.

Here are some of the common connection failure modes:

No response beyond “Connecting…”

Connecting to <server-name>:5222...

This is likely a DNS lookup failure. Check the XMPP server name in jabber-account-list.

STARTTLS negotiation failed

When attempting to connect to, for instance, example.com, one of the following messages:

[email protected]: connection lost: ‘STARTTLS negotiation failed: GnuTLS error: #<process jabber>, nil’

= or =

gnutls.el: (err=[nil] Symbol has no numeric gnutls-code property) boot:  ...

likely indicates the server example.com’s SSL certificate has expired. To confirm this, M-x set-variable RET gnutls-log-level RET 1 RET, then try to connect again. Check the *Messages* buffer for messages of the form:

gnutls.c: [1] (Emacs) verification: certificate has expired

or other verification failed messages.

Connection lost

A message of the form:

[email protected]: connection lost: ‘connection broken by remote peer’

may arise from connecting to the wrong port, for example attempting a STARTTLS connection to a direct TLS port (often 5223).

Authentication failure

STARTTLS encryption required, but disabled/non-functional at our end

This likely means that the “gnutls” package is not available. Check

(gnutls-available-p)

if that returns nil, consult

(info "(emacs-gnutls) Help For Users")

for more details and potential mitigation.

Further reading

Documentation for developers is present in DEV.org.

How-to guides

See also - how-to guides in the developer documentation.

How to install jabber.el

from MELPA

1. Add the MELPA repositories to your Emacs - https://melpa.org/#/getting-started
2. Type M-x package-install RET jabber RET

If all goes well, jabber.el commands like jabber-connect should now be available in the M-x menu.

from source with package-vc

1. Ensure you have git, makeinfo (part of the texinfo package), and Emacs 29.1 or newer.
2. Add the following lines to your init.el -

(unless (package-installed-p 'jabber)
  (require 'package-vc)
  (package-vc-install '(jabber
                        :url "https://codeberg.org/emacs-jabber/emacs-jabber"
                        :branch "production"
                        :lisp-dir "lisp"
                        :doc "README.org")))

Alternatively, if you have already cloned the jabber.el repository, you can use the following snippet to install from that repository:

(unless (package-installed-p 'jabber)
  (require 'package-vc)
  (add-to-list 'package-vc-selected-packages
               '(jabber
                 :url "https://codeberg.org/emacs-jabber/emacs-jabber"
                 :branch "production"
                 :lisp-dir "lisp"
                 :doc "README.org"))
  ;; Change the path below to the location of your local jabber.el repository.
  (package-vc-install-from-checkout "~/.local/src/emacs-jabber" "jabber"))

In your init.el, type M-x eval-buffer RET.

If all goes well, jabber.el commands like jabber-connect should now be available in the M-x menu. The documentation for jabber.el should also be installed.

manually from source

1. Ensure you have git, and Emacs 27.1 or newer
2. Clone the repository by typing the following into a terminal -

   git clone https://codeberg.org/emacs-jabber/emacs-jabber
   cd ~/emacs-jabber/
   make
       

3. Add the following lines to your init.el -

   (add-to-list 'load-path "~/emacs-jabber/lisp/")
   (load "~/emacs-jabber/lisp/jabber-autoloads")
       

   …and, while still in your init.el, type M-x eval-buffer RET.

If all goes well, jabber.el commands like jabber-connect should now be available in the M-x menu.

To install the Info documentation, copy jabber.info to /usr/local/info and run "install-info /usr/local/info/jabber.info".

How to register an account

If you don’t have an XMPP account, you need to register one.

1. Set up your own server, or use a public server. Curated lists of public servers may be found at https://compliance.conversations.im/old/ and https://providers.xmpp.net/.
2. If your server supports In-Band Registration, you can register from Emacs -
   1. Press C-u C-x C-j C-c, or C-u M-x jabber-connect.
   2. Enter your desired JID in the form [email protected].
   3. Fill out and send the registration form.
3. If your server does not support In-Band Registration, register on the server website.

How to chat with jabber.el

1. Connect to your server by typing C-x C-j C-c (or M-x jabber-connect). Enter your JID and password.
2. Open a chat buffer in one of the following ways -
   • Place point on a contact in the roster buffer, and hit RET.
   • Press C-x C-j C-j (M-x jabber-chat-with) and enter a JID in the minibuffer.
     • This can also be used to join MUCs.
3. In the chat buffer, type your message and hit RET to send it.
   • To insert a newline in your message, press C-j.
4. If you wish to disconnect, type M-x jabber-disconnect or C-x C-j C-d.
   • To disconnect just one account, type M-x jabber-disconnect-one or C-u C-x C-j C-d.

Credits

Developers

• Tom Berger
• Magnus Henoch
• Kirill A. Korinskiy
• Detlev Zundel
  • wmii support
• Evgenii Terechkov

Contributors

• Georg Lehner
  • network transport functions
• Anthony Chaumas-Pellet
• Jérémy Compostella
• Mathias Dahl
  • history logging
  • watch functionality
• Mario Domenech Goulart
  • sawfish support
  • xmessage support
• Nolan Eakins
• Ami Fischman
  • Chat State Notifications
• François Fleuret
• David Hansen
• Adam Sjøgren
  • notifications.el support
• Rodrigo Lazo
  • notifications.el support
  • libnotify.el support
• Justin Kirby
• Carl Henrik Lunde
  • network transport functions
  • activity tracking
• Olivier Ramonat
• Andrey Slusar
• Valery V. Vorotyntsev
  • GMail notifications
• Milan Zamazal
• Xavier Maillard
• Vitaly Mayatskikh
• Alexander Solovyov
• Demyan Rogozhin
  • XML console mode
• Michael Cardell Widerkrantz
  • tmux support
• Case Duckworth (acdw)
  • PR #2
• Hugh Daschbach (hdasch)
  • MUC presence announcements
  • Enable XEP-0280 (message carbons) by default

Maintainers

• wgreenhouse
  • 2021 resurrection
• cngimenez
  • HTTP Upload support
  • documentation for FSM and its use in this project
• contrapunctus
  • literate Org migration
  • Makefile (shoutout to tomasino of #[email protected] for the Makefile-debugging help)
  • migration back to traditional source files