Jabber Developer
72f4f186da
All checks were successful
CI Code / Check spelling (push) Successful in 18s
CI Code / Check coding style (push) Successful in 34s
CI Code / Code Coverage (push) Successful in 2m36s
CI Code / Linux (debian) (push) Successful in 4m41s
CI Code / Linux (ubuntu) (push) Successful in 4m52s
CI Code / Linux (arch) (push) Successful in 5m40s
Sync with upstream profanity-im/profanity.
Major upstream changes incorporated:
Memory management
- Replace malloc+memset with g_new0 throughout codebase
- Adopt auto_gchar / auto_gcharv / auto_gerror / auto_jid cleanup macros
- Replace free() with g_free() for GAlloc'd memory
Editor rewrite
- Remove pthread-based async editor; use GChildWatch callback API
- New launch_editor(initial_content, callback, user_data) interface
- Proper signal handling (SIGINT, SIGTSTP, SIGPIPE reset in child)
- ui_suspend()/ui_resume() integration for TTY management
OMEMO improvements
- Dual backend support: libsignal-protocol-c and libomemo-c
- Proper pre-key removal after use (XEP-0384 compliance)
- Automatic pre-key regeneration when store drops below threshold
- New functions: omemo_is_device_active(), omemo_is_jid_trusted()
- omemo_get_jid_untrusted_fingerprints() for better error messages
- Fingerprint notifications on new device identity discovery
- Deterministic pre-key ID generation tracking max_pre_key_id
- omemo_trust_changed() UI updates on trust state changes
JID validation
- RFC 6122-compliant validation in jid_is_valid()
- Character-level checks (RFC 6122 forbidden chars: & ' / : < > @)
- Length limits: 1023 per component, 3071 total
- New jid_is_valid_user_jid() for user vs. service JID distinction
Database
- Schema migration v3: UNIQUE constraint on archive_id for deduplication
- Triggers for corrected message tracking (replaces_db_id / replaced_by_db_id)
- db_history_result_t return type, _truncate_datetime_suffix()
UI / console
- win_warn_needed() / win_warn_sent() warning deduplication hash table
- PAD_MIN_HEIGHT dynamic pad sizing with PAD_THRESHOLD auto-cleanup
- Spellcheck integration in input field with Unicode word detection
- cons_spellcheck_setting() for /settings ui output
- /[command]? shortcut for command help
Account config
- Account name sanitization for GKeyFile special chars ([ ] = # \n \r)
- Replace popen() with g_spawn_sync() for eval_password
- TLS policy: add "direct" option alongside legacy
Connection
- Port validation with g_assert (0–65535)
- SHA-256 certificate fingerprint support (XMPP_CERT_PUBKEY_FINGERPRINT_SHA256)
- "direct" TLS policy alias for legacy SSL
Common utilities
- str_xml_sanitize() for XML 1.0 illegal character removal
- string_matches_one_of() with formatted error messages
- valid_tls_policy_option() helper
- prof_date_time_format_iso8601() utility
- Improved strip_arg_quotes() with backslash unescaping
- prof_occurrences() uses g_slist_prepend + reverse for performance
PGP / OX
- Proper GPGME resource cleanup with goto-cleanup pattern
- g_string_free(xmppuri) leak fix in _ox_key_lookup
CSV export
- Use GString + g_file_set_contents instead of raw write() syscalls
Tests
- Restructured into subdirectories: command/, config/, xmpp/, ui/, omemo/, otr/, pgp/
- New test_cmd_ac.c for autocompleter unit tests
- Updated stubs for new UI suspend/resume functions
License headers
- Migrate to SPDX-3.0 identifiers (GPL-3.0-or-later WITH OpenSSL-exception)
────────────────────────────────────────────────────
cproof-specific preservations:
- XEP-0308 LMC: replace_id ?: id logic in message/stanza/omemo
- Force encryption: cmd_force_encryption, test_forced_encryption
- CWE-134: format string protection (cons_show("%s", ...))
- y_start_pos-based paging in window.c
- db_history_result_t return type, _truncate_datetime_suffix()
Merge-time fixes:
- common.c: format-security (-Werror) — cons_show(errmsg) → cons_show("%s", errmsg)
- database.c: null-deref guard — !msg->timestamp → msg && !msg->timestamp
- console.c: implicit size_t → int cast — (int)(maxlen + 1)
- tlscerts.c: %d for size_t — %zu
Build system:
- Kept autotools (Makefile.am, configure.ac); upstream uses Meson
- Restored deleted files: bootstrap.sh, autogen.sh, ax_valgrind_check.m4, configure-debug
- Updated Makefile.am test paths for subdirectory structure
- Added test_cmd_ac, test_forced_encryption to test sources
Functional tests:
- Use cproof version; upstream requires stbbr_for_xmlns from updated stabber
- Not yet available in devs/stabber fork
Closes #64
Merge author: jabber.developer2
Commits authors:
Michael Vetter <jubalh@iodoru.org>
& Steffen Jaeckel <s@jaeckel.eu>
273 lines
10 KiB
Groff
Executable File
273 lines
10 KiB
Groff
Executable File
.TH man 1 "2026-03-23" "0.17.0" "Profanity XMPP client"
|
||
.SH NAME
|
||
Profanity \- a simple console based XMPP chat client.
|
||
.SH SYNOPSIS
|
||
.B profanity
|
||
[\-vh] [\-l level] [\-a account]
|
||
.SH DESCRIPTION
|
||
.B Profanity
|
||
is a simple lightweight console based XMPP chat client. Its emphasis is
|
||
on having a simple and configurable command driven UI, see the homepage
|
||
at:
|
||
.br
|
||
.PP
|
||
<https://profanity-im.github.io>
|
||
.SH OPTIONS
|
||
.TP
|
||
.BI "\-v, \-\-version"
|
||
Show version and build information.
|
||
.TP
|
||
.BI "\-h, \-\-help"
|
||
Show help on command line arguments.
|
||
.TP
|
||
.BI "\-a, \-\-account "ACCOUNT
|
||
Auto connect to an account on startup,
|
||
.I ACCOUNT
|
||
must be an existing account.
|
||
.TP
|
||
.BI "\-c, \-\-config"
|
||
Use an alternative config file.
|
||
.TP
|
||
.BI "\-l, \-\-log "LEVEL
|
||
Set the logging level,
|
||
.I LEVEL
|
||
may be set to DEBUG, INFO (the default), WARN or ERROR.
|
||
.TP
|
||
.BI "\-f, \-\-logfile"
|
||
Specify a different logfile
|
||
.TP
|
||
.BI "\-r, \-\-cmd"
|
||
Specify the commands that should be run right after starting up.
|
||
This can be given multiple times, e.g.
|
||
.EX
|
||
profanity --cmd /foo --cmd "/sleep 10" --cmd /quit
|
||
.EE
|
||
.TP
|
||
.BI "\-t, \-\-theme "THEME
|
||
Specify which theme to use.
|
||
.I THEME
|
||
must be one of the themes installed in $XDG_CONFIG_HOME/profanity/themes
|
||
.SH KEYBINDINGS
|
||
.TP
|
||
.BR Tab , " Shift+Tab"
|
||
Tab completion next, previous. Works for commands, nicks and
|
||
quotes (when input line starts with
|
||
.BR > ).
|
||
.TP
|
||
.BR ALT+1..Alt-0 " or " F1..F10
|
||
Choose window 1..10.
|
||
.TP
|
||
.BR ALT+q..Alt-p " (in QWERTY layout)"
|
||
Choose window 11..20.
|
||
.TP
|
||
.BI ALT+LEFT
|
||
Choose previous chat window.
|
||
.TP
|
||
.BI ALT+RIGHT
|
||
Choose next chat window.
|
||
.TP
|
||
.BI PAGEUP
|
||
Page the active window up.
|
||
.TP
|
||
.BI PAGEDOWN
|
||
Page the active window down.
|
||
.TP
|
||
.BI ALT+PAGEUP
|
||
Page the occupants or roster panel up.
|
||
.TP
|
||
.BI ALT+PAGEDOWN
|
||
Page the occupants or roster panel down.
|
||
.TP
|
||
.BI ALT+UP " or " ALT+WHEEL UP
|
||
Scroll up. Note: limited support for scrolling with mouse wheel,
|
||
please, get in touch with devs if you know how to add support
|
||
for other terminals.
|
||
.TP
|
||
.BI ALT+DOWN " or " ALT+WHEEL DOWN
|
||
Scroll down. See note above.
|
||
.TP
|
||
.BI ALT+a
|
||
Jump to the next unread window.
|
||
.TP
|
||
.BI ALT+v
|
||
Mark current window for later reading with an attention flag.
|
||
.TP
|
||
.BI ALT+m
|
||
Switch between windows marked with the attention flag.
|
||
.TP
|
||
.BI ALT+ENTER
|
||
Add newline character without sending a message/command.
|
||
.TP
|
||
.BI ALT+c
|
||
Run external editor (see
|
||
.BR profanity-editor (1))
|
||
for current input line.
|
||
.TP
|
||
.BI CTRL+DOWN
|
||
Store current input line in history but do not execute it.
|
||
.PP
|
||
.I Note:
|
||
Profanity is using GNU Readline library to handle input so
|
||
default configuration file
|
||
.I ~/.inputrc
|
||
affects operation. In addition to that
|
||
.I $XDG_CONFIG_HOME/profanity/inputrc
|
||
is read after all default keybindigs are set so one can override
|
||
or add settings there. For reference, see Readline documentation:
|
||
.I "info readline ""Command Line Editing"" ""Readline Init File"" ""Readline Init File Syntax"""
|
||
and the list of available Profanity commands in
|
||
.IR inputwin.c .
|
||
Standard Readline keybindings are supported, including
|
||
.B C-r
|
||
for interactive history search and
|
||
.B C-x C-r
|
||
for reloading inputrc without restart.
|
||
.SH USING PROFANITY
|
||
The first step is to connect to an XMPP Server. The \fB/connect\fR and \fB/account\fR command can be used to setup the XMPP accounts within profanity (see
|
||
.BR profanity-connect (1)
|
||
and
|
||
.BR profanity-account (1))
|
||
with an existing XMPP Account. The \fB/register\fR command can be used to register an account on a server.
|
||
.BR profanity-register (1)
|
||
Use the \fB/help commands connection\fR command in profanity to display more commands for managing your connection.
|
||
.PP
|
||
The roster is your address book. By default, your roster will be shown in "window 1" which is the profanity \fB/console\fR.
|
||
It's possible to \fB/roster hide\fR and to \fB/roster show\fR the address book in the profanity console. Buddies can be added via \fB/roster add JID\fR.
|
||
.PP
|
||
To see the online status of your contacts, the \fB/sub\fR command can be used to manage subscriptions to the presence of contacts.
|
||
\fB/sub request\fR will send a request. \fB/sub allow\fR is used to approve a contact's subscription request. Use \fB/help commands roster\fR to get a list of commands which can be used to manage your roster.
|
||
.PP
|
||
Open chat windows can been shown by \fB/wins\fR command. Jumping to a window can be done via \fB/win NUMBER\fR or \fB/win JID\fR. profanity supports autocompletion with TAB-Key.
|
||
.
|
||
The \fB/msg\fR command can be used to start a chat with your contact. Groupchats can be joined with the \fB/join\fR command or managed within the account's bookmark.
|
||
.PP
|
||
If the group chat is stored in the bookmarks, the group chat can be set to auto-join. If the auto-join is switched off, use \fB/bookmark join\fR to join the group chat.
|
||
The \fB/sendfile\fR and \fB/url\fR command can be used to share and download files. Enter > and press the TAB key to quote an existing message in the chat window.
|
||
.PP
|
||
The user guide can be found at <https://profanity-im.github.io/userguide.html>.
|
||
.SH ENCRYPTION
|
||
Profanity supports various kinds of encryption: OMEMO, OTR, PGP, OX.
|
||
You can only enable one of them per correspondent at a time.
|
||
.TP
|
||
.BR OMEMO
|
||
OMEMO (/omemo) is defined in XEP-0384. It uses an implementation of the Signal protocol for key management and to synchronize messages among different clients. It works even when other clients are offline. And offers Perfect Forward Secrecy and Plausible deniability. Servers need to support PEP (XEP-0163).
|
||
We implement the "siacs" version of OMEMO. Version 0.3.0, which is currently the widest adopted option.
|
||
OMEMO is the only encryption option in Profanity that also supports encryption for MUCs (XEP-0045) and file transfer via HTTP upload (XEP-0363).
|
||
.TP
|
||
.BR OTR
|
||
OTR (/otr) is defined in XEP-0364. It uses a combination of the AES symmetric-key algorithm, the Diffie–Hellman key exchange, and the SHA-1 hash function. It offers deniable authentication and Perfect Forward Secrecy. To initialize a session both clients need to be online at the same time. A session is between two clients, so multiclient chats are not working. Which is a feature not a bug. OTR does by design not work for MUCs.
|
||
.TP
|
||
.BR OpenPGP
|
||
OpenPGP (/pgp) is defined in XEP-0027. Is uses a public and secret key. It is also known as Legacy OpenPGP and has been deprecated. It doesn't provide protection against replay attacks. MUCs and file transfer via HTTP upload are not specified and thus not supported.
|
||
.TP
|
||
.BR OX
|
||
OX (/ox) is defined in XEP-0373 and XEP-0374. It's a more modern way to use OpenPGP on XMPP and tries to fix the shortcomings of legacy XEP-0027. Servers need to support PEP (XEP-0163). MUCs and file transfer via HTTP upload are not specified and thus not supported.
|
||
.TP
|
||
.BR DETAILS
|
||
For more details read the relevant XEPs and look at the overview at <https://wiki.xmpp.org/web/XMPP_E2E_Security>
|
||
.SH TERMINOLOGY
|
||
There is some XMPP specific terminology that might be unknown for fresh users. We will try to describe them here since they are often references in the help and man pages.
|
||
.TP
|
||
.BR JID
|
||
Stands for Jabber ID. It refers to an XMPP address. Historically XMPP was also known as Jabber.
|
||
.TP
|
||
.BR MAM
|
||
Stands for Message Archive Management (XEP-0313) and describes the ability to store messages on the server and retrieve them later.
|
||
.TP
|
||
.BR MUC
|
||
Stands for Mutli-User Chats (XEP-0045) and are also called, groups, group chats, chatrooms or conferences.
|
||
.TP
|
||
.BR Roster
|
||
The roster is your contact list. By default displayed at the right side on the console window. See RFC6121.
|
||
.TP
|
||
.BR XEP
|
||
XMPP is an extendable protocol. There are core features and optional features described in XMPP Extension Protocols, short XEPs.
|
||
.PP
|
||
There are various kind of messages.
|
||
.TP
|
||
1:1 messages are regular messages from one party to another party, from one JID to the other JID. Often you have the other party added to your roster.
|
||
.TP
|
||
MUC messages are messages from one party to a group chat.
|
||
.TP
|
||
MUC PM (MUC private message) are messages from one party to another party which are in the same group chat. You might not have the JID of this person in your roster or don't know their JID at all. Communication is done over the MUC via the nick. Only the two parties can see the message. In the Android client Conversations this is displayed as "whispering". If a user leaves a MUC another user can join the MUC with the same nick unless the nick is registered. Which often isn't the case.
|
||
.SH SEE ALSO
|
||
.B Profanity
|
||
itself has a lot of built\-in help. Check the
|
||
.I /help
|
||
command for more information. Type "/help help" for information
|
||
on how to use help itself. Profanity ships with one man page for
|
||
each built-in command, e.g. there is
|
||
.BR profanity-account (1)
|
||
for
|
||
.IR /account .
|
||
.SH CONFIGURATION
|
||
Configuration for
|
||
.B Profanity
|
||
is stored in
|
||
.I $XDG_CONFIG_HOME/profanity/profrc
|
||
, details on commands for configuring Profanity can be found at <https://jabber.space/command-reference/> or the respective built\-in help or man pages.
|
||
.SS Message History Storage
|
||
By default, message history is stored in an SQLite database. An alternative flat-file backend
|
||
stores messages as human-readable plain text files that can be edited with any text editor.
|
||
.PP
|
||
To enable flat-file logging, set in
|
||
.IR profrc :
|
||
.PP
|
||
.EX
|
||
[logging]
|
||
dblog=flatfile
|
||
.EE
|
||
.PP
|
||
Or use the command:
|
||
.B /privacy logging flatfile
|
||
.PP
|
||
Flat-file logs are stored under
|
||
.IR $XDG_DATA_HOME/profanity/flatlog/ ,
|
||
organized as
|
||
.IR {account_jid}/{contact_jid}/history.log .
|
||
.PP
|
||
Each line has the format:
|
||
.br
|
||
.EX
|
||
{ISO8601} [{type}|{enc}|id:{id}|aid:{archive_id}|corrects:{id}] {sender}: {message}
|
||
.EE
|
||
.PP
|
||
Use
|
||
.B /history verify
|
||
to check integrity of stored history (both SQLite and flat-file).
|
||
.PP
|
||
Use
|
||
.B /history export [<jid>]
|
||
to copy messages from SQLite to flat-file format (merge with existing data), or
|
||
.B /history import [<jid>]
|
||
to copy from flat-file to SQLite.
|
||
Both operations skip duplicates.
|
||
Omit the JID to process all contacts.
|
||
.PP
|
||
Use
|
||
.B /history switch sqlite|flatfile
|
||
to change the active database backend at runtime without reconnecting.
|
||
.SH BUGS
|
||
Bugs can either be reported by raising an issue at the Github issue tracker:
|
||
.br
|
||
.PP
|
||
<https://github.com/profanity-im/profanity/issues>
|
||
.br
|
||
.PP
|
||
or to the mailing list at:
|
||
.br
|
||
.PP
|
||
<https://lists.posteo.de/listinfo/profanity>
|
||
.br
|
||
.SH LICENSE
|
||
Copyright (C) 2012 \- 2019 James Booth <boothj5web@gmail.com>.
|
||
Copyright (C) 2019 \- 2026 Michael Vetter <jubalh@iodoru.org>.
|
||
License GPLv3+: GNU GPL version 3 or later <https://www.gnu.org/licenses/gpl.html>
|
||
This is free software; you are free to change and redistribute it.
|
||
There is NO WARRANTY, to the extent permitted by law.
|
||
.SH AUTHORS/CREDITS
|
||
.B Profanity
|
||
was created by James Booth
|
||
.B <boothj5web@gmail.com>
|
||
with many contributions from others, see the full list at: <https://github.com/profanity-im/profanity/graphs/contributors>
|