This is the README file for rumba.

What does rumba do?
===================
If you know smbfs for Linux: rumba is roughly the same. It is derived
from smbfs, but runs as a user level program, not in the kernel. If you
know samba: rumba is roughly the opposite: a client for the Lanmanager
protocol. If you know neither of these: rumba lets you mount drives
exported by Windows (f.Workgroups/95/NT), Lan Manager, OS/2 etc. on
Unix machines.


Does rumba run on my machine?
=============================
Currently, rumba can be compiled for:
  - NEXTSTEP 3.X and 4.X (tested for i386 and m68k architectures)
  - Linux
It should be relatively easy to port rumba to other Unix-like operating
systems (see "How do I port rumba to XXX?")


Where can I get rumba?
======================
You can either fetch the source code or the binary distribution for
NEXTSTEP/OPENSTEP. Note, however, that compiling the source for
NEXTSTEP/OPENSTEP requires the developer version and gnumake, which is
distributed with OPENSTEP but not with NEXTSTEP developer.
You can download the following files:

    rumba.0.4.s.gnutar.gz       the sourcecode of rumba
    rumba.0.4.NI.b.gnutar.gz    fat binary for Intel and Motorola CPUs

These files will be (or are) available from the sites:

    ftp://peanuts.leo.org/pub/comp/platforms/next/Unix/network/filetransfer/
    ftp://next-ftp.peak.org/pub/next/submissions/
    or wherever it will move to.

    ftp://hal.kph.tuwien.ac.at/pub/NeXT/tools/rumba/


What's the difference between rumba and smbfs for Linux?
========================================================
rumba is currently based on the modules "proc.c", "sock.c" and
"smbmount.c" of smbfs 0.8, but runs in user-space, not as part of the
kernel. It uses the nfs interface to the kernel. This has several
advantages:
  - In case of a crash, it's just a user program that crashes, not
    the kernel. It should be possible to restart rumba and continue
    the work.
  - You can re-export the rumba-mounted filesystems with an nfs daemon
    that allows re-exporting, because rumba has to create pseudo inode
    numbers.
Of course, there are also disadvantages:
  - Nfs has no way of telling about open files and file locking. rumba
    opens the file at every read- or write-request and keeps it open
    for 5 seconds (without any locking) for a faster access in
    subsequent accesses to the same file. This may cause problems with
    file-locking by other clients. smbfs on the other hand keeps the
    file open as long as it is opened by a program.
  - Due to the translation to nfs, rumba is slower than smbfs.


