configuration.rst 37.1 KB
Newer Older
mathieui's avatar
mathieui committed
1 2
.. _config:

mathieui's avatar
mathieui committed
3 4
Configuration
=============
mathieui's avatar
mathieui committed
5

mathieui's avatar
mathieui committed
6
The configuration is located in the file ``~/.config/poezio/poezio.cfg``
mathieui's avatar
mathieui committed
7 8 9 10
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
mathieui's avatar
mathieui committed
11
in the :ref:`keys-page` documentation file.
mathieui's avatar
mathieui committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31

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
mathieui's avatar
mathieui committed
32
----------------------
mathieui's avatar
mathieui committed
33 34 35 36 37

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.

mathieui's avatar
mathieui committed
38 39
The options here are separated thematically for convenience but they all
go into the main config section.
mathieui's avatar
mathieui committed
40 41


mathieui's avatar
mathieui committed
42 43
Security
~~~~~~~~
mathieui's avatar
mathieui committed
44

mathieui's avatar
mathieui committed
45 46
Options pertaining to security, such as :ref:`TLS encryption <security settings>`
and certificate validation.
mathieui's avatar
mathieui committed
47

mathieui's avatar
mathieui committed
48 49
.. glossary::
    :sorted:
mathieui's avatar
mathieui committed
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64

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

65 66 67 68 69
        The SHA-2 fingerprint of the SSL certificate as a hexadecimal string,
        you should not touch it, except if know what you are doing.

        .. note:: the fingerprint was previously stored in SHA-1, and has been
                silently upgraded to SHA-2 if the SHA-1 still matched.
mathieui's avatar
mathieui committed
70

71 72 73 74 75 76 77 78
    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 :ref:`ciphers` dedicated section
        for more details.

mathieui's avatar
mathieui committed
79
    force_encryption
80

mathieui's avatar
mathieui committed
81
        **Default value:** ``true``
82

mathieui's avatar
mathieui committed
83 84 85
        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.
86

mathieui's avatar
mathieui committed
87
    ignore_certificate
88

mathieui's avatar
mathieui committed
89
        **Default value:** ``false``
90

mathieui's avatar
mathieui committed
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
        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…

.. glossary::
    :sorted:

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

mathieui's avatar
mathieui committed
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135
    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
mathieui's avatar
mathieui committed
136
        If this is empty, the $USER environment variable will be used
mathieui's avatar
mathieui committed
137

mathieui's avatar
mathieui committed
138
    server
mathieui's avatar
mathieui committed
139

mathieui's avatar
mathieui committed
140
        **Default value:** ``anon.jeproteste.info``
mathieui's avatar
mathieui committed
141

mathieui's avatar
mathieui committed
142 143
        The server to use for anonymous authentication;
        make sure it supports anonymous authentification.
mathieui's avatar
mathieui committed
144

mathieui's avatar
mathieui committed
145
        Note that this option doesn’t do anything at all if you’re using your own JID.
mathieui's avatar
mathieui committed
146

mathieui's avatar
mathieui committed
147
    alternative_nickname
mathieui's avatar
mathieui committed
148

mathieui's avatar
mathieui committed
149
        **Default value:** ``[empty]``
mathieui's avatar
mathieui committed
150

mathieui's avatar
mathieui committed
151 152 153 154 155 156
        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\_".
mathieui's avatar
mathieui committed
157 158


mathieui's avatar
mathieui committed
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
    keyfile

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

        Path to a PEM private key file to use for certificate authentication
        through SASL External. If set, :term:`certfile` **MUST** be set as well
        in order to login.

    certfile

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

        Path to a PEM certificate file to use for certificate authentication
        through SASL External. If set, :term:`keyfile` **MUST** be set as well
        in order to login.

mathieui's avatar
mathieui committed
175
    rooms
mathieui's avatar
mathieui committed
176

mathieui's avatar
mathieui committed
177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
        **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.

    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.

    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.

mathieui's avatar
mathieui committed
208 209 210 211 212 213 214
    open_all_bookmarks

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

        If this option is set to ``true``, all remote bookmarks, even
        those that do not have autojoin, will be opened on startup.
        (the tabs without autojoin will not be joined)
