<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
 <!ENTITY ktalkd "<application>ktalkd</application>">
]>
<book lang="en">

<bookinfo>
<title>The ktalkd Handbook</title>
<authorgroup>
<author>
<firstname>David</firstname>
<surname>Faure</surname>
<affiliation>
<address><email>faure@kde.org</email></address>
</affiliation>
</author>
</authorgroup>
<date>14/11/1998</date>
<releaseinfo>0.09.00</releaseinfo>
<abstract>
<para>This handbook describes ktalkd version 0.9.0</para>
</abstract>
<keywordset>
<keyword>KTALKD</keyword>
<keyword>kotalkd</keyword>
<keyword>talk</keyword>
<keyword>talkd</keyword>
<keyword>otalk</keyword>
<keyword>ntalk</keyword>
<keyword>ktalkdlg</keyword>
<keyword>kcmktalkd</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para><literal remap="tt">ktalkd</literal> is an enhanced talk daemon - a program to handle incoming talk requests,
announce them and allow you to respond to it using a talk client.</para>

<para>GLOSSARY : In this document, if somebody wants to talk to you, you are 
designated as the "callee".</para>

<para><literal remap="tt">ktalkd</literal> has the following features :</para>

<para><variablelist>
<varlistentry>
<term>KDE or not KDE</term>
<listitem>
<para>That is the question. :) More seriously, this means that
<literal remap="tt">ktalkd</literal> is able to be compiled with or without KDE support.
To use it without KDE, the compilation stage will detect if X or Qt 
or KDE is not installed, but you can force a non-KDE daemon if you 
use the configure option '--without-X'.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Answering machine</term>
<listitem>
<para>If the callee isn't logged on, or doesn't answer after
the second announcement, an answering machine is launched, takes the
message, and mails it to the callee.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Sound</term>
<listitem>
<para>If desired, a sound is played with the announcement.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>X Announce</term>
<listitem>
<para>If compiled with KDE installed, ktalkd will use
<emphasis remap="bf">ktalkdlg</emphasis>, a KDE dialog, for announcement.
If <emphasis remap="bf">ktalk</emphasis> is running, it will be asked to make the announcement 
itself. (New since 0.8.8).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Multiple displays annoucement</term>
<listitem>
<para>If you are logged remotely (e.g. with an
<literal remap="tt">"export DISPLAY=..."</literal> command), the X announcement will be made on
this display too. Answer on the one you want !
If you're also logged in a text terminal, and if you're NOT using xterms
(internal restriction), then you'll see a text announcement too, in case 
you're using the text terminal at the time of the announcement.  </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Forwarding   <emphasis remap="it">(New since 0.8.0)</emphasis></term>
<listitem>
<para>You can set up a forward to another user even to another host
if you're away. There are 3 different forwarding methods. See section 'Usage'.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Configuration</term>
<listitem>
<para>If ktalkd is compiled for KDE, it reads config from KDE config files,
the sitewide ($KDEDIR/share/config/ktalkdrc) and the user one, in its home directory.
The sitewide one has to be manually edited by the administrator, but there is now
a configuration dialog for the user one. It's called <emphasis remap="bf">kcmktalkd</emphasis> and can 
be found in the KDE Control Center after installing <literal remap="tt">ktalkd</literal>.
On non-KDE systems, <literal remap="tt">ktalkd</literal> will read /etc/talkd.conf.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Internationalization</term>
<listitem>
<para>Under KDE, the announcement will be in your language provided that
you set it in the KDE menus and that someone translated <emphasis remap="bf">ktalkdlg</emphasis> to your
language. The same goes for the configuration dialog, <emphasis remap="bf">kcmktalkd</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Support for otalk and ntalk   <emphasis remap="it">(New since 0.8.1)</emphasis></term>
<listitem>
<para>ktalkd now supports both protocols, even when forwarding. 
ktalk supports both protocols as well.</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>I hope you will enjoy this talk daemon,</para>

<para>David Faure</para>

<para><ulink url="mailto:faure@kde.org">faure@kde.org</ulink></para>
</chapter>

<chapter id="supportedplatforms">
<title>Supported Platforms</title>

<para><variablelist>
<varlistentry>
<term>RedHat Linux 5.x</term>
<listitem>
<para>My development platform. Fully tested on it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Other Linux, BSD</term>
<listitem>
<para>Should compile and run well.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Solaris</term>
<listitem>
<para>It won't work until somebody makes a replacement for snprintf. 
Of course, one should be able to install another libc to solve this...</para>
</listitem>
</varlistentry>
<varlistentry>
<term>AIX</term>
<listitem>
<para>I've heard about problems about localtime, ctime, and assorted functions.</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>I would be glad to receive comments about compiling and running <literal remap="tt">ktalkd</literal>
on those and other systems.</para>
</chapter>

