Blu256: fix formatting

2023-12-18T11:27:38Z

fix formatting

Blu256: Add page about TDM (Remote login via XDMCP + some technical info from the README file)

2023-12-18T11:26:19Z

Add page about TDM (Remote login via XDMCP + some technical info from the README file)

New page

''TDM'' is the default graphical display manager of the Trinity Desktop Environment. It handles local and remote logins on a machine.

__TOC__

== Remote login ==
Remote login can be performed via the XDMCP protocol. Due to security concerns, the XDMCP host component is disabled by default in TDM (but you can still connect to XDMCP hosts as a client).

{{WarningBox|text=ArchWiki on the matter of [https://wiki.archlinux.org/title/XDMCP XDMCP]:
''XDMCP is, similarly to telnet, doing unencrypted authentication. If snooping is possible, this leaves the system vulnerable to attack. It is disabled by default, using an ssh tunnel for X traffic is preferred.''
As a matter of fact, you should only use it in a completely trusted and controlled environment.
}}

To be able to login into a machine remotely you should edit the <tt>tdmrc</tt> file. Find the section titled <tt>[Xdmcp]</tt> and set the <tt>Enable</tt> key to <tt>true</tt>. Then, restart the tdm service.

On the remote side select "Remote login" from the options menu of the TDM login screen. You should be presented with a dialog of the remote machines to which you can connect via XDMCP. If you don't see the machine you want to connect to in the list, enter its IP address and press "Add". It should appear in the list.

By default a host might not allow remote connections despite being open for XDMCP requests. In XDMCP terminology, the host must be "Willing" to accept the remote connection. If you see "Display not authorized to connect" in the remote login dialog next to the address/hostname of the machine you want to connect to, you have to configure which hosts are allowed to connect to the machine. Follow the instructions in the <tt>Xaccess</tt> file (it should be in the same directory as <tt>tdmrc</tt>) to set up authorized hosts. After that, restart TDM and repeat the process.

When you select the desired host in the remote login menu and press "Connect", assuming the configuration is correct, you will be presented with the login screen of the host you are trying to connect to. If you see the local login screen again, then something has gone wrong. Ensure you have configured both instances of TDM according to the above instructions.

== Technical details ==

=== TDM's file system layout ===

* <span style='color: darkorange'><tt>${tde_confdir}</tt> is usually <tt>${prefix}/share/config</tt></span>
* <span style='color: darkorange'><tt>${tde_datadir}</tt> is usually <tt>${prefix}/share/apps</tt></span>
* <tt>${tde_confdir}/tdm/{tdmrc,Xservers,Xaccess,Xwilling,...}</tt>
* <tt>${tde_datadir}/tdm/sessions/*.desktop</tt>
* <tt>/etc/X11/sessions/,/usr/share/xsessions/</tt>
* <tt>${tde_datadir}/tdm/pics/users/</tt>
* <tt>${tde_datadir}/tdm/pics/</tt>
* <tt>${tde_datadir}/tdm/faces/*.face{,.icon}</tt>
* <tt>/usr/share/faces/</tt>
* <tt>/var/run/xauth/A*</tt>
* <tt>/var/run/xdmctl/xdmctl*</tt>
* <tt>/var/run/tdm.pid</tt>
* <tt>/var/lib/tdm/tdmsts</tt>
* <tt><site-specific>/*.dmrc</tt>
* <tt>$HOME/.face{,.icon}</tt>
* <tt>$HOME/.dmrc</tt>

=== How to setup TDM ===

TDM's config files are all located in <tt>${tde_confdir}/tdm</tt>. "make install" will create a probably working configuration, either by deriving it from an already present TDM/XDM installation or by using defaults if no previous installation is found.

You can change the configuration from the Trinity Control Center. You will find the "Login Manager" module in the "System Administration" group.

Have a look at <tt>README.pam</tt> in the <tt>tdebase</tt> top level directory if your system uses PAM.

=== Configuring session types ===
Session types are represented by .desktop files in appropriate locations. The format of the .desktop files is (not yet) defined in the FreeDesktop.org desktop entry spec. Differences to "standard" .desktop files are:
* the <code>Type</code> is fixed to <tt>XSession</tt> and can be omitted.
* the <code>Encoding</code> is fixed to <tt>UTF-8</tt> and can be omitted.
* the <code>Exec</code> field will be passed to <tt>"eval exec"</tt> in a bourne shell; no macro expansion is performed on it. "default", "custom" and "failsafe" are magic constants that cause special actions.
* <code>Name</code>, <code>Comment</code>, <code>TryExec</code> and <code>Hidden</code> are supported.
* the remaining keys have no meaning currently.

Session types are internally identified by filename (without extension); that's what will be saved to <tt>~/.dmrc</tt> and what DESKTOP_SESSION will be set to. For every magic <code>Exec</code> constant a session type of the same name exists.

Unless your system is configured differently already, you should create a directory <tt>${tde_confdir}/tdm/sessions</tt> and add this to <tt>tdmrc</tt>:

<syntaxhighlight lang="ini">
[X-*-Core]
SessionsDirs=${tde_confdir}/tdm/sessions,${tde_datadir}/tdm/sessions
</syntaxhighlight>

{{WarningBox|text=Always keep in mind the following:
* You must use actual paths instead of variables, see the section about TDM's file system layout.
* Do any changes only in the config directory - any changes in the data directory will be lost after the next TDE update.}}

To override a session type, copy the .desktop file from the data directory to the config directory and edit it at will. Removing the shipped session types can be accomplished by "shadowing" them with .desktop files containing <code>Hidden=true</code>.

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.

=== The command sockets ===
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.

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

There are two types of sockets: the global one (<tt>dmctl</tt>) and the per-display ones (<tt>dmctl-<display></tt>).

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 <code>FifoGroup=</code>, otherwise it's root. The file permissions of the subdirs are <tt>rwxr-x---</tt> (0750).

The fields of a command are separated by tabs (\t), the fields of a list are separated by spaces, literal spaces in list fields are denoted by "<tt>\s</tt>". The command is terminated by a newline (<tt>\n</tt>). The same applies to replies. The reply on success is "<tt>ok</tt>", possibly followed by the requested information. The reply on error is an errno-style word (e.g., "<tt>perm</tt>", "<tt>noent</tt>", etc.) followed by a longer explanation.

==== Global commands ====

{|class="wikitable"
|-
| <syntaxhighlight lang="shell">login {display} ("now"|"schedule") {user} {password} [session_arguments]</syntaxhighlight>
| Login user at specified display. if "now" is specified, a possibly running session is killed, otherwise the login is done after the session exits.
<tt>session_arguments</tt> are printf-like escaped contents for <tt>.dmrc</tt>. Unlisted keys will default to previously saved values.
|}

==== Per-display commands ====

{|class="wikitable"
|-
| <syntaxhighlight lang="shell">lock</syntaxhighlight>
| 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.
|-
| <syntaxhighlight lang="shell">unlock</syntaxhighlight>
| Reverse the effect of "lock": re-enable auto-relogin.
|-
| <syntaxhighlight lang="shell">suicide</syntaxhighlight>
| The currently running session is forcibly terminated. No auto-relogin is attempted, but a scheduled "login" command will be executed.
|}

==== Commands for all sockets ====

{|class="wikitable"
|-
| <syntaxhighlight lang="shell">caps</syntaxhighlight>
| Returns a list this socket's capabilities:
{|
|<code>tdm</code>
| identifies tdm, in case some other DM implements this protocol, too
|-
| <code>list</code>, <code>activate</code>, <code>lock</code>, <code>suicide</code>, <code>login</code>
| whether the respective command is supported
|-
| <code>bootoptions</code>
| whether the <tt>listbootoptions</tt> command and the "=" option to "<tt>shutdown</tt>" are supported
|-
| <code>shutdown {list}</code>
| whether "shutdown" is supported and allowed to the listed users (comma-separated), "*" means all authenticated users
|-
| <code>shutdown</code>
| whether "shutdown" is supported and allowed to everybody
|-
| <code>nuke {list}</code>
| whether forced shutdown is allowed to the listed users
|-
| <code>nuke</code>
| whether forced shutdown is allowed to everybody
|-
| <code>reserve {number}</code>
| whether reserve displays are configured and <number> are available at this time
|}
|-
| <syntaxhighlight lang="shell">list [all|alllocal]</syntaxhighlight>
| Return a list of running sessions. By default all active sessions are listed.

If "<tt>all</tt>" is specified, passive sessions are listed as well.

If "<tt>alllocal</tt>" is specified, passive sessions are listed as well, but all incoming remote sessions are skipped.

Each session entry is a comma-separated tuple of:
* Display or TTY name
* VT name for local sessions
* Logged in user's name, empty for passive sessions and outgoing remote sessions (local chooser mode)
* Session type or remote host for outgoing remote sessions, empty for passive sessions
* A flag field:
** "t" for tty sessions
** "*" for the display belonging to the requesting socket
** "!" for sessions that cannot be killed by the requesting socket
|-
| <syntaxhighlight lang="shell">reserve [timeout in seconds]</syntaxhighlight>
| 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.
Permitted only on sockets of local displays and the global socket.
|-
| <syntaxhighlight lang="shell">activate (vt|display)</syntaxhighlight>
| Switch to a particular VT (virtual terminal). The VT may be specified either directly (e.g., vt3) or by a display using it (e.g., :2).
Permitted only on sockets of local displays and the global socket.
|-
| <syntaxhighlight lang="shell">listbootoptions</syntaxhighlight>
| List available boot options.
=> "ok" list default current
*default and current are indices into the list and are -1 if unset or undeterminable.
|-
| <syntaxhighlight lang="shell">shutdown (reboot|halt)[={bootchoice}] (ask|trynow|forcenow|schedule|start (-1|end (force|forcemy|cancel)))</syntaxhighlight>
| Request a system shutdown, either a reboot or a halt/poweroff.
An OS choice for the next boot may be specified from the list returned by "listbootoptions".

Shutdowns requested from per-display sockets are executed when the current session on that display exits. Such a request may pop up a dialog asking for confirmation and/or authentication.

* <tt>start</tt> is the time for which the shutdown is scheduled. If it starts with a plus-sign, the current time is added. Zero means immediately.
* <tt>end</tt> 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. Minus one means wait infinitely. If end is through and active sessions are still running, TDM can do one of the following:
** <tt>cancel</tt> - give up the shutdown.
** <tt>force</tt> - shut down nonetheless.
** <tt>forcemy</tt> - shut down nonetheless if all active sessions belong to the requesting user. Only for per-display sockets.
* <tt>trynow</tt> is a synonym for "0 0 cancel", <tt>forcenow</tt> for "0 0 force" and <tt>schedule</tt> for "0 -1".
* <tt>ask</tt> attempts an immediate shutdown and interacts with the user if active sessions are still running. Only for per-display sockets.
* <tt>start</tt> and end are specified in seconds since the UNIX epoch.
|-
| <syntaxhighlight lang="shell">shutdown cancel [local|global]</syntaxhighlight>
| Cancel a scheduled shutdown. The global socket always cancels the currently pending shutdown, while per-display sockets default to cancelling their queued request.
|-
| <syntaxhighlight lang="shell">shutdown status</syntaxhighlight>
| Return a list with information about shutdowns.
The entries are comma-separated tuples of:
* ("global"|"local") - pending vs. queued shutdown. A local entry can be returned only by a per-display socket.
* ("halt"|"reboot")
* start
* end
* ("ask"|"force"|"forcemy"|"cancel")
* Numeric user ID of the requesting user, -1 for the global socket.
* The next boot OS choice or "-" for none.
|}

There are two ways of using the sockets:
* Connecting them directly. FifoDir is exported as $DM_CONTROL; the name of per-display sockets can be derived from $DISPLAY.
* By using the <tt>tdmctl</tt> command (e.g., from within a shell script). Try "<tt>tdmctl -h</tt>" to find out more.

Here is an example bash script "reboot into FreeBSD":

<syntaxhighlight lang="shell">
if tdmctl | grep -q shutdown; then
IFS=$'\t'
set -- `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 > /dev/null
else
echo "FreeBSD boot unavailable."
fi
else
echo "Boot options unavailable."
fi
else
echo "Cannot reboot system."
fi
</syntaxhighlight>

== Troubleshooting ==
TDM accepts two command line options related to logging:

-debug <n>
<n> is a decimal or hexadecimal (prefix 0x) number.
The number is a bitfield, i.e., it is formed by summing up the
required values from this table:
1 (0x1) - core debugging. Probably the most useful one.
2 (0x2) - config reader debugging.
4 (0x4) - greeter debugging.
8 (0x8) - IPC debugging. This logs _all_ communication between the
core, the config reader and the greeter - including the
passwords you type, so edit the log before showing it to
somebody.
This attempts to synchronize the processes to interleave the
log messages optimally, but will probably fail unless you use
-debug 0x80 as well.
16 (0x10) - wait after forking session sub-daemon.
32 (0x20) - wait after starting config reader.
64 (0x40) - wait after starting greeter.
The wait options are only useful if you need to attach a debugger
to a process, but it crashes before you are able to do so without
the delay. See below.
128 (0x80) - don't use syslog for internally generated messages.
256 (0x100) - core Xauth debugging.
1024 (0x400) - run config reader and greeter through valgrind.
2048 (0x800) - run config reader and greeter through strace.

Logs from "-debug 7" are usually a good start.

-error <file>, -logfile <file>
<file> is the file to log various messages to. The default log file is
/var/log/tdm.log. For internal reasons there is no option in tdmrc to
permanently specify the log file location. If you redirect TDM's
standard error output to a file, TDM will log there.
If TDM is configured to use syslog (and it _very_ probably is on any
modern system), all internally generated messages are logged to the
"daemon" facility. The log usually can be found in /var/log/debug.log
and /var/log/daemon.log; make sure that daemon.* is logged (look at
/etc/syslog.conf).
If you have problems logging in and your system uses PAM (also quite
probable on modern systems), the "auth" and "authpriv" syslog facilities
are interesting, too.

When reporting bugs, send all the logs together with a detailed description of what you did and what happened. If your problem is related to a specific configuration, you should also attach a tar.gz archive of your TDM config directory.

=== Producing a backtrace ===
If a backtrace is requested from you and TDM didn't create one yet via the usual drkonqi procedure, you'll have to do that yourself. The keyphrase is "attaching gdb". How exactly this is done depends on the part that crashes:

==== Attaching gdb to the process ====
===== Master daemon =====
Actually you should never need to attach to it, as you can start it within the debugger already:

<syntaxhighlight lang="shell-session">
# gdb --args tdm -nodaemon -debug 7
(gdb) run
</syntaxhighlight>

===== Display subdaemon =====
Find (using ps) the process with a name like "-:0" (where :0 is actually the display this process is for). This process' PPID is the master daemon. Attach to it this way:

<syntaxhighlight lang="shell-session">
# gdb tdm <the PID you found>
(gdb) cont
</syntaxhighlight>

If the subdaemon crashes before you can attach, add 16 to the debug flags when you start TDM.

===== Config reader =====
You will have to add 32 to the debug flags almost certainly. The PPID will be the master daemon as well.

<syntaxhighlight lang="shell-session">
# gdb tdm_config $(pidof tdm_config)
(gdb) cont
</syntaxhighlight>

===== Greeter =====
If it's too fast, add 64 to -debug. The PPID will be the subdaemon.

<syntaxhighlight lang="shell-session">
# gdb tdm_greet $(pidof tdm_greet)
(gdb) cont
</syntaxhighlight>

The simplification with "pidof" works only if you have only one display, otherwise you have to find the PID manually (by using ps -fx).

==== Reproduce crash and create backtrace ====
Once you got gdb attached to the offending process, do whatever is needed to make it crash (probably nothing, if you had to use a delay parameter).

Once it crashed, gdb will tell you a signal name, like SIGSEGV - that's the first interesting part. Then you have to create the actual backtrace:

<syntaxhighlight lang="shell-session">
(gdb) bt
</syntaxhighlight>

The output of this command is interesting for the developer, so a backtrace might be useful even if nothing crashes, but instead hangs. In this case don't use "cont" after attaching, but use "bt" right away. If the process is already running, interrupt it with ctrl-c.

For obvious reasons you have to run gdb on a different virtual terminal than the X server. To get there, press alt-ctrl-f1 and log in as root. To switch to the X server's vt, press alt-ctrl-f7 (the exact function key may be different on your system). You may also use a remote login from a second machine. In any case it is advantageous to have mouse support on the debugging console for copying the backtrace.

Note that a backtrace is usually much more useful if the binary contains debugging info.

← Older revision		Revision as of 11:27, 18 December 2023
Line 1:		Line 1:
	''TDM'' is the default graphical display manager of the Trinity Desktop Environment. It handles local and remote logins on a machine.		'''TDM''' is the default graphical display manager of the Trinity Desktop Environment. It handles local and remote logins on a machine.

	__TOC__		__TOC__

TDM - Revision history

Blu256: fix formatting

Blu256: Add page about TDM (Remote login via XDMCP + some technical info from the README file)