summaryrefslogtreecommitdiffstats
path: root/doc/tdm/index.docbook
blob: 089bc3dc068164bfc3a4cacd89b2308adf081f80 (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
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
"dtd/kdex.dtd" [
  <!ENTITY kappname "&tdm;">
  <!ENTITY package "tdebase">
  <!ENTITY tdmrc "<filename>tdmrc</filename>">
  <!ENTITY ksmserver "<application>ksmserver</application>">
  <!ENTITY kdesktop "<application>kdesktop</application>">
  <!ENTITY XDMCP "<acronym>XDMCP</acronym>">
  <!ENTITY xdm "<application>xdm</application>">
  <!ENTITY tdmrc-ref SYSTEM "tdmrc-ref.docbook">
  <!ENTITY % addindex "INCLUDE">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<book lang="&language;">
<bookinfo>
<title>The &tdm; Handbook</title>

<authorgroup>
<author>&tde-authors;</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
<!--
<othercredit role="developer">
&Oswald.Buddenhagen; &Oswald.Buddenhagen.mail;
<contrib>Developer</contrib>
</othercredit>
<othercredit role="reviewer">
&Lauri.Watts; &Lauri.Watts.mail;
<contrib>Reviewer</contrib>
</othercredit> -->

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<copyright>
<year>2000</year>
<holder>&Neal.Crook;</holder>
</copyright>

<copyright>
<year>2002</year>
<holder>&Oswald.Buddenhagen;</holder>
</copyright>

<copyright>
<year>2003</year>
<holder>&Lauri.Watts;</holder>
</copyright>

<copyright>
<year>&tde-copyright-date;</year>
<holder>The TDE Documentation Team</holder>
</copyright>

<date>&tde-release-date;</date>
<releaseinfo>&tde-release-version;</releaseinfo>

<abstract>
<para>This document describes &tdm;, the &tde; Display Manager. &tdm;
is also known as the <quote>Login Manager</quote>.</para>
</abstract>

<keywordset>
<keyword>TDE</keyword>
<keyword>tdm</keyword>
<keyword>xdm</keyword>
<keyword>display manager</keyword>
<keyword>login manager</keyword>
</keywordset>
</bookinfo>

<!-- ********************************************************************** -->  
<chapter id="introduction">
<title>Introduction</title>

<para>&tdm; provides a graphical interface that allows you to log in to a
system. It prompts for login (username) and password, authenticates the user
and starts a <quote>session</quote>. &tdm; is superior to &xdm;, the X
Display Manager, in a number of ways.</para>

</chapter>

<!-- Chapters to write -->
<!-- * Just enough config to get it to run and login to TDE 
     * Adding more session types (GNOME, etc)
     * Adding other customizations to XSession (ssh/gpg-agent, etc)
     * Further customization to TDM (via the kcontrol module, and by 
       hand)
     * XDMCP by query
     * XDMCP by broadcast
     * Sound transparency (if Ade can tell me how!)
     * Document all Keys in the Config File
     * Pull in all options from the KControl Module
     * More resources
-->

<chapter id="quickstart">
<title>Quick Start Guide</title>

<para>This is a quick start guide for users who fit the following
pattern:</para>

<itemizedlist>
<listitem>
<para>X is configured and works with the command
<command>startx</command> from the commandline.</para>
</listitem>
<listitem>
<para>Each user will generally only use a single window manager or
desktop environment, and does not change this choice very
often, or is comfortable editing a single text file in order to change
their choice.</para>
</listitem>
</itemizedlist>

<para>This scenario will be sufficient for many environments where a single
user or several users normally boot the computer and log into their
preferred environment.</para>

<procedure>
<title>Setting up a Default Session</title>
<step>
<para>Create or open the file <filename>~/.xinitrc</filename></para>
<para>If you already have a working <filename>~/.xinitrc</filename>, go to
the next step</para>
</step>
<step>
<para>If one does not already exist, add a line to the
<filename>~/.xinitrc</filename> to start your preferred window manager
or desktop environment.</para>
<para>For &tde; you should enter:</para>
<screen><userinput>starttde</userinput></screen>
<para>For other window managers or desktop environments, you should
look in their documentation for the correct command.</para>
</step>
<step><para>Make a link as follows:</para>
<screen><userinput><command>ln</command> <option>-s</option> <parameter>~/.xinitrc ~/.xsession</parameter></userinput></screen>
</step>
</procedure>

<para>At this point, typing <userinput><command>startx</command></userinput>
on the commandline should start X, with a &tde; session. The next task is
to try &tdm;.</para>

<para>As <systemitem class="username">root</systemitem>, type
<userinput><command>tdm</command></userinput> at the prompt.</para>

<para>You should see a login window, which is described more fully in <xref
linkend="login" />.</para>

<para>Typing your normal username and password in the fields provided, and
leaving <option>default</option> selected as the session type should now
open a &tde; session for your user.</para>

<para>If you have other users to configure, you should repeat the procedure
above for each of them.</para>

<note>
<para>This is a quick guide to getting up and running only. You probably
will want to customize &tdm; further, for example, to hide the names of the
system accounts, to allow further sessions, and much more. Please read
through the rest of this manual to find out how to do these things.</para>
</note>

</chapter>

<chapter id="login"> 
<title>The Login Window</title> 

<para>The &tdm; interface consists of two dialog boxes: a login dialog
and a shutdown dialog.</para>

<note><para>The &tdm; interface might be protected by the Trinity Secure Access
Key (SAK) mechanism. When the SAK is enabled, users are prompted to press
<keycombo action="simul">&Ctrl; &Alt;<keycap>Delete</keycap></keycombo>
to obtain access to the &tdm; interface.</para></note>

<para>The main login dialog box has these controls:</para>

<itemizedlist> 
<listitem>
<para>A <guilabel>Username:</guilabel> field for you to enter your
username.</para>
</listitem>

<listitem>
<para>A <guilabel>Password:</guilabel> field for you to enter your
password.</para>
</listitem>

<listitem>
<para>(Optionally) a graphical image of each user (for example, a digitized
photograph). Clicking on an image is equivalent to typing the associated
username into the <guilabel>Username:</guilabel> field. (This feature is an
imitation of the login box on &IRIX;).</para> 
</listitem>

<listitem>
<para>A <guilabel>Menu</guilabel> drop down box that allows &tdm; to be used
to start sessions with various different window managers or desktop
environments installed on the system.</para>
</listitem>

<listitem>
<para>(Optionally) a region to the right of the
<guilabel>Username:</guilabel>, <guilabel>Password:</guilabel> and
<guilabel>Session Type:</guilabel> fields which can be used to display
either a static image or an analog clock.</para>
</listitem>

<listitem>
<para>A <guibutton>Login</guibutton> button that validates the
username/password combination and attempts to start a session of the
selected type.</para>
</listitem>

<listitem>
<para>A <guibutton>Clear</guibutton> button that clears the text from
the <guilabel>Login</guilabel> and <guilabel>Pass</guilabel>
fields.</para>
</listitem> 

<listitem>
<para>A <guibutton>Menu</guibutton> button that opens an action menu
with the following items:</para>
 
<itemizedlist>
<listitem>
<para>(On local displays) A <guimenuitem>Restart X Server</guimenuitem> item
that terminates the currently running &X-Server;, starts a new one and
displays the login dialog again. You can use this if the display content
seems to be broken somehow.</para>
</listitem>

<listitem>
<para>(On remote displays) A <guimenuitem>Close Connection</guimenuitem>
item that closes the connection to the &XDMCP; server you are currently
connected to. If you got to this server through a host chooser, this will
bring you back to the chooser, otherwise it will only reset the &X-Server;
and bring up the login dialog again.</para>
</listitem>

<listitem>
<para>(Optionally on local displays) A <guimenuitem>Console
Mode</guimenuitem> item that terminates the currently running &X-Server; and
leaves you alone with a console login. &tdm; will resume the graphical login
if nobody is logged in at the console for some time.</para>
</listitem>
</itemizedlist>
</listitem>

<listitem>
<para>(Optionally) A <guibutton>Shutdown</guibutton> button that displays
the <guilabel>Shutdown</guilabel> dialog box.</para>
</listitem>
</itemizedlist>

<para>The <guilabel>Shutdown</guilabel> dialog box presents a set of
radio buttons that allow one of these options to be selected:</para>

<variablelist>
<varlistentry>
<term>Shutdown</term> 
<listitem>
<para>Shut the system down in a controlled manner, ready for
power-down.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Restart</term>
<listitem>
<para>Shut the system down and reboot. For systems that use
<application>Lilo</application>, an optional drop down box allows you to
select a particular operating-system kernel to be used for the
reboot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Restart X Server</term> 
<listitem>
<para>Stop and then restart the X-server. Typically, you might need to use
this option if you have changed your X11 configuration in some way.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Console Mode</term>
<listitem>
<para>Stop the &X-Server; and return the system to console mode. This is
achieved by bringing the system down to runlevel 3. Typically, the system
manager might need to use this option before upgrading or re-configuring X11
software.</para> 
</listitem>
</varlistentry>
</variablelist>

<para>Pressing the <guibutton>OK</guibutton> button initiates the selected
action; pressing the <guibutton>Cancel</guibutton> button returns to the
main &tdm; dialog box.</para>

</chapter>

<!-- *********************************************************************** -->
<chapter id="configuring-tdm">
<title>Configuring &tdm;</title>

<para>This chapter assumes that &tdm; is already up and running on your
system, and that you simply want to change its behavior in some way.</para>

<para>Upon starting, &tdm; reads its configuration from the folder
<filename class="directory">$TDEDIR/share/config/tdm/</filename> (this may
be <filename class="directory">/etc/trinity/tdm/</filename> or something else
on your system).</para>

<para>The main configuration file is &tdmrc;; all other files are
referenced from there and could be stored under any name anywhere on
the system. Usually that would not make much sense for obvious
reasons (one particular exception is referencing configuration files
of an already installed &xdm;. However, when a new &tdm; is installed,
it will import settings from those files if it finds an already installed
&xdm;).</para>

<para>Since &tdm; must run before any user is logged in, it is not
associated with any particular user. Therefore, it is not possible to have
user-specific configuration files; all users share the common &tdmrc;. It
follows from this that the configuration of &tdm; can only be altered by
those users who have write access to
<filename>$<envar>TDEDIR</envar>/share/config/tdm/tdmrc</filename> (normally
restricted to system administrators logged in as <systemitem
class="username">root</systemitem>).</para>

<para>You can view the &tdmrc; file currently in use on your system, and you
can configure &tdm; by editing that file. Alternately, you can use the
graphical configuration tool provided by the &kcontrolcenter; (under
<menuchoice><guisubmenu>System Administration</guisubmenu><guimenuitem>Login
Manager</guimenuitem></menuchoice>), which is described in the next section.
</para>

<para>The remainder of this chapter describes configuring &tdm;
using the &kcontrolcenter; module, and the <link linkend="tdm-files">next
chapter</link> describes the options available in &tdmrc; itself. If
you only need to configure for local users, the &kcontrolcenter; module
should be sufficient for your needs. If you need to configure remote
logins, or have multiple &tdm; sessions running, you will need to continue reading.</para>

<sect1 id="tdm-kcontrol-module">
<sect1info>
<authorgroup>
<author>&Thomas.Tanghus; &Thomas.Tanghus.mail;</author>
<author>&Steffen.Hansen; &Steffen.Hansen.mail;</author>
<author>&Mike.McBride; &Mike.McBride.mail;</author>
</authorgroup>
</sect1info>

<title>The Login Manager &kcontrolcenter; Module</title>

<para>Using this module, you can configure the &tde; graphical login
manager, &tdm;. You can change how the login screen looks, who has
access using the login manager and who can shutdown the
computer.</para>

<note><para>All settings will be written to the configuration file
&tdmrc;, which in its original state has many comments to help you
configure &tdm;. Using this &kcontrolcenter; module will strip these
comments from the file. Consider making a backup of &tdmrc; before
making changes. All available options in &tdmrc; are covered
in <xref linkend="tdm-files"/>.</para>

<para>The options listed in this chapter are cross referenced with
their equivalents in &tdmrc;. All options available in the &kcontrol;
module are also available directly in &tdmrc; but the reverse is not
true.</para></note>

<para>In order to organize all of these options, this module is
divided into several sections: <link
linkend="tdmconfig-appearance"><guilabel>Appearance</guilabel></link>,
<link linkend="tdmconfig-font"><guilabel>Font</guilabel></link>, <link
linkend="tdmconfig-background"><guilabel>Background</guilabel></link>,
<link
linkend="tdmconfig-shutdown"><guilabel>Shutdown</guilabel></link>,
<link linkend="tdmconfig-users"><guilabel>Users</guilabel></link> and
<link
linkend="tdmconfig-convenience"><guilabel>Convenience</guilabel></link>.</para>

<para>You can switch between the sections using the tabs at the top of
the window.</para>

<note><para>If you are not currently logged in as a superuser, you
will need to select the <guibutton>Administrator Mode...</guibutton>
Button. You will then be asked for a superuser password. Entering a
correct password will allow you to modify the settings of this
module.</para></note>

<sect2 id="tdmconfig-appearance">
<title>Appearance</title>

<para>From this page you can change the visual appearance of &tdm;,
&tde;'s graphical login manager.</para>

<para>The <guilabel>Greeting:</guilabel> is the title of the login
 screen. Setting this is especially useful if you have many servers users
 may log in to. You may use various placeholders, which are described
 along with the corresponding key
 <link linkend="option-greetstring"><option>GreetString</option></link>
 in &tdmrc;.
</para>

<para>You can then choose to show either the current system time, a logo or
nothing special in the login box. Make your choice in the radio buttons
labeled <guilabel>Logo area:</guilabel>. This corresponds to <link
linkend="option-logoarea"><option>LogoArea</option></link> in &tdmrc;</para>

<para>If you chose <guilabel>Show logo</guilabel> you can now choose a
logo:</para>

<itemizedlist>
<listitem>
<para>Drop an image file on the image button.</para>
</listitem>
<listitem>
<para>Click on the image button and select a new image from the image chooser
dialog.</para>
</listitem>
</itemizedlist>

<para>If you do not specify a logo the default
<filename>$<envar>TDEDIR</envar>/share/apps/tdm/pics/tdelogo.png</filename>
will be displayed.</para>

<para>Normally the login box is centered on the screen. Use the
<guilabel>Position:</guilabel> options if you want it to appear
elsewhere on the screen. You can specify the relative position
(percentage of the screen size) for the center of the login window,
relative to the top left of the display, in the fields labeled
<guilabel>X:</guilabel> and <guilabel>Y:</guilabel> respectively.
These correspond to the key
<link linkend="option-greeterpos"><option>GreeterPos</option></link>
in &tdmrc;.</para>

<para>While &tde;'s style depends on the settings of the user logged
in, the style used by &tdm; can be configured using the <guilabel>GUI
Style:</guilabel> and <guilabel>Color Scheme:</guilabel> options.
These correspond to the keys <link
linkend="option-guistyle"><option>GUIStyle</option></link> and <link
linkend="option-colorscheme"><option>ColorScheme</option></link> in
&tdmrc; respectively.</para>

<para>Below that, you have a drop down box to choose the language for
your login box, corresponding to setting <option>Language</option> in
&tdmrc;.</para>

<para>In this same section &tdm; can be configured to use a <guilabel>Secure
Attention Key</guilabel> (SAK). A Secure Attention Key is a special key press
to which only certain privileged applications are able to respond, such as the
login and screen unlock dialogs. This mechanism prevents a malevolent user
from creating an exact copy of the login screen to "sniff" or "phish" passwords
or other sensitive information. The unprivileged copy is unable to detect the
SAK key press, thereby providing a visible difference in operation to the
user.</para>

<para>When the Trinity SAK is enabled, users are prompted to press
<keycombo action="simul">&Ctrl; &Alt;<keycap>Delete</keycap></keycombo>
before sensitive information is requested.

<screenshot>
<screeninfo>The Trinity Secure Attention Key dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="tsak.png" format="PNG"/>
</imageobject>
<textobject><phrase>The Trinity Secure Attention Key dialog</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para>When SAK is enabled, and the
<keycombo action="simul">&Ctrl; &Alt;<keycap>Delete</keycap></keycombo>
dialog does not appear before sensitive information is requested, someone might
be attempting to "phish" for that information. A prudent course of action would
be to terminate the active X11 session via <keycombo action="simul">&Ctrl; &Alt;
<keycap>Backspace</keycap></keycombo> or any other distribution-specific key press
for this action, thereby restoring control to the kernel and base system.</para>

<para>Generally, using the Trinity SAK is a good idea when supporting many
graphical login accounts on a machine. For example, in enterprise environments
or computer laboratories. When only one graphical login account is used, or
only a few accounts in a controlled environment, such as with a home computer,
Trinity SAK will not provide tangible benefits over the standard login
methods.</para>

<note><para>Trinity SAK requires evdev to be running and the Linux uinput kernel
module to be loaded.</para></note>

</sect2>

<sect2 id="tdmconfig-font">
<title>Font</title>

<para>From this section of the module you can change the fonts used in the
login window. Only fonts available to all users are available here, not
fonts you have installed on a per user basis.</para>

<para>You can select three different font styles from the drop down box
(<guilabel>General:</guilabel>, <guilabel>Failures:</guilabel>,
<guilabel>Greeting:</guilabel>). When you click on the
<guibutton>Choose...</guibutton> button a dialog appears from which you can
select the new characteristics for the font style.</para>

<itemizedlist>
<listitem>
<para>The <guilabel>General:</guilabel> font is used in all other places in the
login window.</para>
</listitem>
<listitem>
<para>The <guilabel>Failures:</guilabel> font is used when a login
fails.</para>
</listitem>
<listitem>
<para>The <guilabel>Greeting:</guilabel> font is the font used for the title
(Greeting String).</para>
</listitem>
</itemizedlist>

<para>You can also check the box labeled <guilabel>Use anti-aliasing for
fonts</guilabel> if you want smoothed fonts in the login dialog.</para>

</sect2>

<sect2 id="tdmconfig-background">
<title>Background</title>

<para>Here you can change the desktop background which will be displayed
before a user logs in. You can have a single color or an image as a
background. If you have an image as the background and select center, the
selected background color will be used around the image if it is not
large enough to cover the entire desktop.</para>

<para>The background colors and effects are controlled by the options on
the tab labeled <guilabel>Background</guilabel> and you select a
background image and its placement from the options on the tab labeled
<guilabel>Wallpaper</guilabel>.</para>

<para>To change the default background color(s) simply click either of
the color buttons and select a new color.</para>

<para>The drop down box above the color buttons provides you with several
different blend effects. Choose one from the list, and it will be
previewed on the small monitor at the top of the window. Your choices
are:</para>

<variablelist>
<varlistentry>
<term>Flat</term>
<listitem><para>By choosing this mode, you select one color (using the color
button labeled <guibutton>Color 1</guibutton>), and the entire background is
covered with this one color.</para></listitem>
</varlistentry>
<varlistentry>
<term>Pattern</term>
<listitem><para>By choosing this mode, you select two colors (using both color
buttons).</para> <para>You then select a pattern by clicking
<guilabel>Setup</guilabel>. This opens a new dialog window, which gives you
the opportunity to select a pattern. Simply click once on the pattern of your
choice, then click on <guilabel>OK</guilabel>, and &tde; will render the pattern
you selected using the two colors you selected. For more on patterns, see the
section <ulink url="help:/kcontrol/background/index.html#bkgnd-patterns">Background: Adding, Removing and Modifying
Patterns</ulink>.</para></listitem>
</varlistentry>
<varlistentry>
<term>Background Program</term>
<listitem><para>By selecting this option, you can have &tde; use an external
program to determine the background. This can be any program of your choosing.
For more information on this option, see the section entitled <ulink
url="help:/kcontrol/background/index.html#bkgnd-programs">Background: Using an external program</ulink>.</para></listitem>
</varlistentry>
<varlistentry>
<term>Horizontal Gradient</term>
<listitem><para>By choosing this mode, you select two colors (using both color
buttons). &tde; will then start with the color selected by <guilabel>Color
1</guilabel> on the left edge of the screen, and slowly transform into the
color selected by <guilabel>Color 2</guilabel> by the time it gets to the
right edge of the screen.</para></listitem>
</varlistentry>
<varlistentry>
<term>Vertical Gradient</term>
<listitem><para>By choosing this mode, you select two colors (using both color
buttons). &tde; will then start with the color selected by <guilabel>Color
1</guilabel> on the top edge of the screen, and slowly transform into the color
selected by <guilabel>Color 2</guilabel> as it moves to the bottom of the
screen.</para></listitem>
</varlistentry>
<varlistentry>
<term>Pyramid Gradient</term>
<listitem><para>By choosing this mode, you select two colors (using both color
buttons). &tde; will then start with the color selected by <guilabel>Color
1</guilabel> in each corner of the screen, and slowly transform into the color
selected by <guilabel>Color 2</guilabel> as it moves to the center of the
screen.</para></listitem> 
</varlistentry>
<varlistentry>
<term>Pipecross Gradient</term>
<listitem><para>By choosing this mode, you select two colors (using both color
buttons). &tde; will then start with the color selected by <guilabel>Color
1</guilabel> in each corner of the screen, and slowly transform into the color
selected by <guilabel>Color 2</guilabel> as it moves to the center of the
screen. The <quote>shape</quote> of this gradient is  different then the pyramid
gradient.</para></listitem>
</varlistentry>
<varlistentry>
<term>Elliptic Gradient</term>
<listitem><para>By choosing this mode, you select two colors (using both color
buttons). &tde; will then start with the color selected by <guilabel>Color
2</guilabel> in the center of the screen, and slowly transform into the color
selected by <guilabel>Color 1</guilabel> as it moves to the edges, in an
elliptical pattern.</para></listitem> 
</varlistentry>
</variablelist>

<para>The setup button is only needed for if you select <guilabel>Background
program</guilabel> or <guilabel>Patterns</guilabel>. In these instances,
another window will appear to configure the specifics.</para>
<para><emphasis>Wallpaper</emphasis></para>
<para>To select a new background image first, click on the
<guilabel>Wallpapers</guilabel> tab, then  you can either select an image from the drop down list labeled <guilabel>Wallpaper</guilabel> or select
<guibutton>Browse...</guibutton> and select an image file from a file
selector.</para>

<para>The image can be displayed in six different ways:</para>
<variablelist>
<varlistentry>
<term>No wallpaper</term> 
<listitem><para>No image is displayed. Just the background colors.</para>
</listitem></varlistentry>
<varlistentry>
<term>Centered</term> 
<listitem><para>The image will be centered on the screen. The background colors
will be present anywhere the image does not cover.</para> </listitem>
</varlistentry>
<varlistentry>
<term>Tiled</term>
<listitem><para>The image will be duplicated until it fills the entire
desktop. The first image will be placed in the upper left corner of the screen,
and duplicated downward and to the right.</para> </listitem>
</varlistentry>
<varlistentry>
<term>Center Tiled</term>
<listitem><para>The image will be duplicated until it fills the entire
desktop. The first image will be placed in the center of the screen, and
duplicated upward, downward to the right, and to the left.</para> </listitem>
</varlistentry>
<varlistentry>
<term>Centered Maxpect</term>
<listitem><para>The image will be placed in the center of the screen. It will
be scaled to fit the desktop, but it will not change the aspect ratio of the
original image. This will provide you with an image that is not distorted.
</para> </listitem>
</varlistentry>
<varlistentry>
<term>Scaled</term>
<listitem><para>The image will be scaled to fit the desktop. It will be
stretched to fit all four corners.</para> </listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="tdmconfig-shutdown">
<title>Shutdown</title>

<para><guilabel>Allow Shutdown</guilabel></para>
<para>Use this drop down box to choose who is allowed to shut down:</para>
<itemizedlist>
<listitem>
<para><guilabel>Nobody</guilabel>: No one can shutdown the computer using
&tdm;. You must be logged in, and execute a command.</para>
</listitem>
<listitem>
<para><guilabel>Everybody</guilabel>:  Everyone can shutdown the computer using
&tdm;.</para>
</listitem>
<listitem><para><guilabel>Only Root</guilabel>: &tdm; requires that the
<systemitem>root</systemitem> password be entered before shutting down the
computer.</para></listitem> 
</itemizedlist>

<para>You can independently configure who is allowed to issue a
shutdown command for the <guilabel>Local:</guilabel> and
<guilabel>Remote:</guilabel> users.</para>

<para><emphasis>Commands</emphasis></para> <para>Use these text fields to
define the exact shutdown command.</para> <para>The
<guilabel>Halt:</guilabel> command defaults to <!-- Are these defaults still
correct? they disagree with what's in --> <!-- tdmrc -->
<command>/sbin/halt</command>. The <guilabel>Restart:</guilabel> command
defaults to
<command>/sbin/reboot</command>.</para>

<para>When <guilabel>Show boot options</guilabel> is enabled, &tdm;
will on reboot offer you options for the lilo boot manager. For this
feature to work, you will need to supply the correct paths to your
<command>lilo</command> command and to lilo's map file. Note that this
option is not available on all operating systems.</para>

<para><emphasis>Restart X-Server with session exit</emphasis></para>
<para>Whether the login manager should restart the local X-Server after
a session exit instead of resetting. Use this option when the X-Server
leaks memory, crashes the system on reset attempts, or otherwise exhibits
display issues or artifacts.</para>

</sect2>

<sect2 id="tdmconfig-users">
<title>Users</title>

<para>From here you can change the way users are represented in the
login window.</para>

<para>You may disable the user list in &tdm; entirely in the
<guilabel>Show Users</guilabel> section. You can choose from:</para>

<variablelist>
<varlistentry>
<term><guilabel>Show List</guilabel></term>
<listitem>
<para>Only show users you have specifically enabled in the list
alongside</para>
<para>If you do not check this box, no list will be shown. This is the most secure setting, since an
attacker would then have to guess a valid login name as well as a
password. It's also the preferred option if you have more than a
handful of users to list, or the list itself would become
unwieldy.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Inverse selection</guilabel></term>
<listitem>
<para>Allows you to intead select a list of users that should
<emphasis>not</emphasis> be shown, and all other users will be
listed.</para>
</listitem>
</varlistentry>
</variablelist>

<para>Independently of the users you specify by name, you can use the
<guilabel>System UIDs</guilabel> to specify a range of valid
<acronym>UID</acronym>s that are shown in the list. By default user
id's under 1000, which are often system or daemon users, and user id's
over 65000, are not shown.</para>

<para>You can also enable the <guilabel>Sort users</guilabel>
checkbox, to have the user list sorted alphabetically. If this is
disabled, users will appear in the order they are listed in the
password file. &tdm; will also autocomplete user names if you enable the
<guilabel>Autocompletion</guilabel> option.</para>

<para>If you choose to show users, then the login window will show
images (which you select), of a list of users. When someone is ready
to login, they may select their user name/image, enter their password,
and they are granted access.</para>

<para>If you permit a user image, then you can configure the source
for those images.</para>

<para>You can configure the admin picture here, for each user on the
system. Depending on the order selected above, users may be able to
override your selection.</para>

<para>If you choose not to show users, then the login window will be
more traditional. Users will need to type their username and password
to gain entrance. This is the preferred way if you have many users on
this terminal.</para>

</sect2>

<sect2 id="tdmconfig-convenience">
<title>Convenience</title>

<para>In the <guilabel>convenience</guilabel> tab you can configure
some options that make life easier for lazy people, like automatic
login or disabling passwords.</para>

<important><para>Please think more than twice before using these
options. Every option in the <guilabel>Convenience</guilabel> tab is
well-suited to seriously compromise your system security. Practically,
these options are only to be used in a completely non-critical
environment, &eg; a private computer at home.</para></important>

<sect3 id="loginmanager-convenience-autologin">
<title>Automatic Login</title>

<para>Automatic login will give anyone access to a certain account on
your system without doing any authentication. You can enable it using
the option <guilabel>Enable Auto-login</guilabel>.</para>

<para>You can choose the account to be used for automatic login from
the list labeled <guilabel>User:</guilabel>.</para>

</sect3>

<sect3 id="loginmanager-convenience-nopasswd">
<title><guilabel>Password-Less Login</guilabel></title>

<para>Using this feature, you can allow certain users to login without
having to provide their password. Enable this feature using the
<guilabel>Enable Password-less logins</guilabel> option.</para>

<para>Below this option you'll see a list of users on the system.
Enable password-less login for specific users by checking the checkbox
next to the login names. By default, this feature is disabled for
all users.</para>

<important><para>Again, this option should only be used in a safe
environment. If you enable it on a rather public system you should
take care that only users with heavy access restrictions are granted
password-less login, &eg;
<systemitem>guest</systemitem>.</para></important>

<para>You can also choose which user is <quote>preselected</quote>
when &tdm; starts. The default is <guilabel>None</guilabel>, but you
can choose <guilabel>Previous</guilabel> to have &tdm; default to the
last successfully logged in user, or you can
<guilabel>Specify</guilabel> a particular user to always be selected
from the list. You can also have &tdm; set the focus to the password
field, so that when you reach the &tdm; login screen, you can type the
password immediately.</para>

<para>The <guilabel>Automatically login after X server crash</guilabel>
option allows you to skip the authentication procedure when your X
server accidentally crashed.</para>

</sect3>

</sect2>

</sect1>

</chapter>

&tdmrc-ref;

<!-- ************************************************************ -->   
<chapter id="configuring-your-system-for-tdm">
<title>Configuring your system to use &tdm;</title>

<para>This chapter assumes that your system is already configured to
run the &X-Window;, and that you only need to reconfigure it to
allow graphical login.</para>

<sect1 id="setting-up-tdm">
<title>Setting up &tdm;</title>

<para>The fundamental thing that controls whether your computer boots to a
terminal prompt (console mode) or a graphical login prompt is the default
runlevel. The runlevel is set by the program <application> <ulink
url="man:init">/sbin/init</ulink></application> under the control of the
configuration file <filename>/etc/inittab</filename>. The default runlevels
used by different &UNIX; systems (and different &Linux; distributions) vary,
but if you look at <filename>/etc/inittab</filename> the start of it should
be something like this:</para>

<screen># Default runlevel. The runlevels used by RHS are:
# 0 - halt (Do NOT set initdefault to this)
# 1 - Single user mode
# 2 - Multiuser, without NFS
# 3 - Full multiuser mode
# 4 - unused
# 5 - X11
# 6 - reboot (Do NOT set initdefault to this)

id:3:initdefault:  
</screen>

<para>All but the last line of this extract are comments. The comments
show that runlevel 5 is used for X11 and that runlevel 3 is used for
multi-user mode without X11 (console mode). The final line specifies
that the default runlevel of the system is 3 (console mode). If your
system currently uses graphical login (for example, using &xdm;) its
default runlevel will match the runlevel specified for X11.</para>

<para>The runlevel with graphical login (&xdm;) for some common &Linux;
distributions is:</para>

<itemizedlist>
<listitem><para>5 for &RedHat; 3.x and later, and for &Mandrake;</para></listitem>
<listitem><para>4 for Slackware</para></listitem>
<listitem><para>3 for &SuSE;. 4.x and 5.x</para></listitem>
</itemizedlist>

<para>The first step in configuring your system is to ensure that you
can start &tdm; from the command line. Once this is working, you can
change your system configuration so that &tdm; starts automatically
each time you reboot your system.</para>

<para>To test &tdm;, you must first bring your system to a runlevel
that does not run &xdm;. To do so, issue a command like this:</para>

<screen><command>/sbin/init <option>3</option></command></screen>

<para>Instead of the number <option>3</option> you should specify the
appropriate runlevel for console mode on your system.</para>

<para>If your system uses Pluggable Authentication Modules
(<abbrev>PAM</abbrev>), which is normal with recent &Linux; and &Solaris;
systems, you should check that your <abbrev>PAM</abbrev> configuration permits
login through the service named <literal>tde</literal>. If you previously used
&xdm; successfully, you should not need to make any
changes to your <abbrev>PAM</abbrev> configuration in order to use
&tdm;. <filename>/etc/pam.conf</filename> or
<filename>/etc/pam.d/tde</filename>. Information on configuring
<abbrev>PAM</abbrev> is beyond the scope of this handbook, but
<abbrev>PAM</abbrev> comes with comprehensive documentation (try looking in
<filename>/usr/share/doc/*pam*/html/</filename>).</para>

<para>Now it's time for you to test &tdm; by issuing the following
command:</para>

<screen><command>tdm <option>-nodaemon</option></command>
</screen>

<para>If you get a &tdm; login dialog and you are able to log in,
things are going well. The main thing that can go wrong here is that
the run-time linker might not find the shared &Qt; or &tde; libraries.
If you have a binary distribution of the &tde; libraries, make sure
&tdm; is installed where the libraries believe &tde; is installed and
try setting some environment variables to point to your &tde; and &Qt;
libraries.</para>

<para>For example:</para>

<screen><command>export 
<option>TDEDIR=<replaceable>/opt/tde</replaceable></option></command>
<command>export 
<option>QTDIR=<replaceable>/usr/lib/qt2</replaceable></option></command>
<command>export 
<option>PATH=<replaceable>$TDEDIR/bin:$QTDIR/bin:$PATH</replaceable></option></command>
<command>export 
<option>LD_LIBRARY_PATH=<replaceable>$TDEDIR/lib:$QTDIR/lib</replaceable></option></command>
</screen>

<para>If you are still unsuccessful, try starting &xdm; instead, to
make sure that you are not suffering from a more serious X
configuration problem.</para>

<para>When you are able to start &tdm; successfully, you can start to
replace &xdm; by &tdm;. Again, this is distribution-dependent.</para>

<itemizedlist>
<listitem>
<para>For &RedHat;, edit <filename>/etc/inittab</filename>, look for this
 line:</para>
<screen>x:5:respawn:/usr/X11/bin/xdm -nodaemon</screen>
<para>and replace with:</para>
<screen>x:5:respawn:/opt/tde/bin/tdm</screen>
<para>This tells <command>init</command>(8) to respawn &tdm; when the
system is in run level  5. Note that &tdm; does not need the
 <option>-nodaemon</option> option.</para>
</listitem>
<listitem>
<para>For &Mandrake;, the X11 runlevel in
<filename>/etc/inittab</filename> invokes the shell script
<filename>/etc/X11/prefdm</filename>, which is set up to select from
amongst several display managers, including &tdm;. Make sure that all
the paths are correct for your installation.</para> 
</listitem>
<listitem>
<para>For &SuSE;, edit <filename>/sbin/init.d/xdm</filename> to add a
first line:</para>

<screen>. /etc/rc.config
DISPLAYMANAGER=tdm
export DISPLAYMANAGER</screen>
</listitem>
<listitem><para>For FreeBSD, edit <filename>/etc/ttys</filename> and find
the line like this:</para>
<screen>ttyv8   "/usr/X11R6/bin/xdm -nodaemon"  xterm   off secure</screen>
<para>and edit it to this:</para>
<screen>ttyv8   "/usr/local/bin/tdm"  xterm   on secure</screen>
</listitem>

<listitem><para>Most other distributions are a variation of one of
these.</para></listitem>
</itemizedlist>

<para>At this stage, you can test &tdm; again by bringing your system
to the runlevel that should now run &tdm;. To do so, issue a command
like this:</para>

<screen><command>/sbin/init <option>5</option></command>
</screen>

<para>Instead of the number <option>5</option> you should specify the
appropriate runlevel for running X11 on your system.</para>

<para>The final step is to edit the <parameter>initdefault</parameter>
entry in <filename>/etc/inittab</filename> to specify the appropriate
runlevel for X11.</para>

<warning><para>Before you make this change, ensure that you have a way
to reboot your system if a problem occurs. This might be a
<quote>rescue</quote> floppy-disk provided by your operating system
distribution or a specially-designed <quote>rescue</quote>
floppy-disk, such as <literal>tomsrtbt</literal>. Ignore this advice
at your peril.</para></warning>

<para>This usually involves changing the line:</para>
<screen>id:3:initdefault:</screen>
<para>to</para>
<screen>id:5:initdefault:</screen>

<para>When you reboot your system, you should end up with the
graphical &tdm; login dialog.</para>

<para>If this step is unsuccessful the most likely problem is that the
environment used at boot time differs from the environment that you used for
testing at the command line. If you are trying to get two versions of &tde;
to co-exist, be particularly careful that the settings you use for your
<envar>PATH</envar> and <envar>LD_LIBRARY_PATH</envar> environment variables
are consistent, and that the startup scripts are not over-riding them in
some way.</para>

</sect1>

</chapter>

<chapter id="different-window-managers-with-tdm">
<title>Supporting multiple window managers</title>

<para>&tdm; detects most available window manager and desktop environments when
it is run. Installing a new one should make it automatically available in
the &tdm; main dialog <guilabel>Session Type:</guilabel>.</para>

<para>If you have a very new window manager, or something that &tdm; does
not support, the first thing you should check is that the application to be
run is in the <envar>PATH</envar> and has not been renamed during the
install into something unexpected.</para>

<para>If the case is that the application is too new and not yet supported
by &tdm;, you can quite simply add a new session.</para>

<para>The sessions are defined in <firstterm>.desktop</firstterm> files in
<filename
class="directory">$<envar>TDEDIR</envar>/share/apps/tdm/sessions</filename>.
You can simply add an appropriately named <literal
role="extension">.desktop</literal> file in this directory. The fields
are:</para>

<programlisting>[Desktop Entry]
Encoding=UTF-8 <lineannotation>This is fixed to <option>UTF-8</option> and
may be omitted</lineannotation>
Type=XSession <lineannotation>This is fixed to <option>XSession</option> and
may be omitted</lineannotation>
Exec=<replaceable>executable name</replaceable> <lineannotation>Passed to
<command>eval exec</command> in a Bourne shell</lineannotation>
TryExec=<replaceable>executable name</replaceable> <lineannotation>Supported
but not required</lineannotation>
Name=<replaceable>name to show in the &tdm; session list</replaceable></programlisting>

<para>There are also three <quote>magic</quote>:</para>

<variablelist>
<varlistentry>
<term>default</term>
<listitem>
<para>
The default session for &tdm; is normally &tde; but can be configured by the
system administrator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>custom</term>
<listitem>
<para>
The Custom session will run the users ~/.xsession if it exists.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>failsafe</term>
<listitem>
<para>
Failsafe will run a very plain session, and is useful only for debugging
purposes.
</para>
</listitem>
</varlistentry>
</variablelist>

<para>To override a session type, copy the .desktop file from the data dir
to the config dir and edit it at will. Removing the shipped session types
can be accomplished by <quote>shadowing</quote> them with .desktop files
containing Hidden=true. For the magic session types no .desktop files exist
by default, but &tdm; pretends they would, so you can override them like any
other type. I guess you already know how to add a new session type by
now. ;-)</para>

</chapter>

<chapter id="xdmcp-with-tdm">
<title>Using &tdm; for Remote Logins (&XDMCP;)</title>

<para>&XDMCP; is the Open Group standard, the <quote>X Display Manager
Control Protocol</quote>. This is used to set up connections between
remote systems over the network.</para>

<para>&XDMCP; is useful in multiuser situations where there are users
with workstations and a more powerful server that can provide the
resources to run multiple X sessions. For example, &XDMCP; is a good
way to reuse old computers - a Pentium or even 486 computer with 16 Mb
RAM is sufficient to run X itself, and using &XDMCP; such a computer can
run a full modern &tde; session from a server. For the server part,
once a single &tde; (or other environment) session is running, running
another one requires very few extra resources.</para>

<para>However, allowing another method of login to your machine
obviously has security implications. You should run this service only
if you need to allow remote X Servers to start login sessions on your
system. Users with a single &UNIX; computer should not need to run
this.</para>

</chapter>

<chapter id="advanced-topics">
<title>Advanced Topics</title>

<sect1 id="command-sockets">
<title>Command Sockets</title>

<para>This is a feature you can use to remote-control &tdm;. It's mostly
intended for use by &ksmserver; and &kdesktop; from a running session, but
other applications are possible as well.</para>

<para>The sockets are &UNIX; domain sockets which live in subdirectories of the
directory specified by <option>FifoDir</option>=. The subdir is the key to
addressing and security; the sockets all have the file name
<filename>socket</filename> and file permissions
<literal>rw-rw-rw-</literal> (0666). This is because some systems don't care
for the file permission of the socket files.</para>

<para>There are two types of sockets: the global one (tdmctl) and the
per-display ones (tdmctl-&lt;display&gt;).</para>

<para>The global one's subdir is owned by root, the subdirs of the per-display
ones' are owned by the user currently owning the session (root or the
logged in user). Group ownership of the subdirs can be set via FifoGroup=,
otherwise it is root. The file permissions of the subdirs are rwxr-x---
(0750).</para>

