# The &kbear; Handbook

Björn
Sahlström

     kbjorn@users.sourceforge.net

Peter
Swärd

     tocool@telia.com

2000
2001
2002
Björn Sahlström
&FDLNotice;
Wen Jun 010 13:00:00 CEST 2002
0.8

&kbear; is a graphical ftp client with ability to connect to multiple hosts simultanously.

This Handbook describes &kbear; Version 2.0

KDE
Networking
KBear
ftp
Internet

## Introduction

The &kbear; Team welcomes you to &kbear;, a user-friendly ftp client for the K Desktop Environment. Our goal has been to give you an easy to use ftp client.

Before you get starting, we suggest that you read through the Getting Started section first so that your setup goes smoothly.

&kbear;'s homepage is at http://kbear.sourceforge.net

Feel free to come with suggestions to make it better at kbjorn@users.sourceforge.net.

## Getting Started

This is a short introduction to &kbear; and its usage so you can start working with it right away. For more in-depth information see the Using &kbear; and Using The Sitemanager sections. Note that &kbear;'s installation is described in the appendix.

### Starting &kbear;

You can start &kbear; from the K menu or from the command line. Note that there can only be one instance of &kbear;, if you try to start &kbear; and it's already running, the command line options will only be passed to the running instance.

#### From the Menu

Open the &kde; program menu by clicking on the big K icon on the toolbar at the bottom left of your screen. This will raise the program menu. Move your cursor up the menu to the Internet menu item. A list of available applications will appear. Choose &kbear;.

#### From the Command Line

You can start &kbear; by typing its name on the command line. If you give an URL, as in the example below, it will open that URL if possible. You can even give a space separated list of URL:s.

    %kbear ftp://ftp.kde.org/pub/kde

#### First start

Invoking &kbear; for the first time will start the Setup Wizard. It consists of four sections: View Settings, Window Settings, Miscellaneous, and Firewall Settings.

These sections can also be found in the menu Settings Configure &kbear;. The settings in these sections are fairly straightforward and most users can skip it right away and use the default settings. There is one exception though: users who are behind a firewall may need to setup this in the page Firewall Settings.

### Working with &kbear;

Working with &kbear; is easy, but if you run into any problem just hit the 'whats this button', which is the small question mark in the upper right corner of the window. Then move the mouse cursor to the area you have questions about, and click again. A help message will then appear at the cursor position.

When the application is started for the first time you will have one visible child view. This child view shows your local file system. By default it contains your home directory. Most other ftp clients has a splitted view were the local file system is shown on one side, and the remote file system on the other side. &kbear;, on the other hand, can open an unlimited number of remote sites (your system is the only limit). Therefore, each site is opened in a separate child view, including the local file system.

You can now connect to a remote host, either from the Sitemanager menu or from the Sitemanager dialog. If you want to add your own sites to the Sitemanager or want more information on how to use it, see the Using The Sitemanager section for instructions how to do this. If you have used earlier version of &kbear; your old Sitemanager will be automatically imported.

Once you have opened a remote site you can copy and move files and folders to or from your local filesystem. Just select the files/folders you want to transfer and drag them to the destination view, and drop them. The transfer will start directly and the transfer view will show up, unless you set it not to, and show the progress of your transfer.

## Using &kbear;

### Open a connection

There are four ways to connect to a remote site.

- The Ctrl N FTP Quick Connect command, also available in the toolbar.

- The Sitemanager that's available from the toolbar.

- The Sitemanager menu.

- The FTP Open Recent menu.

#### The Quick Connect dialog

The Quick Connect is available either from the menu command Ctrl N FTP Quick Connect or from the toolbar. This dialog allows you to connect to a host even if it's not in the SiteManager. Here you first have to add the name of the host you want to connect to, just the name without protocol. Like `ftp.kde.org or 127.0.0.1`. You then have to select what protocol to use. When you select a protocol KBear tries to set the correct default port for that protocol, according to your system settings. If you don't want to use the default port, you can change it to the port number you want to use. Unless you want to use anonymous login you also has to an enter user name and a password for the specified site. Finally set the start path for the remote host and click the Connect button.

