openwrt: sysupgrade

sysupgrade

用法：

sysupgrade [<升級選項>...] <image file 或 URL>
sysupgrade [-q] [-i] <備份選項>

升級選項：

• -d 重啟前等待 delay 秒
• -f 從 .tar.gz (文件或鏈接) 中恢復配置文件
• -i 交互模式
• -c 保留 /etc 中所有修改過的文件
• -n 重刷固件時不保留配置文件
• -T | --test 校驗固件 config .tar.gz，但不真正燒寫
• -F | --force 即使固件校驗失敗也強制燒寫
• -q 較少的輸出信息
• -v 詳細的輸出信息
• -h 顯示幫助信息

備份選項：

• -b | --create-backup
  把sysupgrade.conf 里描述的文件打包成.tar.gz 作為備份，不做燒寫動作
• -r | --restore-backup
  從-b 命令創建的 .tar.gz 文件里恢復配置，不做燒寫動作
• -l | --list-backup
  列出 -b 命令將備份的文件列表，但不創建備份文件

舉例

• 更新openwrt.bin固件
  sysupgrade openwrt.bin

• 強制更新openwrt.bin固件
  sysupgrade會檢查支持板子的固件頭信息，如果一個model沒有在sysupgrade的支持列表里，使用-F來忽略檢查失敗，強制燒寫。
  sysupgrade -F openwrt.bin

• 更新后不保存之前的配置
  sysupgrade燒寫時默認會備份配置文件，在燒寫后把配置文件覆蓋到新系統中。-n參數指定不做這個動作。
  sysupgrade -n openwrt.bin

• 備份配置文件到/tmp/backup.tgz
  sysupgrade -b /tmp/backup.tgz

• 恢復之前備份的/tmp/backup.tgz
  sysupgrade -r /tmp/backup.tgz

• 列出會被備份的文件
  sysupgrade -l
  列出的文件會在-b備份時或系統升級時被保存。

實現

解析選項參數

# parse options
while [ -n "$1" ]; do
	case "$1" in
		-i) export INTERACTIVE=1;;
		-d) export DELAY="$2"; shift;;
		-v) export VERBOSE="$(($VERBOSE + 1))";;
		-q) export VERBOSE="$(($VERBOSE - 1))";;
		-n) export SAVE_CONFIG=0;;
		-c) export SAVE_OVERLAY=1;;
		-b|--create-backup) export CONF_BACKUP="$2" NEED_IMAGE=1; shift;;
		-r|--restore-backup) export CONF_RESTORE="$2" NEED_IMAGE=1; shift;;
		-l|--list-backup) export CONF_BACKUP_LIST=1; break;;
		-f) export CONF_IMAGE="$2"; shift;;
		-F|--force) export FORCE=1;;
		-T|--test) export TEST=1;;
		-h|--help) export HELP=1; break;;
		-*)
			echo "Invalid option: $1"
			exit 1
		;;
		*) break;;
	esac
	shift;
done

export CONFFILES=/tmp/sysupgrade.conffiles
export CONF_TAR=/tmp/sysupgrade.tgz

export ARGV="$*"
export ARGC="$#"

解析選項。\(ARGV是參數列表，\)ARGC是參數個數。
選項中有-d, -b, -r, -f時，由於這些選項都要帶一個參數，所以使用了shift去減少\(ARGV和\)ARGC的值。

CONFFILES 和 CONF_TAR 是兩個臨時文件，后面會用到。

sysupgrade openwrt.bin --> ARGV="openwrt.bin", ARGC=1
sysupgrade -b config.backup --> ARGV為空，ARGC=0

判斷參數合法

[ -n "$ARGV" -a -n "$NEED_IMAGE" ] && {
	cat <<-EOF
		-b|--create-backup and -r|--restore-backup do not perform a firmware upgrade.
		Do not specify both -b|-r and a firmware image.
	EOF
	exit 1
}

如果sysupgrade附帶參數-b或-r時，則$NEED_IMAGE=1，否則為空
當$NEED_IMAGE=1時，我們希望ARGV是空的，否則就是出錯，則輸出幫助信息，並退出。
例如:

• sysupgrade -b config.backup，此時$NEED_IMAGE=1, ARGV為空，合法
• sysupgrade -b config.backup openwrt.bin，此時$NEED_IMAGE=1, ARGV為"openwrt.bin"，參數多了，錯誤。

# hooks
sysupgrade_image_check="platform_check_image"
[ $SAVE_OVERLAY = 0 -o ! -d /overlay/etc ] && \
	sysupgrade_init_conffiles="add_uci_conffiles" || \
	sysupgrade_init_conffiles="add_overlayfiles"

帶-c參數，且"/overlay/etc"目錄存在 --> sysupgrade_init_conffiles="add_overlayfiles"
否則 --> sysupgrade_init_conffiles="add_uci_conffiles"

這里會影響要備份的配置文件

include /lib/upgrade

包含lib/upgrade目錄下的所有文件

[ "$1" = "nand" ] && nand_upgrade_stage2 $@

