<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
 <!ENTITY komba2 "<application>Komba2</application>">
]>

<book id="Komba2" lang="&language;">
<bookinfo>
<title>The &komba2; Handbook</title>

<!-- copied from kmail -->

<authorgroup>
<author>
	<firstname>Frank</firstname>
	<surname>Schwanz</surname>
</author>
</authorgroup>

<date>18/02/2001</date>
<releaseinfo>0.7</releaseinfo>


<abstract>
<para>The document was updated at least to version 0.7.</para>

<para>Even if you don't like reading documentation: Some very helpful hints you probably
don't want to miss are collected in the
<link linkend="secintro">Introduction</link>
section.</para>

<para>Please mail any comments and additions to
<email>schwanz@fh-brandenburg.de</email>.</para>

</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>Samba</keyword>
<keyword>Komba</keyword>
<keyword>Windows</keyword>
</keywordset>
</bookinfo>

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

<para>The &komba2; Team welcomes you to &komba2;, a windows network administratingtool for the
K Desktop Environment. Our target is to make an administrating that is beautiful and intuitive
without sacrificing power.</para>

<para>If you have never used komba before, we suggest that you read through
the <link linkend="secgettingstarted">Getting Started</link> section first so that your setup goes smoothly.</para>

<para>Since people don't read documentation anyway, here is a collection of the most helpful tips:</para>


<itemizedlist>

<listitem><para>&komba2; needs some programs installed and permissions to be set. (smbmount and smbunmount).
Read <link linkend="runnonroot">Use &komba2; as user</link></para></listitem>

<listitem><para>Your <ulink url="http://www.samba.org">Samba</ulink> installation should be work before you use &komba2;.</para></listitem>


<!-- TODO: add other tips for "invisible" features here -->

</itemizedlist>
<para>&komba2;s homepage is <ulink url="http://zeus.fh-brandenburg.de/~schwanz/php/komba.php3">http://zeus.fh-brandenburg.de/~schwanz/php/komba.php3</ulink>.</para>

<para>Please report bugs in &komba2; using <menuchoice><guimenu>Help</guimenu><guimenuitem>Report bug...</guimenuitem></menuchoice>.</para>

<para>We hope you'll enjoy &komba2;!</para>

</chapter>

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

<sect1 id="getting-komba2">
<title>How can I get &komba2;</title>

<para>You can get the newest version of &komba2; at
<ulink url="http://zeus.fh-brandenburg.de/~schwanz/php/komba.php3">Komba-Homepage</ulink>.
</para>
</sect1>

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

<para>
If you downloaded the sources of &komba2;, make following step on console
<screen width="40">
<prompt>%</prompt> <userinput>tar xvzf ./komba2-*.tar.gz</userinput>
<prompt>%</prompt> <userinput>cd komba2-*</userinput>
<prompt>%</prompt> <userinput>./configure</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>
</para>
<para>Please note, you need root permissions for the last step.</para>

</sect1>

<sect1 id="beforerun">
<title>Before you run &komba2; the first time</title>
<para>The most problems with &komba2; depends on a wrong samba configuration.
That's why you should take some time and verify your settings.</para>