From this dialog you can also choose to add the site automatically to the Sitemanager.

#### The SiteManager

To connect from the Sitemanager, just select one of the sites in the tree view to the left, and then click on the Connect button.

For more information on how to use the Sitemanager, se the chapter Using the Sitemanager.

#### The SiteManager menu

The SiteManager menu contains the whole Sitemanager database in a menu tree. Just select one of the sites from the menu to open it.

#### The Open Recent menu

Here you have a list of the ten most recent visited connections from the Sitemanager. Just select one of the options and the specified site will be opened. If the site has been removed from the Sitemanager you will be warned about this and the site will also be romoved from the FTP Open Recent menu.

### Copy or move files and folders

Once you have opened a remote site, you can start to transfer files and folders. &kbear; is capable of transfering files, not just to or from your local filesystem, but also between two remote hosts. Transfering files in &kbear; is easy. You will here get a short desciption of the two different ways to start a transfer in &kbear;: drag and drop and cut and paste.

#### Drag and drop

First you have to select the file(s) and/or folder(s) you want to transfer. By holding the Ctrl key pressed you can select several items. When you have selected all items you want to transfer, just press the left mouse button and hold it down. You will notice that the mouse cursor will change shape as soon as you start to move the mouse, indicating that you're dragging some items.Now move the mouse cursor to the view that holds the destination for your transfer, and release the mouse button. When you release the mouse button a small popup menu will show up, asking you to select wether you want to copy or move the file(s). Once you have selected the method, the transfer will start and an item will be shown in the transfer view, displaying the status and progress of your transfer.

By using the keyboard you can start the transfer directly without selecting transfer type in the popup menu. If you hold the Ctrl key pressed when you drop the item(s) a copy operation will start. If you hold the Ctrl and Shift keys pressed when you drop the items, a move operation will start.

If you hold the dragged item over a folder a little while the folder will be opened. This way you can work your way down in the directory tree, while still dragging the item, until you reach the position where you want to drop it.

#### Cut and paste

As with drag and drop you first have to select the file(s) and/or folder(s) you want to transfer. Once you have done this you have to decide wether you want to copy or move the items. By selecting the menu option Edit Copy or pressing the key combination Ctrl C you select to copy the selected item(s). By selecting the menu option Edit Cut or pressing the key combination Ctrl X you select to move the selected item(s). Then activate the destination view and select the menu option Edit Paste or press the key combination Ctrl V. The transfer will now start and an item will be shown in the transfer view, displaying the status and progress of your transfer.

You can also copy and move file(s) and folder(s) to or from Konqueror, and probably some other KDE applications.

### Additional views

Except for the child views, &kbear; has two other types of views: the transfer view and the log view.

#### Transfer view

The transfer view will show itself as soon as you start a transfer and will continously show status and progress of all transfers. It consists of a so called tab view and will show a tab for each site that has active transfers. As soon as the transfers for a specific site has finished the tab will be removed. When the last tab is removed the view will hide itself again.

If you click with the right mouse button on an active item in the transfer view a popup menu will show up with the option cancel. This way you can stop an active transfer. If the item is queued the popup menu will show the option start instead, so you can start a queued transfer.

#### Log view

The log view will show itself as soon as you open a remote site and it will continously show log information. It consists of a so called tab view and will show a tab for each open remote site. As soon as you close a site its tab will be removed and when the last tab is removed the view will hide itself again.

If you click with the right mouse button in a log page a small popup menu will show. Here you can select to mark all lines and copy the log contents into a document for example. You can also select to save the complete log content to a file.

&kbear; is only capable to produce complete log information for the ftp protocol.

## Using The Sitemanager

### General information