<para>The fields of a command are separated by tabs (<token>\t</token>), the
fields of a list are separated by spaces, literal spaces in list fields are
denoted by <token>\s</token>.</para>

<para>The command is terminated by a newline (<token>\n</token>).</para>

<para>The same applies to replies. The reply on success is
<returnvalue>ok</returnvalue>, possibly followed by the requested
information. The reply on error is an errno-style word (&eg;
<returnvalue>perm</returnvalue>, <returnvalue>noent</returnvalue>, &etc;)
followed by a longer explanation.</para>

<variablelist>
<title>Global commands:</title>
<varlistentry>
<term><command>login</command> <option>display</option>
(<parameter>now</parameter> | <parameter>schedule</parameter>) <parameter>user</parameter> <parameter>password</parameter>
[session_arguments]</term>
<listitem>
<para>login user at specified display. if <parameter>now</parameter> is
specified, a possibly running session is killed, otherwise the login is done
after the session exits. session_arguments are printf-like escaped contents
for .dmrc. Unlisted keys will default to previously saved values.</para>
</listitem>
</varlistentry>
</variablelist>

<variablelist>
<title>Per-display commands:</title>
<varlistentry>
<term><command>lock</command></term>
<listitem>
<para>The display is marked as locked. If the &X-Server; crashes in this
state, no auto-relogin will be performed even if the option is on.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>unlock</command></term>
<listitem>
<para>Reverse the effect of <command>lock</command>, and re-enable
auto-relogin.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>suicide</command></term>
<listitem>
<para>The currently running session is forcibly terminated. No auto-relogin
is attempted, but a scheduled "login" command will be executed.</para>
</listitem>
</varlistentry>
</variablelist>

