Configuration

The configuration is located in the file ~/.config/poezio/poezio.cfg On its first startup, poezio will create that file (and its containing directories) with the default configuration. You can edit that file manually or use the /set command to edit some of its values directly from poezio. This file is also used to configure key bindings, but this is explained in the Keys documentation file.

That file is read at each startup and the configuration is saved when poezio is closed.

This configuration file requires all global options to be in a section named [Poezio]. Some other options can be in optional sections and will apply only to tabs having the option’s name.

An option is formatted like this:

option = value

An empty value doesn’t mean that the default value will be used. That’s just an empty value. To use the default value, just comment or remove the option entirely.

Here is a list of all the available configuration options, their meaning and their default value.

Global section options

These options have a sense when they are in the global section. Some of them can also be in an optional configuration section, see the next section of this documentation.

The options here are separated thematically for convenience but they all go into the main config section.

Security

Options pertaining to security, such as TLS encryption and certificate validation.

ca_cert_path

Default value: [empty]

Path to the certificate of the Certification Authority. As some services may keep different certificates, it is an alternative to the Trust On First Use model provided by the certificate option. This option is not affected by ignore_certificate and boths checks may be active at the same time.

certificate

Default value: [empty]

The fingerprint of the SSL certificate as a hexadecimal string, you should not touch it, except if know what you are doing.

ciphers

Default value: HIGH+kEDH:HIGH+kEECDH:HIGH:!PSK:!SRP:!3DES:!aNULL

The TLS cipher suites allowed, in OpenSSL format. Modify this if you know what you are doing, see the Ciphers dedicated section for more details.

force_encryption

Default value: true

If set to true, all connections will use TLS by default. Only turn this to false if you cannot connect to your server, and do not care about your password or the pricacy of your communications.

ignore_certificate

Default value: false

Skip certificate validation on connection when true. Useful when you are in anonymous mode and changing servers often. Dangerous in other cases, from a security perspective.

Account

Options related to account configuration, nickname…

alternative_nickname

Default value: [empty]

If you want poezio to join the room with an alternative nickname when your nickname is already in use in the room you wanted to join, put a non-empty value. If you don’t, poezio won't join the room This value will be added to your nickname to create the alternative nickname. For example, if you set "_", and wanted to use the nickname "john", your alternative nickname will be "john_".

custom_host

Default value: [empty]

A custom host that will be used instead of the DNS records for the server (anonymous or the jid’s) defined above. You should not need this in a "normal" use case.

custom_port

Default value: [empty]

A custom port to use instead of the 5222. This option can be combined with custom_host. You should not need this in a "normal" use case.

default_nick

Default value: [empty]

the nick you will use when joining a room with no associated nick If this is empty, the $USER environnement variable will be used

jid

Default value: [empty]

Jabber identifier. Specify it only if you want to connect using an existing account on a server. This is optional and useful only for some features, like room administration or nickname registration. The server option will be ignored if you specify a JID (Jabber id) It should be in the form nickname@server.tld

password

Default value: [empty]

A password is needed only if you specified a jid. It will be ignored otherwise If you leave this empty, the password will be asked at each startup, which is recommended.

resource

Default value: [empty]

The resource you will use. If it's empty, your resource will be chosen (most likely randomly) by the server. It is not recommended to use a resource that is easy to guess, because it can lead to presence leak.

rooms

Default value: [empty]

The rooms you will join automatically on startup, with associated nickname or not.

Format : room@server.tld/nickname:room2@server.tld/nickname2.

The default_nick option will be used if "/nickname" is not specified.

server

Default value: anon.jeproteste.info

The server to use for anonymous authentication; make sure it supports anonymous authentification.

Note that this option doesn’t do anything at all if you’re using your own JID.

status

Default value: [empty]

The status (show) poezio will send when connecting. It can be available, dnd, chat, xa or away.

Nothing or an invalid value will mean available.

status_message

Default value: [empty]

The status message poezio will send when connecting.

Connectivity

---