<chapter id="installation">
<title>Installation</title>

<sect1 id="howtoobtainktalkd">
<title>How to obtain ktalkd</title>

<para><literal remap="tt">ktalkd</literal> is now a core application of the KDE project 
<ulink url="http://www.kde.org">http://www.kde.org</ulink>, part of the
<emphasis remap="bf">kdenetwork</emphasis> package.</para>

<para>But you can always download the latest <literal remap="tt">ktalkd</literal> from the main ftp site of the KDE project,
<ulink url="ftp://ftp.kde.org/pub/kde">ftp://ftp.kde.org/pub/kde</ulink> and from its mirrors.
It's usually found in <ulink url="ftp://ftp.kde.org/pub/kde/stable/latest/apps/network">ftp://ftp.kde.org/pub/kde/stable/latest/apps/network</ulink> </para>
</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>In order to successfully compile <literal remap="tt">ktalkd</literal>, you need the latest versions 
of the KDE libraries as well as the Qt C++ library. All required 
libraries as well as ktalkd itself can be found on 
<ulink url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>.</para>
</sect1>

<sect1 id="compilationandinstallation">
<title>Compilation and installation</title>

<para>In order to compile and install <literal remap="tt">ktalkd</literal> on your system, type the 
following in the base directory of the <literal remap="tt">ktalkd</literal> distribution:
<screen>% ./configure
% make
% make install
</screen>
</para>

<para>As <literal remap="tt">ktalkd</literal> is a daemon, <literal remap="tt">make install</literal> will require root privileges.</para>

<para>Don't forget to update /etc/inetd.conf.
For example, on a linux system, if kde is in /opt/kde, change the lines 
concerning talk and ntalk to :
<screen>talk   dgram   udp     wait    root    /usr/sbin/tcpd  /opt/kde/bin/kotalkd
ntalk  dgram   udp     wait    root    /usr/sbin/tcpd  /opt/kde/bin/ktalkd
</screen>

A script is provided, to make the necessary change automatically. 
Update your inetd.conf file just by running 
<screen>% ./post-install.sh
</screen>

Anyway, you'll have to <emphasis remap="bf">restart inetd</emphasis> after this.
On most Linux systems, do :
<screen>% killall -HUP inetd
</screen>
</para>

<para>Please inform me of any modification you had to undertake in order to
get <literal remap="tt">ktalkd</literal> to compile on your platform.</para>
</sect1>
</chapter>

<chapter id="usage">
<title>Usage</title>

<para>To use ktalkd, you need a talk client. The text-based <literal remap="tt">talk</literal> is available on 
most Unix systems. Try <literal remap="tt">talk your&lowbar;username</literal> to see what happens when you
receive a talk request. You can also try the answering machine the same way :
initiate a talk to yourself, ignore the announcement twice, and you'll see the
answering machine.</para>

<para>There is a talk client with a graphical interface for the KDE, <literal remap="tt">ktalk</literal>.
It's not yet shipped with KDE packages, but you can find it on
ftp://ftp.kde.org. It should be in
<ulink url="ftp://ftp.kde.org/pub/kde/stable/latest/apps/network">ftp://ftp.kde.org/pub/kde/stable/latest/apps/network</ulink></para>

<para>The announcement dialog box is trivial : respond or ignore.</para>

<para>The configuration dialog should be rather straight forward, except for setting up a
forward to another user (or even to another host).</para>

<sect1 id="choosingaforwardingmethod">
<title>Choosing a Forwarding Method</title>

<para>None is perfect, they all have pros (+) and cons (-).</para>

