~ubuntu-branches/ubuntu/utopic/kde-workspace/utopic-proposed

<para>It is possible to set how many lines of text will be shown beneath each icon with the <guilabel>Lines for icon text:</guilabel> If the text is longer than can be shown in the configured number of lines, it will be truncated. You can also set a value for the <guilabel>Width for icon text:</guilabel> option. The value is in pixels, and the default is <guilabel>Auto</guilabel>, which is a default calculated based on the current font.

786

</para>

787

788

<para>Finally you can set the <guilabel>Size of the background

789

cache:</guilabel>. The default (2048 KB) is usually a safe

790

choice.</para>

791

-->

792

</sect3>

793

794

795

<title>Adding, Removing and Modifying Wallpapers and Patterns</title>

796

797

<para>There is a button under the preview monitor labeled <guibutton>Get

798

New Wallpapers</guibutton> that helps you fetch new wallpaper images from a

799

selection of popular images from the <ulink

800

url="http://www.kde-look.org">KDE-Look</ulink> website. You can of course

801

select any image you have available to use as wallpaper, and it may be

802

stored in any location on your hard drive. To have a wallpaper show up in

803

the list automatically for all users, you should save it to the <filename

804

class="directory">$<envar>KDEDIR</envar>/share/wallpapers</filename>

805

folder.</para>

806

807

<para>A pattern is a picture file which &kde; uses as a template to

808

draw your background. The picture file provides the shapes, but &kde;

809

provides the colors. &kde; is packaged with several patterns, and you also

810

can add new patterns.</para>

811

812

<para>To add a new pattern that is available to every user on your

813

computer, simply place the file in <filename

814

class="directory">$<envar>KDEDIR</envar>/share/apps/kdm/patterns/</filename>.</para>

815

816

<para>Copy a <literal role="extension">.desktop</literal> file from

817

this folder, and name it the same as your new pattern image file.

818

Modify the contents to suit your new pattern.</para>

819

820

<para>To add a new pattern for a single user, add the files to

821

<filename

822

class="directory">$<envar>KDEHOME</envar>/share/apps/kdm/patterns/</filename>.</para>

823

824

<para>For best results, the pattern should be a grayscale PNG file.</para>

825

826

</sect3>

827

828

</sect2>

829

830

831

<title>Theme</title>

832

<para>This page consists of three sections:</para>

833

834

<para>A list of installed themes, where you can select the one to be used.</para>

835

836

<para>A screenshot with a preview of the selected theme and additional

837

information like <guilabel>Copyright</guilabel> and <guilabel>Description</guilabel>.</para>

838

839

<para>Three buttons to install or remove a theme and a button to launch

840

the <guilabel>Get Hot New Stuff</guilabel> dialog where you can download new themes.</para>

841

842

<note><para>The settings on this page are only available in themed mode.</para></note>

843

844

</sect2>

845

846

847

<title>Shutdown</title>

848

849

<para><guilabel>Allow Shutdown</guilabel></para>

850

<para>Use this drop down box to choose who is allowed to shut down:</para>

851

852

853

<para><guilabel>Nobody</guilabel>: No one can shutdown the computer using

854

&kdm;. You must be logged in, and execute a command.</para>

855

</listitem>

856

857

<para><guilabel>Everybody</guilabel>: Everyone can shutdown the computer using

858

&kdm;.</para>

859

</listitem>

860

<listitem><para><guilabel>Only Root</guilabel>: &kdm; requires that the

861

<systemitem>root</systemitem> password be entered before shutting down the

862

computer.</para></listitem>

863

</itemizedlist>

864

865

<para>You can independently configure who is allowed to issue a

866

shutdown command for the <guilabel>Local:</guilabel> and

867

<guilabel>Remote:</guilabel> users.</para>

868

869

<para><emphasis>Commands</emphasis></para> <para>Use these text fields to

870

define the exact shutdown command.</para> <para>The

871

<guilabel>Halt:</guilabel> command defaults to <!-- Are these defaults still

872

correct? they disagree with what's in -->

873

<command>/sbin/halt</command>. The <guilabel>Reboot:</guilabel> command

874

defaults to

875

<command>/sbin/reboot</command>.</para>

876

877

<para>When <guilabel>Boot manager</guilabel> is set to <guilabel>Grub</guilabel>

878

or <guilabel>Lilo</guilabel>, &kdm;

879

will on reboot offer you options for these boot managers. Note that this

880

option is not available on all operating systems.</para>

881

882

</sect2>

883

884

885

<title>Users</title>

886

887

<para>From here you can change the way users are represented in the

888

889

890

<para>Independently of the users you specify by name, you can use the

891

<guilabel>System UIDs</guilabel> to specify a range of valid

892

<acronym>UID</acronym>s that are shown in the list. By default user

893

id's under 1000, which are often system or daemon users, and user id's

894

over 30000, are not shown.</para>

895

896

<para>You may disable the user list in &kdm; entirely in the

897

<guilabel>Users</guilabel> section. You can choose from:</para>

898

899

900

901

902

903

<para>Only show users you have specifically not excluded in the list