mathieui's avatar
mathieui committed
215 216 217 218 219 220 221 222 223 224 225 226 227 228



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.


.. glossary::
    :sorted:

    auto_reconnect
mathieui's avatar
mathieui committed
229

230
        **Default value:** ``true``
mathieui's avatar
mathieui committed
231

232 233
        Auto-reconnects you when you get disconnected from the
        server. Poezio will try to reconnect forever, until it succeeds.
mathieui's avatar
mathieui committed
234

mathieui's avatar
mathieui committed
235 236
    connection_check_interval

237
        **Default value:** ``300``
mathieui's avatar
mathieui committed
238 239 240 241 242 243 244 245 246 247

        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

248
        **Default value:** ``30``
mathieui's avatar
mathieui committed
249

250
        The timeout delay of the ping referenced above, 30 should really be fine, but
mathieui's avatar
mathieui committed
251 252 253 254 255 256 257 258 259 260 261 262
        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.

    autorejoin
mathieui's avatar
mathieui committed
263 264 265

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

mathieui's avatar
mathieui committed
266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286
        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.


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 :ref:`carbons <carbons-details>` or
:ref:`user activity/gaming/mood/tune <pep-details>`.

.. glossary::
    :sorted:
mathieui's avatar
mathieui committed
287

mathieui's avatar
mathieui committed
288 289
    enable_carbons

mathieui's avatar
mathieui committed
290
        **Default value:** ``true``
mathieui's avatar
mathieui committed
291

mathieui's avatar
mathieui committed
292 293 294 295
        Set this to ``false`` to disable Message Carbons (XEP-280), which allows
        transparent message delivery from and to other resources with carbons
        enabled. There should be no reason to disable this except if you encounter
        issues with your server.
mathieui's avatar
mathieui committed
296

mathieui's avatar
mathieui committed
297 298 299 300 301 302 303 304 305
    enable_smacks

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

        Stream Management (XEP-0198) is an extension designed to improve
        the reliability of XMPP in unreliable network conditions (such
        as mobile networks). It can however increase bandwidth usage.
        It also requires server support.

mathieui's avatar
mathieui committed
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
    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.

337 338 339 340 341 342 343 344
    go_to_previous_tab_on_alt_number

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

       If this is set to ``true``, when Alt+x is pressed, where x is a
       number, if you are already on the tab number x, you will jump to the
       previously selected tab. Otherwise you’ll stay on the same tab.

345 346 347 348 349 350 351 352
    group_corrections

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

        Enable a message to “correct” (replace) another message in the display if the
        sender intended it as such. See :ref:`Message Correction <correct-feature>` for
        more information.

mathieui's avatar
mathieui committed
353 354 355 356 357 358 359 360

    force_remote_bookmarks

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

        Try to retrieve your remote bookmarks, even when your server doesn’t advertise
        support.

mathieui's avatar
mathieui committed
361
    use_bookmark_method
mathieui's avatar
mathieui committed
362

mathieui's avatar
mathieui committed
363
        **Default value:** ``[empty]``
mathieui's avatar
mathieui committed
364

mathieui's avatar
mathieui committed
365 366 367
        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.
mathieui's avatar
mathieui committed
368

mathieui's avatar
mathieui committed
369
    use_pep_nick
mathieui's avatar
mathieui committed
370 371 372

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

mathieui's avatar
mathieui committed
373 374
        Use the nickname broadcasted by the user if set to ``true``, and if none
        has already been set manually.
mathieui's avatar
mathieui committed
375

mathieui's avatar
mathieui committed
376
    use_remote_bookmarks
mathieui's avatar
mathieui committed
377

mathieui's avatar
mathieui committed
378
        **Default value:** ``true``
mathieui's avatar
mathieui committed
379

mathieui's avatar
mathieui committed
380 381
        Use this option to force the use of local bookmarks if needed.
        Anything but "false" will be counted as true.
mathieui's avatar
mathieui committed
382

mathieui's avatar
mathieui committed
383
    display_gaming_notifications
mathieui's avatar
mathieui committed
384

mathieui's avatar
mathieui committed
385
        **Default value:** ``false``
mathieui's avatar
mathieui committed
386

mathieui's avatar
mathieui committed
387 388
        If set to true, notifications about the games your are playing
        will be displayed in the info buffer as 'Gaming' messages.
