Implement help option -h

bin/probe_saml_idp.sh

@@ -16,6 +16,67 @@
 # limitations under the License.
 #######################################################################
 
+script_version="0.1"
+user_agent_string="SAML IdP Probe ${script_version}"
+
+#######################################################################
+# help message
+#######################################################################
+
+display_help () {
+/bin/cat <<- HELP_MSG
+	${user_agent_string}
+
+	Given a single identifier, assumed to be an IdP entityID, probe
+	all browser-facing SAML2 SSO endpoints in metadata.
+
+	Usage: ${0##*/} [-hvq] [-t CONNECT_TIME [-m MAX_TIME]] [-r MAX_REDIRS] (-u MDQ_BASE_URL | -f MD_PATH) ID
+	
+	Options:
+	   -h      Display this message
+	   -v      Write verbose messages to stdout
+	   -q      Run quietly (i.e., write no messages to stdout)
+	   -t      Time (in secs) to connect to the host
+	   -m      Maximum time (in secs) of a complete probe
+	   -r      Maximum number of HTTP redirects followed
+	   -u      Base URL of a Metadata Query Server
+	   -f      Path to a local metadata file
+
+	Option -h is mutually exclusive of all other options. Options
+	-q and -v are mutually exclusive of each other. Options -u and -f 
+	are mutually exclusive of each other as well.
+
+	The argument of the -t option is the TCP connect time, that is, 
+	the maximum time (in secs) allotted to the TCP connection. Note 
+	that the TCP connect time includes the time it takes to do a 
+	DNS name lookup. Since the latter is unconstrained, it may
+	consume all available TCP connect time. Thus the TCP connect 
+	time should be kept small (on the order of a few seconds) since 
+	larger values will slow this script considerably.
+
+	The argument of the -m option is the maximum total time (in secs)
+	allotted to each probe. A reasonable value is a few seconds
+	beyond the TCP connect time. Any value less than the TCP connect
+	time causes the script to immediately fail.
+	
+	Entity metadata is required to process each identifier. Metadata is 
+	obtained in one of two ways, by consulting a Metadata Query Server 
+	just-in-time or by using a pre-provisioned metadata aggregate. These
+	correspond to options -u and -f, respectively. Exactly one of these
+	options is required.
+	
+	Option -f takes an optional file argument (MD_PATH), the absolute 
+	path to a local SAML metadata file. The script searches this file for 
+	a corresponding entity descriptor as it processes each identifier.
+	
+	Option -u takes an optional URI argument (MDQ_BASE_URL), the base 
+	URL of a Metadata Query Server (i.e., a server that conforms to the 
+	Metadata Query Protocol). The base URL is used to construct an MDQ 
+	request URL, which the script uses to request entity metadata 
+	just-in-time.
+HELP_MSG
+}
+
 #######################################################################
 # Bootstrap
 #######################################################################
@@ -155,6 +216,11 @@ if $md_query_mode; then
 	fi
 	$verbose_mode && printf "$script_name using base URL: %s\n" "$mdq_base_url"
 elif $md_file_mode; then
+
+	# temporary
+	echo "ERROR: $script_name: option -f not yet implemented" >&2
+	exit 2
+
 	if [ -z "$md_path" ]; then
 		echo "ERROR: $script_name: option -f requires an argument" >&2
 		exit 2