904

alongside</para>

905

<para>If you do not check this box, no list will be shown. This is the most secure setting, since an

906

attacker would then have to guess a valid login name as well as a

907

password. It is also the preferred option if you have more than a

908

handful of users to list, or the list itself would become

909

unwieldy.</para>

910

</listitem>

911

</varlistentry>

912

913

<term><guilabel>Autocompletion</guilabel></term>

914

915

<para>If this option is checked, &kdm; will automatically complete user names while

916

they are typed in the line edit.</para>

917

</listitem>

918

</varlistentry>

919

920

<term><guilabel>Inverse selection</guilabel></term>

921

922

<para>Allows you to instead select a list of users that should

923

be shown, and all other users will <emphasis>not</emphasis> be

924

listed.</para>

925

</listitem>

926

</varlistentry>

927

</variablelist>

928

929

<para>You can also enable the <guilabel>Sort users</guilabel>

930

checkbox, to have the user list sorted alphabetically. If this is

931

disabled, users will appear in the order they are listed in the

932

password file. &kdm; will also autocomplete user names if you enable the

933

<guilabel>Autocompletion</guilabel> option.</para>

934

935

<para>If you choose to show users, then the login window will show

936

images (which you select), of a list of users. When someone is ready

937

to login, they may select their user name/image, enter their password,

938

and they are granted access.</para>

939

940

<para>If you permit a user image, then you can configure the <guilabel>

941

User Image Source</guilabel>:</para>

942

943

<para>Here you can specify where &kdm; will obtain the images that represent users.

944

<guilabel>System</guilabel> represents the global folder; these are the pictures you can set

945

below. <guilabel>User</guilabel> means that &kdm; should read the user's

946

<filename>$<envar>HOME</envar>/.face.icon</filename> file.

947

The two selections in the middle define the order of preference if both

948

sources are available.

949

</para>

950

951

<para>If you choose not to show users, then the login window will be

952

more traditional. Users will need to type their username and password

953

to gain entrance. This is the preferred way if you have many users on

954

this terminal.</para>

955

956

</sect2>

957

958

959

<title>Convenience</title>

960

961

<para>In the <guilabel>Convenience</guilabel> tab you can configure

962

some options that make life easier for lazy people, like automatic

963

964

965

<important><para>Please think more than twice before using these

966

options. Every option in the <guilabel>Convenience</guilabel> tab is

967

well-suited to seriously compromise your system security. Practically,

968

these options are only to be used in a completely non-critical

969

environment, &eg; a private computer at home. </para></important>

970

971

972

<title>Automatic Login</title>

973

974

<para>Automatic login will give anyone access to a certain account on

975

your system without doing any authentication. You can enable it using

976

the option <guilabel>Enable Auto-Login</guilabel>.</para>

977

978

<para>You can choose the account to be used for automatic login from

979

the list labeled <guilabel>User:</guilabel>.</para>

980

981

<para>With <guilabel>Lock session</guilabel> the automatically started session

982

will be locked immediately (provided it is a &kde; session). This can be used

983

to obtain a super-fast login restricted to one user.</para>

984

985

986

<para>Automatic login can be suppressed by pressing the &Shift; key immediately

987

after the &X-Server; switches to graphics mode and releasing it when &kdm;'s

988

hourglass cursor appears.</para>

989

</sect3>

990

991

992

<title><guilabel>Preselected User</guilabel></title>

993

994

<para>You can also choose which user is <quote>preselected</quote>

995

when &kdm; starts. The default is <guilabel>None</guilabel>, but you

996

can choose <guilabel>Previous</guilabel> to have &kdm; default to the

997

last successfully logged in user, or you can

998

<guilabel>Specify</guilabel> a particular user to always be selected

999

from the list. You can also have &kdm; set the focus to the password

1000

field, so that when you reach the &kdm; login screen, you can type the

1001

password immediately.</para>

1002

1003

</sect3>

1004

1005

1006

<title><guilabel>Password-Less Login</guilabel></title>

1007

1008

<para>Using this feature, you can allow certain users to login without

1009

having to provide their password. Enable this feature using the

1010

<guilabel>Enable Password-Less Logins</guilabel> option.</para>

1011

1012

<para>Below this option you'll see a list of users on the system.

1013

Enable password-less login for specific users by checking the checkbox

1014

next to the login names. By default, this feature is disabled for

1015

all users.</para>

1016

1017

<important><para>Again, this option should only be used in a safe

1018

environment. If you enable it on a rather public system you should

1019

take care that only users with heavy access restrictions are granted

1020

password-less login, &eg;

1021

<systemitem>guest</systemitem>.</para></important>

1022

1023

<para>The <guilabel>Automatically login after X server crash</guilabel>

1024

option allows you to skip the authentication procedure when your X

1025

server accidentally crashed.</para>

1026

1027

</sect3>

1028

1029

</sect2>

1030

1031

</sect1>

1032

1033

</chapter>

1034

1035

&kdmrc-ref;

1036

1037

&theme-ref;

1038

1039

1040

1041

<title>Configuring your system to use &kdm;</title>