mathieui's avatar
mathieui committed
389

mathieui's avatar
mathieui committed
390
    display_tune_notifications
mathieui's avatar
mathieui committed
391

mathieui's avatar
mathieui committed
392
        **Default value:** ``false``
mathieui's avatar
mathieui committed
393

mathieui's avatar
mathieui committed
394 395
        If set to true, notifications about the music your contacts listen to
        will be displayed in the info buffer as 'Tune' messages.
mathieui's avatar
mathieui committed
396

mathieui's avatar
mathieui committed
397
    display_mood_notifications
mathieui's avatar
mathieui committed
398

mathieui's avatar
mathieui committed
399
        **Default value:** ``false``
mathieui's avatar
mathieui committed
400

mathieui's avatar
mathieui committed
401 402
        If set to true, notifications about the mood of your contacts
        will be displayed in the info buffer as 'Mood' messages.
mathieui's avatar
mathieui committed
403

mathieui's avatar
mathieui committed
404
    display_activity_notifications
mathieui's avatar
mathieui committed
405

mathieui's avatar
mathieui committed
406
        **Default value:** ``false``
mathieui's avatar
mathieui committed
407

mathieui's avatar
mathieui committed
408 409
        If set to true, notifications about the current activity of your contacts
        will be displayed in the info buffer as 'Activity' messages.
mathieui's avatar
mathieui committed
410

mathieui's avatar
mathieui committed
411
    enable_xhtml_im
mathieui's avatar
mathieui committed
412

mathieui's avatar
mathieui committed
413
        **Default value:** ``true``
mathieui's avatar
mathieui committed
414

mathieui's avatar
mathieui committed
415 416 417
        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.
mathieui's avatar
mathieui committed
418

419 420 421 422 423 424 425 426 427 428 429 430 431
    request_message_receipts

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

        Request message receipts when sending messages (except in groupchats).

    ack_message_receipts

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

        Acknowledge message receipts requested by the other party.


mathieui's avatar
mathieui committed
432
    send_chat_states
mathieui's avatar
mathieui committed
433

mathieui's avatar
mathieui committed
434
        **Default value:** ``true``
mathieui's avatar
mathieui committed
435

mathieui's avatar
mathieui committed
436 437 438
        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.
mathieui's avatar
mathieui committed
439

mathieui's avatar
mathieui committed
440 441 442
        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.
mathieui's avatar
mathieui committed
443 444


mathieui's avatar
mathieui committed
445
    send_os_info
mathieui's avatar
mathieui committed
446

mathieui's avatar
mathieui committed
447
        **Default value:** ``true``
mathieui's avatar
mathieui committed
448

mathieui's avatar
mathieui committed
449 450
        If ``true``, information about the Operation System you're using
        will be sent when requested by anyone
451
        Set to ``false`` if you don't want people to know these information.
mathieui's avatar
mathieui committed
452

mathieui's avatar
mathieui committed
453
        Note that this information will not be sent if :term:`send_poezio_info` is False
mathieui's avatar
mathieui committed
454

mathieui's avatar
mathieui committed
455
    send_poezio_info
mathieui's avatar
mathieui committed
456

mathieui's avatar
mathieui committed
457
        **Default value:** ``true``
mathieui's avatar
mathieui committed
458

mathieui's avatar
mathieui committed
459 460 461
        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
mathieui's avatar
mathieui committed
462

mathieui's avatar
mathieui committed
463
    send_time
mathieui's avatar
mathieui committed
464

mathieui's avatar
mathieui committed
465
        **Default value:** ``true``
mathieui's avatar
mathieui committed
466

mathieui's avatar
mathieui committed
467 468
        If ``true``, your current time will be sent if asked
        Set to ``false`` if you don't want people to know that information
mathieui's avatar
mathieui committed
469

mathieui's avatar
mathieui committed
470 471
Visual interface
~~~~~~~~~~~~~~~~
mathieui's avatar
mathieui committed
472

mathieui's avatar
mathieui committed
473 474 475
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.
mathieui's avatar
mathieui committed
476 477


mathieui's avatar
mathieui committed
478 479
.. glossary::
    :sorted:
mathieui's avatar
mathieui committed
480

mathieui's avatar
mathieui committed
481
    use_tab_nicks
mathieui's avatar
mathieui committed
482 483 484

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

485
        The tabs have a name, and a nick, which is, for a contact, its name in
mathieui's avatar
mathieui committed
486 487 488
        the contact list, or for a private conversation, the nickname in the
        chatroom. Set this to ``true`` if you want to have them shown instead
        of the jid of the contact.
mathieui's avatar
mathieui committed
489

mathieui's avatar
mathieui committed
490
    theme
mathieui's avatar
mathieui committed
491

mathieui's avatar
mathieui committed
492
        **Default value:** ``[empty]``
mathieui's avatar
mathieui committed
493

mathieui's avatar
mathieui committed
494 495
        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.
mathieui's avatar
mathieui committed
496

mathieui's avatar
mathieui committed
497 498 499 500
        If the file is not found (or no filename is specified) the default
        theme will be used instead

    themes_dir
mathieui's avatar
mathieui committed
501 502 503

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

mathieui's avatar
mathieui committed
504 505 506
        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.
mathieui's avatar
mathieui committed
507

mathieui's avatar
mathieui committed
508
        This directory will be created at startup if it doesn't exist
509

510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525
    show_composing_tabs

        **Default value:** ``direct``

        Highlight tabs where the last activity was a "composing" chat state,
        which means the contact is currently typing.

        Possible values are:

        - ``direct``: highlight only in one-to-one chats (equiv. of private & conversation)
        - ``private``: highlight only in private chats inside chatrooms
        - ``conversation``: highlight only in chats with contacts or direct JIDs
        - ``muc``: highlight only in chatrooms
        - ``true``: highlight all possible tabs (equiv. of muc & private & conversation)
        - ``false`` or any other value: don’t highlight anything

mathieui's avatar
mathieui committed
526
    user_list_sort
527

mathieui's avatar
mathieui committed
528
        **Default value:** ``desc``
529

530 531 532
        If set to ``desc``, the chatroom users will be displayed from top to
        bottom in the list, if set to ``asc``, they will be displayed from
        bottom to top.
mathieui's avatar
mathieui committed
533

534 535 536 537 538 539 540 541 542
    deterministic_nick_colors

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

        Use a deterministic algorithm to choose the user colors in chatrooms if
        set to ``true``. Otherwise the colors will be picked randomly.

        The value of this option affects the behavior of :term:`/recolor`.

543 544 545 546 547
    nick_color_aliases

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

	Automatically search for color of nick aliases. For example, if nick is
mathieui's avatar
mathieui committed
548
	set to red, _nick, nick\_, _nick_, nick\__ etc. will have the same color.
549
	Aliases colors are checked first, so that it is still possible to have
mathieui's avatar
mathieui committed
550
	different colors for nick\_ and nick.
551

mathieui's avatar
mathieui committed
552
    vertical_tab_list_size
mathieui's avatar
mathieui committed
553

mathieui's avatar
mathieui committed
554
        **Default value:** ``20``
mathieui's avatar
mathieui committed
555

556
        Horizontal size of the vertical tab list.
mathieui's avatar
mathieui committed
557

mathieui's avatar
mathieui committed
558
    vertical_tab_list_sort
mathieui's avatar
mathieui committed
559

mathieui's avatar
mathieui committed
560
        **Default value:** ``desc``
mathieui's avatar
mathieui committed
561

mathieui's avatar
mathieui committed
562 563
        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.
mathieui's avatar
mathieui committed
564

mathieui's avatar
mathieui committed
565
    filter_info_messages
mathieui's avatar
mathieui committed
566

mathieui's avatar
mathieui committed
567
        **Default value:** ``[empty]``
mathieui's avatar
mathieui committed
568

mathieui's avatar
mathieui committed
569 570 571
        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.
mathieui's avatar
mathieui committed
572

mathieui's avatar
mathieui committed
573
    hide_exit_join
mathieui's avatar
mathieui committed
574

mathieui's avatar
mathieui committed
575
        **Default value:** ``-1``
mathieui's avatar
mathieui committed
576

mathieui's avatar
mathieui committed
577 578
        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``.
mathieui's avatar
mathieui committed
579

