Greyhole Installation Instructions
==================================

The following instructions are for Fedora 12.
If you know what you're doing, you should have no problem installing on any other operating system that runs Samba (http://www.samba.org).

Note: I tried using Ubuntu 9.10 first, but had bad experiences with the CIFS server & client there... so I switched to FC12. I still have the install notes I used for Ubuntu; feel free to use that if you want.

1. Install Greyhole into /usr/local/greyhole/:
	(Or any other directory of your choice; just substitute your path for the rest of the installation instructions.)

	Get the latest version from http://code.google.com/p/greyhole/downloads/list
	tar zxf greyhole-*.tar.gz
	mv greyhole-* /usr/local/greyhole

2. Install the required applications: PHP 5 (cli) with MySQL extension, MySQL server, Samba, GCC:

	Fedora: sudo yum install mysql-server php php-mysql samba samba-common patch gcc
	Ubuntu: sudo apt-get install mysql-server php5-cli php5-mysql samba samba-common samba-common-bin build-essential

3. Samba, before 3.4.3, has a bug when trying to delete symbolic links (which Greyhole use extensively); we need Samba 3.4.3 or more.
   Plus, we need to compile our own VFS module.
   If you already run version 3.4.3 or higher, you'll just need to compile vfs_greyhole.c, and install it.

	Fedora:
	sudo yum install samba-common samba --enablerepo=updates-testing
	wget ftp://rpmfind.net/linux/fedora/updates/testing/12/SRPMS/samba-3.4.4-52.fc12.src.rpm
	rpm -ivh samba-3.4.4-52.fc12.src.rpm
	cd rpmbuild/SOURCES
	tar zxf samba-3.4.4.tar.gz
	cd samba-3.4.4/source3/
	cp /usr/local/greyhole/samba-module/vfs_greyhole.c modules/
	./configure
	patch -p1 < /usr/local/greyhole/samba-module/Makefile.patch
	make
	if [ `uname -i | grep 64 | wc -l` == 1 ]; then sudo cp bin/greyhole.so /usr/lib64/samba/vfs/greyhole.so; else sudo cp bin/greyhole.so /usr/lib/samba/vfs/greyhole.so; fi
	sudo service smb restart

	Ubuntu:
	wget http://samba.org/samba/ftp/stable/samba-3.4.3.tar.gz
	tar zxf samba-3.4.3.tar.gz && rm samba-3.4.3.tar.gz
	cd samba-3.4.3/source3/modules
	wget http://www.pommepause.com/blog/wp-content/uploads/2009/12/vfs_greyhole.c
	cd ..
	./configure --cache-file=./config.cache --with-fhs --enable-shared --enable-static --disable-pie --prefix=/usr --sysconfdir=/etc --libdir=/usr/lib --with-privatedir=/etc/samba --with-piddir=/var/run/samba --localstatedir=/var --with-rootsbindir=/sbin --with-pammodulesdir=/lib/security --with-pam --with-syslog --with-utmp --with-readline --with-pam_smbpass --with-libsmbclient --with-winbind --with-shared-modules=idmap_rid,idmap_ad --with-automount --with-ldap --with-ads --with-dnsupdate --with-cifsmount --with-acl-support --with-quotas
	patch -p1 < /usr/local/greyhole/samba-module/Makefile.patch
	make
	sudo make install
	sudo /etc/init.d/samba restart

4. Setup Samba:

	Edit /etc/samba/smb.conf
	Change or add the following values in the [global] section:

		log file = /var/log/samba/samba.log
		max log size = 0
		syslog = 0
		follow symlinks = yes
		wide links = yes
		log level = 0 vfs:2

	For each of your shares, add a 'dfree command' and 'vfs objects' lines, as seen below.

	Example share definition:
		[share_name]
		    path = /path/to/share_name
		    create mask = 0770
		    directory mask = 0770
		    read only = no
		    available = yes
		    browseable = yes
		    writable = yes
		    guest ok = no
		    printable = no
			dfree command = /usr/local/greyhole/greyhole-dfree
		    vfs objects = greyhole

	Notes:
		/path/to/ will be the value of your Landing Zone in Greyhole configuration file (later).
		All your shares needs to be subdirectories of that folder, and have no space in their names.

	Fedora: sudo service smb restart
	Ubuntu: sudo /etc/init.d/samba restart

5. Remove any old samba.log you might have; that will only contain invalid entries that Greyhole won't understand:

	sudo rm /var/log/samba/samba.log

6. Setup the MySQL database:

	mysql -u root -p -e "create database greyhole; grant all on greyhole.* to greyhole_user@localhost identified by '89y63jdwe';"
	mysql -u greyhole_user -p89y63jdwe greyhole < /usr/local/greyhole/mysql.sql

7. Cutomize the Greyhole configuration file:

	sudo cp /url/local/greyhole/greyhole.example.conf /etc/greyhole.conf
	
	Cutomize /etc/greyhole.conf as needed.

8. Make sure Samba can use our custom dfree command:

	sudo chown root /usr/local/greyhole/greyhole-dfree
	sudo chmod 755 /usr/local/greyhole/greyhole-dfree

9. For each directory you defined as 'storage_pool_directories', execute the following command, while the partition is mounted:

	touch <dir>/.greyhole_uses_this

	Example: touch /mnt/hdd0/gh/.greyhole_uses_this

	Those files will be used to differentiate an empty mount from a now-gone mount.
	i.e. Greyhole will output a warning if this file is not in the root directory where it is about to try to save a file, and it won't use that directory. This will prevent Greyhole from filling the / partition when a partition is unmounted!

10. Schedule a daily fsck. Add this in the root crontab (or cron.d / cron.daily if you prefer):

	0 0 * * *       /usr/local/greyhole/greyhole-executer --fsck --email-report > /dev/null

	fsck should take about 10 minutes per 50,000 files (depends on how many storage pool directories you have).
	If you use the --email-report option, make sure your PHP can send emails. Gust configure sendmail or postfix to be able to send email from the command line and you should be fine.

11. Add Greyhole to services that start on boot:

	sudo ln -s /usr/local/greyhole/initd_script.sh /etc/init.d/greyhole

	Fedora: sudo chkconfig --add greyhole; sudo chkconfig greyhole on
	Ubuntu: sudo update-rc.d greyhole defaults 98 20

12. Setup logrotate for /var/log/greyhole.log:

	sudo cp /usr/local/greyhole/logrotate.example /etc/logrotate.d/greyhole
	
	Customize /etc/logrotate.d/greyhole as needed.

13. Setup logrotate for the Samba log; edit /etc/logrotate.d/samba:

	prerotate
		/usr/local/greyhole/greyhole-executer --prerotate
	endscript
	...
	postrotate
		/usr/local/greyhole/greyhole-executer --postrotate > /dev/null || true
	endscript

14. Work around problems with the CIFS client; edit /etc/rc.local:

	# cifs client workaround
	# Ref: http://blog.dhampir.no/content/cifs-vfs-no-response-for-cmd-n-mid
	modprobe cifs
	echo 0 > /proc/fs/cifs/OplockEnabled

15. Start the Greyhole service:

	Fedora: sudo service greyhole start
	Ubuntu: sudo /etc/init.d/greyhole start


Check for errors in the Greyhole log file: /var/log/greyhole.log


If you use any application that needs to use files on your shares, you'll need to mount the shares locally, and point those applications to those mounts.
You should not touch the files in your storage pool directories, or in your landing zone.