You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
656 lines
20 KiB
656 lines
20 KiB
<?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 "tdenetwork">
|
|
<!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>
|
|
</authorgroup>
|
|
|
|
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
|
|
|
<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>2003-09-17</date>
|
|
<releaseinfo>1.0.1</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 VNC 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>tdenetwork</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 VNC client to
|
|
view or even control the desktop.
|
|
</para>
|
|
|
|
<para>
|
|
You would typically use &krfb; with the &kde; VNC 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.trinitydesktop.org">http://bugs.trinitydesktop.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
|
|
free 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>
|
|
<imageobject>
|
|
<imagedata fileref="screenshot.eps" format="EPS"/>
|
|
</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>Create 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>
|
|
<imageobject>
|
|
<imagedata fileref="personal_invitation.eps" format="EPS"/>
|
|
</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>Invite via Email...</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>
|
|
<imageobject>
|
|
<imagedata fileref="email_invitation.eps" format="EPS"/>
|
|
</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; allows you to manage those invitations. The
|
|
dialog to control these is available using <guibutton>Manage
|
|
Invitations...</guibutton> on the &krfb; main window. If you select
|
|
that button, &krfb; will bring up a window as shown below.
|
|
</para>
|
|
|
|
<para>
|
|
<screenshot>
|
|
<screeninfo>&krfb; invitation management</screeninfo>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="invitation_management.png" format="PNG"/>
|
|
</imageobject>
|
|
<imageobject>
|
|
<imagedata fileref="invitation_management.eps" format="EPS"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&krfb; invitation management</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</para>
|
|
|
|
<para>
|
|
The invitation management window allows you to create more invitations
|
|
(using the <guibutton>New Personal Invitation...</guibutton> and
|
|
<guibutton>New Email Invitation...</guibutton> buttons, which have the
|
|
same effect as the <guibutton>Create Personal Invitation...</guibutton>
|
|
and <guibutton>Invite via Email...</guibutton> buttons on the &krfb; main
|
|
window.
|
|
</para>
|
|
|
|
<para>
|
|
The invitation managment window also allows you to delete existing
|
|
invitations. To just delete one of the invitations, select it with the
|
|
mouse or keyboard tabs (it should become highlighted), and then select
|
|
the <guibutton>Delete</guibutton>. To delete all invitations, just
|
|
select the <guibutton>Delete All</guibutton> button.
|
|
</para>
|
|
|
|
<!-- OK, so this is obvious, I only did it for completeness -->
|
|
<para>
|
|
Selecting <guibutton>Close</guibutton> closes this dialog.
|
|
</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 its control module, which you can access using
|
|
the normal &kde; control center, and you can also access using the
|
|
<guibutton>Configure...</guibutton> on the &krfb; main window. The &krfb;
|
|
configuration is controlled using a tabbed window, as shown in the
|
|
screenshot below:
|
|
</para>
|
|
|
|
<para>
|
|
<screenshot>
|
|
<screeninfo>&krfb; Configuration (Access Tab)</screeninfo>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="configuration_access.png" format="PNG"/>
|
|
</imageobject>
|
|
<imageobject>
|
|
<imagedata fileref="configuration_access.eps" format="EPS"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&krfb; Configuration (Access Tab)</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</para>
|
|
|
|
<sect2 id="rfb-access">
|
|
<title><guilabel>Access</guilabel></title>
|
|
|
|
<para>
|
|
The <guilabel>Access</guilabel> tab allows you configure settings
|
|
related to access to the &krfb; server.
|
|
</para>
|
|
|
|
<para>
|
|
The <guibutton>Create and Manage Invitations...</guibutton> takes you to
|
|
the <link linkend="krfb-managing-invitations">&krfb; invitation management window</link>,
|
|
which was described previously.
|
|
</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>
|
|
The <guilabel>Allow uninvited connections</guilabel> checkbox 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 checkboxes 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>Confirm
|
|
uninvited connections before accepting</guilabel>. Conversely, if the
|
|
machine is a server and you are using &krfb; for remote
|
|
administration, you probably want to deselect <guilabel>Confirm
|
|
uninvited connections before accepting</guilabel>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
&krfb; uses the normal RFB 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>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="rfb-session">
|
|
<title><guilabel>Session</guilabel></title>
|
|
|
|
<para>
|
|
&krfb; allows you to control whether the background image is passed to
|
|
the client, or not. This is controlled using a checkbox in the
|
|
<guilabel>Session</guilabel> tab, as shown below.
|
|
</para>
|
|
|
|
<para>
|
|
<screenshot>
|
|
<screeninfo>&krfb; Configuration (Session Tab)</screeninfo>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="configuration_session.png" format="PNG"/>
|
|
</imageobject>
|
|
<imageobject>
|
|
<imagedata fileref="configuration_session.eps" format="EPS"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&krfb; Configuration (Session Tab)</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</para>
|
|
|
|
<para>
|
|
If you check the box, &krfb; will not transfer the background
|
|
image. If you leave it blank, it is up to the client whether the
|
|
background image is transferred or not transferred.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="rfb-network">
|
|
<title><guilabel>Network</guilabel></title>
|
|
|
|
<para>
|
|
The <guilabel>Network</guilabel> tab allows control over the port that
|
|
&krfb; uses, as shown below.
|
|
</para>
|
|
|
|
<para>
|
|
<screenshot>
|
|
<screeninfo>&krfb; Configuration (Network Tab)</screeninfo>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="configuration_network.png" format="PNG"/>
|
|
</imageobject>
|
|
<imageobject>
|
|
<imagedata fileref="configuration_network.eps" format="EPS"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>&krfb; Configuration (Network Tab)</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</screenshot>
|
|
</para>
|
|
|
|
<para>
|
|
If you select the <guilabel>Assign port automatically</guilabel>
|
|
checkbox, then &krfb; will locate a suitable port, and invitations
|
|
will match this port. If you deselect the <guilabel>Assign port
|
|
automatically</guilabel> 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>
|
|
|
|
</sect2>
|
|
|
|
</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>
|
|
<imageobject>
|
|
<imagedata fileref="connection.eps" format="EPS"/>
|
|
</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> checkbox 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="dcop">
|
|
<title>Developer's Guide to &krfb;</title>
|
|
|
|
<para>
|
|
&krfb; supports a small number of &DCOP; commands, which are described
|
|
in this chapter. If you aren't familiar with &DCOP;, then you don't
|
|
need to worry about this. However if you'd like to automate some of
|
|
your &krfb; (or other &kde; application) actions, &DCOP; is a useful
|
|
tool. You can find out more about &DCOP; in its on-line documentation,
|
|
and in tutorials on <ulink
|
|
url="http://developer.kde.org">http://developer.kde.org</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
You can shut down the &krfb; application using the quit command, as
|
|
shown in this example:
|
|
</para>
|
|
|
|
<informalexample>
|
|
<screen>
|
|
<prompt>%</prompt>dcop krfb-1507 MainApplication-Interface quit
|
|
</screen>
|
|
</informalexample>
|
|
|
|
<note>
|
|
<para>
|
|
You will need to change the <userinput>krfb-1507</userinput> in the
|
|
example to match the instance of &krfb; that you actually want to
|
|
shutdown. If you run <command>dcop</command> with no options, you will
|
|
get a list of all applications that are running and &DCOP; can
|
|
control.
|
|
</para>
|
|
</note>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="faq">
|
|
<title>Questions and Answers</title>
|
|
|
|
<!-- (OPTIONAL but recommended) This chapter should include all of the silly
|
|
(and not-so-silly) newbie questions that fill up your mailbox. This chapter
|
|
should be reserved for BRIEF questions and answers! If one question uses more
|
|
than a page or so then it should probably be part of the
|
|
"Using this Application" chapter instead. You should use links to
|
|
cross-reference questions to the parts of your documentation that answer them.
|
|
This is also a great place to provide pointers to other FAQ's if your users
|
|
must do some complicated configuration on other programs in order for your
|
|
application work. -->
|
|
|
|
|
|
&reporting.bugs;
|
|
&updating.documentation;
|
|
|
|
<!-- Needs some content.
|
|
<qandaset id="faqlist">
|
|
<qandaentry>
|
|
<question>
|
|
<para>A question </para>
|
|
</question>
|
|
<answer>
|
|
<para>and an answer.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandaset>
|
|
-->
|
|
</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 © 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>
|