<variablelist>
<title>Commands for all sockets</title>
<varlistentry>
<term><command>caps</command></term>
<listitem>
<para>Returns a list of this socket's capabilities:</para>

<variablelist>
<varlistentry>
<term><returnvalue>&tdm;</returnvalue></term>
<listitem>
<para>identifies &tdm;, in case some other DM implements this protocol,
too</para>
</listitem>
</varlistentry>
<varlistentry>
<term><returnvalue>list</returnvalue>, <returnvalue>lock</returnvalue>,
<returnvalue>suicide</returnvalue>, <returnvalue>login</returnvalue></term>
<listitem>
<para>The respective command is supported</para>
</listitem>
</varlistentry>
<varlistentry>
<term><returnvalue>bootoptions</returnvalue></term>
<listitem>
<para>The <command>listbootoptions</command> command and the
<option>=</option> to <command>shutdown</command> are supported</para>
</listitem>
</varlistentry>
<varlistentry>
<term><returnvalue>shutdown &lt;list&gt;</returnvalue></term>
<listitem>
<para><command>shutdown</command> is supported and allowed for the listed
users (a comma separated list.)  <returnvalue>*</returnvalue> means all
authenticated users.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><returnvalue>nuke &lt;list&gt;</returnvalue></term>
<listitem>
<para>Forced shutdown may be performed by the listed users.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><returnvalue>nuke</returnvalue></term>
<listitem>
<para>Forced shutdown may be performed by everybody</para>
</listitem>
</varlistentry>
<varlistentry>
<term><returnvalue>reserve &lt;number&gt;</returnvalue></term>
<listitem>
<para>Reserve displays are configured, and <returnvalue>number</returnvalue>
are available at this time</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>list</command> [<parameter>all</parameter> |
<parameter>alllocal</parameter>]</term>
<listitem>
<para>Return a list of running sessions. By default all active sessions are
listed. if <parameter>all</parameter> is specified, passive sessions are
listed as well. If <parameter>alllocal</parameter> is specified, passive
sessions are listed as well, but all incoming remote sessions are
skipped.</para>
<para>Each session entry is a comma separated tuple of:</para>
<itemizedlist>
<listitem><para>Display or TTY name</para></listitem>
<listitem><para>VT name for local sessions</para></listitem>
<listitem><para>Logged in user's name, empty for passive sessions and
outgoing remote sessions (local chooser mode)</para></listitem>
<listitem><para>Session type or <quote>&lt;remote&gt;</quote> for outgoing
remote sessions, empty for passive sessions.</para></listitem>
<listitem><para>A Flag field:</para>
<itemizedlist><listitem><para><literal>*</literal> for the display belonging
to the requesting socket.</para></listitem>
<listitem><para><literal>!</literal> for sessions that cannot be killed by the
reqeusting socket.</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>New fields may be added in the future.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>reserve</command> [<parameter>timeout in
seconds</parameter>]</term>
<listitem>
<para>Start a reserve login screen. If nobody logs in within the specified
amount of time (one minute by default), the display is removed again. When
the session on the display exits, the display is removed, too.</para>
<para>Permitted only on sockets of local displays and the global
socket.</para> 
</listitem>
</varlistentry>

<varlistentry>
<term><command>activate</command>
(<parameter>vt</parameter>|<parameter>display</parameter>)</term>
<listitem>
<para>Switch to a particular VT (virtual terminal). The VT may be specified
either directly (&eg; <parameter>vt3</parameter>) or by a display using it
(eg; <parameter>:2</parameter>).</para>
<para>Permitted only on sockets of local displays and the global
socket.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>listbootoptions</command></term>
<listitem>
<para>List available boot options.</para>
<!--FIXME: "ok" list default current
    default and current are indices into the list and are -1 if unset or
    undeterminable. -->
</listitem>
</varlistentry>

<varlistentry>
<term><command>shutdown</command> (<parameter>reboot</parameter> |
<parameter>halt</parameter>)
[<parameter>=<replaceable>bootchoice</replaceable></parameter>]
(<parameter>ask</parameter>|<parameter>trynow</parameter>|<parameter>forcenow</parameter>|<parameter>schedule</parameter>|<parameter>start
(<parameter>-1</parameter>|<parameter>end
(<parameter>force</parameter>|<parameter>forcemy</parameter>|<parameter>cancel)</parameter>)</parameter>)</parameter>)</term>
<listitem>
<para>Request a system shutdown, either a reboot or a halt/poweroff.</para>
<para>An OS choice for the next boot may be specified from the list returned
by <command>listbootoptions</command></para>
<para>Shutdowns requested from per-display sockets are executed when the
current sessino on that display exits. Such a request may pop up a dialog
asking for confirmation and/or authentication</para>
<para><parameter>start</parameter> is the time for which the shutdown is
scheduled. If it starts with a plus-sign, the current time is added. Zero
means immediately.</para>
<para><parameter>end</parameter> is the latest time at which the shutdown
should be performed if active sessions are still running. If it starts with
a plus-sign, the start time is added. -1 means wait infinitely. If end is
through and active sessions are still running, &tdm; can do one of the
following:</para>
<itemizedlist>
<listitem><para><parameter>cancel</parameter> - give up the
shutdown</para></listitem>
<listitem><para><parameter>force</parameter> - shut down
nonetheless</para></listitem>
<listitem><para><parameter>forcemy</parameter> - shut down nonetheless if
all active sessions belong to the requesting user. Only for per-display sockets.</para></listitem>
</itemizedlist>
<para><parameter>start</parameter> and <parameter>end</parameter> are
specified in seconds since the &UNIX; epoch.</para>
<para><parameter>trynow</parameter> is a synonym for <parameter>0 0
cancel</parameter>, <parameter>forcenow</parameter> for <parameter>0 0
force</parameter> and <parameter>schedule</parameter> for <parameter>0
-1</parameter>.</para>
<para><parameter>ask</parameter> attempts an immediate shutdown and
interacts with the user if active sessions are still running. Only for
per-display sockets.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>shutdown cancel</command>
[<parameter>local</parameter>|<parameter>global</parameter>}</term>
<listitem>
<para>Cancel a scheduled shutdown. The global socket always cancels the
currently pending shutdown, while per-display sockets default to cancelling
their queued request.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>shutdown status</command></term>
<listitem>
<para>Return a list with information about shutdowns.</para>
<para>The entries are a comma-separated tuples of:</para>
<itemizedlist>
<listitem>
<para>(<returnvalue>global</returnvalue>|<returnvalue>local</returnvalue>) -
pending vs. queued shutdown. A local entry can be returned only by a
per-display socket.</para>
</listitem>
<listitem><para>(<returnvalue>halt</returnvalue>|<returnvalue>reboot</returnvalue>)</para></listitem>
<listitem><para>start</para></listitem>
<listitem><para>end</para></listitem>
<listitem><para>("ask"|"force"|"forcemy"|"cancel")</para></listitem>
<listitem><para>Numeric user ID of the requesting user, -1 for the global
socket.</para></listitem>
<listitem><para>The next boot OS choice or "-" for none.</para></listitem>
</itemizedlist>
<para>New fields might be added later</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
<para>There are two ways of using the sockets:</para>
<itemizedlist>
<listitem>
<para>Connecting them directly. FifoDir is exported as
$<envar>DM_CONTROL</envar>; the name of per-display sockets can be derived
from $<envar>DISPLAY</envar>.</para>
</listitem>
<listitem>
<para>By using the <command>tdmctl</command> command (&eg; from within a
shell script). Try <command>tdmctl</command> <option>-h</option> to find out
more.</para>
</listitem>
</itemizedlist>