The Sitemanager is your personal site library. By default it contains some useful ftp sites, but you can add, remove and re-arrange the contents after your own needs. The Sitemanager is a so called plugin, a component that, even if it's plugged into the main window, live it's own life, independent from the main application. This makes it possible for the Sitemanager to also plug into Konqueror.

The Sitemanager dialog consists of a treeview to left containing the whole site database with all its goups and subgroups. Groups are shown as direcories and sites are shown as files in the tree view. If you select a site in the treeview, the information of the selected site will be shown to the right. Once a site is selected you just has to click the Connect button to connect to it. You can also connect by double clicking the site.

Once in a while it happends that the Sitemanager contents doesn't show up. You can then reload the contents with th reload button below the treeview.

#### Earlier versions

If you have used older versions of &kbear; you may have a personalized Sitemanager already. This old version is not compatible with the new one. But don't worry, you don't have to re-type all your sites, instead you can use the import filter system to import your old Sitemanager, see the How to import bookmarks files section.

#### The Database

Since the Sitemanager can plug into both &kbear; and Konqueror there is a big chance that there will be more than one Sitemanager running at the same time. Therefore is the management of the database moved into an external daemon like application that the Sitemanager communicates with. This application is automatically started and stopped by the Sitemanager. By default it show a small icon in the system tray (an open book with a small bear inside). This icon can be hidden from within the Sitemanager dialog.

#### The Sitemanager in Konqueror

As mentioned before the Sitemanager also plugs into Konqueror. Here you can use it in the same way as from within &kbear;. If you have several Sitemanager dialogs open at the same time they will always be synchronized with each other. So if you make changes in one of them the changes will directly take effect in all other open Sitemanagers. Even &kbear;:s Firewall settings work in Konqueror.

There is one issue though: it might happend that all settings in the Sitemanager may not work within Konqueror, especially the advanced site options. Normally they will, but if you make any changes these may not take effect until you restart Konqueror.

### Changing contents in the Sitemanager

#### Site and Group names in the Sitemanager

Each site or group name has to be unique within the group. This means that if you have a group, all it's children need to have unique names. For example: lets say you have a group named group1. Then you can't have two sites with the same name if they both have group1 as parent. The name can exist in other groups or in subgroups though. This is not a practical problem though since the database will rename the site or group if the name already exist. If you save a site with the name myname and the name already exist it will be renamed to myname (2). If myname (2) already exist it will be myname (3) and so on.

#### How to create a new site

First thing to do is to decide where in the site tree you want the site to be saved. To do this just select a group in the tree view, the site will then become a child of the selected group when saved. If you select a site the saved site will become a child of the same group as the selected site. If no site or group is selected the saved site will be saved as a root level site.

Once you have decided where you want the site to be saved, you can start to enter the information needed:

Label

  Here you need to enter a name for the site, see section above about names in the Sitemanager.

Host name

  Here you need to enter the name of the host to connect to, just the name without protocol, like: `ftp.kde.org` or `127.0.0.1`.

Protocol

  Here you have to select what protocol you want to use when connecting to the host. The number available protocols depends on your system. When you select a protocol &kbear; automatically try to detect the default port for the selected protocol.

Port

  Here you can select the port you want to use when connecting to the host. Normally you don't have to change this.

Anonymous

  If you're connecting to an anonymous server you can check this option.

Advanced...

  See Advanced Settings section below.

User name

  If you need to specify a user name to log in to the host, you can do so here.

Password

  If you need to specify a password to login to the host, you can do so here.

Local path

  By default &kbear; sets the path in the local filesystem view to your home directory when conecting to a host. If you want it to set another path, specify this here.

Remote path

  Set the initial directory for the remote host here.

Description

  Here you can specify a short description for the site (fully optional).

#### How to create a new group

As when creating a new site you first have to select where in the site tree you want to add the site by selecting an existing group. Then just click on the New Group button. A small dialog will appear where you can specify the name for the new group. About names in the Sitemanager see above section about names.

#### How to move a site or group

