path: root/doc/source/configuration.rst

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 :term:`/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 :ref:`keys-page` 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.

.. glossary::
    :sorted:

    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

    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\_".

    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.

    auto_reconnect

        **Default value:** ``false``

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

    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)

    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 :term:`certificate` option.
        This option is not affected by :term:`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.

    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 (seriously?).

    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.

    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 :term:`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

    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_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_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_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_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_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 :term:`display_tune_notifications` option will be ignored.

    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.

    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.

    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 :term:`/link` documentation for details.

    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 :term:`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

    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.

    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``

    jid

        **Default value:** ``[empty]``

        Jabber identifiant. 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 :term:`server` option will be ignored if you specify a JID (Jabber id)
        It should be in the form nickname@server.tld

    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

    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 :term:`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

    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

    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.

    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.

    password

        **Default value:** ``[empty]``

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

    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.

    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.

    remote_fifo_path

        **Default value:** ``./poezio.fifo``

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

    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 :term:`default_nick` option will be used if "/nickname" is not specified.

    roster_group_sort

        **Default value:** ``name``

        How to sort the roster groups. The principles are the same as :term:`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.

    save_status

        **Default value:** ``true``

        Save the status automatically in the :term:`status` and :term:`status_message` options.

    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_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 :term:`/presence`) or sent by a
        MUC.

    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 :term:`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

    separate_history

        **Default value:** ``false``

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

    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.

    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 :term:`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_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 :term:`show_tab_names` and :term:`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.

    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.

    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_log

        **Default value:** ``true``

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

    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.

    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.

    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 :term:`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 :term:`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

    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.

    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.

    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.


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.

.. code-block:: ini

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

.. glossary::
    :sorted:

    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 :term:`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_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.

    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.

    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.

    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 :term:`use_log` 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.