<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&krfb;">
  <!ENTITY package "kdenetwork">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"> <!-- ONLY If you are writing non-English 
                                     original documentation, change 
                                     the language here -->
    
  <!-- Do not define any other entities; instead, use the entities
       from entities/general.entities and $LANG/user.entities. -->
]>
<!-- Based on kdoctemplate v0.9 January 10 2003 -->

<book lang="&language;">

<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->

<bookinfo>
<title>The &krfb; Handbook</title>

<authorgroup>
<author>
&Brad.Hards;
&Brad.Hards.mail;
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2003</year>
<holder>&Brad.Hards;</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->

<legalnotice>&FDLNotice;</legalnotice>

<!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (YYYY-MM-DD) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->

<date>2010-02-09</date>
<releaseinfo>&kde; 4.4</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
&krfb; is a server application that allows you to share your current
session with a user on another machine, who can use a <acronym>VNC</acronym> client to
view or even control the desktop.
</para>
</abstract>

<!-- This is a set of Keywords for indexing by search engines.
Please at least include KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
<keyword>KDE</keyword>
<keyword>kdenetwork</keyword>
<keyword>krfb</keyword>
<keyword>VNC</keyword>
<keyword>RFB</keyword>
<keyword>krdc</keyword>
<keyword>Desktop Sharing</keyword>
<keyword>Remote Control</keyword>
<keyword>Remote Assistance</keyword>
<keyword>Remote Desktop</keyword>
</keywordset>

</bookinfo>

<!-- The contents of the documentation begin here.  Label
each chapter so with the id attribute. This is necessary for two reasons: it
allows you to easily reference the chapter from other chapters of your
document, and if there is no ID, the name of the generated HTML files will vary
from time to time making it hard to manage for maintainers and for the CVS
system. Any chapter labelled (OPTIONAL) may be left out at the author's
discretion. Other chapters should not be left out in order to maintain a
consistent documentation style across all KDE apps. -->

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

<!-- The introduction chapter contains a brief introduction for the
application that explains what it does and where to report
problems. Basically a long version of the abstract.  Don't include a
revision history. (see installation appendix comment) -->

<para>
&krfb; is a server application that allows you to share your current
session with a user on another machine, who can use a <acronym>VNC</acronym> client to
view or even control the desktop.
</para>

<para>
You would typically use &krfb; with the &kde;  <acronym>VNC</acronym> client, which is
&krdc;, since it closely matches the special features of &krfb;.
</para>

<para>
&krfb; doesn't require you to start a new X session - it can share
the current session. This makes it very useful when you want someone
to help you perform a task.
</para>

<para>
Please report any problems or feature requests to the &kde; mailing
lists or file a bug at <ulink
url="http://bugs.kde.org">http://bugs.kde.org</ulink>. 
</para>
</chapter>

<chapter id="what-is-RFB">
<title>The Remote Frame Buffer protocol</title>

<para>
This chapter provides a brief description of the Remote Frame Buffer
protocol used by &krfb; and by other compatible systems. If you are
already familiar with Remote Frame Buffer, you can safely skip this
chapter.
</para>

<para>
The high level implementation of a system using the Remote Frame
Buffer protocol is known as Virtual Network Computer, or more often
just as <acronym>VNC</acronym>. 
</para>

<para>
Remote Frame Buffer (or <acronym>RFB</acronym> for short) is a simple
protocol for remote access to graphical user interfaces. It works at
the frame-buffer level, which roughly corresponds to the rendered
screen image, which means that it can be applied to all windowing
systems (including X11, &MacOS; and &Microsoft; &Windows;). Remote
Frame Buffer applications exist for many platforms, and can often be
freely re-distributed.
</para>

<para>
In the Remote Frame Buffer protocol, the application that runs on the
machine where the user sits (containing the display, keyboard and
pointer) is called the client. The application that runs on the
machine where the framebuffer is located (which is running the
windowing system and applications that the user is remotely
controlling) is called the server. &krfb; is the &kde; server for the
Remote Frame Buffer protocol. &krdc; is the &kde; client for the
Remote Frame Buffer protocol.
</para>