If you want to move a site or a group to another position in the site tree then do like this: Click on the item you want to move and hold the mouse button down. Then drag the item to the position where you want it, still with the mouse button pressed, until you reach the position where you want to place it. Release the mouse button and the item will be moved. Note that when dropping the item it may not showup exactly where you dropped it since the treeview sorts it's items. It will still be at the same level though.

If you hold the dragged item over a group a little while the group will be opened. This way you can work your way down in the tree, while still dragging the item, until you reach the position where you want to drop it.

#### How to rename a site or group

If you want to rename a site or group just right click with the mouse at the item you want to rename. A small menu with the option Rename appears. Select this option and you will now be able to rename the site or group. When you're done just push the Enter key.

#### How to remove a site or group

To remove a site or group just select the site or group you want to remove and push the Remove button.

#### How to import bookmarks files

The Sitemanager has a flexible system to import bookmark files from other ftp clients as well as for the old Sitemanager. When you first run this version &kbear; will automatically import the old Sitemanager file, but it can also be manually imported later. If you want to import a bookmark file just click on the Import... button in the Sitemanager. A small dialog will open, showing all available import filters to the left. Select the filter that you want to use and click the Import button. A fileselect dialog will now appear, asking you to specify the file to import.

#### Advanced Settings

In most cases the default settings will let you connect to, and work against, a remote host. There are some hosts that require special settings though. If you encounter any problems trying to connect to, or work against, a specific host, these settings may help you to solve these problems.

You will here get a brief description about the settings on this page. If you're interested in more information about the FTP protocol, see http://www.rfc.net/. This information can be quite hard to read though, and there are probably other information available on the Internet that's easier to understand.

##### Disable Passive mode, Extended Passive mode

By default &kbear; uses so called Passive mode, `PASV`. This command requests the server to listen on a data port which is not its default data port and to wait for a connection rather than initiate one itself. If you disable this option &kbear; will use the `PORT` instead. This command sets the data port to be used in data connection.

Using `PASV` will work in nearly all cases since &kbear; falls back in `PORT` mode if `PASV` fails.

##### Don't send `list -a`

Here you can specify if you don't want to send `list -a` to the server to retreive a directory listing. In some cases this can be useful since there are some servers that don't understand `list -a`. On the other hand, if you don't send `list -a`, you can't retreive hidden Unix files.

##### Use .part extension

KDE can add .part to the file name during transfers to indicate that the transfer is partially done. This can cause trouble on a server where you don't have permissions to rename files. If you don't want to use the .part extension, uncheck this option.

##### Turn off log

If you don't want &kbear; to produce log information for this site, check this option. Producing log information can reduce transfer speed so if you notice this, check this option.

##### Queue transfers

Here you can override the global queue option from the settings dialog. If the global option is set to not queue transfers, you can override this for this specific site. This can be useful since some servers only allow a single connection from a specific host.

##### Use a single connection

If you check this option &kbear; will use a single connection for all filesystem oprations (not transfers). This will lead to that, for example, a listing operation will be blocked until a delete operation is finished. This can be useful since some servers only allow a single connection from a specific host.

##### Transfer mode

Here you can specify how you want files to be transfered when using the ftp protocol. `Binary` will work in 99% of the transfers. Some files, like some perl scripts will be damaged this way though. Therefore you can specify to transfer files in `ASCII` mode instead.

##### Reconnect automatically

Here you can specify if you want &kbear; to try to reconnect automatically if connection fails. You can also specify the time to elapse between attempts and how many times it should try to reconnect.

## Configure &kbear;

### View Settings

The settings in the View Settings page let you select what parts of the GUI you want to be visible. Here you can hide/show toolbars, statusbar etc.

Default view settings

  In this first section you can select what kind of directory listing you want, detailed or icon mode. The thumbnails give you a preview of how they look.

Default visible settings

  Here you can select what GUI parts of the MainWindow you want to be visible. In the subarea Child Views you can also select visible parts of the child views. This can be usefull if you have a low resolution screen, so the child views occupy less screen space.