1042

1043

<para>This chapter assumes that your system is already configured to

1044

run the &X-Window;, and that you only need to reconfigure it to

1045

allow graphical login.</para>

1046

1047

1048

<title>Setting up &kdm;</title>

1049

1050

<para>The fundamental thing that controls whether your computer boots to a

1051

terminal prompt (console mode) or a graphical login prompt is the default

1052

runlevel. The runlevel is set by the program <application> <ulink

1053

url="man:init">/sbin/init</ulink></application> under the control of the

1054

configuration file <filename>/etc/inittab</filename>. The default runlevels

1055

used by different &UNIX; systems (and different &Linux; distributions) vary,

1056

but if you look at <filename>/etc/inittab</filename> the start of it should

1057

be something like this:</para>

1058

1059

<screen># Default runlevel. The runlevels used by RHS are:

1060

# 0 - halt (Do NOT set initdefault to this)

1061

# 1 - Single user mode

1062

# 2 - Multiuser, without NFS

1063

# 3 - Full multiuser mode

1064

# 4 - unused

1065

# 5 - X11

1066

# 6 - reboot (Do NOT set initdefault to this)

1067

1068

id:3:initdefault:

1069

</screen>

1070

1071

<para>All but the last line of this extract are comments. The comments

1072

show that runlevel 5 is used for X11 and that runlevel 3 is used for

1073

multi-user mode without X11 (console mode). The final line specifies

1074

that the default runlevel of the system is 3 (console mode). If your

1075

system currently uses graphical login (for example, using &xdm;) its

1076

default runlevel will match the runlevel specified for X11.</para>

1077

1078

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

1079

distributions is:</para>

1080

1081

1082

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

1083

<listitem><para>4 for Slackware</para></listitem>

1084

1085

</itemizedlist>

1086

1087

<para>The first step in configuring your system is to ensure that you

1088

can start &kdm; from the command line. Once this is working, you can

1089

change your system configuration so that &kdm; starts automatically

1090

each time you reboot your system.</para>

1091

1092

<para>To test &kdm;, you must first bring your system to a runlevel

1093

that does not run &xdm;. To do so, issue a command like this:</para>

1094

1095

1096

1097

<para>Instead of the number <option>3</option> you should specify the

1098

appropriate runlevel for console mode on your system.</para>

1099

1100

<para>If your system uses Pluggable Authentication Modules

1101

(<abbrev>PAM</abbrev>), which is normal with recent &Linux; and &Solaris;

1102

systems, you should check that your <abbrev>PAM</abbrev> configuration permits

1103

1104

&xdm; successfully, you should not need to make any

1105

changes to your <abbrev>PAM</abbrev> configuration in order to use

1106

&kdm;. <filename>/etc/pam.conf</filename> or

1107

<filename>/etc/pam.d/kde</filename>. Information on configuring

1108

<abbrev>PAM</abbrev> is beyond the scope of this handbook, but

1109

<abbrev>PAM</abbrev> comes with comprehensive documentation (try looking in

1110

<filename>/usr/share/doc/*pam*/html/</filename>).</para>

1111

1112

<para>Now it's time for you to test &kdm; by issuing the following

1113

command:</para>

1114

1115

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

1116

</screen>

1117

1118

<para>If you get a &kdm; login dialog and you are able to log in,

1119

things are going well. The main thing that can go wrong here is that

1120

the run-time linker might not find the shared &Qt; or &kde; libraries.

1121

If you have a binary distribution of the &kde; libraries, make sure

1122

&kdm; is installed where the libraries believe &kde; is installed and

1123

try setting some environment variables to point to your &kde; and &Qt;

1124

libraries.</para>

1125

1126

<para>For example:</para>

1127

1128

<screen><command>export

1129

<option>KDEDIR=<replaceable>/opt/kde</replaceable></option></command>

1130

<command>export

1131

<option>QTDIR=<replaceable>/usr/lib/qt4</replaceable></option></command>

1132

<command>export

1133

<option>PATH=<replaceable>$KDEDIR/bin:$QTDIR/bin:$PATH</replaceable></option></command>

1134

<command>export

1135

<option>LD_LIBRARY_PATH=<replaceable>$KDEDIR/lib:$QTDIR/lib</replaceable></option></command>

1136

</screen>

1137

1138

<para>If you are still unsuccessful, try starting &xdm; instead, to

1139

make sure that you are not suffering from a more serious X

1140

configuration problem.</para>

1141

1142

<para>When you are able to start &kdm; successfully, you can start to

1143

replace &xdm; by &kdm;. Again, this is distribution-dependent.</para>

1144

1145

1146

1147

<para>For &RedHat;, edit <filename>/etc/inittab</filename>, look for this

1148

line:</para>

1149

<screen>x:5:respawn:/usr/X11/bin/xdm -nodaemon</screen>

1150

<para>and replace with:</para>

1151

<screen>x:5:respawn:/opt/kde/bin/kdm</screen>

1152

<para>This tells <command>init</command>(8) to respawn &kdm; when the

1153

