SliTaz Secure File Storage
===============================================================================


Ssfs is personal, secure, fast and light online file storage powered by
SSH, Rsync, Lsyncd and SHell script. It monitors a local folder and automatically
synchronizes the remote server. When files are transferred they are compressed and
encrypted with SSH. Connections to the remote host are automated with a RSA key,
and for each client the key must be sent to the server via a SSH password login.

Using ssfs lets you have a live synchronized and secure folder between many
computers with an online copy on a secure Linux server. But even without any
connections you have access to your files. Connections to the remote server
can also be done using the command line and 'ssh' from any clients such as
BSD, Android, OSX or Windows via Putty.

Ssfs is very easy to install, setup and configure to create your own secure 
online file storage. It provides a cmdline tool for the client and server with 
a built in help. This README is also a howto in itself.

On the server side admin can choose by creating standard accounts or chrooted
accounts which enforce server security by restricting available commands in a
minimal chroot environment. User $HOME should be set to 0700 so users can't see
other users files.


Overview
--------

    * Online live sync with encrypted data
    * Drop files in a folder and they will be synced
    * Even without any connection you still have your data
    * Fast and light using stable and mature GNU tools
    * Encrypted file transfer using SSH protocol
    * Easy to setup on the client and server side
    * Virtual disk storage for quota management
    * Minimal and restrictive but yet powerful chroot
    * Command line chrooted SSH access for users
    * Easy to backup, update and maintain vdisk


Quick start guide
-----------------

    * Install ssfs on server and clients if not yet done
    * Create a vdisk on server # ssfs-server gen-vdisk
    * Check if chroot works (exit to quit) # ssfs-server chroot
    * Add a chrooted user to the Ssfs virtual disk so it can sync
      files or connect via SSH from a client:
      # ssfs-server adduser --login=demo --id=2000 --pass=demo
    * On the client side: ssfs-box setup or from the cmdline:
      $ ssfs setup --login=demo --host="server name or ip"
    * On the client you can start ssfs on user login via the WM
      autostart script and/or the command $ ssfs sync
    * Get support and show your love for Ssfs on the SCN group:
      http://scn.slitaz.org/groups/ssfs/


Installation
------------
To work you need a SSH client, 'rsync' and 'lsyncd' installed. On SliTaz you
can simply install ssfs and it's dependencies or 'make install' from the
source directory (see the Development section). 


Client help and setup
---------------------
The cmdline interface ssfs lets you setup a client and start the daemon and
synchronize live with your system session via the Window Manager autostart
script or your personal ~/.profile file. To get a list of commands with
a short description:

$ ssfs help

To setup a client by creating a Lua configuration file and sending the RSA key
to the server, you can use the command 'setup'. Setup needs a login name and
server name or IP address and it will also create a secure RSA if none exists:

$ ssfs setup --login=user --host=server

Once the client is setup you can synchronize from the server and start a live
sync. You can also get quick access to your files and ssfs info with a nice
startup icon in the desktop panel. To sync and start Ssfs notify:

$ ssfs sync
$ ssfs-box notify &


GUI & Web interface
-------------------
Actually there is a small GTK/Yad but no web interface. The tool ssfs-box will
display info if a configuration file exists or start the setup box. There is no
plan for a users files web interface since security if more important, actually
a user's home has 0700 mode so a standard web server running user www can't see
the files. We may implement a HTTP Public dir which could handle xHTML pages, a
wiki, etc.

The GTK gui provides a notification mode as explained previously and the main
window can be started from the standard menu within the Network category.


Ssfs chroot SHell
-----------------
The tool ssfs-sh is used to chroot a user on login and sets minimal environment
variables. For each user ssfs-sh is the default SHell on the server and is
executed inside the new root. So ssfs-sh must be installed on the server and
in the virtual disk minimal chroot. Using a custom tool such as Ssfs SHell
enforces security and lets you execute commands on login, ssfs-sh also exports
the new user $HOME and changes the directory to it since chroot will drop us
in / by default.

The SHell is part of Ssfs features and provides a secure user access, SSH
login is automated with a RSA key where chrooted users have access to all
commands in /bin and a helper tool called 'ssfs-env' is available. Ssfs-env
can display server info, list files and search for files or commands. Like
all other Ssfs tools users can get a small built-in help usage. To connect
to the server and display ssfs-env help:

$ ssfs login
user@ssfs:~$ ssfs-env help


