configuration.rst 38.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
        The SHA-2 fingerprint of the SubjectPublicKeyInfo of the SSL
        certificate as a hexadecimal string, you should not touch it,
        except if know what you are doing.
68

69
70
71
72
73
74
        .. note:: the fingerprint was previously a fingerprint of the whole
                  certificate, while it is now only of the SubjectPublicKeyInfo,
                  which persists across LetsEncrypt renewals, and therefore
                  reduces the noise generated by the alert dialog.

     .. versionchanged:: 0.12
mathieui's avatar
mathieui committed
75

76
77
78
79
80
81
82
83
    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.

84
85
86
87
88
89
90
91
92
    default_muc_service

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

       If specified, will be used instead of the MUC service provided by
       the user domain.

       .. versionadded:: 0.13

mathieui's avatar
mathieui committed
93
    force_encryption
94

mathieui's avatar
mathieui committed
95
        **Default value:** ``true``
96

mathieui's avatar
mathieui committed
97
98
99
        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.
100

mathieui's avatar
mathieui committed
101
    ignore_certificate
102

mathieui's avatar
mathieui committed
103
        **Default value:** ``false``
104

mathieui's avatar
mathieui committed
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
        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)
127
        It should be in the form nickname@server.tld or nickname@server.tld/resource
128

mathieui's avatar
mathieui committed
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
    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
150
        If this is empty, the $USER environment variable will be used
mathieui's avatar
mathieui committed
151

mathieui's avatar
mathieui committed
152
    server
mathieui's avatar
mathieui committed
153

mathieui's avatar
mathieui committed
154
        **Default value:** ``anon.jeproteste.info``
mathieui's avatar
mathieui committed
155

mathieui's avatar
mathieui committed
156
        The server to use for anonymous authentication;
Link Mauve's avatar
Link Mauve committed
157
        make sure it supports anonymous authentication.
mathieui's avatar
mathieui committed
158

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

mathieui's avatar
mathieui committed
161
    alternative_nickname
mathieui's avatar
mathieui committed
162

mathieui's avatar
mathieui committed
163
        **Default value:** ``[empty]``
mathieui's avatar
mathieui committed
164

mathieui's avatar
mathieui committed
165
166
167
168
169
170
        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
171
172


mathieui's avatar
mathieui committed
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
    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
189
    rooms
mathieui's avatar
mathieui committed
190

mathieui's avatar
mathieui committed
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
        **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
222
223
224
225
226
227
228
    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
229
230
231
232
233
234
235
236
237
238
239
240
241
242



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
243

244
        **Default value:** ``true``
mathieui's avatar
mathieui committed
245

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

mathieui's avatar
mathieui committed
249
250
    connection_check_interval

251
        **Default value:** ``300``
mathieui's avatar
mathieui committed
252
253
254
255
256
257
258
259
260
261

        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

262
        **Default value:** ``30``
mathieui's avatar
mathieui committed
263

264
        The timeout delay of the ping referenced above, 30 should really be fine, but
mathieui's avatar
mathieui committed
265
266
267
268
269
270
271
272
273
274
275
276
        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
277
278
279

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

mathieui's avatar
mathieui committed
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
        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
301

mathieui's avatar
mathieui committed
302
303
304

    enable_avatars

305
        **Default value:** ``true``
mathieui's avatar
mathieui committed
306
307
308

        Display contact avatars in the roster.

mathieui's avatar
mathieui committed
309
310
    enable_carbons

mathieui's avatar
mathieui committed
311
        **Default value:** ``true``
mathieui's avatar
mathieui committed
312

mathieui's avatar
mathieui committed
313
314
315
316
        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
317

mathieui's avatar
mathieui committed
318
319
320
321
322
323
324
325
326
    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
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
    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.

358
359
360
361
362
363
364
365
    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.

366
367
368
369
370
371
372
373
    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
374
375
    bookmark_on_join

376
        **Default value:** ``false``
mathieui's avatar
mathieui committed
377
378
379

        If ``true``, poezio will bookmark automatically every room that is joined with
        a manual ``/join`` command.
mathieui's avatar
mathieui committed
380
381
382
383
384
385
386
387

    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
388
    use_bookmark_method
mathieui's avatar
mathieui committed
389

