xref: /freebsd-10.1-release/usr.sbin/bsdconfig/share/media/ftp.subr

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 (INCLUDING, 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/device.subr
f_include $BSDCFG_SHARE/dialog.subr
f_include $BSDCFG_SHARE/media/common.subr
f_include $BSDCFG_SHARE/media/tcpip.subr
f_include $BSDCFG_SHARE/strings.subr
f_include $BSDCFG_SHARE/struct.subr
f_include $BSDCFG_SHARE/variable.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 menu_list="
		'$msg_main_site'          'ftp.freebsd.org'
		'URL'                     '$msg_specify_some_other_ftp_site'
		'IPv6 $msg_main_site'     'ftp.freebsd.org'
		' IPv6 $msg_france'       'ftp4.fr.freebsd.org'
		' IPv6 $msg_france #8'    'ftp8.fr.freebsd.org'
		' IPv6 $msg_ireland'      'ftp3.ie.freebsd.org'
		' IPv6 $msg_japan'        'ftp2.jp.freebsd.org'
		' IPv6 $msg_sweden'       'ftp4.se.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 #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_armenia'            'ftp1.am.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_brazil'             'ftp2.br.freebsd.org'
		' $msg_brazil #3'         'ftp3.br.freebsd.org'
		' $msg_brazil #4'         'ftp4.br.freebsd.org'
		'$msg_canada'             'ftp.ca.freebsd.org'
		'$msg_china'              'ftp.cn.freebsd.org'
		'$msg_czech_republic'     'ftp.cz.freebsd.org'
		'$msg_denmark'            'ftp.dk.freebsd.org'
		'$msg_estonia'            'ftp.ee.freebsd.org'
		'$msg_finland'            'ftp.fi.freebsd.org'
		'$msg_france'             'ftp.fr.freebsd.org'
		' $msg_france #3'         'ftp3.fr.freebsd.org'
		' $msg_france #4'         'ftp4.fr.freebsd.org'
		' $msg_france #5'         'ftp5.fr.freebsd.org'
		' $msg_france #6'         'ftp6.fr.freebsd.org'
		' $msg_france #7'         'ftp7.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 #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_ireland'            '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_latvia'             'ftp.lv.freebsd.org'
		'$msg_lithuania'          'ftp.lt.freebsd.org'
		'$msg_netherlands'        'ftp.nl.freebsd.org'
		' $msg_netherlands #2'    'ftp2.nl.freebsd.org'
		'$msg_new_zealand'        'ftp.nz.freebsd.org'
		'$msg_norway'             'ftp.no.freebsd.org'
		'$msg_poland'             'ftp.pl.freebsd.org'
		' $msg_poland #2'         'ftp2.pl.freebsd.org'
		'$msg_russia'             'ftp.ru.freebsd.org'
		' $msg_russia #2'         'ftp2.ru.freebsd.org'
		' $msg_russia #4'         'ftp4.ru.freebsd.org'
		' $msg_russia #5'         'ftp5.ru.freebsd.org'
		' $msg_russia #6'         'ftp6.ru.freebsd.org'
		'$msg_slovak_republic'    'ftp.sk.freebsd.org'
		' $msg_slovak_republic #2' 'ftp2.sk.freebsd.org'
		'$msg_slovenia'           'ftp.si.freebsd.org'
		'$msg_south_africa'       'ftp.za.freebsd.org'
		' $msg_south_africa #2'   'ftp2.za.freebsd.org'
		' $msg_south_africa #4'   'ftp4.za.freebsd.org'
		'$msg_spain'              'ftp.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 #6'         'ftp6.se.freebsd.org'
		'$msg_switzerland'        'ftp.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_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_ukraine'            'ftp.ua.freebsd.org'
		' $msg_ukraine #7'        'ftp7.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 #8'            'ftp8.us.freebsd.org'
		' $msg_usa #10'           'ftp10.us.freebsd.org'
		' $msg_usa #11'           'ftp11.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 hline="$msg_select_a_site_thats_close"

	local height width rows
	eval f_dialog_menu_size height width rows \
	                        \"\$title\"  \
	                        \"\$btitle\" \
	                        \"\$prompt\" \
	                        \"\$hline\"  \
	                        $menu_list

	local mtag
	mtag=$( eval $DIALOG \
		--title \"\$title\"             \
		--backtitle \"\$btitle\"        \
		--hline \"\$hline\"             \
		--ok-label \"\$msg_ok\"         \
		--cancel-label \"\$msg_cancel\" \
		--menu \"\$prompt\"             \
		$height $width $rows            \
		$menu_list                      \
		2>&1 >&$DIALOG_TERMINAL_PASSTHRU_FD
	) || return $DIALOG_CANCEL
	f_dialog_data_sanitize mtag

	case "$mtag" in
	URL) setvar $VAR_FTP_PATH "other" ;;
	*)
		local value
		value=$( eval f_dialog_menutag2item \"\$mtag\" $menu_list )
		setvar $VAR_FTP_PATH "ftp://$value"
	esac
	
	return $DIALOG_OK
}

