From b60ca25e53a95d47ca533c93a0f5964aef9600bb Mon Sep 17 00:00:00 2001
From: Joshua Tauberer <jt@occams.info>
Date: Sat, 7 Jun 2014 14:55:57 -0400
Subject: [PATCH] add comments to the new get_default_hostname etc. functions,
 and simplify the logic in the Vagrantfile and start.sh so that we always call
 into the same two functions

---
 Vagrantfile        |  2 +-
 setup/functions.sh | 25 +++++++++++++++++++++----
 setup/start.sh     |  9 ++-------
 3 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/Vagrantfile b/Vagrantfile
index 06c660c..861f276 100644
--- a/Vagrantfile
+++ b/Vagrantfile
@@ -18,7 +18,7 @@ Vagrant.configure("2") do |config|
 	# machine figure out its own public IP and it'll take a
 	# subdomain on our justtesting.email domain so we can get
 	# started quickly.
-    export PUBLIC_IP=auto-web
+    export PUBLIC_IP=auto
     export PUBLIC_HOSTNAME=auto-easy
     export CSR_COUNTRY=US
 
diff --git a/setup/functions.sh b/setup/functions.sh
index d98405f..1a18b28 100644
--- a/setup/functions.sh
+++ b/setup/functions.sh
@@ -20,30 +20,47 @@ function apt_install {
 }
 
 function get_default_hostname {
+	# Guess the machine's hostname. It should be a fully qualified
+	# domain name suitable for DNS. None of these calls may provide
+	# the right value, but it's the best guess we can make.
 	set -- $(hostname --fqdn      2>/dev/null ||
                  hostname --all-fqdns 2>/dev/null ||
                  hostname             2>/dev/null)
-	printf '%s\n' "$1"
+	printf '%s\n' "$1" # return this value
 }
 
 function get_default_publicip {
-	get_publicip_from_web_service || get_publicip_from_dns
+	# Get the machine's public IP address. The machine might have
+	# an IP on a private network, but the IP address that we put
+	# into DNS must be one on the public Internet. Try a public
+	# API, but if that fails (maybe we don't have Internet access
+	# right now) then use the IP address that this machine knows
+	# itself as.
+	get_publicip_from_web_service || get_publicip_fallback
 }
 
 function get_publicip_from_web_service {
+	# This seems to be the most reliable way to determine the
+	# machine's public IP address: asking a very nice web API
+	# for how they see us. Thanks go out to icanhazip.com.
 	curl --fail --silent icanhazip.com 2>/dev/null
 }
 
-function get_publicip_from_dns {
+function get_publicip_fallback {
+	# Return the IP address that this machine knows itself as.
+	# It certainly may not be the IP address that this machine
+	# operates as on the public Internet. The machine might
+	# have multiple addresses if it has multiple network adapters.
 	set -- $(hostname --ip-address       2>/dev/null) \
 	       $(hostname --all-ip-addresses 2>/dev/null)
 	while (( $# )) && is_loopback_ip "$1"; do
 		shift
 	done
-	printf '%s\n' "$1"
+	printf '%s\n' "$1" # return this value
 }
 
 function is_loopback_ip {
+	# helper for get_publicip_fallback
 	[[ "$1" == 127.* ]]
 }
 
diff --git a/setup/start.sh b/setup/start.sh
index cec5c90..51a1ebd 100755
--- a/setup/start.sh
+++ b/setup/start.sh
@@ -71,18 +71,13 @@ fi
 
 # Automatic configuration, e.g. as used in our Vagrant configuration.
 if [ "$PUBLIC_IP" == "auto" ]; then
-	# Assume `get_publicip_from_dns` gives the correct public IP address for the machine.
-	PUBLIC_IP=`get_publicip_from_dns`
-	echo "IP Address: $PUBLIC_IP"
-fi
-if [ "$PUBLIC_IP" == "auto-web" ]; then
 	# Use a public API to get our public IP address.
-	PUBLIC_IP=`get_publicip_from_web_service`
+	PUBLIC_IP=`get_default_publicip`
 	echo "IP Address: $PUBLIC_IP"
 fi
 if [ "$PUBLIC_HOSTNAME" == "auto-easy" ]; then
 	# Generate a probably-unique subdomain under our justtesting.email domain.
-	PUBLIC_HOSTNAME=m`get_publicip_from_dns | sha1sum | cut -c1-5`.justtesting.email
+	PUBLIC_HOSTNAME=m`get_default_publicip | sha1sum | cut -c1-5`.justtesting.email
 	echo "Public Hostname: $PUBLIC_HOSTNAME"
 fi