USAGE

Greyhole Configuration Instructions
===================================

The following are instructions on how to configure and run Greyhole.

You need Greyhole installed for those instructions to make sense. 
See https://github.com/gboudreau/Greyhole/wiki/Installing for details.

To configure Greyhole, you can either choose to use the web UI (wizard), or do the steps manually, from a terminal.

If you'd like to use the web UI, start the built-in server from a terminal:

    sudo php -S 0.0.0.0:8012 /usr/share/greyhole/web-app/index.php

Then point your browser to: http://server_hostname_or_ip:8012/install/

If you'd prefer to use the command line, follow the steps below instead.

Most of the commands below require root access, so now would be a good time
to become root, if you're not already (use `sudo -i` if you don't have the root password).

1. Read the following documentation pages.  
   The first page will help you understand why you're doing the next steps.  
   The second page will help you choose your Landing Zones (/path/to/landing_zone/share_name, in the next step) correctly.

   How Greyhole Works:     https://github.com/gboudreau/Greyhole/wiki/HowGreyholeWorks  
   About the Landing Zone: https://github.com/gboudreau/Greyhole/wiki/AboutLZ
   
2. Setup Samba:

	Before you continue, make sure you have shares created on Samba, and that you are able to connect to those shares remotely (or locally, using mount.cifs).  
	Of note: Samba uses its own users database; you'll need to create your user(s) using `smbpasswd -a` before you can connect to your shares.

	Edit `/etc/samba/smb.conf`  
	Change or add the following values in the [global] section (making sure this section is above all shares definition):

		unix extensions = no # Or use 'allow insecure wide links = yes', if you want/need to keep unix extensions enabled
		wide links = yes

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

	Example share definition:

		[share_name]
		    path = /path/to/landing_zone/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/bin/greyhole-dfree
		    vfs objects = greyhole

	Fedora: service smb restart  
	Ubuntu (< 10): /etc/init.d/samba restart  
	Ubuntu (10-14): restart smbd  
	Ubuntu (15+): service smbd restart  
	Debian: service samba restart

3. Setup the database:

	Make sure your MySQL server service (mysqld) is running, and runs on boot.

	Fedora: service mysqld start; chkconfig mysqld on  
	Ubuntu (< 10): /etc/init.d/mysqld start; update-rc.d mysqld defaults  
	Ubuntu (10-14): start mysql  
	Ubuntu (15+): service mysql start  
	Debian: service mysql start
		
     	# Remove the -p parameter if your MySQL root user doesn't require a password for local connections.
	    mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS greyhole; CREATE USER IF NOT EXISTS greyhole_user@localhost IDENTIFIED BY '89y63jdwe'; GRANT ALL ON greyhole.* TO greyhole_user@localhost;"
	    mysql -u greyhole_user -p89y63jdwe greyhole < /usr/share/greyhole/schema-mysql.sql

4. Customize the Greyhole configuration file, /etc/greyhole.conf, as needed.  
   Important: you need to either use the `date.timezone` setting in your php.ini, or specify your timezone in greyhole.conf, using the `timezone` config option.

5. Start the Greyhole service:

	Fedora: service greyhole start  
	Ubuntu (< 10): /etc/init.d/greyhole start  
	Ubuntu (10-14): start greyhole  
	Ubuntu (15+): service greyhole start  
	Debian: service greyhole start

    Check for errors, or check what the Greyhole service is working on, in the Greyhole log: greyhole --logs

6. If you'd like Greyhole to check your file copies, to make sure they all have the same checksum (as they should),
   you'll need to manually (or using cron) schedule a fsck using the --checksums option.  
   As this can be quite time-consuming, it is not enabled by default in the Greyhole crontab.  
   Example cron job (first Sunday of every month, at 1am):  

       0 1 1-7 * *  [ "$(date '+\%u')" = "7" ] && greyhole --fsck --email-report --checksums

If you use any applications that needs to use files on your shares locally (on the same server), you'll need to mount the shares locally, and point your applications to those mounts.  
You should never work on the files in your storage pool directories, or the symlinks in your shared directories.  
Ref: https://github.com/gboudreau/Greyhole/wiki/Mountshareslocally