Get configs on boot
-------------------
Ssfs can be used in a boot script to connect to a remote host and retrieve data
before a user session is started. It can be useful to provide persistent data for
Live systems and web boot.


Quota management
----------------
Actually the quota storage is based on a shared idea, the vdisk has a size and
all users share the space. For a pay service the vdisk can grow following the
users donations or monthly subscription. Also when sshs-server creates a user
it assigns a default quota that could be used as a per user quota.


Server setup
------------
On the server you must have a SSH server running and an user account with a
~/Sync folder in user home. You can have both, standard accounts or chrooted
accounts, for a hosted service it is recommended to use a chroot and a Ssfs
virtual disk. The vdisk can be any size you want and have a minimal chroot
environment that is under 2Mb with all binaries in /bin and libraries in /lib.

If you want to create a vdisk and chroot automatically you can use use the tool
ssfs-server. Here is a short example to create a chroot and create a user
login 'tux-sync' with a protected $HOME in the chroot, the root directory can
be specified on the command line or changed in the configuration file. The
vdisk creation size is set in Gb and can be changed in the config file or from
the cmdline:

# ssfs-server gen-vdisk --size=2
# ssfs-server adduser --login=tux-sync --id=2000 --pass=tuX0cc

Users can be listed or completely deleted including all files in home. More
information can be found with the built in help:

# ssfs-server help

The vdisk chroot system can be extended if you want to provide more commands 
to users. The minimal SliTaz chroot is easily maintainable and built using
standard SliTaz packages. The package ssfs-busybox provides the minimal base
commands such as ls, cp, mc, cat, grep and has no dependencies since we just
need a few shared libs in /lib. Ssfs original chroot files are stored in the
directory /usr/share/ssfs/rootfs. The virtual disk contains a Linux journalled
ext3 filesystem that you can check and verify with:

# ssfs-server check-vdisk

In a production environment don't forget to mount Ssfs vdisk on boot via fstab.
For maintenance purposes you can manually mount or unmount the disk and also
update it with a command, example:

# ssfs-server mount-vdisk
# ssfs-server up-vdisk


Ssfs virtual disk
-----------------
A virtual Ssfs disk is a raw file created with dd and formatted in ext3. It is
mounted by default on /ssfs and contains a minimal chroot environment with a user's
home directory. We use a virtual disk to enforce security and use a separate
media for Ssfs secure files, it also protects the host and limits storage size.
The tool ssfs-server handles vdisk creation but you can also create one manually
or use a separate HD if the server has more than one disk. To create a 2Gb
vdisk and format it to ext3:

# dd if=/dev/zero of=/home/ssfs.disk bs=1G count=2
# mkfs.ext3 -T ext3 -L "Ssfs" -F /home/ssfs.disk

Now you have a virtual disk you can mount it, the path must match SSFS_CHROOT
found in ssfs-server.conf, default mount point is /ssfs to clearly separate
the filesystem from the standard host file hierarchy:

# mkdir /ssfs
# mount -o loop -t ext3 /home/ssfs.disk /ssfs

To automatically mount the vdisk on boot you may want to add a ssfs system user
and a line into the file /etc/fstab:

# adduser -S -g "Ssfs Server" -h /ssfs -s /bin/false ssfs
/home/ssfs.disk    /ssfs ext3    rw,loop,ssfs,ssfs  0 0


Server users config
-------------------
When adding a user with 'ssfs-server adduser', the user is added to the host
/etc/passwd and a custom user config file is created in SSFS_USERS with the
login name.


Server web interface
--------------------
The Ssfs package provides a small CGI SHell web interface to the server. The goal 
is to provide a service status and information. It uses the server configuration 
to know the Ssfs virtual disk path and display statistics about the filesystem.


Development and Bugs
--------------------
If you want to install the latest code to test and help in development you can
clone the ssfs Mercurial repository. As usual, closely follow the SliTaz light 
philosophy with speed and security in mind: hg clone http://hg.slitaz.org/ssfs

Install with 'make && make install' (DESTDIR is supported for packaging),
update the POT file if any new strings have been added with 'make pot',
and merger PO files with the command 'make msgmerge'. Any ideas are welcome
and can be discussed. If you are searching for something to do you can have a
look at the TODO file :-)

Bugs can be reported on the SliTaz mailing list, forum or scn since the devel
forum is synced. All sites are linked from: http://www.slitaz.org/

To share ideas and get involved in the Ssfs project you can join the Ssfs group
on the SliTaz Community Network website : http://scn.slitaz.org/groups/ssfs/


===============================================================================