mathieui's avatar
mathieui committed
580 581
        Default setting means:
        - all quit and join notices will be displayed
mathieui's avatar
mathieui committed
582

mathieui's avatar
mathieui committed
583
    hide_status_change
mathieui's avatar
mathieui committed
584

mathieui's avatar
mathieui committed
585
        **Default value:** ``120``
mathieui's avatar
mathieui committed
586

mathieui's avatar
mathieui committed
587 588 589
        Set a number for this setting.
        The join AND status-change notices will be
        displayed according to this number.
mathieui's avatar
mathieui committed
590

mathieui's avatar
mathieui committed
591
        ``-1``: the notices will ALWAYS be displayed
mathieui's avatar
mathieui committed
592

mathieui's avatar
mathieui committed
593
        ``0``: the notices will NEVER be displayed
mathieui's avatar
mathieui committed
594

mathieui's avatar
mathieui committed
595 596
        ``n``: On any other number, the notices will only be displayed
        if the user involved has talked since the last n seconds
mathieui's avatar
mathieui committed
597

mathieui's avatar
mathieui committed
598
        if the value is incorrect, ``-1`` is assumed
mathieui's avatar
mathieui committed
599

mathieui's avatar
mathieui committed
600 601
        Default setting means that status changes won't be displayed
        unless the user talked in the last 2 minutes
mathieui's avatar
mathieui committed
602

mathieui's avatar
mathieui committed
603
    hide_user_list
mathieui's avatar
mathieui committed
604

mathieui's avatar
mathieui committed
605
        **Default value:** ``false``
mathieui's avatar
mathieui committed
606

mathieui's avatar
mathieui committed
607 608 609
        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
mathieui's avatar
mathieui committed
610

mathieui's avatar
mathieui committed
611
    highlight_on
mathieui's avatar
mathieui committed
612 613 614

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

mathieui's avatar
mathieui committed
615 616
        a list of words (separated by a colon (:)) that will be
        highlighted if said by someone on a room
mathieui's avatar
mathieui committed
617

mathieui's avatar
mathieui committed
618
    information_buffer_popup_on
mathieui's avatar
mathieui committed
619

mathieui's avatar
mathieui committed
620
        **Default value:** ``error roster warning help info``
mathieui's avatar
mathieui committed
621

mathieui's avatar
mathieui committed
622 623 624 625
        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.
mathieui's avatar
mathieui committed
626

mathieui's avatar
mathieui committed
627 628
        A list of message types that should make the information buffer grow
        Possible values: ``error``, ``roster``, ``warning``, ``info``, ``help``
mathieui's avatar
mathieui committed
629

630 631 632 633 634 635 636
    information_popup_type_filter

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

        Some informational messages (error, a contact getting connected, etc)
        are sometimes added to the information buffer.

637
        A list of message types separated by colons (":") that should never be displayed in the information
638 639 640
        buffer.
        Possible values: ``error``, ``roster``, ``warning``, ``info``, ``help``

mathieui's avatar
mathieui committed
641
    display_user_color_in_join_part
mathieui's avatar
mathieui committed
642

643
        **Default value:** ``true``
mathieui's avatar
mathieui committed
644

645 646
        If set to true, the color of the nick will be used in chatroom
        information messages, instead of the default color from the theme.
mathieui's avatar
mathieui committed
647

mathieui's avatar
mathieui committed
648
    enable_vertical_tab_list
mathieui's avatar
mathieui committed
649

mathieui's avatar
mathieui committed
650
        **Default value:** ``false``
mathieui's avatar
mathieui committed
651

mathieui's avatar
mathieui committed
652 653
        If ``true``, a vertical list of tabs, with their name, is displayed on the left of
        the screen.
mathieui's avatar
mathieui committed
654

mathieui's avatar
mathieui committed
655
    max_nick_length
mathieui's avatar
mathieui committed
656

mathieui's avatar
mathieui committed
657
        **Default value:** ``25``
mathieui's avatar
mathieui committed
658

mathieui's avatar
mathieui committed
659 660 661
        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.
mathieui's avatar
mathieui committed
662 663 664 665 666

    roster_group_sort

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