system is in run level 5. Note that &kdm; does not need the

1154

<option>-nodaemon</option> option.</para>

1155

</listitem>

1156

1157

<para>For &Mandrake;, the X11 runlevel in

1158

<filename>/etc/inittab</filename> invokes the shell script

1159

<filename>/etc/X11/prefdm</filename>, which is set up to select from

1160

amongst several display managers, including &kdm;. Make sure that all

1161

the paths are correct for your installation.</para>

1162

</listitem>

1163

1164

<para>For &SuSE;, edit <filename>/sbin/init.d/xdm</filename> to add a

1165

first line:</para>

1166

1167

<screen>. /etc/rc.config

1168

DISPLAYMANAGER=kdm

1169

export DISPLAYMANAGER</screen>

1170

</listitem>

1171

<listitem><para>For FreeBSD, edit <filename>/etc/ttys</filename> and find

1172

the line like this:</para>

1173

<screen>ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure</screen>

1174

1175

<screen>ttyv8 "/opt/kde/bin/kdm" xterm on secure</screen>

1176

</listitem>

1177

1178

<listitem><para>Most other distributions are a variation of one of

1179

these.</para></listitem>

1180

</itemizedlist>

1181

1182

<para>At this stage, you can test &kdm; again by bringing your system

1183

to the runlevel that should now run &kdm;. To do so, issue a command

1184

like this:</para>

1185

1186

1187

</screen>

1188

1189

<para>Instead of the number <option>5</option> you should specify the

1190

appropriate runlevel for running X11 on your system.</para>

1191

1192

<para>The final step is to edit the <parameter>initdefault</parameter>

1193

entry in <filename>/etc/inittab</filename> to specify the appropriate

1194

runlevel for X11.</para>

1195

1196

<warning><para>Before you make this change, ensure that you have a way

1197

to reboot your system if a problem occurs. This might be a

1198

<quote>rescue</quote> floppy-disk provided by your operating system

1199

distribution or a specially-designed <quote>rescue</quote>

1200

floppy-disk, such as <literal>tomsrtbt</literal>. Ignore this advice

1201

at your peril.</para></warning>

1202

1203

<para>This usually involves changing the line:</para>

1204

<screen>id:3:initdefault:</screen>

1205

1206

<screen>id:5:initdefault:</screen>

1207

1208

<para>When you reboot your system, you should end up with the

1209

graphical &kdm; login dialog.</para>

1210

1211

<para>If this step is unsuccessful the most likely problem is that the

1212

environment used at boot time differs from the environment that you used for

1213

testing at the command line. If you are trying to get two versions of &kde;

1214

to co-exist, be particularly careful that the settings you use for your

1215

<envar>PATH</envar> and <envar>LD_LIBRARY_PATH</envar> environment variables

1216

are consistent, and that the startup scripts are not over-riding them in

1217

some way.</para>

1218

1219

</sect1>

1220

1221

</chapter>

1222

1223

1224

<title>Supporting multiple window managers</title>

1225

1226

<para>&kdm; detects most available window managers and desktop environments when

1227

it is run. Installing a new one should make it automatically available in

1228

the &kdm; main dialog's <guimenuitem>Session Type</guimenuitem> submenu.</para>

1229

1230

<para>If you have a very new window manager, or something that &kdm; does

1231

not support, the first thing you should check is that the executable to be

1232

run is in the <envar>PATH</envar> and has not been renamed by the distributor

1233

into something unexpected.</para>

1234

1235

<para>If the case is that the session type is not supported by &kdm; yet

1236

(maybe because it is too new), you can quite easily add it.</para>

1237

1238

<para>The session types are defined by <firstterm>.desktop</firstterm> files

1239

located in the directories listed in <link

1240

linkend="option-sessionsdirs"><option>SessionsDirs</option></link>. The

1241

last named directory contains the system-provided default session types

1242

and is <filename

1243

class="directory">$<envar>KDEDIR</envar>/share/apps/kdm/sessions</filename>

1244

in an installation from source. Software upgrades will typically overwrite

1245

anything in here, so it is unwise to use it for configuration purposes.

1246

Instead, a separate configuration directory should be listed first. It is

1247

set to <filename

1248

class="directory">$<envar>KDEDIR</envar>/share/config/kdm/sessions</filename>

1249

in an installation from source, but distributors often change it to something

1250

like <filename class="directory">/etc/kde4/kdm/sessions</filename>.

1251

You can simply add an appropriately named <literal

1252

role="extension">.desktop</literal> files here. The fields are:</para>

1253

1254

<programlisting>[Desktop Entry]

1255

Encoding=UTF-8 <lineannotation>This is fixed to <option>UTF-8</option> and

1256

may be omitted</lineannotation>

1257

Type=XSession <lineannotation>This is fixed to <option>XSession</option> and

1258

may be omitted</lineannotation>

1259

Exec=<replaceable>executable name</replaceable> <lineannotation>Passed to

1260

<command>eval exec</command> in a Bourne shell</lineannotation>

1261

TryExec=<replaceable>executable name</replaceable> <lineannotation>Supported

1262