The last option on this page: Save settings used when closing the application means that all settings that are in use when closing the application will be saved and used as default at next startup.

### Window Settings

The settings in the Window Settings page let you select one of the different window modes that &kbear; can operate in.

TopLevel/ChildFrame mode

  In this first section you can select between three different window modes: TopLevel mode, ChildFrame mode and TabPage mode.

  - TopLevel mode means that all child views are detached from the MainWindow and are displayed as toplevel windows.

  - ChildFrame mode means that all child views are attached to the MainWindow and are displayed within the MainWindow.

  - TabPage mode means that all child views are attached to the MainWindow and are displayed as TabWindow within the MainWindow.

  The last option, Remember window positions..., let you select if the positions of the child views should be saved and reused.

Set default ChidFrame mode

  Here you can select how the child views should be arranged when in ChildFrame mode and also if they should be arraged automatically.

### Miscellaneous Settings

The settings in the Miscellaneous Settings page let you setup the following:

- Show system tray icon - Check this if you want the system tray icon to be visible. This give the opportunity to minimize the Application to just this icon. This can be useful for very long downloads. When moving the mose over the system tray icon a popup will show the number of active and queued transfers.

- On active transfers... - Check this option if you want the application to ask for confirmation before exiting if there are active or queued transfers.

- Run 'Tip of today'... - Check this option if you want the 'Tip of today' dialog to run on startup.

- Queue transfers - Check this option if you want to queue the transfers. This means that there will always be only one active transfer at a time. The transfers will show up in the transfer view as queued though.

- Email adress - Here you can set the email adress you want to use for login at anonymous servers.

- Preview mode - When you click on a file &kbear; tries to find an embeddable part that can show the selected file. Here you can select if you want the file to be opened in ReadOnly- or ReadWrite- mode, or if you want to be asked everytime.

### Firewall Settings

If you are behind a Firewall you may need to specify how to connect and login. If you're not behind a Firewall, just make sure that the Firewall type is set to No firewall.

#### How to setup the Firewall

First you have to set username, password etc. for the Firewall, note: you don't have to set all fields, just the ones you need. In the combobox Firewall type you have seven predefined Firewall types, one of these should work for most users. If not, or if you encounter any problem logging in, there is a last type: Special. If you choose this type you can specify your own login macro in the edit box below.

We take an example, lets say you need to login like this:

    USER fwuser
    PASS fwpass
    USER user@host:port
    PASS pass

Then you have to create a macro like this:

    USER %fu
    PASS %fp
    USER %hu@%hh:%ho
    PASS %hp

Note that each line will become a command sent to the Firewall host. If you don't know how to connect, then you can always experiment with all likely and non-likely combinations.

Note that these settings only apply to the ftp protocol, &kbear; has no internal Firewall support for other protocols. For those you have to fall back to KDE:s own proxy settings.

## Menu Entries

### The FTP Menu

Ctrl N FTP Quick connect

  Creates a new connection, this is an alternative for connecting from the Sitemanager.

Ctrl W FTP Close connection

  Close the connection for the active child view.

FTP Open Recent

  Open a submenu with the ten most recent used connections from the SiteManager.

FTP Clear recent

  Clears the Open Recent menu.

Ctrl Q FTP Quit

  Quits &kbear;

### The Edit Menu

Ctrl X Edit Cut

  Cut out the selected items in the active child view to the clipboard

Ctrl C Edit Copy

  Copy the selected items in the active view to the clipboard

Ctrl V Edit Paste

  Paste the contents in the clipboard into the active view

Ctrl A Edit Select All

  Selects all items in the active view.

Edit Deselect

  Deselects all items in the active view.

Edit Invert Selection

  Inverts the selection in the active view.

Ctrl F Edit Find

  Open a dialog where you can specify a search text to search for in the active view. You can use all kinds of wildcards here.

### The SiteManager Menu