<para>Here is an example bash script <quote>reboot into FreeBSD</quote>:</para>

<programlisting>if tdmctl | grep -q shutdown; then
  IFS=$'\t'
  set  -- mdash; `tdmctl listbootoptions`
  if [ "$1" = ok ]; then
        fbsd=$(echo "$2" | tr ' ' '\n' | sed -ne 's,\\s, ,g;/freebsd/I{p;q}')
        if [ -n "$fbsd" ]; then
      tdmctl shutdown reboot "=$fbsd" ask &gt; /dev/null
        else
          echo "FreeBSD boot unavailable."
        fi
  else
    echo "Boot options unavailable."
  fi
else
  echo "Cannot reboot system."
fi</programlisting>

</sect1>
<!-- Riddell: so there's no GUI you need to edit tdmrc to say UseTheme=true and Theme=/path/to/theme.xml
[13:31] <Riddell> jriddell.org/programs has an example theme 

<sect1 id="dm-themes">
<title>Themes</title>

&tdm; has limited support for desktop manager themes. You may enable them
by adding <userinput>UseTheme=true</userinput> to <filename>tdmrc</filename>
and <userinput>Theme=/path/to/theme.xml</userinput>. 
</sect1>
-->
</chapter>

<chapter id="Other-Information">
<title>Other sources of information</title>