# 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 "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 device_network
		if ! f_device_select_tcp; then
			unset $VAR_FTP_PATH
			return $FAILURE
		fi
		local dev if
		f_getvar $VAR_NETWORK_DEVICE if
		f_device_find -1 "$if" $DEVICE_TYPE_NETWORK dev
		f_struct_copy "$dev" device_network
	fi
	if ! f_device_init device_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
	#
	# The order in-which the below individual cases appear is important!
	#
	"["*"]":*/*) # IPv6 address with port and directory
		f_dprintf "Looks like an IPv6 addr with port/dir: %s" \
		          "$hostname"
		hostname="${hostname#\[}"
		port="${hostname#*\]:}"
		port="${port%%[!0-9]*}"
		dir="/${hostname#*/}"
		hostname="${hostname%%\]:*}"
		;;
	"["*"]":*) # IPv6 address with port
		f_dprintf "Looks like an IPv6 addr with port: %s" "$hostname"
		hostname="${hostname#\[}"
		port="${hostname#*\]:}"
		port="${port%%[!0-9]*}"
		hostname="${hostname%%\]:*}"
		;;
	"["*"]"/*) # IPv6 address with directory
		f_dprintf "Looks like an IPv6 addr with dir: %s" "$hostname"
		hostname="${hostname#\[}"
		dir="/${hostname#*/}"
		hostname="${hostname%%\]*}"
		;;
	"["*"]") # IPv6 address
		f_dprintf "Looks like an IPv6 addr: %s" "$hostname"
		hostname="${hostname#\[}"
		hostname="${hostname%\]}"
		;;
	#
	# ^^^ IPv6 above / DNS Name or IPv4 below vvv
	#
	*:*/*) # DNS name or IPv4 address with port and directory
		f_dprintf "Looks like a %s with port/dir: %s" \
		          "DNS name or IPv4 addr" "$hostname"
		port="${hostname#*:}"
		port="${port%%[!0-9]*}"
		dir="/${hostname#*/}"
		hostname="${hostname%%:*}"
		;;
	*:*) # DNS name or IPv4 address with port
		f_dprintf "Looks like a DNS name or IPv4 addr with port: %s" \
		          "$hostname"
		port="${hostname#*:}"
		hostname="${hostname%%:*}"
		;;
	*/*) # DNS name or IPv4 address with directory
		f_dprintf "Looks like a DNS name or IPv4 addr with dir: %s" \
		          "$hostname"
		dir="/${hostname#*/}"
		hostname="${hostname%%/*}"
		;;
	*) # DNS name or IPv4 address
		f_dprintf "Looks like a DNS name or IPv4 addr: %s" "$hostname"
		: leave hostname as-is
	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 device_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  device_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
	f_struct "$dev" || return $FAILURE
	$dev get private netDev || return $SUCCESS # No net == happy net
debug=1 f_dprintf "netDev=[$netDev]"
	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
	f_struct "$dev" || return $FAILURE
	$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

	$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_show_msg "$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_show_msg "$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
					if ( dir != "/" ) sub("/$", "", dir)
				}
				/^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 '
				/^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 $DIALOG_OK ]; 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_type]
#
# 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. If $probe_type is present and non-NULL,
# returns success if $file exists. If $probe_type is equal to $PROBE_SIZE,
# prints the size of $file in bytes to standard-out.
#
# 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 funcname=f_media_get_ftp
	local dev="$1" file="$2" probe_type="$3" hosts=

	f_dprintf "f_media_get_ftp: dev=[%s] file=[%s] probe_type=%s" \
	          "$dev" "$file" "$probe_type"

	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 dir mode rx
	f_getvar $VAR_FTP_DIR\#/ dir
	f_getvar $VAR_FTP_STATE mode

	local port="${ftp_port:+:$ftp_port}"
	case "$host" in *:*) host="[$host]"; esac

	f_dprintf "sending ftp request for: %s" "ftp://$host$port/$dir/$file"

	if [ "$probe_type" ]; then
		local url="ftp://$userpass$host$port/$dir/$file" size
		[ "$use_anon" ] && url="ftp://$host$port/$dir/$file"
		if ! f_eval_catch -dk size $funcname fetch \
			'fetch -s "%s"' "$url" || ! f_isinteger "$size"
		then
			f_dprintf "size request failed!"
			[ "$probe_type" = "$PROBE_SIZE" ] && echo "-1"
			return $FAILURE
		fi
		[ "$probe_type" = "$PROBE_SIZE" ] && echo "$size"
		return $SUCCESS
	fi

	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