Options about general or chatroom connectivity. Reconnecting does not work very well, but you will at least want to know when you get disconnected.

auto_reconnect

Default value: false

Auto-reconnects you when you get disconnected. Should not be necessary, so the default is false.

autorejoin

Default value: false

Set to true if you want to automatically rejoin the room when you're kicked.

autorejoin_delay

Default value: 5

Set to the number of seconds before reconnecting after getting kicked. 0, a negative value, or no value means you reconnect instantly. This option only works if autorejoin is enabled.

connection_check_interval

Default value: 60

A ping is sent to the server every N seconds, N being the value of that option. Change this to a low value if you want to know quickly when you are disconnected, and to a very high value if bandwidth matters so much that you can’t afford 100 bytes/minute, or if you don’t want to waste your battery by waking up the TCP connection too often. Disable this ping altogether by setting this value to 0.

connection_timeout_delay

Default value: 10

The timeout delay of the ping referenced above, 10 should really be fine, but if your network is really unstable, it can be set higher or lower, depending of your preference.

whitespace_interval

Default value: 300

Interval of the whitespace keepalive sending to the server. 300 should be fine, but change it if some services have a stricter policy on client inactivity.

XMPP features

These options enable, disable, or allow to configure the behavior of some non-essential XMPP features. There is a dedicated page to understand what is carbons or user activity/gaming/mood/tune.

display_activity_notifications

Default value: false

If set to true, notifications about the current activity of your contacts will be displayed in the info buffer as 'Activity' messages.

display_gaming_notifications

Default value: false

If set to true, notifications about the games your are playing will be displayed in the info buffer as 'Gaming' messages.

display_mood_notifications

Default value: false

If set to true, notifications about the mood of your contacts will be displayed in the info buffer as 'Mood' messages.

display_tune_notifications

Default value: false

If set to true, notifications about the music your contacts listen to will be displayed in the info buffer as 'Tune' messages.

enable_carbons

Default value: false

Set this to true to enable Message Carbons (XEP-280), which allows transparent message delivery from and to other resources with carbons enabled.

enable_user_activity

Default value: true

Set this to false if you don’t want to receive the activity of your contacts.

enable_user_gaming

Default value: true

Set this to false if you don’t want to receive the gaming activity of your contacts.

enable_user_mood

Default value: true

Set this to false if you don’t want to receive the mood of your contacts.

enable_user_nick

Default value: true

Set to false if you don’t want your contacts to hint you their identity.

enable_user_tune

Default value: true

If this is set to false, you will no longer be subscribed to tune events, and the display_tune_notifications option will be ignored.

enable_xhtml_im

Default value: true

XHTML-IM is an XMPP extension letting users send messages containing XHTML and CSS formating. We can use this to make colored text for example. Set to true if you want to see colored (and otherwise formatted) messages.

send_chat_states

Default value: true

if true, chat states will be sent to the people you are talking to. Chat states are, for example, messages informing that you are composing a message or that you closed the tab, etc.

Set to false if you don't want people to know these information Note that you won’t receive the chat states of your contacts if you don't send yours.

send_os_info

Default value: true

If true, information about the Operation System you're using will be sent when requested by anyone Set to false if you don't want people to know these informations.

Note that this information will not be sent if send_poezio_info is False

send_poezio_info

Default value: true

if true, information about the software (name and version) will be sent if requested by anyone Set to false if you don't want people to know these information

send_time

Default value: true

If true, your current time will be sent if asked Set to false if you don't want people to know that information

use_bookmark_method

Default value: [empty]

The method that poezio will use to store your bookmarks online. Possible values are: privatexml, pep. You should not have to edit this in a normal use case.

use_pep_nick

Default value: true

Use the nickname broadcasted by the user if set to true, and if none has already been set manually.

use_remote_bookmarks

Default value: true

Use this option to force the use of local bookmarks if needed. Anything but "false" will be counted as true.

Visual interface

All these options will change how poezio looks, either by removing parts of the interface, adding them, changing the ordering of stuff, or the way messages are displayed.