<para>Since &tdm; is descended from &xdm;, the <ulink
url="man:xdm">&xdm; man page</ulink> may provide useful background
information. For X-related problems try the man pages <ulink
url="man:X">X</ulink> and <ulink url="man:startx">startx</ulink>. If you have
questions about &tdm; that are not answered by this handbook, take advantage of
the fact the &tdm; is provided under the terms of the <abbrev>&GNU;</abbrev>
General Public License: look at the source code.
</para>

</chapter>


<chapter id="credits"><title>Credits and License</title>

<para>&tdm; is derived from, and includes code from,
&xdm; (C) Keith Packard, MIT X Consortium.</para>

<para>&tdm; 0.1 was written by &Matthias.Ettrich;. Later versions till &tde;
2.0.x were written by &Steffen.Hansen;. Some new features for &tde; 2.1.x and
a major rewrite for &tde; 2.2.x made by &Oswald.Buddenhagen;.</para>

<para>Other parts of the &tdm; code are copyright by the authors, and
licensed under the terms of the <ulink url="common/gpl-license.html">&GNU;
GPL</ulink>. Anyone is allowed to change &tdm; and redistribute the result
as long as the names of the authors are mentioned.</para>

<para>&tdm; requires the &Qt; library, which is copyright Troll Tech AS.</para>

