TDE network applications
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.

668 lines

  1. <?xml version="1.0" ?>
  2. <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  3. <!ENTITY kappname "&krfb;">
  4. <!ENTITY package "tdenetwork">
  5. <!ENTITY % addindex "IGNORE">
  6. <!ENTITY % English "INCLUDE"> <!-- ONLY If you are writing non-English
  7. original documentation, change
  8. the language here -->
  9. <!-- Do not define any other entities; instead, use the entities
  10. from entities/general.entities and $LANG/user.entities. -->
  11. ]>
  12. <!-- Based on kdoctemplate v0.9 January 10 2003 -->
  13. <book lang="&language;">
  14. <!-- This header contains all of the meta-information for the document such
  15. as Authors, publish date, the abstract, and Keywords -->
  16. <bookinfo>
  17. <title>The &krfb; Handbook</title>
  18. <authorgroup>
  19. <author>
  20. &Brad.Hards;
  21. &Brad.Hards.mail;
  22. </author>
  23. </authorgroup>
  25. <copyright>
  26. <year>2003</year>
  27. <holder>&Brad.Hards;</holder>
  28. </copyright>
  29. <!-- Translators: put here the copyright notice of the translation -->
  30. <legalnotice>&FDLNotice;</legalnotice>
  31. <!-- Date and version information of the documentation
  32. Don't forget to include this last date and this last revision number, we
  33. need them for translation coordination !
  34. Please respect the format of the date (YYYY-MM-DD) and of the version
  35. (V.MM.LL), it could be used by automation scripts.
  36. Do NOT change these in the translation. -->
  37. <date>2003-09-17</date>
  38. <releaseinfo>1.0.1</releaseinfo>
  39. <!-- Abstract about this handbook -->
  40. <abstract>
  41. <para>
  42. &krfb; is a server application that allows you to share your current
  43. session with a user on another machine, who can use a VNC client to
  44. view or even control the desktop.
  45. </para>
  46. </abstract>
  47. <!-- This is a set of Keywords for indexing by search engines.
  48. Please at least include KDE, the KDE package it is in, the name
  49. of your application, and a few relevant keywords. -->
  50. <keywordset>
  51. <keyword>KDE</keyword>
  52. <keyword>tdenetwork</keyword>
  53. <keyword>krfb</keyword>
  54. <keyword>VNC</keyword>
  55. <keyword>RFB</keyword>
  56. <keyword>krdc</keyword>
  57. <keyword>Desktop Sharing</keyword>
  58. <keyword>Remote Control</keyword>
  59. <keyword>Remote Assistance</keyword>
  60. <keyword>Remote Desktop</keyword>
  61. </keywordset>
  62. </bookinfo>
  63. <!-- The contents of the documentation begin here. Label
  64. each chapter so with the id attribute. This is necessary for two reasons: it
  65. allows you to easily reference the chapter from other chapters of your
  66. document, and if there is no ID, the name of the generated HTML files will vary
  67. from time to time making it hard to manage for maintainers and for the CVS
  68. system. Any chapter labelled (OPTIONAL) may be left out at the author's
  69. discretion. Other chapters should not be left out in order to maintain a
  70. consistent documentation style across all KDE apps. -->
  71. <chapter id="introduction">
  72. <title>Introduction</title>
  73. <!-- The introduction chapter contains a brief introduction for the
  74. application that explains what it does and where to report
  75. problems. Basically a long version of the abstract. Don't include a
  76. revision history. (see installation appendix comment) -->
  77. <para>
  78. &krfb; is a server application that allows you to share your current
  79. session with a user on another machine, who can use a VNC client to
  80. view or even control the desktop.
  81. </para>
  82. <para>
  83. You would typically use &krfb; with the &kde; VNC client, which is
  84. &krdc;, since it closely matches the special features of &krfb;.
  85. </para>
  86. <para>
  87. &krfb; doesn't require you to start a new X session - it can share
  88. the current session. This makes it very useful when you want someone
  89. to help you perform a task.
  90. </para>
  91. <para>
  92. Please report any problems or feature requests to the &kde; mailing
  93. lists or file a bug at <ulink
  94. url=""></ulink>.
  95. </para>
  96. </chapter>
  97. <chapter id="what-is-RFB">
  98. <title>The Remote Frame Buffer protocol</title>
  99. <para>
  100. This chapter provides a brief description of the Remote Frame Buffer
  101. protocol used by &krfb; and by other compatible systems. If you are
  102. already familiar with Remote Frame Buffer, you can safely skip this
  103. chapter.
  104. </para>
  105. <para>
  106. The high level implementation of a system using the Remote Frame
  107. Buffer protocol is known as Virtual Network Computer, or more often
  108. just as <acronym>VNC</acronym>.
  109. </para>
  110. <para>
  111. Remote Frame Buffer (or <acronym>RFB</acronym> for short) is a simple
  112. protocol for remote access to graphical user interfaces. It works at
  113. the frame-buffer level, which roughly corresponds to the rendered
  114. screen image, which means that it can be applied to all windowing
  115. systems (including X11, &MacOS; and &Microsoft; &Windows;). Remote
  116. Frame Buffer applications exist for many platforms, and can often be
  117. free re-distributed.
  118. </para>
  119. <para>
  120. In the Remote Frame Buffer protocol, the application that runs on the
  121. machine where the user sits (containing the display, keyboard and
  122. pointer) is called the client. The application that runs on the
  123. machine where the framebuffer is located (which is running the
  124. windowing system and applications that the user is remotely
  125. controlling) is called the server. &krfb; is the &kde; server for the
  126. Remote Frame Buffer protocol. &krdc; is the &kde; client for the
  127. Remote Frame Buffer protocol.
  128. </para>
  129. <para>
  130. It takes a reasonable amount of network traffic to send an image of
  131. the framebuffer, so Remote Frame Buffer works best over high
  132. bandwidth links, such as a local area network. It is still possible to
  133. use &krfb; over other links, but performance is unlikely to be as good.
  134. </para>
  135. </chapter>
  136. <chapter id="using-krfb">
  137. <title>Using &krfb;</title>
  138. <!-- This chapter should tell the user how to use your app. You should use as
  139. many sections (Chapter, Sect1, Sect3, etc...) as is necessary to fully document
  140. your application. -->
  141. <para>
  142. It is very easy to use &krfb; - it has a simple interface, as shown in
  143. the screenshot below.
  144. </para>
  145. <para>
  146. <screenshot>
  147. <screeninfo>Here's a screenshot of &krfb;</screeninfo>
  148. <mediaobject>
  149. <imageobject>
  150. <imagedata fileref="screenshot.png" format="PNG"/>
  151. </imageobject>
  152. <imageobject>
  153. <imagedata fileref="screenshot.eps" format="EPS"/>
  154. </imageobject>
  155. <textobject>
  156. <phrase>&krfb; main window</phrase>
  157. </textobject>
  158. </mediaobject>
  159. </screenshot>
  160. </para>
  161. <para>
  162. When you want to allow someone to access your desktop, you can create
  163. an personal invitation using the <guibutton>Create Personal
  164. Invitation...</guibutton> button, which will bring up a window
  165. containing the information needed to access your desktop. An example
  166. is shown below.
  167. </para>
  168. <para>
  169. <screenshot>
  170. <screeninfo>Example &krfb; personal invitation</screeninfo>
  171. <mediaobject>
  172. <imageobject>
  173. <imagedata fileref="personal_invitation.png" format="PNG"/>
  174. </imageobject>
  175. <imageobject>
  176. <imagedata fileref="personal_invitation.eps" format="EPS"/>
  177. </imageobject>
  178. <textobject>
  179. <phrase>Example &krfb; personal invitation</phrase>
  180. </textobject>
  181. </mediaobject>
  182. </screenshot>
  183. </para>
  184. <para>
  185. To increase security, the invitation is only valid for an
  186. hour after it is created, and of course the person connecting has to
  187. have the correct password.
  188. </para>
  189. <para>
  190. Since you may want to invite someone to access your desktop by email,
  191. &krfb; can create invitations as email messages. You can create such
  192. an invitation using the <guibutton>Invite via Email...</guibutton>
  193. button on the &krfb; main window. This will usually bring up an email
  194. message that looks like the following, ready for you to type in the
  195. email address of the person you are sending the invitation to.
  196. </para>
  197. <para>
  198. <screenshot>
  199. <screeninfo>Example &krfb; email invitation</screeninfo>
  200. <mediaobject>
  201. <imageobject>
  202. <imagedata fileref="email_invitation.png" format="PNG"/>
  203. </imageobject>
  204. <imageobject>
  205. <imagedata fileref="email_invitation.eps" format="EPS"/>
  206. </imageobject>
  207. <textobject>
  208. <phrase>Example &krfb; email invitation</phrase>
  209. </textobject>
  210. </mediaobject>
  211. </screenshot>
  212. </para>
  213. <warning>
  214. <para>
  215. &krfb; will warn you about the security implications of sending this
  216. information across an insecure link. You must heed those warnings.
  217. </para>
  218. <para>
  219. If you cannot encrypt the email (or otherwise secure the link),
  220. sending invitations by email is a very serious security risk, since
  221. anyone can read the password and address from the email as it passes
  222. over the network. This means that they can potentially take control of
  223. your machine.
  224. </para>
  225. <para>
  226. If you cannot encrypt the email message, it may be better to use a
  227. personal invitation, telephone the person you are giving access to,
  228. verify the identity of that person, and provide the required
  229. invitation information that way.
  230. </para>
  231. </warning>
  232. <sect1 id="krfb-managing-invitations">
  233. <title>Managing &krfb; invitations</title>
  234. <para>
  235. Having created an invitation (either a personal invitation or one that
  236. was sent by email), &krfb; allows you to manage those invitations. The
  237. dialog to control these is available using <guibutton>Manage
  238. Invitations...</guibutton> on the &krfb; main window. If you select
  239. that button, &krfb; will bring up a window as shown below.
  240. </para>
  241. <para>
  242. <screenshot>
  243. <screeninfo>&krfb; invitation management</screeninfo>
  244. <mediaobject>
  245. <imageobject>
  246. <imagedata fileref="invitation_management.png" format="PNG"/>
  247. </imageobject>
  248. <imageobject>
  249. <imagedata fileref="invitation_management.eps" format="EPS"/>
  250. </imageobject>
  251. <textobject>
  252. <phrase>&krfb; invitation management</phrase>
  253. </textobject>
  254. </mediaobject>
  255. </screenshot>
  256. </para>
  257. <para>
  258. The invitation management window allows you to create more invitations
  259. (using the <guibutton>New Personal Invitation...</guibutton> and
  260. <guibutton>New Email Invitation...</guibutton> buttons, which have the
  261. same effect as the <guibutton>Create Personal Invitation...</guibutton>
  262. and <guibutton>Invite via Email...</guibutton> buttons on the &krfb; main
  263. window.
  264. </para>
  265. <para>
  266. The invitation managment window also allows you to delete existing
  267. invitations. To just delete one of the invitations, select it with the
  268. mouse or keyboard tabs (it should become highlighted), and then select
  269. the <guibutton>Delete</guibutton>. To delete all invitations, just
  270. select the <guibutton>Delete All</guibutton> button.
  271. </para>
  272. <!-- OK, so this is obvious, I only did it for completeness -->
  273. <para>
  274. Selecting <guibutton>Close</guibutton> closes this dialog.
  275. </para>
  276. </sect1>
  277. <sect1 id="krfb-configuration">
  278. <title>Configuring &krfb;</title>
  279. <para>
  280. In addition to the main &krfb; interface shown and described above, you can also
  281. control &krfb; using its control module, which you can access using
  282. the normal &kde; control center, and you can also access using the
  283. <guibutton>Configure...</guibutton> on the &krfb; main window. The &krfb;
  284. configuration is controlled using a tabbed window, as shown in the
  285. screenshot below:
  286. </para>
  287. <para>
  288. <screenshot>
  289. <screeninfo>&krfb; Configuration (Access Tab)</screeninfo>
  290. <mediaobject>
  291. <imageobject>
  292. <imagedata fileref="configuration_access.png" format="PNG"/>
  293. </imageobject>
  294. <imageobject>
  295. <imagedata fileref="configuration_access.eps" format="EPS"/>
  296. </imageobject>
  297. <textobject>
  298. <phrase>&krfb; Configuration (Access Tab)</phrase>
  299. </textobject>
  300. </mediaobject>
  301. </screenshot>
  302. </para>
  303. <sect2 id="rfb-access">
  304. <title><guilabel>Access</guilabel></title>
  305. <para>
  306. The <guilabel>Access</guilabel> tab allows you configure settings
  307. related to access to the &krfb; server.
  308. </para>
  309. <para>
  310. The <guibutton>Create and Manage Invitations...</guibutton> takes you to
  311. the <link linkend="krfb-managing-invitations">&krfb; invitation management window</link>,
  312. which was described previously.
  313. </para>
  314. <para>
  315. The <guilabel>Announce service on the network</guilabel> checkbox
  316. controls whether &krfb; announces invitations over the network using
  317. Service Location Protocol. This is normally a good idea, but only
  318. works really well with a Service Location Protocol aware client, such
  319. as &krdc;.
  320. </para>
  321. <para>
  322. The <guilabel>Allow uninvited connections</guilabel> checkbox controls
  323. whether &krfb; allows connection without an invitation. If uninvited
  324. connections are allowed, then you should probably specify a
  325. password. You can also use the checkboxes here to choose whether you
  326. have to confirm the connection before it proceeds, and whether the
  327. person connecting can control the desktop, or only view.
  328. </para>
  329. <para>
  330. If the machine is a workstation, and you choose to allow uninvited
  331. connections, you probably want to select the <guilabel>Confirm
  332. uninvited connections before accepting</guilabel>. Conversely, if the
  333. machine is a server and you are using &krfb; for remote
  334. administration, you probably want to deselect <guilabel>Confirm
  335. uninvited connections before accepting</guilabel>.
  336. </para>
  337. <note>
  338. <para>
  339. &krfb; uses the normal RFB password system, which does not transfer
  340. your password in the clear across the network. Instead, it uses a
  341. challenge-response system. This is reasonably secure, as long as the
  342. password is securely guarded.
  343. </para>
  344. </note>
  345. </sect2>
  346. <sect2 id="rfb-session">
  347. <title><guilabel>Session</guilabel></title>
  348. <para>
  349. &krfb; allows you to control whether the background image is passed to
  350. the client, or not. This is controlled using a checkbox in the
  351. <guilabel>Session</guilabel> tab, as shown below.
  352. </para>
  353. <para>
  354. <screenshot>
  355. <screeninfo>&krfb; Configuration (Session Tab)</screeninfo>
  356. <mediaobject>
  357. <imageobject>
  358. <imagedata fileref="configuration_session.png" format="PNG"/>
  359. </imageobject>
  360. <imageobject>
  361. <imagedata fileref="configuration_session.eps" format="EPS"/>
  362. </imageobject>
  363. <textobject>
  364. <phrase>&krfb; Configuration (Session Tab)</phrase>
  365. </textobject>
  366. </mediaobject>
  367. </screenshot>
  368. </para>
  369. <para>
  370. If you check the box, &krfb; will not transfer the background
  371. image. If you leave it blank, it is up to the client whether the
  372. background image is transferred or not transferred.
  373. </para>
  374. </sect2>
  375. <sect2 id="rfb-network">
  376. <title><guilabel>Network</guilabel></title>
  377. <para>
  378. The <guilabel>Network</guilabel> tab allows control over the port that
  379. &krfb; uses, as shown below.
  380. </para>
  381. <para>
  382. <screenshot>
  383. <screeninfo>&krfb; Configuration (Network Tab)</screeninfo>
  384. <mediaobject>
  385. <imageobject>
  386. <imagedata fileref="configuration_network.png" format="PNG"/>
  387. </imageobject>
  388. <imageobject>
  389. <imagedata fileref="configuration_network.eps" format="EPS"/>
  390. </imageobject>
  391. <textobject>
  392. <phrase>&krfb; Configuration (Network Tab)</phrase>
  393. </textobject>
  394. </mediaobject>
  395. </screenshot>
  396. </para>
  397. <para>
  398. If you select the <guilabel>Assign port automatically</guilabel>
  399. checkbox, then &krfb; will locate a suitable port, and invitations
  400. will match this port. If you deselect the <guilabel>Assign port
  401. automatically</guilabel> checkbox, you can specify a particular
  402. port. Specifying a particular port may be useful if you are using
  403. port-forwarding on the firewall. Note that if Service Location
  404. Protocol is turned on, this will automatically deal with identifying
  405. the correct port.
  406. </para>
  407. </sect2>
  408. </sect1>
  409. <sect1 id="krfb-connection">
  410. <title>What happens when someone connects to &krfb;</title>
  411. <para>
  412. When someone connects to &krfb; on your machine, you will get a pop-up
  413. notification that looks like the following screenshot, unless you are
  414. accepting uninvited connections without warning.
  415. </para>
  416. <para>
  417. <screenshot>
  418. <screeninfo>&krfb; Connection Window</screeninfo>
  419. <mediaobject>
  420. <imageobject>
  421. <imagedata fileref="connection.png" format="PNG"/>
  422. </imageobject>
  423. <imageobject>
  424. <imagedata fileref="connection.eps" format="EPS"/>
  425. </imageobject>
  426. <textobject>
  427. <phrase>&krfb; Connection Window</phrase>
  428. </textobject>
  429. </mediaobject>
  430. </screenshot>
  431. </para>
  432. <para>
  433. If you <guibutton>Accept Connection</guibutton>, the client can
  434. proceed to authenticate (which requires the correct password for a
  435. personal invitation or email invitation). If you <guibutton>Refuse
  436. Connection</guibutton>, then the attempt to connect will be terminated.
  437. </para>
  438. <para>
  439. The <guilabel>Allow remote user to control keyboard and
  440. mouse</guilabel> checkbox determines whether this client can only
  441. observe, or can take control of your machine.
  442. </para>
  443. <para>
  444. If the client connection is successful, and used the password from a
  445. personal invitation or email invitation, then that invitation is
  446. deleted and cannot be used again. You will also get a small pop-up
  447. window in the dock, that shows that the connection has been made.
  448. </para>
  449. </sect1>
  450. </chapter>
  451. <chapter id="dcop">
  452. <title>Developer's Guide to &krfb;</title>
  453. <para>
  454. &krfb; supports a small number of &DCOP; commands, which are described
  455. in this chapter. If you aren't familiar with &DCOP;, then you don't
  456. need to worry about this. However if you'd like to automate some of
  457. your &krfb; (or other &kde; application) actions, &DCOP; is a useful
  458. tool. You can find out more about &DCOP; in its on-line documentation,
  459. and in tutorials on <ulink
  460. url=""></ulink>.
  461. </para>
  462. <para>
  463. You can shut down the &krfb; application using the quit command, as
  464. shown in this example:
  465. </para>
  466. <informalexample>
  467. <screen>
  468. <prompt>&percnt;</prompt>dcop krfb-1507 MainApplication-Interface quit
  469. </screen>
  470. </informalexample>
  471. <note>
  472. <para>
  473. You will need to change the <userinput>krfb-1507</userinput> in the
  474. example to match the instance of &krfb; that you actually want to
  475. shutdown. If you run <command>dcop</command> with no options, you will
  476. get a list of all applications that are running and &DCOP; can
  477. control.
  478. </para>
  479. </note>
  480. </chapter>
  481. <chapter id="faq">
  482. <title>Questions and Answers</title>
  483. <!-- (OPTIONAL but recommended) This chapter should include all of the silly
  484. (and not-so-silly) newbie questions that fill up your mailbox. This chapter
  485. should be reserved for BRIEF questions and answers! If one question uses more
  486. than a page or so then it should probably be part of the
  487. "Using this Application" chapter instead. You should use links to
  488. cross-reference questions to the parts of your documentation that answer them.
  489. This is also a great place to provide pointers to other FAQ's if your users
  490. must do some complicated configuration on other programs in order for your
  491. application work. -->
  492. &reporting.bugs;
  493. &updating.documentation;
  494. <!-- Needs some content.
  495. <qandaset id="faqlist">
  496. <qandaentry>
  497. <question>
  498. <para>A question </para>
  499. </question>
  500. <answer>
  501. <para>and an answer.</para>
  502. </answer>
  503. </qandaentry>
  504. </qandaset>
  505. -->
  506. </chapter>
  507. <chapter id="credits">
  508. <!-- Include credits for the programmers, documentation writers, and
  509. contributors here. The license for your software should then be included below
  510. the credits with a reference to the appropriate license file included in the KDE
  511. distribution. -->
  512. <title>Credits and License</title>
  513. <para>
  514. &krfb;
  515. </para>
  516. <para>
  517. Program copyright 2002 Tim Jansen <email></email>
  518. </para>
  519. <para>
  520. Contributors:
  521. <itemizedlist>
  522. <listitem><para>Ian Reinhart Geiser <email></email></para>
  523. </listitem>
  524. </itemizedlist>
  525. </para>
  526. <para>
  527. Documentation Copyright &copy; 2003 &Brad.Hards; &Brad.Hards.mail;
  528. </para>
  530. &underFDL; <!-- FDL: do not remove -->
  531. &underGPL; <!-- GPL License -->
  532. </chapter>
  533. <appendix id="installation">
  534. <title>Installation</title>
  535. <sect1 id="getting-krfb">
  536. <title>How to obtain &krfb;</title>
  537. <!-- This first entity contains boiler plate for applications that are
  538. part of KDE CVS. You should remove it if you are releasing your
  539. application -->
  540. &install.intro.documentation;
  541. </sect1>
  542. <sect1 id="compilation">
  543. <title>Compilation and Installation</title>
  544. <!-- This entity contains the boilerplate text for standard -->
  545. <!-- compilation instructions. If your application requires any -->
  546. <!-- special handling, remove it, and replace with your own text. -->
  547. &install.compile.documentation;
  548. </sect1>
  549. </appendix>
  550. &documentation.index;
  551. </book>
  552. <!--
  553. Local Variables:
  554. mode: xml
  555. sgml-minimize-attributes:nil
  556. sgml-general-insert-case:lower
  557. sgml-indent-step:0
  558. sgml-indent-data:nil
  559. End:
  560. vim:tabstop=2:shiftwidth=2:expandtab
  561. -->