<para>
It takes a reasonable amount of network traffic to send an image of
the framebuffer, so Remote Frame Buffer works best over high
bandwidth links, such as a local area network. It is still possible to
use &krfb; over other links, but performance is unlikely to be as good.
</para>

</chapter>

<chapter id="using-krfb">
<title>Using &krfb;</title>

<!-- This chapter should tell the user how to use your app. You should use as
many sections (Chapter, Sect1, Sect3, etc...) as is necessary to fully document
your application. -->

<para>
It is very easy to use &krfb; - it has a simple interface, as shown in
the screenshot below.
</para>

<para>
<screenshot>
<screeninfo>Here's a screenshot of &krfb;</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="screenshot.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>&krfb; main window</phrase>
	  </textobject>
	</mediaobject>
</screenshot>
</para>

<para>
When you want to allow someone to access your desktop, you can create
an personal invitation using the <guibutton>New Personal
Invitation...</guibutton> button, which will bring up a window
containing the information needed to access your desktop. An example
is shown below.
</para>

<para>
<screenshot>
<screeninfo>Example &krfb; personal invitation</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="personal_invitation.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Example &krfb; personal invitation</phrase>
	  </textobject>
	</mediaobject>
</screenshot>
</para>

<para>
To increase security, the invitation is only valid for an
hour after it is created, and of course the person connecting has to
have the correct password. 
</para>

<para>
Since you may want to invite someone to access your desktop by email,
&krfb; can create invitations as email messages. You can create such
an invitation using the <guibutton>New Email Invitation...</guibutton>
button on the &krfb; main window. This will usually bring up an email
message that looks like the following, ready for you to type in the
email address of the person you are sending the invitation to.
</para>

<para>
<screenshot>
<screeninfo>Example &krfb; email invitation</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="email_invitation.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Example &krfb; email invitation</phrase>
	  </textobject>
	</mediaobject>
</screenshot>
</para>

<warning>
<para>
&krfb; will warn you about the security implications of sending this
information across an insecure link. You must heed those warnings.
</para>
<para>
If you cannot encrypt the email (or otherwise secure the link),
sending invitations by email is a very serious security risk, since
anyone can read the password and address from the email as it passes
over the network. This means that they can potentially take control of
your machine.
</para>
<para>
If you cannot encrypt the email message, it may be better to use a
personal invitation, telephone the person you are giving access to,
verify the identity of that person, and provide the required
invitation information that way.
</para>
</warning>

<sect1 id="krfb-managing-invitations">
<title>Managing &krfb; invitations</title>

<para>
Having created an invitation (either a personal invitation or one that
was sent by email), &krfb; main window allows you to delete existing
invitations. To just delete one of the invitations, select it with the
mouse (it should become highlighted), and then select
the <guibutton>Delete</guibutton>. To delete all invitations, just
select the <guibutton>Delete All</guibutton> button.
</para>

</sect1>

<sect1 id="krfb-qit">
<title>Quit &krfb;</title>

<para>
If you close the &krfb; main window the server keeps running, which is
indicated by an icon in the system tray.
To stop &krfb; right click on the  icon in the systems tray and select
<guimenuitem>Quit</guimenuitem>.
</para>

</sect1>

<sect1 id="krfb-configuration">
<title>Configuring &krfb;</title>
<para>
In addition to the main &krfb; interface shown and described above, 
you can also control &krfb;  using the
<guibutton>Configure...</guibutton> on the &krfb; main window. The &krfb;
configuration has two pages, as shown in the screenshot below: 
</para>

<para>
The <guilabel>Network</guilabel> page allows control over the port that
&krfb; uses, as shown below.
</para>

<para>
<screenshot>
<screeninfo>&krfb; Configuration (Network page)</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="configuration_network.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>&krfb; Configuration (Network page)</phrase>
	  </textobject>
	</mediaobject>
</screenshot>
</para>

<para>
The <guilabel>Announce service on the network</guilabel> checkbox
controls whether &krfb; announces invitations over the network using
Service Location Protocol. This is normally a good idea, but only
works really well with a Service Location Protocol aware client, such
as &krdc;.
</para>