display_user_color_in_join_part

Default value: false

If set to true, the color of the nick will be used in MUCs information messages, instead of the default color from the theme.

enable_vertical_tab_list

Default value: false

If true, a vertical list of tabs, with their name, is displayed on the left of the screen.

filter_info_messages

Default value: [empty]

A list of words or sentences separated by colons (":"). All the informational mesages (described above) containing at least one of those values will not be shown.

hide_exit_join

Default value: -1

Exact same thing than hide_status_change, except that it concerns the quit message, and that it will be hidden only if the value is 0.

Default setting means: - all quit and join notices will be displayed

hide_status_change

Default value: 120

Set a number for this setting. The join AND status-change notices will be displayed according to this number.

-1: the notices will ALWAYS be displayed

0: the notices will NEVER be displayed

n: On any other number, the notices will only be displayed if the user involved has talked since the last n seconds

if the value is incorrect, -1 is assumed

Default setting means that status changes won't be displayed unless the user talked in the last 2 minutes

hide_user_list

Default value: false

Whether to hide the list of user in the MultiUserChat tabs or not. Useful for example if you want to copy/paste the content of the buffer, or if you want to gain space

highlight_on

Default value: [empty]

a list of words (separated by a colon (:)) that will be highlighted if said by someone on a room

information_buffer_popup_on

Default value: error roster warning help info

Some informational messages (error, a contact getting connected, etc) are sometimes added to the information buffer. These settings can make that buffer grow temporarly so you can read these information when they appear.

A list of message types that should make the information buffer grow Possible values: error, roster, warning, info, help

max_nick_length

Default value: 25

The maximum length of the nickname that will be displayed in the conversation window. Nicks that are too long will be truncated and have a … appened to them.

popup_time

Default value: 4

The time the message will be visible in the information buffer when it pops up. If the message takes more than one line, the popup will stay visible two more second per additional lines.

roster_group_sort

Default value: name

How to sort the roster groups. The principles are the same as roster_sort (see below).

Available methods are:

• reverse: reverse the current sorting

• name: sort by group name (alphabetical order)

• fold: sort by unfolded/folded

• connected: sort by number of connected contacts

• size: sort by group size

• none: put the "none" group (if any) at the end of the list

roster_show_offline

Default value: false

Set this to true if you want to display the offline contacts too.

roster_sort

Default value: jid:show

How you want the contacts to be sorted inside the roster groups. The given methods are used sequentially (from left to right), so the last one is the one on the far right.

Available methods are :

• reverse: reverse the current sorting

• jid: sort by JID (alphabetical order)

• show: sort by show (available/away/xa/…)

• name: sort by roster name (if no name, then the bare jid is used)

• resource: sort by resource number

• online: sort by online presence (online or not)

Those methods can be arranged however you like, and they have to be separated by colons (":"). If there are more than 3 or 4 chained sorting methods, your sorting is most likely inefficient.

show_inactive_tabs

Default value: true

If you want to show all the tabs in the Tab bar, even those with no activity, set to true. Else, set to false.

show_muc_jid

Default value: true

Set this to false if you want to display only the “user” part of the MUC jid. E.g. if you have poezio@muc.poezio.eu, it will be displayed as poezio. This will be used only if use_tab_nicks is set to true.

show_roster_jids

Default value: true

Set this to false if you want to hide the JIDs in the roster (and keep only the contact names). If there is no contact name, the JID will still be displayed.

show_roster_subscriptions

Defalt value: [empty]

Select the level of display of subscriptions with a char the roster

• all to display all subscriptions

• incomplete to display from, to and none

• one of from, to, none and both to display only that one

• no value or any other value to disable it

show_s2s_errors

Default value: true

Show s2s errors in the roster or not.

show_tab_names

Default value: false

If you want to show the tab name in the bottom Tab bar, set this to true.

show_tab_numbers

Default value: true

If you want to disable the numbers in the bottom Tab bar, set this to false. Note that if both show_tab_names and show_tab_numbers are set to false, the numbers will still be displayed.

