Import media selection/preparation framework (sysinstall inspired). Makes

accessing files from various types of media nice and abstracted away from
the wet-work involved in preparing, validating, and initializing those
types of media. This will be used for the package management system module
and other modules that need access to files and want to allow the user to
decide where those files come from (either in a scripted fashion, prompted
fashion, or any combination thereof).

Heavily inspired by sysinstall and even uses the same reserved words so
that scripts are portable. Coded over months, tested continuously through-
out, and reviewed several times.

Some notes about the changes:
- Move network-setting acquisition/validation routines to media/tcpip.subr
- The options screen from sysinstall has been converted to a dialog menu
- The "UFS" media choice is renamed to "Directory" to reflect how sysinstall
  treats the choice and a new [true] "UFS" media choice has been added that
  acts on real UFS partitions (such as external disks with disklabels).
- Many more help files have been resurrected from sysinstall (I noticed that
  some of the content seems a bit dated; I gave them a once-over but they
  could really use an update).
- A total of 10 media choices are presented (via mediaGetType) including:
  CD/DVD, FTP, FTP Passive, HTTP Proxy, Directory, NFS, DOS, UFS, Floppy, USB
- Novel struct/device management layer for managing the issue of passing
  more information than can comfortably fit in an argument list.

1 files changed, 893 insertions, 0 deletions

