Fish README file Version 0.6 What is Fish? ================================ Fish is a file syncing application. It can transfer multiple folders between multiple machines, keeping these folders synchronized. The Fish package does not need to be available on each machine in the group, only on the machine initiating the synchronization. Who wrote it? ================================ Jesse Smith What license does Fish use? ================================ Fish is licensed under the GNU General Public License, version 2. Please see the LICENSE file for full details. Copyright 2012. How does it work? ================================ Fish starts by accepting a list of folders we wish to synchronized between mutiple computers. It also accepts a list of computers with which we will coordinate. Once every N minutes (60, by default) Fish attempts to connect to each computer on its list and send/receive copies of the folders we have asked it to synchronize. This makes sure each computer has an up-to-date copy of the files in our shared folders. The folders can be located in any location and have any name. The Fish program uses a variety of common open source utilities to perform this work. For a full list, see the Building and Installing section below. Why another file synchronization program? ========================================== The author is a fan of file sync tools, such as Ubuntu One and Dropbox. However, both of these have certain drawbacks. At time of writing, One does not support syncing to multiple peers and Dropbox isn't open source. both services rely on a third party's servers. Sometimes it's good to be able to sync files between hosts on a network instead of (or in paralell with) a third-party. Fish allows us to do this. Building and Installing ============================================ To compile Fish we need a number of libraries and utilities on our system. Specifically we will need a C++ compiler and build tools. Generally these are packaged as "build-essential" on Linux machines. The proper compiler tools should already be installed on BSD systems. At this time Windows and OS X are not supported. The Qt 4 development libraries will also have to be installed if we want the Fish graphical front-end. These Qt libraries are probably available in your package repository under a name like qt4-dev-tools or qt-sdk. When in doubt installing the QtCreator package should pull in all the required dependencies. Once the dependencies are in place, move to the dirctory containing the Fish tarball and run tar zxf fish-0.6.tar.gz cd Fish make (then as root) make install Should we to also install the graphical front-end for Fish, which is useful for configuration, we will run make gui (then as root) make installgui To assist users in building Fish, same make targets have been created to make installing dependencies easier. on Debian, Ubuntu (and related systems). On Debian, run the following as the root user. tar zxf fish-0.6.tar.gz cd Fish make get-debian-deps (do this as root) make make install (do this as root) make installgui (optional: do this as root) On Ubuntu systems, perform the following steps. tar zxf fish-0.6.tar.gz cd Fish sudo make get-ubuntu-deps make sudo make install sudo make installgui (optional) On FreeBSD systems it will hopefully soon be possible to install Fish-Sync using a port. However, if you are compiling Fish-Sync directly from a source package the installation steps are as follows: tar zxf fish-0.6.tar.gz cd Fish gmake CXX=clang su (enter root password) gmake install Please note, if you have installed Fish on other distributions, such as openSUSE, Slackware or Fedora, please send us the commands required to install the necessary dependencies so we can automate the process for your distribution. Thank you. Our contact information is at the bottom of this file. Configuring and Running ========================================== Before we can run Fish we need to make sure various utilites are in place. Fish makes use of a number of commonly available open source tools to do its work. They are: OpenSSH (secure shell client) rsync (remote sync tool) sshpass (program to pass password to OpenSSH) Please make sure the above are installed before attempting to run Fish. Each remote computer we sync with does not need to have Fish installed. All each remote computer needs is a copy of OpenSSH to be installed. And the remote host should support public key logins. This is usually the default behaviour. The OpenSSH server is the only piece of software remote machines need to have running, unless they wish to initiate their own sync operations. To configure Fish we have two options. One is to make use of the Fish GUI, installed in our path as "fish-gui". This graphical front end supports configuring the paths Fish checks to locate its run-time dependencies. It will also allow us to list which hosts we want to sync with and it will allow us to specify which folders to sync. Should we not wish to use a graphical front-end, for example if we're installing Fish on a server, we can manually create configurating files. All Fish configuration files are located in the user's home folder under the .fish subfolder (~/.fish). There are three configuration files. The first one is called "config" (~/.fish/config). Each line of the file contains one variable followed by an equals sign and a value, with no spaces. The following variables are supported in the config file. timecycle (Number of minutes to wait between syncs.) ssh (Location of the ssh command.) copyid (Location of the ssh-copy-id command.) keygen (Location of the ssh-keygen command.) rsync (Location of the rsync command.) pass (Location of the sshpass command.) singlerun (Set to yes if you want Fish to sync once and exit.) What follows is an example config file: timecycle=120 ssh=/usr/bin/ssh copyid=/usr/bin/ssh-copy-id keygen=/usr/bin/ssh-keygen rsync=/usr/bin/rsync pass=/usr/bin/sshpass singlerun=no The second configuration file is called "include" (~/.fish/include) and it lists all of the folders we wish to sync with other computers. Each line of the include file contains one full path to a single folder. For example: /home/myuser/Documents /home/myuser/Pictures /home/myuser/Downloads/programs Each folder and the sub-folders under it are synced with all of the remote computers. The third configuration file is called "hosts" (~/.fish/hosts). It contains a list of remote computers, one on each line. Each line contains five fields. The first field is the name or IP address of a remote computer. The second field is a port number where we can find an OpenSSH server running. The third field is our user name on that host. The fourth field is either a 1 or a 0. A 1 indicates the remote computer already includes our public key for OpenSSH authentication. A 0 means the remote computer does not yet have our key and one must be sent. The fifth and final field is a number indicating whether we wish to (1) send our files to the remote computer, (2) pull files down from the remote computer, (3) both send and recieve files, insuring both are up to date, or (0) no action should be taken with this computer. The following three lines of a "hosts" file show how we can send, receive and full sync files with remote hosts. 192.168.0.101 22 susan 1 1 192.168.0.115 22 bob 1 2 example.com 22 me 1 3 Should we wish to sync specific folders with a specific host, we have that option. Starting in Fish version 0.2 it is possible to match select folders to be synced with one host. In the configuration folder (~/.fish) we create a file with the name "hostname.dir" where "hostname" is the name of the remote computer. It could be "192.168.0.100.dir" or "example-computer.dir". Inside this text file we list the folders we wish to sync with the specific computer. A *.dir configuration file might look like this: /home/susan/Project/Our-Project/ /home/susan/Project/Project-Backups Folders listed in the ~/.fish/include file are synced with ALL REMOTE HOSTS. It is a global list. The folders listed in the *.dir files are specific to just one host. You will note the hosts file does not contain passwords. This is because Fish uses public key authenication to connect us with a remote host. When using the graphical configuration tool (fish-gui) the program will ask us for our password once so it can create and transfer our security key. Once that is done Fish should work automatically without need for a password. If, however, we are running Fish without a graphical front-end it is possible to instruct Fish to prompt us for a password on the command line. Make sure the fourth field of the hosts file is set to 0 like so 192.168.0.100 22 susan 0 3 Then run Fish with the "-i" flag. Like this: fish -i This causes Fish to run in interactive mode and when it comes to a host which does not include a security key Fish will prompt for the host's password. Fish will then transfer the key for us and update the "hosts" configuration file. Warning: If Fish is not run in interactive mode and if keys have not been transferred to the remote computer then Fish will not be able to perform synchronization. It is recommended the first time you run Fish you do so with the "-i" flag to make sure all hosts receive their security keys. Other command line options ========================== Fish supports the following command line options. -h --help Show this information and exit. -v --version Display version and exit. -i --interactive Prompt for needed passwords Recommended for first use of Fish. Terminating or Restarting Fish ============================== When a configuration option changes we may wish to either terminate Fish or cause it to restart and thus re-read its configuration file. Sending the Fish process a SIGHUP signal will cause it to finish what it is doing and then restart itself, causing the configuration files to all be re-read. Sending the Fish process a signal of SIGINT will cause the daemon to finish what it is cleanly doing and attempt to exit cleanly. Any time a change is made to a Fish configuration file it is recommended the daemon be restarted so that the change may immediately take effect. Known Issues ================================== * The Fish graphical front-end (fish-gui) assumes if it finds the file ~/.fish/fish.pid that the daemon is running. However, if Fish is forced to quit due to a segfault or a KILL signal, then the PID file will be left behind. Selecting File->Restart or deleting the ~/.fish/fish.pid file will correct this assumption. Planned features for future versions ====================================== Please see the accompanying TODO file for a list of planned features. Feedback ============================= Comments, questions and feedback can be sent to jessefrgsmith@yahoo.ca Please include the word "Fish" in the subject line of the e-mail. Should you encounter a problem, please include with your bug report, a copy of the Fish log file. This file can be located at ~/.fish/log.txt The file will contain names of your hosts, folders and files, but will _not_ contain copies of your keys or passwords.