but not required</lineannotation>

1263

Name=<replaceable>name to show in the &kdm; session list</replaceable></programlisting>

1264

1265

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

1266

1267

1268

1269

<term>default</term>

1270

1271

<para>

1272

The default session for &kdm; is normally &kde; but can be configured by the

1273

system administrator.

1274

</para>

1275

</listitem>

1276

</varlistentry>

1277

1278

<term>custom</term>

1279

1280

<para>

1281

The Custom session will run the user's ~/.xsession if it exists, falling

1282

back to the default session otherwise.

1283

</para>

1284

</listitem>

1285

</varlistentry>

1286

1287

<term>failsafe</term>

1288

1289

<para>

1290

Failsafe will run a very plain session, and is useful only for debugging

1291

purposes.

1292

</para>

1293

</listitem>

1294

</varlistentry>

1295

</variablelist>

1296

1297

<para>To override a session type, copy the .desktop file from the data dir

1298

to the config dir and edit it at will. Removing the shipped session types

1299

can be accomplished by <quote>shadowing</quote> them with .desktop files

1300

containing Hidden=true. For the magic session types no .desktop files exist

1301

by default, but &kdm; pretends they would, so you can override them like any

1302

other type.</para>

1303

1304

</chapter>

1305

1306

1307

<title>Using &kdm; for Remote Logins (&XDMCP;)</title>

1308

1309

<para>&XDMCP; is the Open Group standard, the <quote>X Display Manager

1310

Control Protocol</quote>. This is used to set up connections between

1311

remote systems over the network.</para>

1312

1313

<para>&XDMCP; is useful in multiuser situations where there are users

1314

with workstations and a more powerful server that can provide the

1315

resources to run multiple X sessions. For example, &XDMCP; is a good

1316

way to reuse old computers - a Pentium or even 486 computer with 16 Mb

1317

RAM is sufficient to run X itself, and using &XDMCP; such a computer can

1318

run a full modern &kde; session from a server. For the server part,

1319

once a single &kde; (or other environment) session is running, running

1320

another one requires very few extra resources.</para>

1321

1322

<para>However, allowing another method of login to your machine

1323

obviously has security implications. You should run this service only

1324

if you need to allow remote X Servers to start login sessions on your

1325

system. Users with a single &UNIX; computer should not need to run

1326

this.</para>

1327

1328

</chapter>

1329

1330

1331

<title>Advanced Topics</title>

1332

1333

1334

<title>Command Sockets</title>

1335

1336

<para>This is a feature you can use to remote-control &kdm;. It's mostly

1337

intended for use by &ksmserver; and &kdesktop; from a running session, but

1338

other applications are possible as well.</para>

1339

1340

<para>The sockets are &UNIX; domain sockets which live in subdirectories of the

1341

directory specified by <option>FifoDir</option>=. The subdir is the key to

1342

addressing and security; the sockets all have the file name

1343

<filename>socket</filename> and file permissions

1344

<literal>rw-rw-rw-</literal> (0666). This is because some systems don't care

1345

for the file permission of the socket files.</para>

1346

1347

<para>There are two types of sockets: the global one (dmctl) and the

1348

per-display ones (dmctl-<display>).</para>

1349

1350

<para>The global one's subdir is owned by root, the subdirs of the per-display

1351

ones' are owned by the user currently owning the session (root or the

1352

logged in user). Group ownership of the subdirs can be set via FifoGroup=,

1353

otherwise it's root. The file permissions of the subdirs are rwxr-x---

1354

(0750).</para>

1355

1356

<para>The fields of a command are separated by tabs (<token>\t</token>), the

1357

fields of a list are separated by spaces, literal spaces in list fields are

1358

denoted by <token>\s</token>.</para>

1359

1360

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

1361

1362

<para>The same applies to replies. The reply on success is

1363

<returnvalue>ok</returnvalue>, possibly followed by the requested

1364

information. The reply on error is an errno-style word (&eg;

1365

<returnvalue>perm</returnvalue>, <returnvalue>noent</returnvalue>, &etc;)

1366

followed by a longer explanation.</para>

1367

1368

1369

<title>Global commands:</title>

1370

1371

1372

<term><command>login</command> <option>display</option>

1373

(<parameter>now</parameter> | <parameter>schedule</parameter>) <parameter>user</parameter> <parameter>password</parameter>

1374

[session_arguments]</term>

1375

1376

<para>login user at specified display. if <parameter>now</parameter> is

1377

specified, a possibly running session is killed, otherwise the login is done

1378

after the session exits. session_arguments are printf-like escaped contents

1379

for .dmrc. Unlisted keys will default to previously saved values.</para>

1380

</listitem>

1381

</varlistentry>

1382

1383

1384

<term><command>resume</command></term>

1385

1386

<para>Force return from console mode, even if TTY logins are still

1387

active.</para>

1388

</listitem>

1389

</varlistentry>

1390

1391

1392

<term><command>manage</command> <parameter>display</parameter>

1393

[<parameter>display_class</parameter>

1394

[<parameter>auth_name</parameter> <parameter>auth_data</parameter>]]</term>