<sect2 id="runsamba">
<title>Does Samba run?</title>
<para>It seems to be trivial but is the most source of trouble. Use
<screen width="40">
<prompt>%</prompt> <userinput>smbclient -L localhost</userinput>
</screen>
to verify the smb-daemon.</para>
<para> And
<screen width="40">
<prompt>%</prompt> <userinput>nmblookup "*" -U localhost</userinput>
</screen>
ensure you that the nmb daemon is running. If the last two commands don't fail, samba seems to be set up correctly.
The configuration of samba fills books. It is not described in this document. The Installation of your distribution
should be running without changes.</para>
<para>In smb.conf (type <userinput>smbstatus -d</userinput> to know where to find it) should you find an entry
<itemizedlist>
<listitem><para>workgroup = </para></listitem>
</itemizedlist>
Set your workgroup behind it. &komba2; use it as startpoint to browse your network.</para>
</sect2>
<sect2 id="runnonroot">
<title>&komba2; as user</title>
<para>The use as non root user should be the normal case. It's recommended not to use &komba2; with su. It creates security holes. In this case &komba2; starts other programs with root permissions (for example Konqueror).</para>
<para>If you start &komba2; as a normal user you have not enough permissions to mount and unmount shares at first.</para>
<para>You have to change the permissions on smbmount and smbumount. Please note, it can open a security lack on your machine.
So be carefull!</para>
<para>It would be enough to change the bit SETUID on smbmnt and smbumount. If this bit is set the programs start with the permissions of the owner
(in this case root).
Now all users can mount and unmount smb shares.</para>
<para>We tell you now how to set the permissions only to group of users. For following commands you must be root. At first you add a group to your system.
<screen width="40">
<prompt>%</prompt> <userinput>groupadd sambamount</userinput>
</screen>
</para>
<para>Now you add the users to the new group.
<screen width="40">
<prompt>%</prompt> <userinput>usermod -G sambamount username</userinput>
</screen></para>
<para>Change the group on  smbmount und smbumount to sambamount.
<screen width="40">
<prompt>%</prompt> <userinput>chgrp sambamount smbumount</userinput>
<prompt>%</prompt> <userinput>chgrp sambamount smbmount</userinput>
</screen>
</para>
<para>At least you set the permissions that only users of the group (and root) can run smbmount and smbunmount and set the SUID bit
<screen width="40">
<prompt>%</prompt> <userinput>chmod 4750 smbumount</userinput>
<prompt>%</prompt> <userinput>chmod 4750 smbmount</userinput>
</screen>
</para>
<para>Now you can use &komba2;.</para>
</sect2>
</sect1>
</chapter>


<chapter id="secgettingstarted">
<title>Getting Started</title>

<para>This is a short introduction to &komba2; and its usage so you can
start working with it right away. For more in-depth information see the
<link linkend="secusingkomba2">Using &komba2;</link> section. </para>
</chapter>




<chapter id="secconfiguration">
<title>Configuration</title>

<para>Use
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configuration...</guimenuitem></menuchoice> to enter some initial information so &komba2; will
be able to properly mount/unmount shares and find hosts.</para>

<para>The Configure window consists of three sections:
<guilabel>IP-Range</guilabel>, <guilabel>Hosts</guilabel> and
<guilabel>Scan/Mount</guilabel>

To begin mount shares you will only have to change the
settings in the <guilabel>Scan/Mount</guilabel> tab.</para>

<sect1 id="settingiprange">
<title>Setting up IP-Ranges</title>

<para>The settings in the <guilabel>IP-Range</guilabel> tab can be left empty at first time. It only will be need if you want scan networks out of samba configuration.
 If you insert ip-ranges leave out the broadcast and the network ip (the first and last ip of the network). We have limited the range to 255 ip's of each network.
Komba could scan more (you can insert more than one range) but notice, network traffic rises! Use it careful! It should work without samba is installed
but it only can find hosts and workgroups, no shares.
</para>

</sect1>

<sect1 id="settinguphosts">
<title>Setting up Hosts</title>

<para>The <guilabel>Hosts</guilabel> tab contains the settings which hosts should be searched every networkscan. If you have a host (domaincontroller) in an other domain
you can insert it here. Try first without it.</para>


</sect1>


<sect1 id="settingupscanmount">
<title>Setting up Scan/Mount</title>

<sect2 id="setupsambaversion">
<title>Samba</title>

<para>Here you must setup your sambaversion you can find it out by typing "smbmount" in terminal. If you have a newer version try the latest.</para>
</sect2>

<sect2 id="setupscan">
<title>Scanning</title>

<para>Here you can say what &komba2; shall do if a new workgroup or host is found. <guilabel>Scan every workgroup which will be found</guilabel> means after a new workgroup is found the master
 of the workgroup will be scanned. <guilabel>Scan every host which will be found</guilabel> detects all samba shares on the remote host. Use it carefull. It can make much traffic and popups many passworddialogs if
you have don't have accounts on them.</para>
<para>If you don't want to be asked for a password while scanning check the button  <guilabel>don't ask for password</guilabel>. If you mount or unmount a share the
passworddialog will popup with checked button too.</para>
</sect2>
<sect2 id="setupdisplay">
<title>Display</title>
<para>At the moment komba supports only disk shares. You can show or hide other shares. <guilabel>show $ shares</guilabel> shows all hidden diskshares. In
windows all shares ends with $ are hidden.  <guilabel>show printer</guilabel> shows printers. There is no support for them but you can display them.
<guilabel>show ipc shares</guilabel> Usually disabled, only for testing.</para>
</sect2>
<sect2 id="setupmount">
<title>Mount</title>
<para>The mountpath you can set here is the default mountpath. Be sure you have permissions to this path. <guilabel>Unmount all connections on exit</guilabel> will
 unmount all mounted shares in view mounted. &komba2; can't differentiate between user-mounted and mounted shares before start, yet. It unmounts ALL smbfs-mounts.