diff --git a/usr.sbin/bsdconfig/share/media/ftp.subr b/usr.sbin/bsdconfig/share/media/ftp.subr
new file mode 100644
index 0000000..ecc7724
--- /dev/null
+++ b/usr.sbin/bsdconfig/share/media/ftp.subr
@@ -0,0 +1,893 @@
+if [ ! "$_MEDIA_FTP_SUBR" ]; then _MEDIA_FTP_SUBR=1
+#
+# Copyright (c) 2012-2013 Devin Teske
+# All Rights Reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+# SUCH DAMAGE.
+#
+# $FreeBSD$
+#
+############################################################ INCLUDES
+
+BSDCFG_SHARE="/usr/share/bsdconfig"
+. $BSDCFG_SHARE/common.subr || exit 1
+f_dprintf "%s: loading includes..." media/ftp.subr
+f_include $BSDCFG_SHARE/struct.subr
+f_include $BSDCFG_SHARE/device.subr
+f_include $BSDCFG_SHARE/dialog.subr
+f_include $BSDCFG_SHARE/strings.subr
+f_include $BSDCFG_SHARE/variable.subr
+f_include $BSDCFG_SHARE/media/common.subr
+f_include $BSDCFG_SHARE/media/tcpip.subr
+f_include $BSDCFG_SHARE/media/network.subr
+
+BSDCFG_LIBE="/usr/libexec/bsdconfig"
+f_include_lang $BSDCFG_LIBE/include/messages.subr
+
+############################################################ GLOBALS
+
+FTP_SKIP_RESOLV=
+
+URL_MAX=261261 # according to actual fetch(1) test-results
+
+FTP_DIRS="
+	.
+	releases/$UNAME_P
+	snapshots/$UNAME_P
+	pub/FreeBSD
+	pub/FreeBSD/releases/$UNAME_P
+	pub/FreeBSD/snapshots/$UNAME_P
+	pub/FreeBSD-Archive/old-releases/$UNAME_P
+" # END-QUOTE
+
+############################################################ FUNCTIONS
+
+# f_dialog_menu_media_ftp
+#
+# Prompt the user to select from a range of ``built-in'' FTP servers or specify
+# their own. If the user makes a choice and doesn't cancel or press Esc, stores
+# the user's choice in VAR_FTP_PATH (see variables.subr) and returns success.
+#
+f_dialog_menu_media_ftp()
+{
+	f_dialog_title "$msg_please_select_a_freebsd_ftp_distribution_site"
+	local title="$DIALOG_TITLE" btitle="$DIALOG_BACKTITLE"
+	f_dialog_title_restore
+
+	local prompt="$msg_please_select_the_site_closest_to_you_or_other"
+	local hline="$msg_select_a_site_thats_close"
+	local menu_list="
+		'$msg_main_site'          'ftp.freebsd.org'
+		'URL'                     '$msg_specify_some_other_ftp_site'
+		'$msg_snapshots_server_japan'
+		                          'snapshots.jp.freebsd.org'
+		'$msg_snapshots_server_sweden'
+		                          'snapshots.se.freebsd.org'
+		'IPv6 $msg_main_site'     'ftp.freebsd.org'
+		' IPv6 $msg_ireland'      'ftp3.ie.freebsd.org'
+		' IPv6 $msg_israel'       'ftp.il.freebsd.org'
+		' IPv6 $msg_japan'        'ftp2.jp.freebsd.org'
+		' IPv6 $msg_usa'          'ftp4.us.freebsd.org'
+		' IPv6 $msg_turkey'       'ftp2.tr.freebsd.org'
+		'$msg_primary'            'ftp1.freebsd.org'
+		' $msg_primary #2'        'ftp2.freebsd.org'
+		' $msg_primary #3'        'ftp3.freebsd.org'
+		' $msg_primary #4'        'ftp4.freebsd.org'
+		' $msg_primary #5'        'ftp5.freebsd.org'
+		' $msg_primary #6'        'ftp6.freebsd.org'
+		' $msg_primary #7'        'ftp7.freebsd.org'
+		' $msg_primary #8'        'ftp8.freebsd.org'
+		' $msg_primary #9'        'ftp9.freebsd.org'
+		' $msg_primary #10'       'ftp10.freebsd.org'
+		' $msg_primary #11'       'ftp11.freebsd.org'
+		' $msg_primary #12'       'ftp12.freebsd.org'
+		' $msg_primary #13'       'ftp13.freebsd.org'
+		' $msg_primary #14'       'ftp14.freebsd.org'
+		'$msg_argentina'          'ftp.ar.freebsd.org'
+		'$msg_australia'          'ftp.au.freebsd.org'
+		' $msg_australia #2'      'ftp2.au.freebsd.org'
+		' $msg_australia #3'      'ftp3.au.freebsd.org'
+		'$msg_austria'            'ftp.at.freebsd.org'
+		' $msg_austria #2'        'ftp2.at.freebsd.org'
+		'$msg_brazil'             'ftp.br.freebsd.org'
+		' $msg_brazil #2'         'ftp2.br.freebsd.org'
+		' $msg_brazil #3'         'ftp3.br.freebsd.org'
+		' $msg_brazil #4'         'ftp4.br.freebsd.org'
+		' $msg_brazil #5'         'ftp5.br.freebsd.org'
+		' $msg_brazil #6'         'ftp6.br.freebsd.org'
+		' $msg_brazil #7'         'ftp7.br.freebsd.org'
+		'$msg_canada'             'ftp.ca.freebsd.org'
+		'$msg_china'              'ftp.cn.freebsd.org'
+		' $msg_china #2'          'ftp2.cn.freebsd.org'
+		'$msg_croatia'            'ftp.hr.freebsd.org'
+		'$msg_czech_republic'     'ftp.cz.freebsd.org'
+		'$msg_denmark'            'ftp.dk.freebsd.org'
+		' $msg_denmark #2'        'ftp2.dk.freebsd.org'
+		'$msg_estonia'            'ftp.ee.freebsd.org'
+		'$msg_finland'            'ftp.fi.freebsd.org'
+		'$msg_france'             'ftp.fr.freebsd.org'
+		' $msg_france #2'         'ftp2.fr.freebsd.org'
+		' $msg_france #3'         'ftp3.fr.freebsd.org'
+		' $msg_france #5'         'ftp5.fr.freebsd.org'
+		' $msg_france #6'         'ftp6.fr.freebsd.org'
+		' $msg_france #8'         'ftp8.fr.freebsd.org'
+		'$msg_germany'            'ftp.de.freebsd.org'
+		' $msg_germany #2'        'ftp2.de.freebsd.org'
+		' $msg_germany #3'        'ftp3.de.freebsd.org'
+		' $msg_germany #4'        'ftp4.de.freebsd.org'
+		' $msg_germany #5'        'ftp5.de.freebsd.org'
+		' $msg_germany #6'        'ftp6.de.freebsd.org'
+		' $msg_germany #7'        'ftp7.de.freebsd.org'
+		' $msg_germany #8'        'ftp8.de.freebsd.org'
+		'$msg_greece'             'ftp.gr.freebsd.org'
+		' $msg_greece #2'         'ftp2.gr.freebsd.org'
+		'$msg_hungary'            'ftp.hu.freebsd.org'
+		'$msg_iceland'            'ftp.is.freebsd.org'
+		'$msg_ireland'            'ftp.ie.freebsd.org'
+		' $msg_ireland #2'        'ftp2.ie.freebsd.org'
+		' $msg_ireland #3'        'ftp3.ie.freebsd.org'
+		'$msg_israel'             'ftp.il.freebsd.org'
+		'$msg_italy'              'ftp.it.freebsd.org'
+		'$msg_japan'              'ftp.jp.freebsd.org'
+		' $msg_japan #2'          'ftp2.jp.freebsd.org'
+		' $msg_japan #3'          'ftp3.jp.freebsd.org'
+		' $msg_japan #4'          'ftp4.jp.freebsd.org'
+		' $msg_japan #5'          'ftp5.jp.freebsd.org'
+		' $msg_japan #6'          'ftp6.jp.freebsd.org'
+		' $msg_japan #7'          'ftp7.jp.freebsd.org'
+		' $msg_japan #8'          'ftp8.jp.freebsd.org'
+		' $msg_japan #9'          'ftp9.jp.freebsd.org'
+		'$msg_korea'              'ftp.kr.freebsd.org'
+		' $msg_korea #2'          'ftp2.kr.freebsd.org'
+		'$msg_lithuania'          'ftp.lt.freebsd.org'
+		'$msg_netherlands'        'ftp.nl.freebsd.org'
+		' $msg_netherlands #2'    'ftp2.nl.freebsd.org'
+		'$msg_norway'             'ftp.no.freebsd.org'
+		' $msg_norway #3'         'ftp3.no.freebsd.org'
+		'$msg_poland'             'ftp.pl.freebsd.org'
+		' $msg_poland #2'         'ftp2.pl.freebsd.org'
+		' $msg_poland #5'         'ftp5.pl.freebsd.org'
+		'$msg_portugal'           'ftp.pt.freebsd.org'
+		' $msg_portugal #2'       'ftp2.pt.freebsd.org'
+		' $msg_portugal #4'       'ftp4.pt.freebsd.org'
+		'$msg_romania'            'ftp.ro.freebsd.org'
+		'$msg_russia'             'ftp.ru.freebsd.org'
+		' $msg_russia #2'         'ftp2.ru.freebsd.org'
+		' $msg_russia #3'         'ftp3.ru.freebsd.org'
+		' $msg_russia #4'         'ftp4.ru.freebsd.org'
+		'$msg_singapore'          'ftp.sg.freebsd.org'
+		'$msg_slovak_republic'    'ftp.sk.freebsd.org'
+		'$msg_slovenia'           'ftp.si.freebsd.org'
+		' $msg_slovenia #2'       'ftp2.si.freebsd.org'
+		'$msg_south_africa'       'ftp.za.freebsd.org'
+		' $msg_south_africa #2'   'ftp2.za.freebsd.org'
+		' $msg_south_africa #3'   'ftp3.za.freebsd.org'
+		' $msg_south_africa #4'   'ftp4.za.freebsd.org'
+		'$msg_spain'              'ftp.es.freebsd.org'
+		' $msg_spain #2'          'ftp2.es.freebsd.org'
+		' $msg_spain #3'          'ftp3.es.freebsd.org'
+		'$msg_sweden'             'ftp.se.freebsd.org'
+		' $msg_sweden #2'         'ftp2.se.freebsd.org'
+		' $msg_sweden #3'         'ftp3.se.freebsd.org'
+		' $msg_sweden #4'         'ftp4.se.freebsd.org'
+		' $msg_sweden #5'         'ftp5.se.freebsd.org'
+		'$msg_switzerland'        'ftp.ch.freebsd.org'
+		' $msg_switzerland #2'    'ftp2.ch.freebsd.org'
+		'$msg_taiwan'             'ftp.tw.freebsd.org'
+		' $msg_taiwan #2'         'ftp2.tw.freebsd.org'
+		' $msg_taiwan #3'         'ftp3.tw.freebsd.org'
+		' $msg_taiwan #4'         'ftp4.tw.freebsd.org'
+		' $msg_taiwan #6'         'ftp6.tw.freebsd.org'
+		' $msg_taiwan #11'        'ftp11.tw.freebsd.org'
+		'$msg_turkey'             'ftp.tr.freebsd.org'
+		' $msg_turkey #2'         'ftp2.tr.freebsd.org'
+		'$msg_uk'                 'ftp.uk.freebsd.org'
+		' $msg_uk #2'             'ftp2.uk.freebsd.org'
+		' $msg_uk #3'             'ftp3.uk.freebsd.org'
+		' $msg_uk #4'             'ftp4.uk.freebsd.org'
+		' $msg_uk #5'             'ftp5.uk.freebsd.org'
+		' $msg_uk #6'             'ftp6.uk.freebsd.org'
+		'$msg_ukraine'            'ftp.ua.freebsd.org'
+		' $msg_ukraine #2'        'ftp2.ua.freebsd.org'
+		' $msg_ukraine #5'        'ftp5.ua.freebsd.org'
+		' $msg_ukraine #6'        'ftp6.ua.freebsd.org'
+		' $msg_ukraine #7'        'ftp7.ua.freebsd.org'
+		' $msg_ukraine #8'        'ftp8.ua.freebsd.org'
+		'$msg_usa #1'             'ftp1.us.freebsd.org'
+		' $msg_usa #2'            'ftp2.us.freebsd.org'
+		' $msg_usa #3'            'ftp3.us.freebsd.org'
+		' $msg_usa #4'            'ftp4.us.freebsd.org'
+		' $msg_usa #5'            'ftp5.us.freebsd.org'
+		' $msg_usa #6'            'ftp6.us.freebsd.org'
+		' $msg_usa #7'            'ftp7.us.freebsd.org'
+		' $msg_usa #8'            'ftp8.us.freebsd.org'
+		' $msg_usa #9'            'ftp9.us.freebsd.org'
+		' $msg_usa #10'           'ftp10.us.freebsd.org'
+		' $msg_usa #11'           'ftp11.us.freebsd.org'
+		' $msg_usa #12'           'ftp12.us.freebsd.org'
+		' $msg_usa #13'           'ftp13.us.freebsd.org'
+		' $msg_usa #14'           'ftp14.us.freebsd.org'
+		' $msg_usa #15'           'ftp15.us.freebsd.org'
+	" # END-QUOTE
+
+	local size
+	size=$( eval f_dialog_menu_size \
+	        	\"\$title\"  \
+	        	\"\$btitle\" \
+	        	\"\$prompt\" \
+	        	\"\$hline\"  \
+	        	$menu_list   )
+
+	local dialog_menu retval mtag value
+	dialog_menu=$( eval $DIALOG \
+		--title \"\$title\"             \
+		--backtitle \"\$btitle\"        \
+		--hline \"\$hline\"             \
+		--ok-label \"\$msg_ok\"         \
+		--cancel-label \"\$msg_cancel\" \
+		--menu \"\$prompt\" $size       \
+		$menu_list                      \
+		2>&1 >&$DIALOG_TERMINAL_PASSTHRU_FD
+	)
+	retval=$?
+	setvar DIALOG_MENU_$$ "$dialog_menu"
+	mtag=$( f_dialog_menutag )
+
+	[ $retval -eq 0 ] || return $FAILURE
+
+	case "$mtag" in
+	URL) setvar $VAR_FTP_PATH "other" ;;
+	*)
+		value=$( eval f_dialog_menutag2item \"\$mtag\" $menu_list )
+		setvar $VAR_FTP_PATH "ftp://$value"
+	esac
+	
+	return $SUCCESS
+}
+
+# f_media_set_ftp
+#
+# Return success if we both found and set the media type to be an FTP server.
+# Variables from variable.subr that can be used to script user input:
+#
+# 	VAR_FTP_PATH
+# 		Can be a URL (including "ftp://" protocol-prefix) or "other"
+# 		(user is prompted to enter FTP URL). If a URL, can optionally
+# 		contain directory prefix after hostname/port. Valid examples
+# 		include:
+# 			ftp://myhost
+# 			ftp://somename:21/pub/
+# 			ftp://192.168.2.3/pub/
+# 			ftp://[::1]:21/
+# 		The default port if not specified is 21.
+# 	VAR_NAMESERVER [Optional]
+# 		If set, overrides resolv.conf(5) and sets the nameserver that
+# 		is used to convert names into addresses (when a name converts
+# 		into multiple addresses, the first address to successfully
+# 		connect is used).
+#
+# Meanwhile, the following variables from variable.subr are set after
+# successful execution:
+#
+# 	VAR_FTP_HOST
+# 		The FTP host to connect to, parsed from VAR_FTP_PATH. In the
+# 		example case of IPv6 where VAR_FTP_PATH is a "ftp://[::1]" this
+# 		variable will be set to "::1" (the outer brackets are removed).
+# 	VAR_FTP_PORT
+# 		The TCP port to connect to, parsed from VAR_FTP_PATH. Usually
+# 		21 unless VAR_FTP_PATH was of one of the following forms:
+# 			ftp://hostname:OTHER_PORT
+# 			ftp://hostname:OTHER_PORT/*
+# 			ftp://ip:OTHER_PORT
+# 			ftp://ip:OTHER_PORT/*
+# 			ftp://[ip6]:OTHER_PORT
+# 			ftp://[ip6]:OTHER_PORT/*
+# 	VAR_FTP_DIR
+# 		If VAR_FTP_PATH contained a directory element (e.g.,
+# 		"ftp://localhost/pub") this variable contains only the
+# 		directory element (e.g., "/pub").
+#
+f_media_set_ftp()
+{
+	f_media_close
+
+	local url
+	f_getvar $VAR_FTP_PATH url
+
+	# If we've been through here before ...
+	if f_struct device_network && [ "${url#$msg_other}" ]; then
+		f_dialog_yesno "$msg_reuse_old_ftp_site_selection_values" ||
+			url=
+	fi
+
+	if [ ! "$url" ]; then
+		f_dialog_menu_media_ftp || return $FAILURE
+		f_getvar $VAR_FTP_PATH url
+	fi
+	[ "$url" ] || return $FAILURE
+
+	case "$url" in
+	other)
+		setvar $VAR_FTP_PATH "ftp://"
+		f_variable_get_value $VAR_FTP_PATH \
+			"$msg_please_specify_url_of_a_freebsd_distribution"
+		f_getvar $VAR_FTP_PATH url
+		if [ ! "${url#ftp://}" ]; then
+			unset $VAR_FTP_PATH
+			return $FAILURE
+		fi
+		if [ ${#url} -gt ${URL_MAX:-261261} ]; then
+			f_show_msg "$msg_length_of_specified_url_is_too_long" \
+			           ${#url} ${URL_MAX:-261261}
+			unset $VAR_FTP_PATH
+			return $FAILURE
+		fi
+		case "$url" in
+		ftp://*) : valid URL ;;
+		*)
+			f_show_msg "$msg_sorry_invalid_url" "$url"
+			unset $VAR_FTP_PATH
+			return $FAILURE
+		esac
+	esac
+	case "$url" in
+	ftp://*) : valid URL ;;
+	*)
+		f_show_msg "$msg_sorry_invalid_url" "$url"
+		unset $VAR_FTP_PATH
+		return $FAILURE
+	esac
+
+	# Set the name of the FTP device to the URL
+	f_struct_new DEVICE device_ftp
+	device_ftp set name "$url"
+
+	if ! f_struct device_network ||
+	   ! f_dialog_yesno "$msg_youve_already_done_the_network_configuration"
+	then
+		f_struct device_network &&
+			f_device_shutdown network
+		if ! f_device_select_tcp; then
+			unset $VAR_FTP_PATH
+			return $FAILURE
+		fi
+		local dev
+		f_getvar $VAR_NETWORK_DEVICE dev
+		f_struct_copy "device_$dev" device_network
+	fi
+	if ! f_device_init network; then
+		f_dprintf "f_media_set_ftp: %s" "$msg_net_device_init_failed"
+		unset $VAR_FTP_PATH
+		return $FAILURE
+	fi
+
+	local hostname="${url#*://}" port=21 dir=/
+	case "$hostname" in
+	"["*"]")
+		hostname="${hostname#\[}"
+		hostname="${hostname%%\]*}"
+		;;
+	"["*"]/"*)
+		hostname="${hostname#\[}"
+		dir="/${hostname#*/}"
+		hostname="${hostname%%\]*}"
+		;;
+	*"/"*)
+		dir="/${hostname#*/}"
+		hostname="${hostname%%/*}"
+		;;
+	"["*"]:"*)
+		hostname="${hostname#\[}"
+		port="${hostname#*\]:}"
+		port="${port%%[!0-9]*}"
+		hostname="${hostname%%\]:*}"
+		;;
+	*)
+		hostname="${hostname%%/*}"
+	esac
+
+	f_dprintf "hostname = \`%s'" "$hostname"
+	f_dprintf "dir = \`%s'" "$dir"
+	f_dprintf "port \# = \`%d'" "$port"
+
+	local ns
+	f_getvar $VAR_NAMESERVER ns
+	[ "$ns" ] || f_resolv_conf_nameservers ns
+	if [ "$ns" -a ! "$FTP_SKIP_RESOLV" ] && ! {
+		f_validate_ipaddr "$hostname" ||
+		f_validate_ipaddr6 "$hostname"
+	}; then
+		f_show_info "$msg_looking_up_host" "$hostname"
+		f_dprintf "%s: Looking up hostname, %s, using host(1)" \
+		          "f_media_set_ftp" "$hostname"
+		if ! f_quietly f_host_lookup "$hostname"; then
+			f_show_msg "$msg_cannot_resolve_hostname" "$hostname"
+			f_struct device_network &&
+				f_device_shutdown network
+			f_struct_free device_network
+			unset $VAR_FTP_PATH
+			return $FAILURE
+		fi
+		f_dprintf "Found DNS entry for %s successfully." "$hostname"
+	fi
+
+	setvar $VAR_FTP_HOST "$hostname"
+	setvar $VAR_FTP_PORT "$port"
+	setvar $VAR_FTP_DIR  "$dir"
+
+	device_ftp set type     $DEVICE_TYPE_FTP
+	device_ftp set init     f_media_init_ftp
+	device_ftp set get      f_media_get_ftp
+	device_ftp set shutdown f_media_shutdown_ftp
+	device_ftp set private  network
+	f_struct_copy device_ftp device_media
+	f_struct_free device_ftp
+
+	return $SUCCESS
+}
+
+# f_media_set_ftp_active
+#
+# Wrapper to f_media_set_ftp to access FTP servers actively.
+#
+f_media_set_ftp_active()
+{
+	setvar $VAR_FTP_STATE "active"
+	f_media_set_ftp
+}
+
+# f_media_set_ftp_passive
+#
+# Wrapper to f_media_set_ftp to access FTP servers passively.
+#
+f_media_set_ftp_passive()
+{
+	setvar $VAR_FTP_STATE "passive"
+	f_media_set_ftp
+}
+
+# f_media_set_ftp_userpass
+#
+# Prompt the user to enter/confirm the username/password variables that will
+# be used to communicate with the FTP servers. Returns success if the user does
+# not cancel or press Esc to either username or password.
+#
+# Variables from variable.subr that can be used to script user input:
+#
+# 	VAR_FTP_USER
+# 		The username to send via ftp(1) when connecting to an FTP
+# 		server.
+# 	VAR_FTP_PASS
+# 		The password to send with the above username.
+#
+# Does not prompt for confirmation of values if VAR_NONINTERACTIVE is set (see
+# variable.subr for more information).
+#
+f_media_set_ftp_userpass()
+{
+	local user pass
+	f_variable_get_value $VAR_FTP_USER \
+		"$msg_please_enter_the_username_you_wish_to_login_as"
+	f_getvar $VAR_FTP_USER user
+	if [ "$user" ]; then
+		f_variable_get_value $VAR_FTP_PASS \
+			"$msg_please_enter_the_password_for_this_user"
+		f_getvar $VAR_FTP_PASS pass
+	else
+		pass=
+	fi
+	[ "$pass" ] # Return status
+}
+
+# f_device_network_up $device
+#
+# Brings up attached network device, if any - takes FTP device as arg.
+#
+f_device_network_up()
+{
+	local dev="$1" netDev
+	device_$dev get private netDev || return $SUCCESS # No net == happy net
+	f_device_init $netDev
+}
+
+# f_device_network_down $device
+#
+# Brings down attached network device, if any - takes FTP device as arg.
+#
+f_device_network_down()
+{
+	local dev="$1" netDev
+	device_$dev get private netDev || return $SUCCESS
+	f_device_shutdown $netDev
+}
+
+# f_media_init_ftp $device
+#
+# Initializes the FTP media device. Returns success if both able to log into
+# the FTP server and confirm the existence of at least one known release path
+# using ftp(1).
+#
+# Variables from variable.subr used to initialize the connection are as follows
+# (all of which are configured by f_media_set_ftp above):
+#
+# 	VAR_FTP_PATH
+# 		The unparsed FTP URL representing the server to contact.
+# 		Usually "ftp://server" for example. Can contain TCP port number
+# 		and/or directory path (but should not contain username/password
+# 		info).
+# 	VAR_FTP_HOST
+# 		The FTP host to connect to. Can be an IPv4 address (e.g.,
+# 		127.0.0.1), IPv6 address (e.g., ::1), or DNS hostname. Usually
+# 		set automatically in f_media_set_ftp() by parsing VAR_FTP_PATH.
+# 	VAR_FTP_PORT
+# 		The TCP port to connect to. Usually set automatically in
+# 		f_media_set_ftp() by parsing VAR_FTP_PATH.
+# 	VAR_FTP_DIR
+# 		The base FTP directory to use when downloading files from the
+# 		FTP server. Usually set automatically in f_media_set_ftp() by
+# 		parsing VAR_FTP_PATH.
+# 	VAR_FTP_USER [Optional]
+# 		If unset, defaults to using anonymous access.
+# 	VAR_FTP_PASS [Optional]
+# 		If unset, defaults to a sensible value.
+#
+# In addition, the following (managed either manually or by f_media_set_ftp_*):
+#
+# 	VAR_FTP_STATE
+# 		Sets FTPMODE for ftp(1) and can be one of:
+# 			active    active mode FTP only
+# 			auto      automatic determination of passive or active
+# 			          (this is the default)
+# 			gate      gate-ftp mode
+# 			passive   passive mode FTP only
+# 		See ftp(1) for additional information.
+#
+# And last, but not least (managed automatically or manually):
+#
+# 	VAR_RELNAME
+# 		Defaults to being set to $(uname -r) but can be overridden.
+# 		This sets the name of a release to look for as part of a well
+# 		known set of paths to search for release data once connected
+# 		via FTP. If set to "__RELEASE" or "any" then the VAR_FTP_DIR is
+# 		taken as the absolute path to the release and no further
+# 		searching is done (see FTP_DIRS above in the GLOBALS section
+# 		for a list of well known paths that are used when searching for
+# 		a VAR_RELNAME sub-directory).
+#
+f_media_init_ftp()
+{
+	local dev="$1"
+
+	local url
+	device_$dev get name url
+	f_dprintf "Init routine called for FTP device. url=[%s]" "$url"
+
+	if [ "$FTP_INITIALIZED" ]; then
+		f_dprintf "FTP device already initialized."
+		return $SUCCESS
+	fi
+
+	# If we can't initialize the network, bag it!
+	f_device_network_up $dev || return $FAILURE
+
+	local cp
+	while :; do
+		f_getvar $VAR_FTP_PATH cp
+		if [ ! "$cp" ]; then
+			if ! f_media_set_ftp ||
+			   ! f_getvar $VAR_FTP_PATH cp ||
+			   [ ! "$cp" ]
+			then
+				f_dialog_msgbox \
+					"$msg_unable_to_get_proper_ftp_path"
+				f_device_network_down $dev
+				return $FAILURE
+			fi
+		fi
+
+		local ftp_host ftp_dir
+		if ! {
+			f_getvar $VAR_FTP_HOST ftp_host &&
+			f_getvar $VAR_FTP_DIR ftp_dir
+		}; then
+			f_dialog_msgbox "$msg_missing_ftp_host_or_directory"
+			f_device_network_down $dev
+			return $FAILURE
+		fi
+
+		local ftp_port
+		f_getvar $VAR_FTP_PORT ftp_port
+		local host="$ftp_host" port="${ftp_port:+:$ftp_port}"
+		case "$host" in *:*) host="[$host]"; esac
+
+		local user pass use_anon=""
+		f_getvar $VAR_FTP_USER user
+		if [ ! "$user" ]; then
+			user="anonymous"
+			use_anon=1
+		fi
+		if ! f_getvar $VAR_FTP_PASS pass; then
+			f_getvar $VAR_HOSTNAME cp
+			if f_running_as_init; then
+				pass="installer@$cp"
+			else
+				local name="$( id -un 2> /dev/null )"
+				pass="${name:-ftp}@$cp"
+			fi
+		fi
+
+		f_show_info "$msg_logging_in_to_user_at_host" \
+		            "$user" "$ftp_host"
+
+		local userpass=""
+		if [ ! "$use_anon" ] && [ "$user" -o "$pass" ]; then
+			userpass="$user${pass:+:$( f_uriencode "$pass" )}"
+			userpass="$userpass${userpass:+@}"
+		fi
+
+		local mode rx
+		f_getvar $VAR_FTP_STATE mode
+
+		if [ "$ftp_dir" ]; then
+			if ! rx=$(
+				printf 'cd "%s"\npwd\n' "$ftp_dir" | eval \
+					FTPMODE=\"\$mode\" \
+					${use_anon:+FTPANONPASS=\"\$pass\"} \
+					ftp -V ${use_anon:+-a} \
+					    \"ftp://\$userpass\$host\$port\" \
+				2>&1
+			); then
+				f_show_msg "$msg_couldnt_open_ftp_connection" \
+				           "$ftp_host" "$rx"
+				break # to failure
+			fi
+			if echo "$rx" | awk -v dir="/${ftp_dir#/}" '
+				BEGIN { found = 0 }
+				/^Remote directory: / {
+					sub(/^[^:]*:[[:space:]]*/, "")
+					if ($0 != dir) next
+					found = 1; exit
+				}
+				END { exit ! found }
+			'; then
+				setvar $VAR_FTP_DIR "$ftp_dir"
+				setvar $VAR_FTP_PATH \
+					"ftp://$ftp_host/${ftp_dir#/}"
+			else
+				f_show_msg \
+				    "$msg_please_check_the_url_and_try_again" \
+				    "ftp://$ftp_host/${ftp_dir#/}"
+				break # to failure
+			fi
+		fi
+
+		#
+		# Now that we've verified that the path we're given is ok,
+		# let's try to be a bit intelligent in locating the release we
+		# are looking for.  First off, if the release is specified as
+		# "__RELEASE" or "any", then just assume that the current
+		# directory is the one we want and give up.
+		#
+		local rel
+		f_getvar $VAR_RELNAME rel
+		f_dprintf "f_media_init_ftp: rel=[%s]" "$rel"
+
+		case "$rel" in
+		__RELEASE|any)
+			FTP_INITIALIZED=YES
+			return $SUCCESS
+			;;
+		*)
+			#
+			# Ok, since we have a release variable, let's walk
+			# through the list of directories looking for a release
+			# directory. First successful CWD wins.
+			#
+			if ! rx=$(
+				for dir in $FTP_DIRS; do
+					# Avoid confusing some servers
+					[ "$dir" = "." ] && continue
+					printf 'cd "/%s/%s"\npwd\n' \
+					       "$dir" "$rel"
+				done | eval \
+					FTPMODE=\"\$mode\" \
+					${use_anon:+FTPANONPASS=\"\$pass\"} \
+					ftp -V ${use_anon:+-a} \
+					    \"ftp://\$userpass\$host\$port\" \
+				2>&1
+			); then
+				f_show_msg "$msg_couldnt_open_ftp_connection" \
+				           "$ftp_host" "$rx"
+				break # to failure
+			fi
+
+			local fdir
+			if fdir=$( echo "$rx" | awk '
+				BEGIN { found = 0 }
+				/^Remote directory: / {
+					sub(/^[^:]*:[[:space:]]*/, "")
+					if ($0 == "/") next
+					# Exit after the first dir
+					found++; print; exit
+				}
+				END { exit ! found }
+			' ); then
+				setvar $VAR_FTP_DIR "$fdir"
+				setvar $VAR_FTP_PATH "ftp://$ftp_host$fdir"
+				FTP_INITIALIZED=YES
+				return $SUCCESS
+			else
+				f_yesno "$msg_cant_find_distribution" \
+				        "$rel" "$ftp_host"
+				if [ $? -eq $SUCCESS ]; then
+					unset $VAR_FTP_PATH
+					f_media_set_ftp && continue
+				fi
+			fi
+		esac
+		break # to failure
+	done
+
+	unset FTP_INITIALIZED $VAR_FTP_PATH
+	f_device_network_down $dev
+	return $FAILURE
+}
+
+# f_media_get_ftp $device $file [$probe_only]
+#
+# Returns data from $file on an FTP server using ftp(1). Please note that
+# $device is unused but must be present (even if null). Information is instead
+# gathered from the environment. $probe_only is currently unused by this media
+# type.
+#
+# Variables from variable.subr used to configure the connection are as follows
+# (all of which are configured by f_media_set_ftp above):
+#
+# 	VAR_FTP_HOST
+# 		FTP host to connect to. Can be an IPv4 address, IPv6 address,
+# 		or DNS hostname of your choice.
+# 	VAR_FTP_PORT
+# 		TCP port to connect on; see f_media_set_ftp() above.
+# 	VAR_FTP_USER [Optional]
+# 		If unset, defaults to using anonymous access.
+# 	VAR_FTP_PASS [Optional]
+# 		If unset, defaults to a sensible value.
+#
+# In addition, the following (managed either manually or by f_media_set_ftp_*):
+#
+# 	VAR_FTP_STATE
+# 		Sets FTPMODE for ftp(1) and can be one of:
+# 			active    active mode FTP only
+# 			auto      automatic determination of passive or active
+# 			          (this is the default)
+# 			gate      gate-ftp mode
+# 			passive   passive mode FTP only
+# 		See ftp(1) for additional information.
+#
+# See variable.subr for additional information.
+#
+# Example usage:
+# 	f_media_set_ftp
+# 	f_media_get_ftp media $file
+#
+f_media_get_ftp()
+{
+	local dev="$1" file="$2" probe_only="$3"
+
+	f_dprintf "f_media_get_ftp: dev=[%s] file=[%s] probe_only=%s" \
+	          "$dev" "$file" "$probe_only"
+
+	local ftp_host ftp_port
+	f_getvar $VAR_FTP_HOST ftp_host
+	f_getvar $VAR_FTP_PORT ftp_port
+
+	if [ ! "$FTP_INITIALIZED" ]; then
+		f_dprintf "No FTP connection open, can't get file %s" "$file"
+		return $FAILURE
+	fi
+
+	if ! {
+		f_validate_ipaddr "$ftp_host" ||
+		f_validate_ipaddr6 "$ftp_host" ||
+		{
+		  f_dprintf "%s: Looking up hostname, %s, using host(1)" \
+		            "f_media_get_ftp" "$ftp_host"
+		  f_host_lookup "$ftp_host" hosts
+		}
+	}; then
+		# All the above validations failed
+		[ "$hosts" ] && f_dialog_msgbox "$hosts"
+		return $FAILURE
+	elif [ ! "$hosts" ]; then
+		# One of the first two validations passed
+		hosts="$ftp_host"
+	fi
+
+	local host connected=
+	for host in $hosts; do
+		f_quietly nc -nz "$host" "$ftp_port" || continue
+		connected=1; break
+	done
+	if [ ! "$connected" ]; then
+		f_show_msg "$msg_couldnt_connect_to_ftp_server %s:%s" \
+		           "$ftp_host" "$ftp_port"
+		return $FAILURE
+	fi
+
+	local user pass use_anon=""
+	f_getvar $VAR_FTP_USER user
+	if [ ! "$user" ]; then
+		user="anonymous"
+		use_anon=1
+	fi
+	if ! f_getvar $VAR_FTP_PASS pass; then
+		f_getvar $VAR_HOSTNAME cp
+		if f_running_as_init; then
+			pass="installer@$cp"
+		else
+			local name="$( id -un 2> /dev/null )"
+			pass="${name:-ftp}@$cp"
+		fi
+	fi
+
+	local userpass=""
+	if [ ! "$use_anon" ] && [ "$user" -o "$pass" ]; then
+		userpass="$user${pass:+:$( f_uriencode "$pass" )}"
+		userpass="$userpass${userpass:+@}"
+	fi
+
+	local ftp_dir mode rx
+	f_getvar $VAR_FTP_DIR ftp_dir
+	f_getvar $VAR_FTP_STATE mode
+
+	local dir="${ftp_dir#/}"
+	local port="${ftp_port:+:$ftp_port}"
+	case "$host" in *:*) host="[$host]"; esac
+
+	f_dprintf "sending ftp request for: %s" "ftp://$host$port/$dir/$file"
+
+	eval FTPMODE=\"\$mode\" ${use_anon:+FTPANONPASS=\"\$pass\"} \
+	     ftp -V ${use_anon:+-a} -o - \
+	     	\"ftp://\$userpass\$host\$port/\$dir/\$file\" 2> /dev/null
+	local retval=$?
+
+	[ $retval -eq $SUCCESS ] || f_dprintf "request failed!"
+	return $retval
+}
+
+# f_media_shutdown_ftp $device
+#
+# Shuts down the FTP device. Return status should be ignored. Note that since
+# we don't maintain an open connection to the FTP server there's nothing to do.
+#
+f_media_shutdown_ftp()
+{
+	[ "$FTP_INITIALIZED" ] || return $SUCCESS
+
+	unset FTP_INITIALIZED
+}
+
+############################################################ MAIN
+
+f_dprintf "%s: Successfully loaded." media/ftp.subr
+
+fi # ! $_MEDIA_FTP_SUBR