1395

1396

<para>Start managing the named foreign display.</para>

1397

<para><parameter>display_class</parameter>, if specified and non-empty,

1398

will be used for configuration matching; see <xref linkend="kdm-files"/>.

1399

</para>

1400

1401

need to be passed if the display requires X authorization. The format is

1402

the same as the 2nd and 3rd column of the <command>xauth list</command>

1403

output.</para>

1404

</listitem>

1405

</varlistentry>

1406

1407

1408

<term><command>unmanage</command> <parameter>display</parameter></term>

1409

1410

<para>Stop managing the named foreign display.</para>

1411

</listitem>

1412

</varlistentry>

1413

1414

</variablelist>

1415

1416

1417

<title>Per-display commands:</title>

1418

1419

1420

1421

<para>The display is marked as locked. If the &X-Server; crashes in this

1422

state, no auto-relogin will be performed even if the option is on.</para>

1423

</listitem>

1424

</varlistentry>

1425

1426

<term><command>unlock</command></term>

1427

1428

<para>Reverse the effect of <command>lock</command>, and re-enable

1429

auto-relogin.</para>

1430

</listitem>

1431

</varlistentry>

1432

1433

<term><command>suicide</command></term>

1434

1435

<para>The currently running session is forcibly terminated. No auto-relogin

1436

is attempted, but a scheduled "login" command will be executed.</para>

1437

</listitem>

1438

</varlistentry>

1439

</variablelist>

1440

1441

1442

<title>Commands for all sockets</title>

1443

1444

1445

1446

1447

<para>Returns a list of this socket's capabilities:</para>

1448

1449

1450

1451

1452

1453

<para>identifies &kdm;, in case some other DM implements this protocol,

1454

too</para>

1455

</listitem>

1456

</varlistentry>

1457

1458

<term><returnvalue>list</returnvalue>, <returnvalue>lock</returnvalue>,

1459

<returnvalue>suicide</returnvalue>, <returnvalue>login</returnvalue>,

1460

<returnvalue>resume</returnvalue>, <returnvalue>manage</returnvalue>

1461

</term>

1462

1463

<para>The respective command is supported</para>

1464

</listitem>

1465

</varlistentry>

1466

1467

<term><returnvalue>bootoptions</returnvalue></term>

1468

1469

<para>The <command>listbootoptions</command> command and the

1470

<option>=</option> to <command>shutdown</command> are supported</para>

1471

</listitem>

1472

</varlistentry>

1473

1474

<term><returnvalue>shutdown <list></returnvalue></term>

1475

1476

<para><command>shutdown</command> is supported and allowed for the listed

1477

users (a comma separated list.) <returnvalue>*</returnvalue> means all

1478

authenticated users.</para>

1479

</listitem>

1480

</varlistentry>

1481

1482

1483

1484

<para>Forced shutdown may be performed by the listed users.</para>

1485

</listitem>

1486

</varlistentry>

1487

1488

1489

1490

<para>Forced shutdown may be performed by everybody</para>

1491

</listitem>

1492

</varlistentry>

1493

1494

<term><returnvalue>reserve <number></returnvalue></term>

1495

1496

<para>Reserve displays are configured, and <returnvalue>number</returnvalue>

1497

are available at this time</para>

1498

</listitem>

1499

</varlistentry>

1500

</variablelist>

1501

1502

</listitem>

1503

</varlistentry>

1504

1505

1506

<term><command>list</command> [<parameter>all</parameter> |

1507

<parameter>alllocal</parameter>]</term>

1508

1509

<para>Return a list of running sessions. By default all active sessions are

1510

listed (this is useful for a shutdown warning). If <parameter>all</parameter>

1511

is specified, passive sessions are listed as well.

1512

If <parameter>alllocal</parameter> is specified, passive

1513

sessions are listed as well, but all incoming remote sessions are

1514

skipped (this is useful for a fast user switching agent).</para>

1515

<para>Each session entry is a comma separated tuple of:</para>

1516

1517

<listitem><para>Display or TTY name</para></listitem>

1518

<listitem><para>VT name for local sessions, remote host name prefixed by

1519

<literal>@</literal> for remote TTY sessions, otherwise empty</para></listitem>

1520

<listitem><para>Logged in user's name, empty for passive sessions and

1521

outgoing remote sessions (local chooser mode)</para></listitem>

1522

<listitem><para>Session type for active local sessions, remote hostname for

1523

outgoing remote sessions, empty for passive sessions.</para></listitem>

1524

<listitem><para>A Flag field:</para>

1525

<itemizedlist><listitem><para><literal>*</literal> for the display belonging

1526

to the requesting socket.</para></listitem>

1527

<listitem><para><literal>!</literal> for sessions that cannot be killed by the

1528

requesting socket.</para></listitem>

1529

<listitem><para><literal>t</literal> for TTY sessions.</para></listitem>

1530

</itemizedlist>

1531

</listitem>

1532

</itemizedlist>

1533

<para>New fields may be added in the future.</para>

1534

</listitem>

1535

</varlistentry>

1536

