#+TITLE: jabber.el - The XMPP client for Emacs
#+TEXINFO_DIR_NAME: * jabber.el: (jabber)
#+TEXINFO_DIR_DESC: jabber.el - The XMPP client for Emacs
#+TEXINFO_DIR_CATEGORY: Emacs

* About
[[https://elpa.nongnu.org/nongnu/jabber.svg]]

=jabber.el= is an [[http://xmpp.org][XMPP]] client for Emacs.

See the [[https://xmpp.org/software/jabber-el/][xmpp.org page]] for the full list of supported XEPs.

+ [[https://thanosapollo.org/projects/jabber/][Homepage]]

+ Source:
  + [[https://git.thanosapollo.org/emacs-jabber/about/][git.thanosapollo.org]]

* Requirements

+ Emacs 29.1 or later, compiled with dynamic module support
+ [[https://elpa.gnu.org/packages/fsm.html][fsm]] 0.2.0 or later
+ [[https://elpa.gnu.org/packages/keymap-popup.html][keymap-popup]] 0.2 or later

** OMEMO encryption (optional)

OMEMO end-to-end encryption uses a native C module built from the
vendored [[https://github.com/mierenhoop/picomemo][picomemo]] source.  Build dependencies: a C compiler,
=pkg-config=, and Mbed TLS 3.0 or later (=mbedcrypto=).

Build the module from the ELPA package directory:

#+begin_src sh
  cd /path/to/elpa/jabber-VERSION
  make module
#+end_src

The resulting =jabber-omemo-core.so= (or =.dylib= on macOS) lands
beside the Elisp files and is loaded automatically.  If the module is
missing, OMEMO use signals =OMEMO module not compiled=.

* Installation
=jabber.el= is available via [[https://elpa.nongnu.org/nongnu/jabber.html][NonGNU ELPA]].  That is the only supported
install path.

#+begin_src emacs-lisp
  (use-package jabber
    :ensure t
    :config
    (setq jabber-account-list
          `(("user@example.org"
             (:password . ,(auth-source-pass-get 'secret "xmpp/example.org")))))
    (jabber-modeline-mode 1)
    :bind-keymap (("C-x C-j" . jabber-global-keymap))
    :hook (kill-emacs . jabber-disconnect))
#+end_src

* Configuration
** Authentication
Accounts are configured via =jabber-account-list=.  The simplest form
uses auth-source =~/.authinfo.gpg= for passwords:

#+begin_src emacs-lisp
  (setq jabber-account-list '(("user@example.org")
                               ("second@account.org")))
#+end_src

** SOCKS5 proxy
An account can connect through an unauthenticated SOCKS5 proxy:

#+begin_src emacs-lisp
  (setq jabber-account-list
        '(("user@example.org"
           (:proxy . (:type socks5 :host "127.0.0.1" :port 9050)))))
#+end_src

The destination hostname is sent to the proxy rather than resolved locally.
Proxy connections bypass SRV lookup and use the JID domain on port 5222, or
=:network-server= and =:port= when those are configured.  STARTTLS is supported.
Direct TLS discovery, proxy authentication, and other proxy protocols are not
supported for proxied accounts.

** Bug references

#+begin_src emacs-lisp
  (add-hook 'jabber-chat-mode-hook #'bug-reference-mode)

  ;; Customize references
  (setq jabber-bug-reference-alist
        '(("jabber-el@conference\\.hmm\\.st"
           "\\(#\\([0-9]+\\)\\)"
           "https://todos.thanosapollo.org/r/emacs-jabber/%s")))
#+end_src

* Basic commands
+ Use =M-x jabber-roster= or =C-x C-j C-r= to get started.