命令指定nand時，則調用nand_upgrade_stage2函數，例如sysupgrade nand openwrt.bin。 暫時使用spi flash，不討論這里。

backup list

add_uci_conffiles() {
	local file="$1"
	( find $(sed -ne '/^[[:space:]]*$/d; /^#/d; p' \
		/etc/sysupgrade.conf /lib/upgrade/keep.d/* 2>/dev/null) \
		-type f 2>/dev/null;
	  opkg list-changed-conffiles ) | sort -u > "$file"
	return 0
}

if [ $CONF_BACKUP_LIST -eq 1 ]; then
	add_uci_conffiles "$CONFFILES"
	cat "$CONFFILES"
	rm -f "$CONFFILES"
	exit 0
fi

列出一份文件列表，放入/tmp/sysupgrade.conffiles，打印出來，然后刪掉。文件列表：

find $(sed -ne '/^[[:space:]]*$/d; /^#/d; p' /etc/sysupgrade.conf /lib/upgrade/keep.d/* 2>/dev/null) -type f 2>/dev/null

opkg list-changed-conffiles

create backup

do_save_conffiles() {
	local conf_tar="${1:-$CONF_TAR}"

	[ -z "$(rootfs_type)" ] && {
		echo "Cannot save config while running from ramdisk."
		ask_bool 0 "Abort" && exit
		return 0
	}
	run_hooks "$CONFFILES" $sysupgrade_init_conffiles
	ask_bool 0 "Edit config file list" && vi "$CONFFILES"

	v "Saving config files..."
	[ "$VERBOSE" -gt 1 ] && TAR_V="v" || TAR_V=""
	tar c${TAR_V}zf "$conf_tar" -T "$CONFFILES" 2>/dev/null

	rm -f "$CONFFILES"
}

if [ -n "$CONF_BACKUP" ]; then
	do_save_conffiles "$CONF_BACKUP"
	exit $?
fi

-b 如果指定打包文件時，$CONF_BACKUP 為那個文件名。則此時按如下流程來生成備份文件：

do_save_conffiles
  -> sysupgrade_init_conffiles
     -> add_uci_conffiles
        -> tar czf /tmp/backup.tgz -T /tmp/sysupgrade.conffiles
	-> rm -f /tmp/sysupgrade.conffiles

restore

if [ -n "$CONF_RESTORE" ]; then
	if [ "$CONF_RESTORE" != "-" ] && [ ! -f "$CONF_RESTORE" ]; then
		echo "Backup archive '$CONF_RESTORE' not found."
		exit 1
	fi

	[ "$VERBOSE" -gt 1 ] && TAR_V="v" || TAR_V=""
	tar -C / -x${TAR_V}zf "$CONF_RESTORE"
	exit $?
fi

sysupgrade -r config.tgz --> tar -C / -xzf config.tgz
解壓，覆蓋到/目錄下

image check

for check in $sysupgrade_image_check; do
	( eval "$check \"\$ARGV\"" ) || {
		if [ $FORCE -eq 1 ]; then
			echo "Image check '$check' failed but --force given - will update anyway!"
			break
		else
			echo "Image check '$check' failed."
			exit 1
		fi
	}
done

sysupgrade openwrt.bin --> 檢查bin文件：platform_check_image openwrt.bin
lib/upgrade/platform.sh 中定義platform_check_image函數，取.bin文件的頭部，檢查magic number

upgrade backup

if [ -n "$CONF_IMAGE" ]; then
	case "$(get_magic_word $CONF_IMAGE cat)" in
		# .gz files
		1f8b) ;;
		*)
			echo "Invalid config file. Please use only .tar.gz files"
			exit 1
		;;
	esac
	get_image "$CONF_IMAGE" "cat" > "$CONF_TAR"
	export SAVE_CONFIG=1
elif ask_bool $SAVE_CONFIG "Keep config files over reflash"; then
	[ $TEST -eq 1 ] || do_save_conffiles
	export SAVE_CONFIG=1
else
	export SAVE_CONFIG=0
fi

在升級時會先保存配置文件到/tmp/sysupgrade.tgz

1. -f 指定配置文件
2. 交互模式 ask_bool 可以獲取輸入值，如果不在交互模式，則ask_bool的第一個參數就是默認值。
   $SAVE_CONFIG默認為1, 這里調用do_save_conffiles保存當前系統的配置文件。

upgrade

if [ -n "$(rootfs_type)" ]; then
	v "Switching to ramdisk..."
	run_ramfs '. /lib/functions.sh; include /lib/upgrade; do_upgrade'
else
	do_upgrade
fi

1. rootfs_type = "overlayfs" ，執行第一個邏輯
2. run_ramfs, 在/tmp/root下安裝一個臨時ramdisk，最后再執行do_upgrade
3. do_upgrade -> platform_do_upgrade -> get_image "$1" | mtd -j "$CONF_TAR" write - "firmware"

mtd工具在寫入時，會把$CONF_TAR文件整合進入jffs2分區，可以看到打印信息：

Appending jffs2 data from /tmp/sysupgrade.tgz to firmware...

---

Sysupgrade – Technical Reference