1537

1538

<term><command>reserve</command></term>

1539

1540

<para>Start a reserve login screen. If nobody logs in within some

1541

time, the display is removed again. When the session on the display

1542

exits, the display is removed, too.</para>

1543

<para>Permitted only on sockets of local displays and the global

1544

socket.</para>

1545

</listitem>

1546

</varlistentry>

1547

1548

1549

<term><command>activate</command>

1550

(<parameter>vt</parameter>|<parameter>display</parameter>)</term>

1551

1552

<para>Switch to a particular VT (virtual terminal). The VT may be specified

1553

either directly (&eg; <parameter>vt3</parameter>) or by a display using it

1554

(eg; <parameter>:2</parameter>).</para>

1555

<para>Permitted only on sockets of local displays and the global

1556

socket.</para>

1557

</listitem>

1558

</varlistentry>

1559

1560

1561

<term><command>listbootoptions</command></term>

1562

1563

<para>List available boot options.</para>

1564

<para>The return value contains these tokens:</para>

1565

1566

1567

<para>A list of boot options (as shown in &kdm; itself).</para>

1568

</listitem>

1569

1570

<para>The default boot option.</para>

1571

</listitem>

1572

1573

<para>The current boot option.</para>

1574

</listitem>

1575

</itemizedlist>

1576

<para>The default and current option are zero-based indices into the list

1577

of boot options. If either one is unset or not determinable, it is -1.</para>

1578

</listitem>

1579

</varlistentry>

1580

1581

1582

<term><command>shutdown</command> (<parameter>reboot</parameter> |

1583

<parameter>halt</parameter>)

1584

[<parameter>=<replaceable>bootchoice</replaceable></parameter>]

1585

(<parameter>ask</parameter>|<parameter>trynow</parameter>|<parameter>forcenow</parameter>|<parameter>schedule</parameter>|<parameter>start

1586

(<parameter>-1</parameter>|<parameter>end

1587

(<parameter>force</parameter>|<parameter>forcemy</parameter>|<parameter>cancel)</parameter>)</parameter>)</parameter>)</term>

1588

1589

<para>Request a system shutdown, either a reboot or a halt/poweroff.</para>

1590

<para>An OS choice for the next boot may be specified from the list returned

1591

by <command>listbootoptions</command></para>

1592

<para>Shutdowns requested from per-display sockets are executed when the

1593

current session on that display exits. Such a request may pop up a dialog

1594

asking for confirmation and/or authentication</para>

1595

<para><parameter>start</parameter> is the time for which the shutdown is

1596

scheduled. If it starts with a plus-sign, the current time is added. Zero

1597

means immediately.</para>

1598

<para><parameter>end</parameter> is the latest time at which the shutdown

1599

should be performed if active sessions are still running. If it starts with

1600

a plus-sign, the start time is added. -1 means wait infinitely. If end is

1601

through and active sessions are still running, &kdm; can do one of the

1602

following:</para>

1603

1604

<listitem><para><parameter>cancel</parameter> - give up the

1605

shutdown</para></listitem>

1606

<listitem><para><parameter>force</parameter> - shut down

1607

nonetheless</para></listitem>

1608

<listitem><para><parameter>forcemy</parameter> - shut down nonetheless if

1609

all active sessions belong to the requesting user.

1610

Only for per-display sockets.</para></listitem>

1611

</itemizedlist>

1612

<para><parameter>start</parameter> and <parameter>end</parameter> are

1613

specified in seconds since the &UNIX; epoch.</para>

1614

<para><parameter>trynow</parameter> is a synonym for <parameter>0 0

1615

cancel</parameter>, <parameter>forcenow</parameter> for <parameter>0 0

1616

force</parameter> and <parameter>schedule</parameter> for <parameter>0

1617

-1</parameter>.</para>

1618

<para><parameter>ask</parameter> attempts an immediate shutdown and

1619

interacts with the user if active sessions are still running. Only for

1620

per-display sockets.</para>

1621

</listitem>

1622

</varlistentry>

1623

1624

1625

<term><command>shutdown cancel</command>

1626

[<parameter>local</parameter>|<parameter>global</parameter>}</term>

1627

1628

<para>Cancel a scheduled shutdown. The global socket always cancels the

1629

currently pending shutdown, while per-display sockets default to cancelling

1630

their queued request.</para>

1631

</listitem>

1632

</varlistentry>

1633

1634

1635

<term><command>shutdown status</command></term>

1636

1637

<para>Return a list with information about shutdowns.</para>

1638

<para>The entries are a comma-separated tuples of:</para>

1639

1640

1641

<para>(<returnvalue>global</returnvalue>|<returnvalue>local</returnvalue>) -

1642

pending vs. queued shutdown. A local entry can be returned only by a

1643

per-display socket.</para>

1644

</listitem>

1645

<listitem><para>(<returnvalue>halt</returnvalue>|<returnvalue>reboot</returnvalue>)</para></listitem>

1646

<listitem><para>start</para></listitem>

1647

1648

<listitem><para>("ask"|"force"|"forcemy"|"cancel")</para></listitem>

