v1.4.0

README.md

@@ -50,9 +50,9 @@ Download the latest release from [GitHub](https://github.com/vmstan/gravity-sync
 
 ```
 cd ~
-wget https://github.com/vmstan/gravity-sync/archive/v1.3.4.zip
+wget https://github.com/vmstan/gravity-sync/archive/v1.4.0.zip
-unzip v1.3.4.zip
+unzip v1.4.0.zip
-mv ~/gravity-sync-1.3.4 ~/gravity-sync
+mv ~/gravity-sync-1.4.0 ~/gravity-sync
 cd gravity-sync
 ```
 
@@ -60,9 +60,26 @@ Please note the script **must** be run from a folder in your user home directory
 
 ## Configuration
 
-After you clone the base configuration, you will need to create a configuration file called `gravity-sync.conf` in the same folder as the script. There will be a file called `gravity-sync.conf.example` that you can use as the basis for your file. 
+### The Easy Way
 
-Make a copy of the example file and modify it with your site specific settings.
+After you install Gravity Sync to your server (reguardless of the option you selected above) you will need to create a configuration file called `gravity-sync.conf` in the same folder as the script. 
+
+```
+./gravity-sync config
+```
+
+This will guide you through the process of:
+- Specifying the IP or DNS name of your primary Pi-hole
+- Specifying the SSH username to connect to your primary Pi-hole
+- Selecting the SSH authentication mechanism (key-pair or password)
+- Configuring your key-pair and applying it to your primary Pi-hole
+- Testing your authentication method
+
+After you've completed your configuration, proceed to the Execution phase. Unless you feel like making this (slightly) harder on yourself.
+
+### The Less Easy Way
+
+There will be a file called `gravity-sync.conf.example` that you can use as the basis for your own `gravity-sync.conf` file. Make a copy of the example file and modify it with your site specific settings.
 
 ```
 cp gravity-sync.conf.example gravity-sync.conf
@@ -165,7 +182,7 @@ Your copy of the `gravity-sync.conf` file, logs and backups should not be be imp
 
 If you installed via Option 2, download and overwrite the `gravity-sync.sh` file with a newer version. With either version, you should review the contents of the script bundle, specifically the example configuration file, to make sure there are no new required settings. 
 
-The goal of Gravity Sync is to be simple, so any additional requirements should also be called out when it's executed. After updating, be sure to manually run a `./gravity-sync.sh compare` or `./gravity-sync.sh pull` to validate things are still working as expected.
+The goal of Gravity Sync is to be simple, so any additional requirements should also be called out when it's executed. After updating, be sure to manually run a `./gravity-sync.sh compare` or `./gravity-sync.sh pull` to validate things are still working as expected. You can run a `./gravity-sync.sh config` at any time to generate a new configuration file.
 
 ## Automation
 
@@ -192,18 +209,14 @@ If you'd like to see the log of what was run the last crontab, you can view that
 
 ## Troubleshooting
 
-If you are unable to run the `gravity-sync.sh` file, make sure it's marked as an executable by Linux.
+If you are just straight up unable to run the `gravity-sync.sh` file, make sure it's marked as an executable by Linux.
 
 ```
 chmod +x gravity-sync.sh
 ```
 
-If you'd like to know what version of the script you have running.
+- If your script prompts for a password on the remote system, make sure that your user account is setup not to require passwords in the sudoers file.
-
+- If you use a non-standard SSH port to connect to your primary Pi-hole, you can add `SSH_PORT='123'` to the bottom of your `gravity-sync.conf` file. (Subsitute 123 for your non-standard port.) This will overwrite the `SSH_PORT=22` at the top of the script as it is imported later in the execution. 
-```
+- If you'd like to know what version of the script you have running by running `./gravity-sync.sh version` 
-./gravity-sync.sh version
+- If the update script fails, make sure you did your original deployment via `git clone` and not a manual install. 
-```
+- If it doesn't kick off, you can manually execute a `git pull` while in the `gravity-sync` directory. 
-
-If the update script fails, make sure you did your original deployment via `git clone` and not a manual install. If it doesn't kick off, you can manually execute a `git pull` while in the `gravity-sync` directory. 
-
-If your script prompts for a password on the remote system, make sure that your user account is setup not to require passwords in the sudoers file.

gravity-sync.conf.example

@@ -1,16 +1,17 @@
 # REQUIRED SETTINGS ######################
 
-# Pi-hole Primary Node in IP or DNS
+# Primary Pi-hole host (in IP or DNS name)
 REMOTE_HOST='192.168.1.10'
 
-# User on Primary PH with SUDO rights
+# User account on primary with SUDO rights
 REMOTE_USER='pi'	
 
 # OPTIONAL SETTING #######################
 
 # Password for REMOTE_USER account
-# Requires SSHPASS installed on server
+# Requires 'SSHPASS' installed on server
+# (ex: sudo apt install sshpass)
 # Less secure and possibly less reliable
-# Leave blank to use (preferred) key-pair SSH auth!
+# Leave blank to use (preferred) key-pair
 
 REMOTE_PASS=''

gravity-sync.sh

@@ -4,16 +4,12 @@
 PROGRAM='Gravity Sync'
 VERSION='1.4.0'
 
-# Must execute from a location in the home folder of the user who own's it (ex: /home/pi/gravity-sync)
+# Execute from the home folder of the user who own's it (ex: 'cd ~/gravity-sync')
-# Configure certificate based SSH authentication between the Pi-hole HA nodes - it does not use passwords
+# For documentation or download updates visit https://github.com/vmstan/gravity-sync
-# Tested against Pihole 5.0 GA on Raspbian Buster and Ubuntu 20.04, but it should work on most configs
-# More installation instructions available at https://vmstan.com/gravity-sync
-# For the latest version please visit https://github.com/vmstan/gravity-sync under Releases
 
 # REQUIRED SETTINGS ##########################
 
-# You MUST define REMOTE_HOST and REMOTE_USER in a file called 'gravity-sync.conf'
+# Run './gravity-sync.sh config' to get started
-# You can copy the 'gravity-sync.conf.example' file in the script directory to get started 
 
 # STANDARD VARIABLES #########################
 
@@ -22,14 +18,18 @@ LOCAL_FOLDR='gravity-sync' # must exist in running user home folder
 CONFIG_FILE='gravity-sync.conf' 	# must exist as explained above
 SYNCING_LOG='gravity-sync.log' 		# will be created in above folder
 CRONJOB_LOG='gravity-sync.cron' 	# only used if cron is configured to output to this file
-BACKUP_FOLD='backup' # must exist as subdirectory in LOCAL_FOLD
+BACKUP_FOLD='backup' 				# must exist as subdirectory in LOCAL_FOLDR
 
 # PH Folder/File Locations
 PIHOLE_DIR='/etc/pihole' 			# default PH data directory
-GRAVITY_FI='gravity.db' # default 
+GRAVITY_FI='gravity.db' 			# default PH database file
 PIHOLE_BIN='/usr/local/bin/pihole' 	# default PH binary directory
 
-# SSH Configuration
+# SSH CONFIGURATION ##########################
+
+# Suggested not to replace these values here
+# Add replacement variables to gravity-sync.conf
+
 SSH_PORT='22' 						# default SSH port
 SSH_PKIF='.ssh/id_rsa.pub' 			# default local SSH key
 
@@ -78,7 +78,8 @@ function import_gs {
 	fi
 }
 
-# Update Function
+# GS Update Functions
+## Master Branch
 function update_gs {
 	TASKTYPE='UPDATE'
 	logs_export 	# dumps log prior to execution because script stops after successful pull
@@ -91,7 +92,7 @@ function update_gs {
 	exit
 }
 
-# Developer Build Update
+## Developer Branch
 function beta_gs {
 	TASKTYPE='BETA'
 	logs_export 	# dumps log prior to execution because script stops after successful pull
@@ -105,7 +106,8 @@ function beta_gs {
 	exit
 }
 
-# Pull Function
+# Gravity Core Functions
+## Pull Function
 function pull_gs {
 	TASKTYPE='PULL'
 	
@@ -185,7 +187,7 @@ function pull_gs {
 	exit_withchange
 }
 
-# Push Function
+## Push Function
 function push_gs {
 	TASKTYPE='PUSH'
 	
@@ -243,7 +245,15 @@ function push_gs {
 }
 
 # Logging Functions
-## Check Log Function
+## Core Logging
+### Write Logs Out
+function logs_export {
+	echo -e "${INFO} Logging Timestamps to ${SYNCING_LOG}"
+	# date >> $HOME/${LOCAL_FOLDR}/${SYNCING_LOG}
+	echo -e $(date) "[${TASKTYPE}]" >> $HOME/${LOCAL_FOLDR}/${SYNCING_LOG}
+}
+
+### Output Sync Logs
 function logs_gs {
 	echo -e "========================================================"
 	echo -e "Recent Complete ${YELLOW}PULL${NC} Executions"
@@ -256,7 +266,8 @@ function logs_gs {
 	exit_nochange
 }
 
-## Crontab Logic
+## Crontab Logs
+### Core Crontab Logs
 function show_crontab {
 	CRONPATH="$HOME/${LOCAL_FOLDR}/${CRONJOB_LOG}"
 	
@@ -281,7 +292,7 @@ function show_crontab {
 	fi
 }
 
-## Check Last Crontab
+### Output Crontab
 function logs_crontab {
 	echo -e "========================================================"
 	echo -e "========================================================"
@@ -292,13 +303,6 @@ function logs_crontab {
 	echo -e "========================================================"
 }
 
-## Log Out
-function logs_export {
-	echo -e "${INFO} Logging Timestamps to ${SYNCING_LOG}"
-	# date >> $HOME/${LOCAL_FOLDR}/${SYNCING_LOG}
-	echo -e $(date) "[${TASKTYPE}]" >> $HOME/${LOCAL_FOLDR}/${SYNCING_LOG}
-}
-
 # Validate Functions
 ## Validate GS Folders
 function validate_gs_folders {
@@ -338,7 +342,8 @@ function validate_ph_folders {
 
 ## Validate SSHPASS
 function validate_os_sshpass {
-    echo -e "${INFO} Checking SSH Configuration"
+	MESSAGE="Checking SSH Configuration"
+    echo -e "${INFO} ${MESSAGE}"
 	
 	if hash sshpass 2>/dev/null
     then
@@ -371,43 +376,7 @@ function validate_os_sshpass {
 	
 }
 
-# List GS Arguments
+## Error Validation
-function list_gs_arguments {
-	echo -e "Usage: $0 [options]"
-	echo -e "Example: '$0 pull'"
-	echo -e ""
-	echo -e "Replication Options:"
-	echo -e " ${YELLOW}pull${NC}		Sync the ${GRAVITY_FI} configuration on primary PH to this server"
-	echo -e " ${YELLOW}push${NC}		Force any changes made on this server back to the primary PH"
-	echo -e " ${YELLOW}compare${NC}	Check to see if there is any variance between primary and secondary"
-	echo -e ""
-	echo -e "Update Options:"
-	echo -e " ${YELLOW}update${NC}		Use GitHub to update this script to the latest version available"
-	echo -e " ${YELLOW}beta${NC}		Use GitHub to update this script to the latest beta version available"
-	echo -e ""
-	echo -e "Debug Options:"
-	echo -e " ${YELLOW}version${NC}	Display the version of the current installed script"
-	echo -e " ${YELLOW}logs${NC}		Show recent successful jobs"
-	echo -e " ${YELLOW}cron${NC}		Display output of last crontab execution"
-	echo -e ""
-	exit_nochange
-}
-
-# Exit Codes
-## No Changes Made
-function exit_nochange {
-	echo -e "${INFO} ${PROGRAM} ${TASKTYPE} Aborting"
-	exit 0
-}
-
-## Changes Made
-function exit_withchange {
-	SCRIPT_END=$SECONDS
-	echo -e "${INFO} ${PROGRAM} ${TASKTYPE} Completed in $((SCRIPT_END-SCRIPT_START)) seconds"
-	exit 0
-}
-
-# Error Validation
 function error_validate {
 	if [ "$?" != "0" ]; then
 	    echo -e "\r${FAIL} ${MESSAGE}"
@@ -417,12 +386,7 @@ function error_validate {
 	fi
 }
 
-# Output Version
+## Validate Sync Required
-function show_version {
-	echo -e "${INFO} ${PROGRAM} ${VERSION}"
-}
-
-# Look for Changes
 function md5_compare {
 	echo -e "${INFO} Comparing ${GRAVITY_FI} Changes"
 	
@@ -446,7 +410,8 @@ function md5_compare {
 	
 }
 
-# Generate Config
+# Configuration Management
+## Generate New Configuration
 function config_generate {
 	MESSAGE="Creating ${CONFIG_FILE} from Template"
 	echo -en "${STAT} ${MESSAGE}"
@@ -518,9 +483,7 @@ function config_generate {
 			
 			echo -e "========================================================"
 			echo -e "========================================================"
-			echo -e ""
 			ssh-keygen -t rsa
-			echo -e ""
 			echo -e "========================================================"
 			echo -e "========================================================"
 		fi
@@ -538,14 +501,12 @@ function config_generate {
 			MESSAGE="Registering Key-Pair on ${REMOTE_HOST}"
 			echo -e "${INFO} ${MESSAGE}"
 			
-			MESSAGE="Enter ${REMOTE_USER}@${REMOTE_HOST}"
+			MESSAGE="Enter ${REMOTE_USER}@${REMOTE_HOST} Password"
 			echo -e "${NEED} ${MESSAGE}"
 			
 			echo -e "========================================================"
 			echo -e "========================================================"
-			echo -e ""
 			ssh-copy-id -f -i $HOME/${SSH_PKIF} ${REMOTE_USER}@${REMOTE_HOST}
-			echo -e ""
 			echo -e "========================================================"
 			echo -e "========================================================"
 		else
@@ -559,7 +520,7 @@ function config_generate {
 	exit_withchange
 }
 
-# Delete Existing Configuration
+## Delete Existing Configuration
 function config_delete {
 	source $HOME/${LOCAL_FOLDR}/${CONFIG_FILE}
 	MESSAGE="Configuration File Exists"
@@ -594,6 +555,47 @@ function config_delete {
 	done
 }
 
+# Exit Codes
+## No Changes Made
+function exit_nochange {
+	echo -e "${INFO} ${PROGRAM} ${TASKTYPE} Aborting"
+	exit 0
+}
+
+## Changes Made
+function exit_withchange {
+	SCRIPT_END=$SECONDS
+	echo -e "${INFO} ${PROGRAM} ${TASKTYPE} Completed in $((SCRIPT_END-SCRIPT_START)) seconds"
+	exit 0
+}
+
+## List GS Arguments
+function list_gs_arguments {
+	echo -e "Usage: $0 [options]"
+	echo -e "Example: '$0 pull'"
+	echo -e ""
+	echo -e "Replication Options:"
+	echo -e " ${YELLOW}pull${NC}		Sync the ${GRAVITY_FI} configuration on primary PH to this server"
+	echo -e " ${YELLOW}push${NC}		Force any changes made on this server back to the primary PH"
+	echo -e " ${YELLOW}compare${NC}	Check to see if there is any variance between primary and secondary"
+	echo -e ""
+	echo -e "Update Options:"
+	echo -e " ${YELLOW}update${NC}		Use GitHub to update this script to the latest version available"
+	echo -e " ${YELLOW}beta${NC}		Use GitHub to update this script to the latest beta version available"
+	echo -e ""
+	echo -e "Debug Options:"
+	echo -e " ${YELLOW}version${NC}	Display the version of the current installed script"
+	echo -e " ${YELLOW}logs${NC}		Show recent successful jobs"
+	echo -e " ${YELLOW}cron${NC}		Display output of last crontab execution"
+	echo -e ""
+	exit_nochange
+}
+
+# Output Version
+function show_version {
+	echo -e "${INFO} ${PROGRAM} ${VERSION}"
+}
+
 # SCRIPT EXECUTION ###########################
 SCRIPT_START=$SECONDS
 	
@@ -708,7 +710,6 @@ case $# in
 					echo -e "${INFO} ${MESSAGE}"
 					
 					config_generate
-
 				fi
 				
 			;;