===========================
Simple TCP FUSE File System
===========================

---
1.2
---

Very brief for now, more to come if there is enough interest.

**Note: Communication protocol in 1.2 is incompatible with older verions.**
Connection attempt will fail if using mixed versions.

Server end may have versions 1.1 and 1.2 installed at the same time if 1.1
is installed when 1.2 is being installed. If this is the case, both 1.1 client
and 1.2 client can connect to stfufs server.


Brief Intro
===========

Simple TCP File System is a FUSE (Filesystem in Userspace) based 
networked file system. It consists of 2 parts. A network server daemon
that is started on the (remote) host and a FUSE module running in user-space
on the local host. Server component is launched via SSH and after client
and server have communicated and created separate TCP connection for 
data transfer SSH link is shut down.

So, this provides somewhat the same functionality than sshfs_, but 
security traded for speed. If security is not an issue, this is useful
at least in the following situations: 1) Either machine is low-end.
2) The machines has important high-load application(s) running.
3) One wants to see real statvfs values ;)

This is one of the first versions. There is lot to improve. 
New versions may come.


License
=======

GPL v2 or later


Install
=======

Client requires FUSE headers and libraries, server does not. Currently 
C99-capable compiler is needed to compile both client and server, but
with little effort on the code, this requirement can be removed from
the server component.

To compile both client and server, enter ``make all``.

Enter ``make client`` or ``make server`` to compile either component.

For developers/testers: Enter ``make debug`` to compile debug build. 

After client compilation on "local" machine (where directory is to be mounted)
and server compilation on "remote" machine (from where directory is mounted),
install client and server by using command ``make install PREFIX=<prefix>``.
Components will be installed in directories ``PREFIX/bin`` and 
``PREFIX/lib/stfufs``. Make sure ``PREFIX/bin`` is in your PATH.

Use
===

In it's basic form, the usage is pretty same as with sshfs_:

``stfufs remote:[directory] mountpoint``

This instructs server try to bind on ports in range 13668 - 14658, on 10 
port increment and if succeeds to bind on any, listen for client to connect
on that port. 
For this to work, one must not have firewall to block on these ports; 
stfufs-server do know when port is already in use, but does not know about
firewall blocking connections. Today, most of the systems (linux distributions,
at least) have firewall blocking connections, so check with your system 
firewall configuration tool how to open the required port(s)


You can also define what port to use for connection:

``stfufs -c <portno> remote:[directory] mountpoint``

Now server tries to bind on given port and if succeeds, listens for
client to connect. The above firewall rules apply.


There is also possibility to make the connection other way around:

``stfufs -b <portno> remote:[directory] mountpoint``

Now client tries to bind on given port and if succeeds, listens for
server to connect. The same firewall rules apply, now on client machine


In both connection directions, there is also a *proxy* option available.
If this sounds too difficult/badly documented, skip over.

example:

``./stfufs -c 2001 -p 127.0.0.1:2000 -d 127.0.0.1:/usr usr``

This informs server to bind on port 2001, but connection is made to
localhost (127.0.0.1) port 2000. On that port, there is proxy pre-configured
to connect to port 2001 on remote machine. This has currently mostly used
for debugging purposes but there might be other uses as well.

And, for another direction:

``./stfufs -b 2001 -p 127.0.0.1:2000 -d 127.0.0.1:/usr usr``

Now client binds to port 2001, server is instructed to connect to
127.0.0.1:2000 (where proxy is configured to connect to 127.0.0.1:2001.)...

Not more on these (tricky) issues for now. In most cases the proxyless
versions work fine.

Testing
=======

(Move this part to developer documentation)

There has been many bugs that has been squashed in this program
after some testing. No-one can ever be sure that all bugs are gone,
since there is no resources to do indefinite testing.

I've so far done some basic testing with devel/test*.sh functions.
Then I tarred ``usr/bin/\*``, which created 95M archive. ``tar -zdf`` verified
all ok. And, for heavy stfufs buffer runs, I've run
``while ls -l usr/bin; do :; done`` for some time..

More tests needs to be developed for more certainty everyhing works fine
-- and for regression testing when new releases are made. I'll investigate
in this (slowly, though); suggestions for tools/methods are greatly
appreciated.


TODO
====
::

  protocol docs
  caching (single element is there now, maybe more, client/server side stuff)
  more docs in general
  protocol updates for smarter stuff
  pretocol using stfufs-buffer code (maybe)
  split client code out of stfufs binary, to make "reverse" mount possible.
  more

Thanks
======

- fuse_
- sshfs_  (reference when doing arg parsing etc.)
- ltspfs_ (reference when creating "minimal" first implementation)


Send comments and suggestions (and bug reports/patches) to too at iki dot fi

.. _fuse: http://fuse.sourceforge.net/
.. _sshfs: http://fuse.sourceforge.net/sshfs.html
.. _ltspfs: http://wiki.ltsp.org/twiki/bin/view/Ltsp/LtspFS