mathieui's avatar
mathieui committed
667 668
        How to sort the contact list groups. The principles are the same
        as :term:`roster_sort` (see below).
mathieui's avatar
mathieui committed
669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687

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

mathieui's avatar
mathieui committed
688
        How you want the contacts to be sorted inside the contact list groups. The given
mathieui's avatar
mathieui committed
689 690 691 692 693 694 695 696
        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/…)
mathieui's avatar
mathieui committed
697
        * ``name``: sort by given name (if no name, then the bare jid is used)
mathieui's avatar
mathieui committed
698 699 700 701 702 703 704
        * ``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.

mathieui's avatar
mathieui committed
705
    show_inactive_tabs
mathieui's avatar
mathieui committed
706 707 708

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

mathieui's avatar
mathieui committed
709 710
        If you want to show all the tabs in the Tab bar, even those
        with no activity, set to ``true``. Else, set to ``false``.
mathieui's avatar
mathieui committed
711

mathieui's avatar
mathieui committed
712
    show_muc_jid
mathieui's avatar
mathieui committed
713 714 715

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

716 717 718 719
        Set this to ``false`` if you want to display only the “user” part of the
        chatroom jid. E.g. if you have **poezio@muc.poez.io**, it will be
        displayed as **poezio**. This will be used only if :term:`use_tab_nicks`
        is set to ``true``.
mathieui's avatar
mathieui committed
720 721 722 723 724

    show_roster_jids

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

mathieui's avatar
mathieui committed
725 726 727
        Set this to ``false`` if you want to hide the JIDs in the contact list
        (and keep only the contact names). If there is no contact name, the
        JID will still be displayed.
mathieui's avatar
mathieui committed
728

729 730 731 732 733 734 735
    show_jid_in_conversations

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

        If ``false``, the JID of the contact will not be displayed in the information
        window in conversation tags.

mathieui's avatar
mathieui committed
736 737 738 739
    show_s2s_errors

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

mathieui's avatar
mathieui committed
740
        Show s2s errors in the contact list or not.
mathieui's avatar
mathieui committed
741

742 743 744 745
    show_roster_subscriptions

        **Defalt value:** ``[empty]``

mathieui's avatar
mathieui committed
746
        Select the level of display of subscriptions with a char in the contact list.
747 748 749 750 751 752

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

mathieui's avatar
mathieui committed
753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772
    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.

mathieui's avatar
mathieui committed
773 774 775 776 777 778 779 780
    create_gaps

        **Default:** ``false``

        Create gaps when moving a tab or closing it. Enabling this option
        will help you keep the tabs at the same place during the execution of
        poezio. (gaps are not created when the closed tab is the last one)

mathieui's avatar
mathieui committed
781
    popup_time
mathieui's avatar
mathieui committed
782

mathieui's avatar
mathieui committed
783
        **Default value:** ``4``
mathieui's avatar
mathieui committed
784

mathieui's avatar
mathieui committed
785 786 787 788
        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.
mathieui's avatar
mathieui committed
789

790 791 792 793
    muc_colors (section)

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

794 795 796
        Fix a color for a nick. Whenever such a nick appears in a chatroom, it
        will be displayed in that color. This color won't be changed by the
        recolor command.
797

mathieui's avatar
mathieui committed
798 799
User Interaction
~~~~~~~~~~~~~~~~
mathieui's avatar
mathieui committed
800

mathieui's avatar
mathieui committed
801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822
Options that change the behavior of poezio in a non-visual manner.

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


    beep_on

823
        **Default value:** ``highlight private invite disconnect``
mathieui's avatar
mathieui committed
824 825 826 827 828

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

        The events can be
829 830 831 832
        - ``highlight`` (when you are highlighted in a chatroom)
        - ``private`` (when a new private message is received, from your
          contacts or someone from a chatroom)
        - ``message`` (any message from a chatroom)
mathieui's avatar
mathieui committed
833 834 835 836 837 838 839 840 841

    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
mathieui's avatar
mathieui committed
842 843 844

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

mathieui's avatar
mathieui committed
845 846 847 848
        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.
mathieui's avatar
mathieui committed
849

mathieui's avatar
mathieui committed
850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866
Logging
~~~~~~~

Options related to logging.

.. glossary::
    :sorted:

    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