<para>
If you select the <guilabel>Use default port</guilabel> checkbox, 
then &krfb; will locate a suitable port, and invitations will match 
this port. If you deselect the this checkbox, you can specify a particular
port. Specifying a particular port may be useful if you are using
port-forwarding on the firewall. Note that if Service Location
Protocol is turned on, this will automatically deal with identifying
the correct port.
</para>

<para>
The <guilabel>Security</guilabel> page allows you configure settings
related to access to the &krfb; server.
</para>

<para>
<screenshot>
<screeninfo>&krfb; Configuration (Security page)</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="configuration_security.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>&krfb; Configuration (Security page)</phrase>
	  </textobject>
	</mediaobject>
</screenshot>
</para>

<para>
The <guilabel>Allow uninvited connections</guilabel> check box controls
whether &krfb; allows connection without an invitation. If uninvited
connections are allowed, then you should probably specify a
password. You can also use the check boxes here to choose whether you
have to confirm the connection before it proceeds, and whether the
person connecting can control the desktop, or only view.
</para>

<para>
If the machine is a workstation, and you choose to allow uninvited
connections, you probably want to select the <guilabel>Ask 
before accepting connections </guilabel>. Conversely, if the
machine is a server and you are using &krfb; for remote
administration, you probably want to deselect this option.
</para>

<note>
<para>
&krfb; uses the normal <acronym>RFB</acronym> password system, which does not transfer
your password in the clear across the network. Instead, it uses a
challenge-response system. This is reasonably secure, as long as the
password is securely guarded.
</para>
</note>

</sect1>

<sect1 id="krfb-connection">
<title>What happens when someone connects to &krfb;</title>

<para>
When someone connects to &krfb; on your machine, you will get a pop-up
notification that looks like the following screenshot, unless you are
accepting uninvited connections without warning.
</para>
<para>
<screenshot>
<screeninfo>&krfb; Connection Window</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="connection.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>&krfb; Connection Window</phrase>
	  </textobject>
	</mediaobject>
</screenshot>
</para>

<para>
If you <guibutton>Accept Connection</guibutton>, the client can
proceed to authenticate (which requires the correct password for a
personal invitation or email invitation). If you <guibutton>Refuse
Connection</guibutton>, then the attempt to connect will be terminated.
</para>

<para>
The <guilabel>Allow remote user to control keyboard and
mouse</guilabel> check box determines whether this client can only
observe, or can take control of your machine. 
</para>

<para>
If the client connection is successful, and used the password from a
personal invitation or email invitation, then that invitation is
deleted and cannot be used again. You will also get a small pop-up
window in the dock, that shows that the connection has been made.
</para>

</sect1>
</chapter>

<chapter id="credits">

<!-- Include credits for the programmers, documentation writers, and
contributors here. The license for your software should then be included below
the credits with a reference to the appropriate license file included in the KDE
distribution. -->

<title>Credits and License</title>

<para>
&krfb;
</para>
<para>
Program copyright 2002 Tim Jansen <email>tim@tjansen.de</email>
</para>
<para>
Contributors:
<itemizedlist>
<listitem><para>Ian Reinhart Geiser <email>geiseri@kde.org</email></para>
</listitem>
</itemizedlist>
</para>

<para>
Documentation Copyright &copy; 2003 &Brad.Hards; &Brad.Hards.mail;
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove -->

&underGPL;        	 <!-- GPL License -->

</chapter>

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

<sect1 id="getting-krfb">
<title>How to obtain &krfb;</title>

<!-- This first entity contains boiler plate for applications that are
part of KDE CVS.  You should remove it if you are releasing your
application --> 

&install.intro.documentation;

</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

<!-- This entity contains the boilerplate text for standard -->
<!-- compilation instructions.  If your application requires any -->
<!-- special handling, remove it, and replace with your own text. -->

&install.compile.documentation;

</sect1>

</appendix>

&documentation.index;
</book>

<!--
Local Variables:
mode: xml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab 
-->