summaryrefslogtreecommitdiff
path: root/doc/source/configuration.rst
blob: 24d82f712422bc847e0787133bb3bfd2c12d89a9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
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
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
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
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
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
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
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
1093
1094
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
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
.. _config:

Configuration
=============

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

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

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

An option is formatted like this:

``option = value``

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

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

Global section options
----------------------

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

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


Security
~~~~~~~~

Options pertaining to security, such as :ref:`TLS encryption <security settings>`
and certificate validation.

.. glossary::
    :sorted:

    ca_cert_path

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

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

    certificate

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

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

    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.

    force_encryption

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

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

    ignore_certificate

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

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



Account
~~~~~~~

Options related to account configuration, nickname…

.. 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)
        It should be in the form nickname@server.tld

    custom_host

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

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

    custom_port

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

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

    default_nick

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

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

    server

        **Default value:** ``anon.jeproteste.info``

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

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

    alternative_nickname

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

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


    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.

    resource

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

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

    rooms

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

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

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

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

    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.

    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)



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

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

        Auto-reconnects you when you get disconnected from the
        server. Poezio will try to reconnect forever, until it succeeds.

    connection_check_interval

        **Default value:** ``300``

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

    connection_timeout_delay

        **Default value:** ``30``

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

    whitespace_interval

        **Default value:** ``300``

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

    autorejoin

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

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

    autorejoin_delay

        **Default value:** ``5``

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


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:

    enable_carbons

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

        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.

    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.

    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.

    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.

    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.


    force_remote_bookmarks

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

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

    use_bookmark_method

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

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

    use_pep_nick

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

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

    use_remote_bookmarks

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

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

    display_gaming_notifications

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

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

    display_tune_notifications

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

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

    display_mood_notifications

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

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

    display_activity_notifications

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

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

    enable_xhtml_im

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

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

    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.


    send_chat_states

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

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

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


    send_os_info

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

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

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

    send_poezio_info

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

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

    send_time

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

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

Visual interface
~~~~~~~~~~~~~~~~

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


.. glossary::
    :sorted:

    use_tab_nicks

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

        The tabs have a name, and a nick, which is, for a contact, its name in
        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.

    theme

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

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

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

    themes_dir

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

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

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

    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

    user_list_sort

        **Default value:** ``desc``

        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.

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

    nick_color_aliases

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

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

    vertical_tab_list_size

        **Default value:** ``20``

        Horizontal size of the vertical tab list.

    vertical_tab_list_sort

        **Default value:** ``desc``

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

    filter_info_messages

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

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

    hide_exit_join

        **Default value:** ``-1``

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

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

    hide_status_change

        **Default value:** ``120``

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

        ``-1``: the notices will ALWAYS be displayed

        ``0``: the notices will NEVER be displayed

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

        if the value is incorrect, ``-1`` is assumed

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

    hide_user_list

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

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

    highlight_on

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

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

    information_buffer_popup_on

        **Default value:** ``error roster warning help info``

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

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

    display_user_color_in_join_part

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

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

    enable_vertical_tab_list

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

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

    max_nick_length

        **Default value:** ``25``

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

    roster_group_sort

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

        How to sort the contact list groups. The principles are the same
        as :term:`roster_sort` (see below).

        Available methods are:
          * ``reverse``: reverse the current sorting
          * ``name``: sort by group name (alphabetical order)
          * ``fold``: sort by unfolded/folded
          * ``connected``: sort by number of connected contacts
          * ``size``: sort by group size
          * ``none``: put the "none" group (if any) at the end of the list

    roster_show_offline

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

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

    roster_sort

        **Default value:** ``jid:show``

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

        Available methods are :

        * ``reverse``: reverse the current sorting
        * ``jid``: sort by JID (alphabetical order)
        * ``show``: sort by show (available/away/xa/…)
        * ``name``: sort by given name (if no name, then the bare jid is used)
        * ``resource``: sort by resource number
        * ``online``: sort by online presence (online or not)

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

    show_inactive_tabs

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

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

    show_muc_jid

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

        Set this to ``false`` if you want to display only the “user” part of the
        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``.

    show_roster_jids

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

        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.

    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.

    show_s2s_errors

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

        Show s2s errors in the contact list or not.

    show_roster_subscriptions

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

        Select the level of display of subscriptions with a char in the contact list.

        - ``all`` to display all subscriptions
        - ``incomplete`` to display *from*, *to* and *none*
        - one of ``from``, ``to``, ``none`` and ``both`` to display only that one
        - no value or any other value to disable it

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

    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)

    popup_time

        **Default value:** ``4``

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

    muc_colors (section)

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

        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.

User Interaction
~~~~~~~~~~~~~~~~

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

        **Default value:** ``highlight private``

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

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

    separate_history

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

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

    words

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

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

Logging
~~~~~~~

Options related to logging.

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

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

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

    log_errors

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

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

    use_log

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

        Set to ``true`` if you want to save logs of all the messages
        in files.

Plugins
~~~~~~~

This sections references the configuration of the plugin system; for
more details, go to the :ref:`dedicated page<plugins-doc>`.

.. glossary::
    :sorted:

    plugins_autoload

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

        Colon-separated list of plugins to load on startup.

    plugins_conf_dir

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

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

    plugins_dir

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

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



Other
~~~~~

.. glossary::
    :sorted:

    exec_remote

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

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


    lang

        **Default value:** ``en``

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

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

    remote_fifo_path

        **Default value:** ``./``

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


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

    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





Optional section options
------------------------

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

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

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

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

.. code-block:: ini

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

.. glossary::
    :sorted:

    autorejoin

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

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

    autorejoin_delay

        **Default value:** ``5``

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

        This option only works if :term:`autorejoin` is ``true``.

    disable_beep

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

        Disable the beeps triggered by this conversation. Works in chatroom
        tabs, private messaging tabs, and conversation tabs.

    display_activity_notifications

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

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

    display_gaming_notifications

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

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

    display_mood_notifications

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

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

    display_user_color_in_join_part

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

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

    display_tune_notifications

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

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

    hide_exit_join

        **Default value:** ``-1``

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

    hide_status_change

        **Default value:** ``120``

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

        ``-1``: the notices will ALWAYS be displayed

        ``0``: the notices will NEVER be displayed

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

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

    highlight_on

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

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

    ignore_private

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

        Ignore private messages sent from this room.

    load_log

        **Default value:** ``10``

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

        No value makes poezio fall back to the global value.

    password

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

        The password needed to join the room.

    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.

    private_auto_response

        **Default value:** ``Not in private, please.``

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

    send_chat_states

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

        Lets you disable/enable chatstates per-JID. Works in chatroom tabs,
        private messaging tabs, and normal conversation tabs.

    show_useless_separator

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

        If ``false``, the separator at the bottom of a chat room will not be
        displayed if no one spoke.

    use_log

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

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

    notify_messages

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

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

    self_ping_delay

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

        When this option is set to a positive value ``n``, poezio will send
        a ping request to its own nick in the chatroom every n seconds of
        inactivity (whenever no new message or presence is received from the
        chatroom for more than n seconds).  If the chatroom service does not
        respond with a successful pong within 60 seconds (that is: on an
        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.

        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.


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