show_timestamps

Default value: true

Whether or not to display a timestamp before each message.

theme

Default value: [empty]

The name of the theme file (without the .py extension) that will be used. The file should be located in the themes_dir directory.

If the file is not found (or no filename is specified) the default theme will be used instead

themes_dir

Default value: [empty]

If themes_dir is not set, themes will searched for in $XDG_DATA_HOME/poezio/themes, i.e. in ~/.local/share/poezio/themes/. So you should specify the directory you want to use instead.

This directory will be created at startup if it doesn't exist

use_tab_nicks

Default value: true

The tabs have a name, and a nick, which is, for a contact, its name in the roster, or for a private conversation, the nickname in the MUC. Set this to true if you want to have them shown instead of the jid of the contact.

user_list_sort

Default value: desc

If set to desc, the MUC users will be displayed from top to bottom in the list, if set to asc, they will be displayed from bottom to top.

vertical_tab_list_size

Default value: 20

Size of the vertical tab list.

vertical_tab_list_sort

Default value: desc

If set to desc, the tabs will be displayed from top to bottom in the list, if set to asc, they will be displayed from bottom to top.

User Interaction

Options that change the behavior of poezio in a non-visual manner.

add_space_after_completion

Default value: true

Whether or not to add a space after a completion in the middle of the input (not at the start of it)

after_completion

Default value: ,

What will be put after the name, when using autocompletion at the beginning of the input. A space will always be added after that

beep_on

Default value: highlight private

The terminal can beep on various event. Put the event you want in a list (separated by spaces).

The events can be - highlight (when you are highlighted in a MUC) - private (when a new private message is received, from your contacts or someone from a MUC) - message (any message from a MUC)

separate_history

Default value: false

If true, the history of inputs of the same nature won’t be shared between tabs (as in weechat).

words

Default value: [empty]

Personal dictionary of the words you use often, that you want to complete through recent words completion. They must be separated bu a colon (:). That completion will work in chatrooms, private conversations, and direct conversations.

Logging

Options related to logging.

load_log

Default value: 10

The number of line to preload in a chat buffer when it opens. The lines are loaded from the log files. 0 or a negative value here disable that option.

log_dir

Default value: [empty]

If log_dir is not set, logs will be saved in $XDG_DATA_HOME/poezio/logs, i.e. in ~/.local/share/poezio/logs/. So, you should specify the directory you want to use instead. This directory will be created if it doesn't exist.

log_errors

Default value: true

Logs all the tracebacks and erors of poezio/sleekxmpp in log_dir/errors.log by default. false disables this option.

use_log

Default value: true

Set to false if you don’t want to save logs of all the messages in files.

Plugins

This sections references the configuration of the plugin system; for more details, go to the dedicated page.

plugins_autoload

Default value: [empty]

Colon-separated list of plugins to load on startup.

plugins_conf_dir

Default value: [empty]

If plugins_conf_dir is not set, plugin configs will be loaded from $XDG_CONFIG_HOME/poezio/plugins. You can specify another directory to use, it will be created if it does not exist.

plugins_dir

Default value: [empty]

If plugins_dir is not set, plugins will be loaded from $XDG_DATA_HOME/poezio/plugins. You can specify another directory to use. It will be created if it does not exist.

Other

exec_remote

Default value: false

If this is set to true, poezio will try to send the commands to a FIFO instead of executing them locally. This is to be used in conjunction with ssh and the daemon.py file. See the /link documentation for details.

lang

Default value: en

The lang some automated entities will use when replying to you.

lazy_resize

Default value: true

Defines if all tabs are resized at the same time (if set to false) or if they are really resized only when needed (if set to true). true should be the most comfortable value

max_lines_in_memory

Default value: 2048

Configure the number of maximum lines (for each tab) that can be kept in memory. If poezio consumes too much memory, lower these values

max_messages_in_memory

Default value: 2048

Configure the number of maximum messages (for each tab) that can be kept in memory. If poezio consumes too much memory, lower these values