mathieui's avatar
mathieui committed
390
        **Default value:** ``[empty]``
mathieui's avatar
mathieui committed
391

mathieui's avatar
mathieui committed
392
393
394
        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
395

mathieui's avatar
mathieui committed
396
    use_pep_nick
mathieui's avatar
mathieui committed
397
398
399

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

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

mathieui's avatar
mathieui committed
403
    use_remote_bookmarks
mathieui's avatar
mathieui committed
404

mathieui's avatar
mathieui committed
405
        **Default value:** ``true``
mathieui's avatar
mathieui committed
406

mathieui's avatar
mathieui committed
407
408
        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
409

mathieui's avatar
mathieui committed
410
    display_gaming_notifications
mathieui's avatar
mathieui committed
411

mathieui's avatar
mathieui committed
412
        **Default value:** ``false``
mathieui's avatar
mathieui committed
413

mathieui's avatar
mathieui committed
414
415
        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
416

mathieui's avatar
mathieui committed
417
    display_tune_notifications
mathieui's avatar
mathieui committed
418

mathieui's avatar
mathieui committed
419
        **Default value:** ``false``
mathieui's avatar
mathieui committed
420

mathieui's avatar
mathieui committed
421
422
        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
423

mathieui's avatar
mathieui committed
424
    display_mood_notifications
mathieui's avatar
mathieui committed
425

mathieui's avatar
mathieui committed
426
        **Default value:** ``false``
mathieui's avatar
mathieui committed
427

mathieui's avatar
mathieui committed
428
429
        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
430

mathieui's avatar
mathieui committed
431
    display_activity_notifications
mathieui's avatar
mathieui committed
432

mathieui's avatar
mathieui committed
433
        **Default value:** ``false``
mathieui's avatar
mathieui committed
434

mathieui's avatar
mathieui committed
435
436
        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
437

mathieui's avatar
mathieui committed
438
    enable_xhtml_im
mathieui's avatar
mathieui committed
439

mathieui's avatar
mathieui committed
440
        **Default value:** ``true``
mathieui's avatar
mathieui committed
441

mathieui's avatar
mathieui committed
442
        XHTML-IM is an XMPP extension letting users send messages containing
Link Mauve's avatar
Link Mauve committed
443
        XHTML and CSS formatting. We can use this to make colored text for example.
mathieui's avatar
mathieui committed
444
        Set to ``true`` if you want to see colored (and otherwise formatted) messages.
mathieui's avatar
mathieui committed
445

mathieui's avatar
mathieui committed
446
447
448
449
450
451
452
453
    enable_css_parsing

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

        When parsing XHTML-IM content, only keep semantic elements, and not inline
        text styles.
        Only useful if :term:`enable_xhtml_im` is enabled.

454
455
456
457
458
459
460
461
462
463
464
465
466
    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
467
    send_chat_states
mathieui's avatar
mathieui committed
468

mathieui's avatar
mathieui committed
469
        **Default value:** ``true``
mathieui's avatar
mathieui committed
470

mathieui's avatar
mathieui committed
471
472
473
        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
474

mathieui's avatar
mathieui committed
475
476
477
        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
478
479


mathieui's avatar
mathieui committed
480
    send_os_info
mathieui's avatar
mathieui committed
481

mathieui's avatar
mathieui committed
482
        **Default value:** ``true``
mathieui's avatar
mathieui committed
483

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

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

mathieui's avatar
mathieui committed
490
    send_poezio_info
mathieui's avatar
mathieui committed
491

mathieui's avatar
mathieui committed
492
        **Default value:** ``true``
mathieui's avatar
mathieui committed
493

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

mathieui's avatar
mathieui committed
498
    send_time
mathieui's avatar
mathieui committed
499

mathieui's avatar
mathieui committed
500
        **Default value:** ``true``
mathieui's avatar
mathieui committed
501

mathieui's avatar
mathieui committed
502
503
        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
504

mathieui's avatar
mathieui committed
505
506
Visual interface
~~~~~~~~~~~~~~~~
mathieui's avatar
mathieui committed
507

mathieui's avatar
mathieui committed
508
509
510
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
511
512


mathieui's avatar
mathieui committed
513
514
.. glossary::
    :sorted:
mathieui's avatar
mathieui committed
515

mathieui's avatar
mathieui committed
516
    use_tab_nicks
mathieui's avatar
mathieui committed
517
518
519

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

520
        The tabs have a name, and a nick, which is, for a contact, its name in
mathieui's avatar
mathieui committed
521
522
523
        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
524

mathieui's avatar
mathieui committed
525
    theme
mathieui's avatar
mathieui committed
526

mathieui's avatar
mathieui committed
527
        **Default value:** ``[empty]``
mathieui's avatar
mathieui committed
528

mathieui's avatar
mathieui committed
529
530
        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
531

mathieui's avatar
mathieui committed
532
533
534
535
        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
536
537
538

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

mathieui's avatar
mathieui committed
539
540
541
        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
542

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

545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
    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
561
    user_list_sort
562

mathieui's avatar
mathieui committed
563
        **Default value:** ``desc``
564

565
566
567
        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
568

569
570
571
572
573
574
575
576
577
    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`.

578
579
580
581
582
    nick_color_aliases

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

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

mathieui's avatar
mathieui committed
587
    vertical_tab_list_size
mathieui's avatar
mathieui committed
588

mathieui's avatar
mathieui committed
589
        **Default value:** ``20``
mathieui's avatar
mathieui committed
590

591
        Horizontal size of the vertical tab list.
mathieui's avatar
mathieui committed
592

mathieui's avatar
mathieui committed
593
    vertical_tab_list_sort
mathieui's avatar
mathieui committed
594

mathieui's avatar
mathieui committed
595
        **Default value:** ``desc``
mathieui's avatar
mathieui committed
596

mathieui's avatar
mathieui committed
597
598
        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
599

mathieui's avatar
mathieui committed
600
    filter_info_messages
mathieui's avatar
mathieui committed
601

mathieui's avatar
mathieui committed
602
        **Default value:** ``[empty]``
mathieui's avatar
mathieui committed
603

mathieui's avatar
mathieui committed
604
        A list of words or sentences separated by colons (":"). All the
Link Mauve's avatar
Link Mauve committed
605
        informational messages (described above) containing at least one of those
mathieui's avatar
mathieui committed
606
        values will not be shown.
mathieui's avatar
mathieui committed
607

mathieui's avatar
mathieui committed
608
    hide_exit_join
mathieui's avatar
mathieui committed
609

mathieui's avatar
mathieui committed
610
        **Default value:** ``-1``
mathieui's avatar
mathieui committed
611

mathieui's avatar
mathieui committed
612
613
        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
614

mathieui's avatar
mathieui committed
615
616
        Default setting means:
        - all quit and join notices will be displayed
mathieui's avatar
mathieui committed
617

mathieui's avatar
mathieui committed
618
    hide_status_change
mathieui's avatar
mathieui committed
619

mathieui's avatar
mathieui committed
620
        **Default value:** ``120``
mathieui's avatar
mathieui committed
621

mathieui's avatar
mathieui committed
622
623
624
        Set a number for this setting.
        The join AND status-change notices will be
        displayed according to this number.
mathieui's avatar
mathieui committed
625

mathieui's avatar
mathieui committed
626
        ``-1``: the notices will ALWAYS be displayed
mathieui's avatar
mathieui committed
627

mathieui's avatar
mathieui committed
628
        ``0``: the notices will NEVER be displayed
mathieui's avatar
mathieui committed
629

mathieui's avatar
mathieui committed
630
631
        ``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
632

mathieui's avatar
mathieui committed
633
        if the value is incorrect, ``-1`` is assumed
mathieui's avatar
mathieui committed
634

mathieui's avatar
mathieui committed
635
636
        Default setting means that status changes won't be displayed
        unless the user talked in the last 2 minutes
mathieui's avatar
mathieui committed
637

mathieui's avatar
mathieui committed
638
    hide_user_list
mathieui's avatar
mathieui committed
639

mathieui's avatar
mathieui committed
640
        **Default value:** ``false``
mathieui's avatar
mathieui committed
641

mathieui's avatar
mathieui committed
642
643
644
        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
645

mathieui's avatar
mathieui committed
646
    highlight_on
mathieui's avatar
mathieui committed
647
648
649

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

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

mathieui's avatar
mathieui committed
653
    information_buffer_popup_on
mathieui's avatar
mathieui committed
654

mathieui's avatar
mathieui committed
655
        **Default value:** ``error roster warning help info``
mathieui's avatar
mathieui committed
656

mathieui's avatar
mathieui committed
657
658
        Some informational messages (error, a contact getting connected, etc)
        are sometimes added to the information buffer. These settings can make
659
        that buffer grow temporarily so you can read these information when they
mathieui's avatar
mathieui committed
660
        appear.
mathieui's avatar
mathieui committed
661

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

665
    information_buffer_type_filter
666
667
668
669
670
671

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

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

672
        A list of message types separated by colons (":") that should never be displayed in the information
673
674
675
        buffer.
        Possible values: ``error``, ``roster``, ``warning``, ``info``, ``help``

mathieui's avatar
mathieui committed
676
    display_user_color_in_join_part
mathieui's avatar
mathieui committed
677

678
        **Default value:** ``true``
mathieui's avatar
mathieui committed
679

680
681
        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
682

mathieui's avatar
mathieui committed
683
    enable_vertical_tab_list
mathieui's avatar
mathieui committed
684

685
        **Default value:** ``true``
mathieui's avatar
mathieui committed
686

687
688
689
        If ``true``, a vertical list of tabs, with their name, is displayed on
        the left of the screen.  Otherwise, it is a horizontal bar with just
        the tab numbers above the input bar.
mathieui's avatar
mathieui committed
690

mathieui's avatar
mathieui committed
691
    max_nick_length
mathieui's avatar
mathieui committed
692

mathieui's avatar
mathieui committed
693
        **Default value:** ``25``
mathieui's avatar
mathieui committed
694

mathieui's avatar
mathieui committed
695
696
697
        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
698
699
700
701
702

    roster_group_sort

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

mathieui's avatar
mathieui committed
703
704
        How to sort the contact list groups. The principles are the same
        as :term:`roster_sort` (see below).
mathieui's avatar
mathieui committed
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723

        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
724
        How you want the contacts to be sorted inside the contact list groups. The given
mathieui's avatar
mathieui committed
725
726
727
728
729
730
731
732
        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
733
        * ``name``: sort by given name (if no name, then the bare jid is used)
mathieui's avatar
mathieui committed
734
735
736
737
738
739
740
        * ``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
741
    show_inactive_tabs
mathieui's avatar
mathieui committed
742
743
744

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

mathieui's avatar
mathieui committed
745
746
        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
747

mathieui's avatar
mathieui committed
748
    show_muc_jid
mathieui's avatar
mathieui committed
749

mathieui's avatar
mathieui committed
750
        **Default value:** ``false``
mathieui's avatar
mathieui committed
751

mathieui's avatar
mathieui committed
752
753
754
755
756
        If set to ``false``, poezio will first display the bookmark name, or if
        empty the user part of the address (before the ``@``) when displaying the
        chatroom tab name. So ``poezio@muc.poez.io`` will get shortened to
        ``poezio`` unless this option is set to ``true``.
        This will be used only if :term:`use_tab_nicks` is set to ``true``.
mathieui's avatar
mathieui committed
757
758
759
760
761

    show_roster_jids

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

mathieui's avatar
mathieui committed
762
763
764
        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
765

766
767
768
769
770
771
772
    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
773
774
775
776
    show_s2s_errors

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

mathieui's avatar
mathieui committed
777
        Show s2s errors in the contact list or not.
mathieui's avatar
mathieui committed
778

779
780
    show_roster_subscriptions

Link Mauve's avatar
Link Mauve committed
781
        **Default value:** ``[empty]``
782

mathieui's avatar
mathieui committed
783
        Select the level of display of subscriptions with a char in the contact list.
784
785
786
787
788
789

        - ``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
790
791
792
793
794
795
    show_tab_names

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

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

796
797
798
799
800
801
802
803
804
805
806
    unique_prefix_tab_names

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

        If this and :term:`show_tab_names` is set to true, only the shortest
        unique prefix of each tab name is shown instead of the full name. This
        can declutter the interface in an instance with many tabs shown in the
        interface, while not having to use numbers (which may change completely due to reordering).

        Takes precedence over `use_tab_nicks`.

mathieui's avatar
mathieui committed
807
808
809
810
811
812
813
814
815
816
817
818
819
820
    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
821
822
823
824
825
826
827
828
    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
829
    popup_time
mathieui's avatar
mathieui committed
830

mathieui's avatar
mathieui committed
831
        **Default value:** ``4``
mathieui's avatar
mathieui committed
832

mathieui's avatar
mathieui committed
833
834
835
836
        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
837

838
839
840
841
    muc_colors (section)

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

842
843
844
        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.
845

mathieui's avatar
mathieui committed
846
847
User Interaction
~~~~~~~~~~~~~~~~
mathieui's avatar
mathieui committed
848

mathieui's avatar
mathieui committed
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
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

871
        **Default value:** ``highlight private invite disconnect``
mathieui's avatar
mathieui committed
872
873
874
875
876

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

        The events can be
mathieui's avatar
mathieui committed
877

878
        - ``highlight`` (when you are highlighted in a chatroom)
mathieui's avatar
mathieui committed
879
        - ``private`` (when a new private message is received, from your contacts or someone from a chatroom)
880
        - ``message`` (any message from a chatroom)
mathieui's avatar
mathieui committed
881
882
883
884
885
886
887
888
889

    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
890
891
892

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

mathieui's avatar
mathieui committed
893
894
895
896
        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
897

mathieui's avatar
mathieui committed
898
899
900
901
902
903
904
905
906
Logging
~~~~~~~

Options related to logging.

.. glossary::
    :sorted:

    log_dir
mathieui's avatar
mathieui committed
907
908
909

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

mathieui's avatar
mathieui committed
910
911
912
913
914
915
916
917
        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``

Link Mauve's avatar
Link Mauve committed
918
        Logs all the tracebacks and errors of poezio/slixmpp in
mathieui's avatar
mathieui committed
919
        :term:`log_dir`/errors.log by default. ``false`` disables this option.
mathieui's avatar
mathieui committed
920
921
922

    use_log

923
        **Default value:** ``true``
mathieui's avatar
mathieui committed
924

925
        Set to ``false`` if you don’t want to write any message to the disk.
mathieui's avatar
mathieui committed
926

mathieui's avatar
mathieui committed
927
928
Plugins
~~~~~~~
mathieui's avatar
mathieui committed
929

mathieui's avatar
mathieui committed
930
931
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
932

mathieui's avatar
mathieui committed
933
934
.. glossary::
    :sorted:
mathieui's avatar
mathieui committed
935

mathieui's avatar
mathieui committed
936
    plugins_autoload
mathieui's avatar
mathieui committed
937

mathieui's avatar
mathieui committed
938
        **Default value:** ``[empty]``
mathieui's avatar
mathieui committed
939

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

mathieui's avatar
mathieui committed
942
    plugins_conf_dir
mathieui's avatar
mathieui committed
943

mathieui's avatar
mathieui committed
944
        **Default value:** ``[empty]``
mathieui's avatar
mathieui committed
945

mathieui's avatar
mathieui committed
946
947
948
949
        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
950

mathieui's avatar
mathieui committed
951
    plugins_dir
mathieui's avatar
mathieui committed
952
953
954

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

mathieui's avatar
mathieui committed
955
956
        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
957
958
        You can specify another directory to use. It will be created if it
        does not exist.
mathieui's avatar
mathieui committed
959
960
961



mathieui's avatar
mathieui committed
962
963
Other
~~~~~
mathieui's avatar
mathieui committed
964

mathieui's avatar
mathieui committed
965
966
.. glossary::
    :sorted:
mathieui's avatar
mathieui committed
967

mathieui's avatar
mathieui committed
968
    exec_remote
mathieui's avatar
mathieui committed
969

mathieui's avatar
mathieui committed
970
        **Default value:** ``false``
mathieui's avatar
mathieui committed
971

mathieui's avatar
mathieui committed
972
973
974
        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
975
976


mathieui's avatar
mathieui committed
977
    lang
mathieui's avatar
mathieui committed
978

mathieui's avatar
mathieui committed
979
        **Default value:** ``en``
mathieui's avatar
mathieui committed
980

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

983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
    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`.
For faster browsing, not all history is shown. View entire blame