<para><emphasis remap="bf">FWA</emphasis> : Forward announcement only. Direct connection. Not recommended.
<itemizedlist>
<listitem>
<para>       (+) You know who the caller is, but</para>
</listitem>
<listitem>
<para>       (-) Caller will have to respond to an announcement from you. Annoying.</para>
</listitem>
<listitem>
<para>       (-) Don't use if you have an answering machine on your 'away' location.
(The answering machine can't popup an announcement, it would be confusing!)</para>
</listitem>
</itemizedlist>
</para>

<para><emphasis remap="bf">FWR</emphasis> : Forward all requests, changing info when necessary. Direct connection.
<itemizedlist>
<listitem>
<para>       (+) Caller won't know that you're away, but</para>
</listitem>
<listitem>
<para>       (-) You won't really know who the caller is - only his username, 
(so you might see "talk from Wintalk@my&lowbar;host")</para>
</listitem>
</itemizedlist>
</para>

<para><emphasis remap="bf">FWT</emphasis> : Forward all requests and take the talk. No direct connection.
<itemizedlist>
<listitem>
<para>       (+) Same as above, but also works if you and caller can't be in
direct contact one with the other (e.g. firewall).</para>
</listitem>
<listitem>
<para>       (+) You'll be told who's really talking to you when you accept the talk</para>
</listitem>
<listitem>
<para>       (-) But as in FWR, you won't know his machine name in the announcement</para>
</listitem>
</itemizedlist>
</para>

<para>In short, use <emphasis remap="bf">FWT</emphasis> it you want to use it behind a firewall (and if ktalkd
can access both networks), and <emphasis remap="bf">FWR</emphasis> otherwise.</para>
</sect1>
</chapter>

<chapter id="questionsandanswers">
<title>Questions and Answers</title>

<sect1 id="whydoesntrootreceivekdeannouncements">
<title>Why Doesn't Root Receive KDE Announcements ?</title>

<para>Because this would be security hole, with the current user detection.
You can bypass the limitation by adding two lines in xdm config files
(which are the same than kdm ones).
Note : the S.u.S.E linux distribution includes those lines by default.</para>

<para>Those config files are normally in a directory such as /etc/X11/xdm,
or /usr/X11R6/lib/X11/xdm on other systems. The following supposes
that they are in /etc/X11/xdm, so you might have to translate them
for another directory.</para>

<para>Here is what you have to do :
Edit the file Xstartup, or create it, (in the xdm config directory) so that it reads :
<screen>#!/bin/sh
/etc/X11/xdm/GiveConsole
sessreg -a -l $DISPLAY -x /etc/X11/xdm/Xservers $USER
</screen>
</para>

<para>and the file Xreset so that it reads :
<screen>#!/bin/sh
/etc/X11/xdm/TakeConsole
sessreg -d -l $DISPLAY $USER   
</screen>
</para>

<para>Make sure that <emphasis remap="bf">xdm-config</emphasis> make reference to those two
files:
<screen>DisplayManager._0.startup:      /etc/X11/xdm/Xstartup
DisplayManager._0.reset:        /etc/X11/xdm/Xreset 
</screen>
</para>

<para>This will make kdm (or xdm) log the user into utmp, which is the right 
thing to do. It's not up to kvt, nor xterm, to log the user, but to
xdm and kdm, in my opinion. However, this will not log the user as a X 
user when using startx... Any hint about that ?</para>
</sect1>

<sect1 id="whydontiasanormaluserreceivekdeannouncements">
<title>Why Don't I, as a Normal User, Receive KDE Announcements ?</title>

<para>If you're running a linux system (with /proc enabled), this behaviour is a
bug. Please send me a description of it so that I correct it.</para>

<para>If you're running linux 2.0.35, this is a known bug in the kernel,
which doesn't let root read /proc. The solution is the same as in section
5.1, provided that you run kdm or xdm to log into X. Or upgrade !</para>

<para>Otherwise, this is normal : ktalkd can't find the user, as KDE doesn't 
log him into utmp and the linux based (/proc) detection is disabled.
The solution is the same as in section 5.1, provided that you run kdm
or xdm to log into X.
Another solution is to make sure you always have a xterm running.</para>
</sect1>

<sect1 id="howdoigetdebugoutputfromktalkd">
<title>How Do I Get Debug Output from Ktalkd ?</title>

<para>As it is a daemon, there is no debug output on standard output. To get 
debugging output (for instance before submitting me a bug report !), update 
the lines in inetd.conf which launches ktalkd and kotalkd to be :
<screen>talk   dgram   udp     wait    root    /usr/sbin/tcpd  /opt/kde/bin/kotalkd -d
ntalk  dgram   udp     wait    root    /usr/sbin/tcpd  /opt/kde/bin/ktalkd -d
</screen>

(notice the <emphasis remap="bf">-d</emphasis> option)</para>

<para>Then edit /etc/syslog.conf to add the following line :
<screen>*.*         /var/log/all_messages
</screen>
</para>

<para>To make it work, you then have to restart inetd and syslogd :
<screen>% killall -HUP inetd
% killall -HUP syslogd
</screen>

Finally, run a talk session and see the result in /var/log/all&lowbar;messages</para>

<para>When submitting a bug report, never forget to include the debugging output, but 
also ktalkd's version number and the "./configure" output. Thanks.</para>
</sect1>
</chapter>

<chapter id="copyright">
<title>Copyright</title>

<para>ktalkd is maintained and improved by David Faure, faure@kde.org</para>

<para>The original program was written by Robert Cimrman, cimrman3@students.zcu.cz</para>

<para><screen>ktalkd is Copyright 1997,1998 David Faure, faure@kde.org

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

</screen>
</para>
</chapter>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