Let it unchecked if you don't know what I mean. <guilabel>Remount all on next start</guilabel> Remember all shares which unmounted on last exit. &komba2; will search on them and mount it if any is found.</para>
</sect2>
<sect2 id="setuppassword">
<title>Password</title>
<para>You can store password (and username, too) in &komba2;'s configurationfile.&komba2; use a very low encryption. (copied from kmail, thanks to the authors) The configurationfile is
read/write only for owner by default but you must know that it is a risk to store your passwords! If you store them all your passwords are in one file!
<guilabel>save by default</guilabel> makes only the option <guilabel>save</guilabel> in passworddialog checked by default. In passworddialog you say if
the password will be stored.</para>
</sect2>

</sect1>
</chapter>

<chapter id="secusingkomba2">
<title>Using &komba2;</title>
<sect1 id="thekombawindows">
<title>The &komba2; views</title>

<sect2 id="thenetworktree">
<title>The Networktree</title>

<para>The <guilabel>Networktree</guilabel> window shows all workgroups, hosts and shares. Hosts can be
online (the screen is blue) or offline (the screen is grey). Shares have different pixmaps for mounted
(an open folder) and unmount (a closed folder). Printers will be shown with a printer pixmap. IPC's with
blockdevice pixmap.</para>

<para>By clicking on a item the menu will changed. So you can use no actions which are not available. The popupmenu
(click the right mousebutton) shows you which actions are possible.</para>
</sect2>

<sect2 id="theinformationtab">
<title>The Informationview</title>

<para><variablelist>
<varlistentry>
<term>For network </term>
<listitem>
<para>The count of workgroups and hosts will be shown.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>For workgroups </term>
<listitem>
<para>The host counts will be shown.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>For hosts </term>
<listitem>
<para>You can see details about the host. In the bottom view you see the netbiosnames
and services of the host.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>For shares </term>
<listitem>
<para>You can see details about the share. If the share is mounted you can the see the mountpoint.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>


<sect2 id="themountedtab">
<title>The Mounted view</title>

<para>In this view you will find all mounted samba shares. You can click on it and in the networktree is
now the current this share. With right click you get a popupmenu. So you can unmount the share or open
a new konquerorwindow (<guilabel>explore</guilabel>).</para>
</sect2>

<sect2 id="thesearchtab">
<title>The Search view</title>
<para>If you want search for a host or share you can do that here. You will only find a name which is in
networktree.You can use regular expressions (mp3* will show all names begins with mp3).</para>
<para>Another way is to search for an IP. You can use regular expressions here, too.</para>
</sect2>
</sect1>

<sect1 id="kombafunctions">
<title>Funktions of &komba2;</title>

<sect2 id="thescanning">
<title>Searching the network</title>

<para>&komba2; searches the network at starting. You can't use the function <emphasis >reload</emphasis> before the network is searched.</para>

<para>Here you will find internals of &komba2;. If you aren't interested in you can jump to the next section.
&komba2; limit the count of searching processes to 10. There are three diffent searchingprocesses in &komba2;.
All other processes waiting in queue. It starts with searching the masterbrowser of your workgroup (entry in smb.conf, look
<link linkend="secgettingstarted">Getting Started</link> ). The command shows the masterbrowser.
<screen width="40">
<prompt>%</prompt> <userinput>nmblookup -M myworkgroup</userinput>
</screen></para>
<para>The found host will be searched for shares, known hosts in the workgroup and all known workgroups with masterbrowsers.
<screen width="40">
<prompt>%</prompt> <userinput>smbclient -L mymasterbrowser</userinput>
</screen></para>
<para>If you checked options in <link linkend="setupscan">setup scanning</link> of &komba2; other found hosts will be searched too.</para>
<para>At the same time &komba2; will be search the host for ip and <trademark>NetBIOS</trademark>-names.
<screen width="40">
<prompt>%</prompt><userinput>nmblookup host -S</userinput>
</screen></para>
<para>The third searching process is the <link linkend="settingiprange">ip-range</link> searching. The function is integrated in &komba2; and looks for hosts on every ip in the range.
Nearly the command :
<screen width="40">
<prompt>%</prompt> <userinput>nmblookup "*" -U ip</userinput>
</screen></para>
<para>Depending on the limit of maximum 10 processes at the same time &komba2; will need 1 min. or more for searching the complete network.</para>
</sect2>