muc_history_length

Default value: 50

Limit the number of messages you want to receive when the multiuserchat rooms send you recent history

0: You won't receive any

-1: You will receive the maximum

n: You will receive at most n messages

Note that if you set a huge number (like the default value), you may not receive that much messages. The server has its own maximum too.

remote_fifo_path

Default value: ./poezio.fifo

The path of the FIFO used to send the commands (see the exec_remote option).

save_status

Default value: true

Save the status automatically in the status and status_message options.

send_initial_presence

Default value: true

Send initial presence (normal behaviour). If false, you will not send nor receive any presence that is not directed (through /presence) or sent by a MUC.

Optional section options

These option can appear in optional sections. These section are named after a JID. These option will apply only for the given JID. For example if an option appears in a section named [user@example.com], it will apply only for the conversations with user@example.com.

If an option appears in a section named [@example.com], it will apply for all the conversations with people @example.com, except when the option is already defined in a [user@example.com] section.

The priority of settings is thus like this: user@example.com > @example.com > Poezio (more specific to less specific)

Note that some of these options can also appear in the global section, they will be used as a fallback value when no JID-specific option is found.

[Poezio]
foo = false
[user@example.com]
foo = true
[@example.com]
bar = false

autorejoin

Default value: false

Set to true if you want to automatically rejoin the room when you're kicked or banned.

autorejoin_delay

Default value: 5

Set to the number of seconds before reconnecting after getting kicked or banned. 0`, a negative value, or no value means instant reconnection.

This option only works if autorejoin is true.

disable_beep

Default value: false

Disable the beeps triggered by this conversation. Works in MucTab, PrivateTab and ConversationTab.

display_activity_notifications

Default value: false

If set to true, notifications about the current activity of your contacts will be displayed in the info buffer as 'Activity' messages.

display_gaming_notifications

Default value: false

If set to true, notifications about the game your are playing will be displayed in the info buffer as 'Gaming' messages.

display_mood_notifications

Default value: false

If set to true, notifications about the mood of your contacts will be displayed in the info buffer as 'Mood' messages.

display_tune_notifications

Default value: false

If set to true, notifications about the music your contacts listen to will be displayed in the info buffer as 'Tune' messages.

display_user_color_in_join_part

Default value: false

If set to true, the color of the nick will be used in MUCs information messages, instead of the default color from the theme.

hide_exit_join

Default value: -1

Exact same thing than hide_status_change, except that it concerns the quit message, and that it will be hidden only if the value is 0. Default setting means: - all quit and join notices will be displayed

hide_status_change

Default value: 120

Set a number for this setting. The join AND status-change notices will be displayed according to this number.

-1: the notices will ALWAYS be displayed

0: the notices will NEVER be displayed

n: On any other number, the notices will only be displayed if the user involved has talked since the last n seconds

if the value is incorrect, -1 is assumed Default setting means that status changes won't be displayed unless the user talked in the last 2 minutes

highlight_on

Default value: [empty]

A list of words (separated by a colon (:)) that will be highlighted if said by someone on a room.

ignore_private

Default value: false

Ignore private messages sent from this room.

load_log

Default value: 10

The number of line to preload in a chat buffer when it opens. The lines are loaded from the log files. 0 or a negative value here disable that option.

No value makes poezio fall back to the global value.

notify_messages

Default value: true

Only for MUC tabs: if true the tab will change its color to notify you when a new message is received. You will still be notified of highlights. Set to false if you’re not interested in a room non-highlight notifications.

password

Default value: [empty]

The password needed to join the room.

private_auto_response

Default value: Not in private, please.

The message you want to be sent when someone tries to message you.

send_chat_states

Default value: true

Lets you disable/enable chatstates per-JID. Works in MucTab, PrivateTab and ConversationTab.

show_useless_separator

Default value: false

If true, show the separator at the bottom of a chat room, even if no one spoke.

use_log

Default value: [empty]

Use logs for this JID or not. No value will make poezio fall back to the global use_log value.