mathieui's avatar
mathieui committed
867 868 869

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

mathieui's avatar
mathieui committed
870 871 872 873 874 875 876 877
        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.

    log_errors

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

878
        Logs all the tracebacks and erors of poezio/slixmpp in
mathieui's avatar
mathieui committed
879
        :term:`log_dir`/errors.log by default. ``false`` disables this option.
mathieui's avatar
mathieui committed
880 881 882

    use_log

883
        **Default value:** ``false``
mathieui's avatar
mathieui committed
884

885
        Set to ``true`` if you want to save logs of all the messages
mathieui's avatar
mathieui committed
886 887
        in files.

mathieui's avatar
mathieui committed
888 889
Plugins
~~~~~~~
mathieui's avatar
mathieui committed
890

mathieui's avatar
mathieui committed
891 892
This sections references the configuration of the plugin system; for
more details, go to the :ref:`dedicated page<plugins-doc>`.
mathieui's avatar
mathieui committed
893

mathieui's avatar
mathieui committed
894 895
.. glossary::
    :sorted:
mathieui's avatar
mathieui committed
896

mathieui's avatar
mathieui committed
897
    plugins_autoload
mathieui's avatar
mathieui committed
898

mathieui's avatar
mathieui committed
899
        **Default value:** ``[empty]``
mathieui's avatar
mathieui committed
900

mathieui's avatar
mathieui committed
901
        Colon-separated list of plugins to load on startup.
mathieui's avatar
mathieui committed
902

mathieui's avatar
mathieui committed
903
    plugins_conf_dir
mathieui's avatar
mathieui committed
904

mathieui's avatar
mathieui committed
905
        **Default value:** ``[empty]``
mathieui's avatar
mathieui committed
906

mathieui's avatar
mathieui committed
907 908 909 910
        If plugins_conf_dir is not set, plugin configs will be loaded from
        :file:`$XDG_CONFIG_HOME/poezio/plugins`.
        You can specify another directory to use, it will be created if it
        does not exist.
mathieui's avatar
mathieui committed
911

mathieui's avatar
mathieui committed
912
    plugins_dir
mathieui's avatar
mathieui committed
913 914 915

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

mathieui's avatar
mathieui committed
916 917
        If plugins_dir is not set, plugins will be loaded from the plugins/
        dir of the poezio install directory, then ``$XDG_DATA_HOME/poezio/plugins``.
mathieui's avatar
mathieui committed
918 919
        You can specify another directory to use. It will be created if it
        does not exist.
mathieui's avatar
mathieui committed
920 921 922



mathieui's avatar
mathieui committed
923 924
Other
~~~~~
mathieui's avatar
mathieui committed
925

mathieui's avatar
mathieui committed
926 927
.. glossary::
    :sorted:
mathieui's avatar
mathieui committed
928

mathieui's avatar
mathieui committed
929
    exec_remote
mathieui's avatar
mathieui committed
930

mathieui's avatar
mathieui committed
931
        **Default value:** ``false``
mathieui's avatar
mathieui committed
932

mathieui's avatar
mathieui committed
933 934 935
        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.
mathieui's avatar
mathieui committed
936 937


mathieui's avatar
mathieui committed
938
    lang
mathieui's avatar
mathieui committed
939

mathieui's avatar
mathieui committed
940
        **Default value:** ``en``
mathieui's avatar
mathieui committed
941

mathieui's avatar
mathieui committed
942
        The lang some automated entities will use when replying to you.
mathieui's avatar
mathieui committed
943

944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962
    extract_inline_images

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

        Some clients send inline images in base64 inside some messages, which results in
        an useless wall of text. If this option is ``true``, then that base64 text will
        be replaced with a :file:`file://` link to the image file extracted in
        :term:`tmp_image_dir` or :file:`$XDG_CACHE_HOME/poezio/images` by default, which
        is usually :file:`~/.cache/poezio/images`

    tmp_image_dir

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

        The directory where poezio will save the images received, if
        :term:`extract_inline_images` is set to true. If unset, poezio
        will default to :file:`$XDG_CACHE_HOME/poezio/images` which is
        usually :file:`~/.cache/poezio/images`.

mathieui's avatar
mathieui committed
963 964
    remote_fifo_path