<sect2 id="themounting">
<title>Mounting shares</title>
<para>You can mount a share to default path wich you can configure in <link linkend="setupmount">setting up the mountpath</link>
and mount to a specified path. Use <emphasis >Mount</emphasis> to mount the share to the default path. &komba2; will create
in the <link linkend="setupmount">configured path</link> a directory named like the host and in the host
hostdirectory it will create a directory named like the share. &komba2; will mount the share in this path.</para>
<para>If you use <emphasis >mount on</emphasis> you can set the mountpath by yourself. &komba2; will mount the share in the given path.
Please note you need write permission on the path.</para>
<para>After mounting the share &komba2; will open a konqueror with the mounted path if you <link linkend="setupmount">set it up </link>.</para>
<para>If you can't use a mounted share (mostly the directory is not available) and &komba2; can't unmount it you can try following as root
<screen width="40">
<prompt>%</prompt> <userinput>umount mountpath</userinput>
</screen></para>
<para>It depends on Samba.</para>
</sect2>

<sect2 id="themessaging">
<title>Sending Messages</title>
<para>&komba2; can send messages to other hosts. It use the Message Service, so you can also sending messages to names other than the hostname.
Some restrictions are to note.<trademark>Windows 98</trademark> hosts need an utility to show the messages (WinPopup), in <trademark>Windows NT</trademark> and
<trademark>Windows 2000</trademark> it is integrated. Samba-hosts need an utility  (like <ulink url="http://zeus.fh-brandenburg.de/~henschel/kpopup.html">KPopup</ulink>), too.</para>
<para>Hosts can have more than one messagename. In a NT network you can send a message to a user and on all hosts where the user is logged the message will be shown.</para>
<para>If you send a message to a workgroup or the complete network &komba2; will send the message to the hostnames.</para>
</sect2>



<sect2 id="thepassword">
<title>Passwords</title>

<para>Every workgroup, host and share can have a password in komba2. If you set a password to a workgroup
all hosts which have no set password will use the workgrouppassword. A share does nearly the same.
If it has no set password the one from the host is taken. If the host have no set password it use the
workgrouppassword.</para>
<para>If you have a share that has no password and the host or workgroup has one set use
 "guest" as username and no password.</para>
<para>If <guilabel>save</guilabel> is checked the password will be stored in the kombaconfigfile.
 Please see <link linkend="setuppassword">Configure password</link>.</para>

<para>At <guilabel>store in</guilabel> you can say there the password has to be stored. So you can set a
passwordquestion for a host to a workgroup.</para>
</sect2>
</sect1>
</chapter>


<chapter id="epilogue">
<title>Epilogue</title>

<sect1 id="secdevelopers">
<title>Original Developers</title>
<!-- please keep in sync with the authors list on the webpage -->

<para><itemizedlist>
	<listitem><para>Frank Schwanz<email>schwanz@fh-brandenburg.de</email></para></listitem>
</itemizedlist></para>

</sect1>


<sect1 id="documentation">
<title>Documentation</title>

	<para>Update for &komba2; 0.63 by Frank Schwanz <email>schwanz@fh-brandenburg.de</email></para>
	<para>Update for &komba2; 0.7  by Frank Schwanz <email>schwanz@fh-brandenburg.de</email></para>
	<para>Original documentation from kmail used as template</para>

	<para>Thanks to</para>

	<para><itemizedlist>
		<listitem><para>Filippo Maguolo<email>maguolo@CS.UniBO.IT</email> (Italian translation)</para></listitem>
		<listitem><para>Marcus Stein <email>marcus-stein@gmx.de</email> (English documentation corrected)</para></listitem>
	</itemizedlist></para>

</sect1>

<sect1 id="copyright">
<title>Copyright</title>

<para>&komba2; is (c) Copyright 1999-2001 The &komba2; developers. It is licensed under the terms of the <ulink
url="common/gpl-licence.html">GNU General Public License</ulink>.</para>

<para>This documentation is (c) Copyright 1999-2001 Frank Schwanz.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.
A copy of the license is <ulink url="common/fdl-licence.html">included</ulink>.</para>

</sect1>
</chapter>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->