1649

<listitem><para>Numeric user ID of the requesting user, -1 for the global

1650

socket.</para></listitem>

1651

<listitem><para>The next boot OS choice or "-" for none.</para></listitem>

1652

</itemizedlist>

1653

<para>New fields might be added later</para>

1654

</listitem>

1655

</varlistentry>

1656

1657

</variablelist>

1658

1659

<para>There are two ways of using the sockets:</para>

1660

1661

1662

<para>Connecting them directly. FifoDir is exported as

1663

$<envar>DM_CONTROL</envar>; the name of per-display sockets can be derived

1664

from $<envar>DISPLAY</envar>.</para>

1665

</listitem>

1666

1667

<para>By using the <command>kdmctl</command> command (&eg; from within a

1668

shell script). Try <command>kdmctl</command> <option>-h</option> to find out

1669

more.</para>

1670

</listitem>

1671

</itemizedlist>

1672

1673

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

1674

1675

<programlisting>if kdmctl | grep -q shutdown; then

1676

IFS=$'\t'

1677

set -- `kdmctl listbootoptions`

1678

if [ "$1" = ok ]; then

1679

fbsd=$(echo "$2" | tr ' ' '\n' | sed -ne 's,\\s, ,g;/freebsd/I{p;q}')

1680

if [ -n "$fbsd" ]; then

1681

kdmctl shutdown reboot "=$fbsd" ask > /dev/null

1682

else

1683

echo "FreeBSD boot unavailable."

1684

1685

else

1686

echo "Boot options unavailable."

1687

1688

else

1689

echo "Cannot reboot system."

1690

fi</programlisting>

1691

1692

</sect1>

1693

</chapter>

1694

1695

1696

<title>Other sources of information</title>

1697

1698

<para>Since &kdm; is descended from &xdm;, the <ulink

1699

url="man:xdm">xdm man page</ulink> may provide useful background

1700

information. For X-related problems try the man pages <ulink

1701

url="man:X">X</ulink> and <ulink url="man:startx">startx</ulink>. If you have

1702

questions about &kdm; that are not answered by this handbook, take advantage of

1703

the fact the &kdm; is provided under the terms of the &GNU;

1704

General Public License: look at the source code.

1705

</para>

1706

1707

</chapter>

1708

1709

1710

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

1711

1712

<para>&kdm; is derived from, and includes code from,

1713

1714

1715

<para>&kdm; 0.1 was written by &Matthias.Ettrich;. Later versions till &kde;

1716

2.0.x were written by &Steffen.Hansen;. Some new features for &kde; 2.1.x and

1717

a major rewrite for &kde; 2.2.x made by &Oswald.Buddenhagen;.</para>

1718

1719

<para>Other parts of the &kdm; code are copyright by the authors, and

1720

licensed under the terms of the <ulink url="common/gpl-license.html">&GNU;

1721

GPL</ulink>. Anyone is allowed to change &kdm; and redistribute the result

1722

as long as the names of the authors are mentioned.</para>

1723

1724

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

1725

1726

<para>Documentation contributors:

1727

1728

1729

<listitem><para>Documentation written by &Steffen.Hansen;

1730

&Steffen.Hansen.mail;</para></listitem>

1731

1732

<listitem><para>Documentation extended by Gregor

1733

Zumstein<email>zumstein@ssd.ethz.ch</email>. Last update August 9,

1734

1998</para></listitem>

1735

1736

<listitem><para>Documentation revised for &kde; 2 by &Neal.Crook;

1737

&Neal.Crook.mail;. Last update August 6,

1738

2000</para></listitem>

1739

1740

<listitem><para>Documentation extended and revised for &kde; 2.2 and 4.0 by

1741

&Oswald.Buddenhagen; &Oswald.Buddenhagen.mail;. Last update December 7,

1742

2007</para></listitem>

1743

1744

</itemizedlist></para>

1745

1746

<para>Documentation copyright &Steffen.Hansen;, Gregor Zumstein, &Neal.Crook;

1747

and &Oswald.Buddenhagen;.

1748

This document also includes large parts of the &xdm; man page,

1749

1750

The theme format documentation is heavily based on the GDM manual,

1751

1752

Sun Microsystems, Inc.</para>

1753

1754

1755

1756

&underFDL;

1757

1758

</chapter>

1759

1760

1761

<title>Glossary</title>

1762

1763

1764

<glossterm>greeter</glossterm>

1765

<glossdef><para>The greeter is the login dialog, &ie; the part of &kdm;

1766

which the user sees.</para>

1767

</glossdef>

1768

</glossentry>

1769

1770

1771

<glossterm id="gloss-entropy">entropy</glossterm>

1772

<glossdef><para>The entropy of a system is the measure of its

1773

unpredictability. This is used during the generation of random numbers.</para>

1774

</glossdef>

1775

</glossentry>

1776

1777

</glossary>

1778

</book>

1779

<!--

1780

Local Variables:

1781

mode: xml

1782

sgml-omittag: nil

1783

sgml-shorttag: t

1784

End:

1785

-->

1786

Older »