965
        **Default value:** ``./``
mathieui's avatar
mathieui committed
966 967

        The path of the FIFO used to send the commands (see the :term:`exec_remote` option).
968 969
        Poezio will try to create a :file:`poezio.fifo` file in this directory.

mathieui's avatar
mathieui committed
970 971 972 973 974 975 976 977 978 979 980 981 982

    save_status

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

        Save the status automatically in the :term:`status` and :term:`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 :term:`/presence`) or sent by a
983
        chatroom.
mathieui's avatar
mathieui committed
984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007

    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
mathieui's avatar
mathieui committed
1008 1009 1010 1011 1012 1013





Optional section options
mathieui's avatar
mathieui committed
1014 1015
------------------------

mathieui's avatar
mathieui committed
1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055
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
mathieui's avatar
mathieui committed
1056 1057 1058
        banned.
       ``0``, a negative value, or no value means instant reconnection.

mathieui's avatar
mathieui committed
1059 1060 1061 1062 1063 1064
        This option only works if :term:`autorejoin` is ``true``.

    disable_beep

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

1065 1066
        Disable the beeps triggered by this conversation. Works in chatroom
        tabs, private messaging tabs, and conversation tabs.
mathieui's avatar
mathieui committed
1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092

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

1093 1094
        If set to ``true``, the color of the nick will be used in chatroom
        information messages, instead of the default color from the theme.
mathieui's avatar
mathieui committed
1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148

    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
mathieui's avatar
mathieui committed
1149 1150
        loaded from the log files.
        ``0`` or a negative value here disable that option.
mathieui's avatar
mathieui committed
1151 1152 1153 1154 1155 1156 1157 1158 1159

        No value makes poezio fall back to the global value.

    password

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

        The password needed to join the room.

mathieui's avatar
mathieui committed
1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177
    eval_password

        **Default value:** [empty]

        A command which execution will retrieve the password from a password manager.

        E.g. with secret-tool and the gnome keyring:

        .. code-block:: bash

            # Storing (to do beforehand)
            secret-tool store --label="My jabber password" xmpp your@jid

            # Retrieving (this should be the value of the option)
            secret-tool lookup xmpp  your@jid

        .. note:: This will only be used if the :term:`password` option is empty.

mathieui's avatar
mathieui committed
1178 1179 1180 1181 1182 1183 1184 1185 1186 1187
    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``

1188 1189
        Lets you disable/enable chatstates per-JID. Works in chatroom tabs,
        private messaging tabs, and normal conversation tabs.
mathieui's avatar
mathieui committed
1190 1191 1192

    show_useless_separator

1193
        **Default value:** ``true``
mathieui's avatar
mathieui committed
1194

1195 1196
        If ``false``, the separator at the bottom of a chat room will not be
        displayed if no one spoke.
mathieui's avatar
mathieui committed
1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208

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

1209 1210 1211 1212
        Only for chatroom 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 are
        not interested in a room non-highlight notifications.
mathieui's avatar
mathieui committed
1213

louiz’'s avatar
louiz’ committed
1214 1215 1216 1217 1218
    self_ping_delay

        **Default value:** ``0``

        When this option is set to a positive value ``n``, poezio will send
1219
        a ping request to its own nick in the chatroom every n seconds of
louiz’'s avatar
louiz’ committed
1220
        inactivity (whenever no new message or presence is received from the
1221
        chatroom for more than n seconds).  If the chatroom service does not
louiz’'s avatar
louiz’ committed
1222
        respond with a successful pong within 60 seconds (that is: on an
1223 1224 1225 1226 1227 1228
        error of the type “not-allowed” which means the chatroom service
        doesn’t consider us to be present in that room, or on a timeout which
        probably means that the service is down), poezio will mark that
        chatroom as not joined and will try to re-join it.  This is useful to
        know when a chatroom server crashes or becomes unavailable, because
        there is no mechanism to be informed of that fact in XMPP.
louiz’'s avatar
louiz’ committed
1229 1230 1231 1232 1233 1234

        A value of at least 60 seconds is recommended, to avoid sending too
        many requests.

        When set to 0 (the default value), no ping request will be sent.

1235 1236

.. _OpenSSL format: https://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT