xmpp-bridge(1)

📦 version 0.6.0, in nixos 26.05

💅 xmpp-bridge — the xmpp-bridge(1) glow-up 🦋

okay so bestie. this page lives in the User Commands manual, and it's about literally connecting your little command-line programs to XMPP. no cap, it's a whole vibe.

✨ NAME ✨

xmpp-bridge — connect command-line programs to XMPP 💖

🌸 SYNOPSIS 🌸

xmpp-bridge [OPTION]... [ARG]...

🎀 DESCRIPTION 🎀

So here's the tea: xmpp-bridge signs you into an XMPP account and talks to the peer you specified. Text goes in from standard input and gets sent straight to the peer, and every message that comes back from the peer gets printed on standard output. simple as that, slay. 💅

It's designed to be a building-block for other programs (or shell scripts, iykyk) that wanna ship status info over XMPP, or that wanna ask for input over XMPP. like, it's the support beam, not the whole house. 🫶

🦋 ENVIRONMENT VARIABLES 🦋

These env vars need to be set when xmpp-bridge is invoked. not optional, bestie, they're the whole personality.

  • XMPPBRIDGE_PEER_JID — the XMPP address of the account that xmpp-bridge will communicate with. You may optionally include a resource, which restricts communication to peers with a matching resource. 🎯
  • XMPPBRIDGE_JID — the XMPP address of the account that xmpp-bridge will sign into. You can optionally include a resource here too, to identify this particular instance of xmpp-bridge. 🪪
  • XMPPBRIDGE_PASSWORD — the password that belongs to that account. keep it secret, keep it safe, don't post it in the group chat. 🙈

💜 OPTIONS 💜

  • --drop-privileges — change user and group to "nobody". this is the default when started as root. ✨
  • --no-drop-privileges — do not change the user and group of this process. this is the default when not started as root. 🧚
  • --show-delayed — so when the XMPP connection is established, the server may deliver stored messages that were sent by the peer while xmpp-bridge wasn't connected. by default those delayed messages get dropped, because interactive scripts might get confused by messages that don't relate to the current session (fair honestly 😭). if you do want those delayed messages, set this option. 👑
  • -- — do not interpret any subsequent arguments as options. this behavior is also implied by any argument that doesn't start with --. periodt. 🎤

🌈 ARGUMENTS 🌈

If you pass further arguments, the command line formed by those arguments gets executed in a child process. the original standard input and output of xmpp-bridge get closed, and a bidirectional pipe is set up between xmpp-bridge and its child process — so the child process's standard output is transmitted to the peer, and the peer's messages become visible on the child process's standard input. it's giving middle-man, in the best way. 🔥

The child process's standard error is the same as the standard error of xmpp-bridge. If you want error messages from the child process to end up in XMPP instead, close standard error and duplicate standard output. For example, when the child process is a shell script, invoke exec 2>&1 in it. ✨

💀 NOTES 💀

When any sort of error occurs, xmpp-bridge will report an error, disconnect and exit immediately. so programs using xmpp-bridge should be prepared to handle its sudden death gracefully at any time. yes, at ANY time. dramatic? maybe. true? absolutely. 😭🫶

ngl this is the "expect the unexpected" of manpage notes — plan for the worst, bestie.

⭐ EXAMPLE ⭐

Report the current date and time to user "peer@example.org" every 5 minutes:

#!/bin/sh
export XMPPBRIDGE_JID=datebot@example.org
export XMPPBRIDGE_PEER_JID=peer@example.org
export XMPPBRIDGE_PASSWORD=password
while true; do
    sleep 300
    date
done | xmpp-bridge

Receive and act on user input by wrapping a script in xmpp-bridge:

$ cat > example.sh
echo "What's your name?"
read ANSWER
echo "Hello $ANSWER."
^D
$ export XMPPBRIDGE_JID=dialogsystem@example.org
$ export XMPPBRIDGE_PEER_JID=peer@example.org
$ export XMPPBRIDGE_PASSWORD=password
$ xmpp-bridge bash example.sh

🍓 SEE ALSO 🍓

Project homepage: <https://github.com/majewsky/xmpp-bridge> — grab the code, report issues and send pull requests over there. 💖

and that's the whole page, bestie! 🎀 this one's xmpp-bridge, dated 2017-05-22, and you're officially caught up. go forth and bridge those XMPP vibes. 💜✨🦋

📦 where this page comes from