SiteManager Reload

  Reloads the Sitemanager contents.

The rest of this menu is a reflection of the Sitemanager database.

### Tools Menu

Tools Show Toolbar

  Show/Hide the Tools Toolbar.

The rest of this menu can be personalized with the Settings Configure Tools menu option.

### The Settings Menu

Settings Show Main Toolbar

  Show/Hide the main toolbar

Settings Show Help Toolbar

  Show/Hide the help toolbar

Settings Show Statusbar

  Show/Hide the Statusbar

Settings Show Taskbar

  Show/Hide the Taskbar, this is the toolbar containing buttons associated to the child views.

Settings Show Transfer View

  Show/Hide the Transfer View (only visible when there are active/queued transfers)

Settings Show Log View

  Show/Hide the Log View ( only visible when there are open remote sites)

Settings Show Your Local Filesystem

  Show/hide the Local Filesystem View

Settings Show Child View Parts

  Open a submenu where you can show/hide tollbar, statusbar etc. in the child views.

Settings Configure Shotcuts

  Open a dialog where you can personalize key shortcuts for different actions.

Settings Configure Toolbars

  Open a dialog where you can configure the toolbars.

Settings Configure &kbear;

  Open the Settings dialog for &kbear;.

Settings Configure Tools

  Open a dialog where you personalize the Tools toolbar.

Settings Run Wizard...

  Starts the &kbear; Setup Wizard.

### The Window Menu

Window Close

  Close the active child view

Window Close All

  Close all child views

Window Minimize All

  Minimize all child views

Window MDI Mode...

  Open a sub menu where you can choose what view mode you want &kbear; to use.

  F5 Window MDI Mode... Toplevel mode

    Switch to TopLevel Mode. This means that all child views are detached from the MainWindow.

  F6 Window MDI Mode... Childframe mode

    Switch to ChildFrame Mode. This means that all child views are attached to the MainWindow and are displayed within the MainWindow.

  F7 Window MDI Mode... Tab Page mode

    Switch to Tab Page Mode. This means that all child views are attached to the MainWindow and are displayed as tabwindows within the MainWindow.

Window Tile...

  Open a sub menu where you can choose how the child views should be organized when in ChildFrame mode.

Window Dock/Undock...

  Open a sub menu containing the names of all child views. If the view you select are docked to the MainFrame it will become undocked and vice versa.

## Credits and License

&kbear; Program copyright 2000, 2001, 2002 by the &kbear; developer team.

### The &kbear; team:

Björn Sahlström kbjorn@users.sourceforge.net

  Project Manager & Principal Developer

Peter Swärd tocool@telia.com

  Developer

Documentation copyright 2000, 2001, 2002 Björn Sahlström kbjorn@users.sourceforge.net

This document has been translated by: Peter Swärd tocool@telia.com

&underFDL;

&underGPL;

## Installation

### How to obtain and install &kbear;

#### How to obtain &kbear;

&kbear; can be found at http://kbear.sourceforge.net/, the main web site of the &kbear; project, or at the main KDE site. It can also be found at any of these KDE mirror sites.

#### Requirements

In order to successfully use &kbear; you need KDE 3.x.x to be installed. Note that &kbear; will compile and run with KDE 3.0 and 3.0.1, but there are some bugs in these releases that can affect &kbear; in some situations. Therefore its recommended to use KDE 3.0.2 or later. The package you need is kdelibs. If you want to compile &kbear; from sources you also need to install the *-devel-* package. If you want to use other protocols than ftp you also need to install kdebase, unless you have separately installed kioslaves like, for example, the fish kioslave.

All required libraries can be found on the main KDE site.

#### Compilation and installation

In order to compile and install &kbear; on your system, type the following in the base directory of the &kbear; distribution:

    %./configure
    %make
    %make install (as root)

Since &kbear; uses autoconf and automake you should have no trouble compiling it. Should you run into problems please report them to the author at kbjorn@users.sourceforge.net

&documentation.index;