<para>Documentation contributors:
<itemizedlist>

<listitem><para>Documentation written by &Steffen.Hansen;
<email>stefh@dit.ou.dk</email></para></listitem>

<listitem><para>Documentation extended by Gregor
Zumstein<email>zumstein@ssd.ethz.ch</email>. Last update August 9,
1998</para></listitem>

<listitem><para>Documentation revised for &tde; 2 by &Neal.Crook; &Neal.Crook.mail;. Last update August 6, 2000</para></listitem>

<listitem><para>Documentation extended and revised for &tde; 2.2 by &Oswald.Buddenhagen; &Oswald.Buddenhagen.mail;. Last update August,
2001</para></listitem>

</itemizedlist></para>

<para>Documentation copyright &Steffen.Hansen;, Gregor Zumstein, &Neal.Crook;
and &Oswald.Buddenhagen;. This document also includes large parts of the &xdm;
man page, which is &copy; Keith Packard.</para>

<!--TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underGPL;

</chapter>

<glossary id="glossary">
<title>Glossary</title>

<glossentry id="gloss-greeter">
<glossterm>greeter</glossterm>
<glossdef><para>The greeter is the login dialog, &ie; the part of &tdm;
which the user sees.</para>
</glossdef>
</glossentry>

<glossentry>
<glossterm id="gloss-entropy">entropy</glossterm>
<glossdef><para>The entropy of a system is the measure of its
unpredictability. This is used during the generation of random numbers.</para></glossdef>
</glossentry>

</glossary>
</book>
<!--
Local Variables:
mode: xml
sgml-omittag: nil
sgml-shorttag: t
End:
-->