How do I use rumba?
===================
The usage of rumba is more or less the same as that of smbmount for
Linux:

    usage: rumba //server/service mount-point [options]

    -s servername   Netbios name of server
    -c clientname   Netbios name of client
        If the hostname of either the server or the client differs from
        the respective hostname, you have to use these options to set
        the netbios names.
    -U username     Username sent to server
        By default, the user name is read from the environment
        variables "USER" or "LOGNAME". If these are not set or if you
        want to log in to the server as a different user, use this
        option to specify the username.
    -u uid          uid the mounted files get
    -g gid          gid the mounted files get
        These options specify the Unix user- and group-IDs for the
        mounted files. The defaults are the real user- and group-IDs of
        the user that runs rumba. You can specify numeric or symbolic
        IDs.
    -f mode         permission the files get (octal notation)
    -d mode         permission the dirs get (octal notation)
    -C              Don't convert password to uppercase
        These three options are self-explaining, I think.
    -P password     Use this password
        You can specify a password from the commandline. To avoid
        compromising your password by using the "ps" command, rumba
        overwrites it with '*' as soon as possible.
    -n              Do not use any password
                    If neither -P nor -n are given, you are
                    asked for a password.
    -S              Read/write access is safe. Without this
                    option, files are closed when switching from
                    read to write or vice versa
        rumba opens all files for read and write. At least samba has
        problems when the file is really used for read _and_ write. To
        avoid these problems, rumba closes and reopens the file when it
        switches from read to write or vice versa. If you don't need
        this behaviour, you may switch it off with this option.
    -w              allow setting files to read only
        The implications of the read only attribute are slightly
        different on DOS/Windows and Unix machines. To avoid problems
        with this, rumba does not set files to read only, unless this
        parameter is given.
    -e              use getattrE and setattrE smb commands
        The core version of the LanManager protocol uses only one time
        per file: the time of the last modification. Unix has 3 times
        for every file. Per default, only the core functions are used
        and all three Unix times are set to the modification time.
        If this option is specified, an attempt is made to use the
        E-commands, which allow the transfer of all three times. The
        disadvantage is a tremendous slowdown when attributes are read,
        because the files must be open if the E-commands should be used.
    -F .            don't fake . entry in root directory
    -F ..           don't fake .. entry in root directory
        Unix requires a "." and ".." entry in each directory. DOS-disks
        don't have them in their root directory. If you mount the root of
        a remote DOS-disk, these entries must be faked. This is the
        default behaviour of rumba, because it is usual to mount the
        root of the disk.
    -h              print this help text
    -v              print version number and exit
    
    -p port         Port to connect to (used only for testing)
    -m max_xmit     max_xmit offered (used only for testing)
    -D debug-mode   activate debugging (bitmask, hex/dec/octal
                    notation) this option also forces foreground
                    operation
        Normally, rumba runs as a daemon. If a debug-mode is specified
        (even if it's 0), rumba stays in foreground to make debugging
        with a debugger easier.

To unmount a rumba-mounted directory, use the script "unrumba" that is
distributed in the source directory:

    usage: unrumba (-a | <mounted path>)

    -a
        Unmount all rumba mounted directories
    <mounted_path>
        Path of the mount point that should be unmounted

I have added the man-page for smbmount to this distribution, because
the operation of rumba and smbmount is so similar. You can view it in
a terminal window by typing:

    nroff -man smbmount.8 | more


Security considerations
=======================
If you want that non-root users can use rumba und unrumba, you must
install them "set uid root" (example for rumba):
    chown root rumba
    chmod u+s rumba
This is a potential security risk. Bugs in rumba or unrumba might allow
non root users to gain root access to your computer. If that's too risky
for you, you can only use the programs as root.


Bugs
====
There are two known problems in rumba, which you might consider as
bugs:
1.) The time needed for readdir is proportional to the number of entries
    within the directory _squared_. This is due to the implementation in
    proc.c from smbfs. It is unlikely that I will change this code
    because I have not written it.
2.) unrumba is a shell script which is far from perfect. It uses grep to
    find the mount entries in /etc/mtab and it finds all entries that
    _contain_ the path specification you entered. If you are good in
    awk and sed syntax, maybe you can help out with a better script.


How do I port rumba to XXX?
===========================
rumba should be relatively easy to port, as long as you have GNU-C
available. There are three files to consider for a port:
  - You have to make an entry in the system specific part of the
    "Makefile".
  - Every system specific header and define should go into #ifdefs in
    "syshdr.h".
  - You have to add a routine that does the mount() system call to
    "syscall.c".
If you have done a new port of rumba, please mail me your changes.


Why is rumba based on smbfs and not on smblib?
==============================================
It would be cleaner to use smblib, because it is designed for purposes
such as rumba. However, smblib does not support setting and reading
file attributes (at least I have not found these operations in version
0.5, which was the newest when I looked). Unfortunately, these
operations are essential for rumba. All calls to the smbfs-routines
are encapsulated in the file "smb_abstraction.c". This makes it easy
to switch to smblib at a later date.


References:
===========
I have used parts of source code or concepts from the following GPL'ed
programs:
  - smbfs, the smb filesystem for Linux by Paal-Kr. Engstad and
    Volker Lendecke
  - nfs-server-2.1 for Linux by Mark A. Shand, Donald J. Becker,
    Rick Sladkey, Fred N. van Kempen and Eric Kasten
  - p3nfs, the Psion NFS daemon by Rudolf Koenig (I think)
  - vmount (by me)


Copyright:
==========
rumba is distributed under the terms of the GNU General Public License
(version 2). You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


Author:
=======
Christian Starkjohann <cs@hal.kph.tuwien.ac.at>
