# The &krfb; Handbook

## Introduction

&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.

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

&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.

Please report any problems or feature requests to the &kde; mailing lists or file a bug at http://bugs.kde.org.

## The Remote Frame Buffer protocol

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.

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

Remote Frame Buffer (or RFB 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.

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.

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.

## Using &krfb;

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

Here's a screenshot of &krfb; &krfb; main window

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

Example &krfb; personal invitation Example &krfb; personal invitation

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.

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 Invite via Email... 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.

Example &krfb; email invitation Example &krfb; email invitation

&krfb; will warn you about the security implications of sending this information across an insecure link. You must heed those warnings.

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.

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.

### Managing &krfb; invitations

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 Manage Invitations... on the &krfb; main window. If you select that button, &krfb; will bring up a window as shown below.

&krfb; invitation management &krfb; invitation management

The invitation management window allows you to create more invitations (using the New Personal Invitation... and New Email Invitation... buttons, which have the same effect as the Create Personal Invitation... and Invite via Email... buttons on the &krfb; main window.

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 Delete. To delete all invitations, just select the Delete All button.

Selecting Close closes this dialog.

### Configuring &krfb;

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 Configure... on the &krfb; main window. The &krfb; configuration is controlled using a tabbed window, as shown in the screenshot below:

&krfb; Configuration (Access Tab) &krfb; Configuration (Access Tab)

The Access tab allows you configure settings related to access to the &krfb; server.

The Create and Manage Invitations... takes you to the &krfb; invitation management window, which was described previously.

The Announce service on the network 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;.

The Allow uninvited connections 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.

If the machine is a workstation, and you choose to allow uninvited connections, you probably want to select the Confirm uninvited connections before accepting. Conversely, if the machine is a server and you are using &krfb; for remote administration, you probably want to deselect Confirm uninvited connections before accepting.

&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.

&krfb; allows you to control whether the background image is passed to the client, or not. This is controlled using a checkbox in the Session tab, as shown below.

&krfb; Configuration (Session Tab) &krfb; Configuration (Session Tab)

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.

The Network tab allows control over the port that &krfb; uses, as shown below.

&krfb; Configuration (Network Tab) &krfb; Configuration (Network Tab)

If you select the Assign port automatically checkbox, then &krfb; will locate a suitable port, and invitations will match this port. If you deselect the Assign port automatically 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.

### What happens when someone connects to &krfb;

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.

&krfb; Connection Window &krfb; Connection Window

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

The Allow remote user to control keyboard and mouse checkbox determines whether this client can only observe, or can take control of your machine.

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.

## Developer's Guide to &krfb;

&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 http://developer.kde.org.

You can shut down the &krfb; application using the quit command, as shown in this example:

    %dcop krfb-1507 MainApplication-Interface quit

You will need to change the `krfb-1507` in the example to match the instance of &krfb; that you actually want to shutdown. If you run `dcop` with no options, you will get a list of all applications that are running and &DCOP; can control.

## Questions and Answers

&reporting.bugs; &updating.documentation;

## Credits and License

&krfb;

Program copyright 2002 Tim Jansen tim@tjansen.de

Contributors:

- Ian Reinhart Geiser geiseri@kde.org

Documentation Copyright © 2003 &Brad.Hards; &Brad.Hards.mail;

&underFDL; &underGPL;

## Installation

### How to obtain &krfb;

&install.intro.documentation;

### Compilation and Installation

&install.compile.documentation;
&documentation.index;