turris-academy/tos3migration: add presentations about TOS 3.x migration

7 files changed, 388 insertions, 0 deletions

diff --git a/turris-academy/tos3migration/Makefile b/turris-academy/tos3migration/Makefile
new file mode 100644
index 0000000..4285339
--- /dev/null
+++ b/turris-academy/tos3migration/Makefile
@@ -0,0 +1,10 @@
+FILE=pres
+
+$(FILE).pdf: $(FILE).tex $(patsubst %.svg,%.pdf,$(wildcard *.svg))
+	pdflatex -shell-escape $<
+
+%.pdf: %.svg
+	inkscape -D -z --file=$< --export-pdf=$@ --export-latex
+
+clean:
+	ls | grep -v -E "($(FILE).tex|Makefile|theme|svg|jpg|png|eps)$$" | xargs rm -rf
diff --git a/turris-academy/tos3migration/migration.png b/turris-academy/tos3migration/migration.png
new file mode 100644
index 0000000..8137bdb
--- /dev/null
+++ b/turris-academy/tos3migration/migration.png
diff --git a/turris-academy/tos3migration/pres.pdf b/turris-academy/tos3migration/pres.pdf
new file mode 100644
index 0000000..474487f
--- /dev/null
+++ b/turris-academy/tos3migration/pres.pdf
diff --git a/turris-academy/tos3migration/pres.tex b/turris-academy/tos3migration/pres.tex
new file mode 100644
index 0000000..4822806
--- /dev/null
+++ b/turris-academy/tos3migration/pres.tex
@@ -0,0 +1,335 @@
+\documentclass[aspectratio=169]{beamer}
+\usepackage{lmodern}
+\usepackage[english]{babel}
+\usepackage[utf8x]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{textpos}
+\usepackage{tikz,calc}
+\usepackage{graphicx}
+\usepackage{wrapfig}
+\usepackage{color}
+\usepackage{mathtools}
+\usepackage{hyperref}
+\usepackage{epstopdf}
+\usepackage{amsmath}
+\usepackage{minted}
+\hypersetup{
+	colorlinks,
+	citecolor=black,
+	filecolor=black,
+	linkcolor=black,
+	urlcolor=black
+}
+\usepackage{pdflscape}
+
+\input{theme/theme.tex}
+
+\title{Update from Turris OS 3.x to 5.x or newer is a big leap}
+\author{Karel Kočí}
+\date{29.11.2021}
+
+\begin{document}
+
+\frame{\titlepage}
+
+\begin{frame}{Turris OS 3.x migration for users}
+	Documentation: https://docs.turris.cz/geek/tos3-migration/
+
+	\vspace{0.3cm}
+
+	\includegraphics[width=10cm]{migration.png}\\
+
+	\vspace{0.3cm}
+	Automatic migration is going to be in waves. The first wave for:
+	\begin{itemize}
+		\item Omnia with serial numbers ending with zero in decimal format
+		\item Turris 1.x routers on BTRFS
+	\end{itemize}
+\end{frame}
+
+\begin{frame}{Important changes}
+	\begin{itemize}
+		\item API tokens are no longer available and mobile application no longer works.
+		\item Server side backups were dropped. Replacement is not yet provided.
+		\item Majordomo is no longer available as well as its package list.
+		\item Automation package list with Domoticz and Home-Assistant is no longer provided.
+		\item Print server CUPS was dropped. Print server package list now provides only p910nd protocol.
+		\item Webcam, sound card, Squid proxy and netutils packages list were dropped.
+		\item Thermometer package was dropped. Use collectd or sensors as a replacement
+		\item Network switch configuration now uses DSA.
+		\item Attack statistics are presented on the Sentinel View instead of project.turris.cz.
+	\end{itemize}
+\end{frame}
+
+\begin{frame}{Why we need migration?}
+	Huge changes between years 2016 and 2018.
+
+	Turris OS 3.x: OpenWrt 15.05 (latest merge January 2016)
+
+	Turris OS 4.0: OpenWrt 18.06
+
+	\begin{itemize}
+		\item Huge changes in configuration
+		\item Change of LibC on Turris 1.x
+		\item Changes in repositories (different layout)
+		\item Changes in packages
+		\item Removal of some functionalities
+	\end{itemize}
+\end{frame}
+
+\begin{frame}{Configuration}
+	\begin{itemize}
+		\item Migration from swconfig to DSA pro for switch configuration
+		\item SFP support in kernel (missing switch in runtime)
+		\item Change of Wi-Fi cards identifier
+		\item Move away from UCI configuration to native for sshd
+		\item Update LXC from 1.0 to 3.0 (4.0)
+		\item Switch from uCollect to Sentinel
+	\end{itemize}
+
+	Load of changes in secondary software..
+\end{frame}
+
+\begin{frame}[fragile]{Configuration migration}
+	Package \textit{tos3to4} with migration scripts in Turris OS 4.0+ due to
+	future extension.
+
+	\begin{minted}[frame=lines]{bash}
+config_load wireless
+wifi_handle() {
+  local radio="$1"
+  config_get path "$radio" path
+  mac="$(cat /sys/devices/platform/"$path"/ieee80211/phy*/macaddress)"
+  uci set "wireless.$radio.macaddr=$mac"
+  uci delete "wireless.$radio.path"
+}
+config_foreach wifi_handle wifi-device
+uci commit wireless
+	\end{minted}
+\end{frame}
+
+\begin{frame}[fragile]{Offline upgrade}
+	Load the new system, migrate configuration and perform reboot...
+
+	\vspace{0.2cm}
+
+	Advantages:
+	\begin{itemize}
+		\item Simple
+		\item Atomic thanks to BTRFS
+	\end{itemize}
+
+	\vspace{0.2cm}
+
+	Why not possible:
+	\begin{minted}[frame=lines]{lua}
+[ -n "$IPKG_INSTROOT" ] || {
+  package_migration
+}
+\end{minted}
+	⇒ Upgrade in runtime
+\end{frame}
+
+\begin{frame}[fragile]{Some theory... Updater}
+	Lua directives/configuration from online source (updater lists).
+
+	\begin{minted}[frame=lines]{lua}
+Repository('turris/core', '../packages/core')
+Install('updater-ng', 'updater-supervisor', { critical = true })
+Package('updater-ng', { replan = 'finished' })
+\end{minted}
+\end{frame}
+
+\begin{frame}[fragile]{Some theory... Package extras}
+	\begin{minted}[frame=lines]{lua}
+Package('updater-ng', { replan = 'finished' })
+\end{minted}
+
+	\begin{itemize}
+		\item \textbf{virtual}: there is no binary package for this name
+		\item \textbf{deps}: additional package dependencies
+		\item \textbf{reboot}: performs \textit{delayed} reboot or unconditional
+			one for \textit{finished}
+		\item \textbf{replan}: \textit{finished} causes reexecution of updater
+			immediately after exit or immediately after installation of that
+			package for \textit{immediate}
+		\item \textbf{abi\_change} and \textbf{abichange\_deep} causes reinstall
+			of all dependent packages
+		\item \textbf{order\_before} and \textbf{order\_after} never worked
+	\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]{First iteration: "this won't work"}
+	Package \textit{tos3to4} in Turris OS 3.x:
+	\begin{minted}[frame=lines]{lua}
+Script("https://repo.turris.cz/hbs/omnia/lists/migrate3x.lua", {
+	security = "Local", ca = system_cas, crl = no_crl,
+	pubkey = { "file:///etc/updater/keys/release.pub" }
+})
+\end{minted}
+
+	\textit{migrate3x.lua} on server:
+	\begin{minted}[frame=lines]{lua}
+Repository("turris", "https://repo.turris.cz/hbs/"..board.."/packages", {
+	priority = 60,
+	subdirs = { "base", "core", "packages", "turrispackages"}
+})
+\end{minted}
+\end{frame}
+
+\begin{frame}[fragile]{Second iteration: "update updater"}
+	\begin{minted}[frame=lines]{lua}
+if version_match(self_version, "<64.0") then
+  Repository("turris", "https://repo.turris.cz/hbs/"..board.."/packages", {
+    priority = 60,
+    subdirs = { "base", "core", "packages", "turrispackages"}
+  })
+  Install('updater-ng', { critical = true })
+  Package('updater-ng', {
+    replan = 'immediate',
+    deps = { 'libgcc', 'busybox', 'tos3to4-early' }
+  })
+end
+Package("libc", { abi_change_deep = true })
+\end{minted}
+\end{frame}
+
+\begin{frame}[fragile]{Updater: welcome in hell}
+	Check for collisions...
+	\begin{minted}[frame=lines]{md}
+DIE: [string "transaction"]:334: [string "transaction"]:158: Collisions:
+• /usr/sbin/cron: vixie-cron (existing-file), cronie (new-file)
+\end{minted}
+
+	\vspace{0.4cm}
+
+	Ok, then:
+	\begin{minted}[frame=lines]{lua}
+Package("cronie", { virtual = true })
+\end{minted}
+	\begin{minted}[frame=lines]{md}
+ERROR: inconsistent: Candidate exists for virtual package gettext-tools
+\end{minted}
+\end{frame}
+
+\begin{frame}[fragile]{Theory follow up... order of changes}
+	\begin{minted}[frame=lines]{lua}
+Install('updater-ng', { critical = true, priority = 50 })
+\end{minted}
+
+	Ordering rules (higher means earlier):
+	\begin{enumerate}
+		\item Dependent for any subsequent package
+		\item Package conflicting with some of the subsequent packages
+		\item Critically requested packages
+		\item Priority (higher means earlier)
+		\item Package installation (package removal are performed at the end)
+	\end{enumerate}
+	BTW, this applies just for newer versions of updater.
+\end{frame}
+
+\begin{frame}[fragile]{Third iteration "early later"}
+	\begin{minted}[frame=lines]{lua}
+  Package('updater-ng', {
+    replan = 'immediate',
+    deps = { 'libgcc', 'busybox' }
+  })
+else
+  if version_match(installed["tos3to4"].version, "<2.0.0") then
+    Install('tos3to4-early', { critical = true, priority = 100 })
+    Package('tos3to4-early', { replan = 'immediate' })
+  end
+end
+\end{minted}
+\end{frame}
+
+\begin{frame}[fragile]{Fourth iteration "ufff it takes sooo long"}
+	OpenWrt uses procd as the init system which communicates over ubus.
+
+	New version of ubus does not communicate with the old one. The timeout is
+	two minutes.
+
+	\begin{minted}[frame=lines]{bash}
+[ -n "${IPKG_INSTROOT}" ] || {
+  ubus call system info 2>/dev/null >&2 || killall ubusd
+}
+\end{minted}
+
+	\begin{minted}[frame=lines]{lua}
+if version_match(installed["ubus"].version, "<2018") then
+  Package("ubus", { replan = 'immediate' })
+end
+\end{minted}
+\end{frame}
+
+\begin{frame}[fragile]{Fifth iteration "missing packages"}
+	\begin{minted}[frame=lines]{lua}
+Install("cups")
+\end{minted}
+
+	\begin{minted}[frame=lines]{md}
+ERROR: inconsistent: Requested package cups that is not available.
+\end{minted}
+
+	\vspace{0.2cm}
+
+	With new feature added to updater:
+	\begin{minted}[frame=lines]{lua}
+Mode("optional_installs")
+\end{minted}
+\end{frame}
+
+\begin{frame}[fragile]{Sixth iteration "localrepo oh localrepo"}
+	Localrepo stores packages that were not installed from repository.
+
+	Those package won't be updated and won't most likely work after upgrade.
+
+	\begin{minted}[frame=lines]{bash}
+SOURCE="/usr/share/updater/localrepo"
+COLLIDED="/usr/share/updater/collided$SOURCE"
+mv "$SOURCE" "$COLLIDED"
+\end{minted}
+
+	\begin{minted}[frame=lines]{lua}
+  Package('updater-ng', {
+    replan = 'immediate',
+    deps = { 'libgcc', 'busybox', 'tos3to4-earliest' }
+  })
+else
+\end{minted}
+\end{frame}
+
+\begin{frame}[fragile]{Seventh iteration "brick"}
+	The system is configured for DSA but there is no DSA in running kernel.
+
+	\begin{minted}[frame=lines]{lua}
+Package("tos3to4", { reboot = "finished" })
+\end{minted}
+\end{frame}
+
+\begin{frame}[fragile]{Eighth iteration... well no, that would be too long}
+	The complete update consists of:
+	\begin{enumerate}
+		\item Installation of \textit{tos3to4} in Turris OS 3.x
+		\item Upgrade of updater to the newest version and installation of
+			\textit{tos3to4-earliest}
+		\item Upgrade of ubus (two minutes of waiting)
+		\item Installation of \textit{tos3to4-early} and updater settings
+			migration
+		\item Upgrade of the rest of the system including removal of old
+			packages
+		\item The last replan
+		\item Reboot
+		\item Removal of \textit{tos3to4} a other migration packages
+	\end{enumerate}
+	Plus few other replans in the meantime and special packages (\textit{fix-*}).
+\end{frame}
+
+\begin{frame}
+	\Large Thank you for attention. Questions?\\
+
+	\vspace{0.5cm}
+	\small karel.koci@nic.cz
+\end{frame}
+
+\end{document}
diff --git a/turris-academy/tos3migration/theme/theme.tex b/turris-academy/tos3migration/theme/theme.tex
new file mode 100644
index 0000000..6648932
--- /dev/null
+++ b/turris-academy/tos3migration/theme/theme.tex
@@ -0,0 +1,43 @@
+% vim: ft=tex
+
+\definecolor{cznicblue}{RGB}{0,56,145}
+\definecolor{cznicred}{RGB}{204,18,38}
+
+\setbeamertemplate{frametitle}{
+	\begin{textblock}{100}[0,0](0.0,1.1)
+		\insertframetitle
+	\end{textblock}
+}
+
+\defbeamertemplate*{footline}{CZ.NIC}{
+	\begin{beamercolorbox}[wd=\paperwidth,ht=2.5ex,dp=1.125ex,
+		leftskip=.3cm,rightskip=.3cm plus1fil]{bottom}
+
+
+	\parbox{15.4cm}{\vspace*{-1.2cm}\hfill\insertpagenumber/\inserttotalframenumber}
+	\end{beamercolorbox}
+}
+
+\setbeamertemplate{background}{
+	\includegraphics[width=\paperwidth,height=\paperheight]{theme/turris_bg_16_9.png}
+}
+
+\defbeamertemplate*{title page}{CZ.NIC}[1][]{
+	\usebeamerfont{title}\usebeamercolor[fg]{title}\inserttitle\par
+	\usebeamerfont{subtitle}\usebeamercolor[fg]{subtitle}\insertsubtitle\par
+	\bigskip
+	\usebeamerfont{author}\usebeamercolor[fg]{author}\insertauthor\par
+	\usebeamerfont{institute}\usebeamercolor[fg]{institute}\insertinstitute\par
+	% Commenting out following lines hides date from first slide
+	\usebeamerfont{date}\usebeamercolor[fg]{date}\insertdate\par
+	\usebeamercolor[fg]{titlegraphic}\inserttitlegraphic
+}
+
+\setbeamercolor{structure}{fg=cznicred}
+\setbeamercolor{title}{fg=cznicblue}
+\setbeamercolor{subtitle}{fg=cznicred}
+\setbeamercolor{frametitle}{fg=cznicblue}
+\setbeamercolor{author}{fg=cznicblue}
+\setbeamercolor{date}{fg=cznicblue}
+
+\beamertemplatenavigationsymbolsempty
diff --git a/turris-academy/tos3migration/theme/turris_bg_16_9.png b/turris-academy/tos3migration/theme/turris_bg_16_9.png
new file mode 100644
index 0000000..51f0724
--- /dev/null
+++ b/turris-academy/tos3migration/theme/turris_bg_16_9.png
diff --git a/turris-academy/tos3migration/theme/turris_bg_4_3.png b/turris-academy/tos3migration/theme/turris_bg_4_3.png
new file mode 100644
index 0000000..009adf5
--- /dev/null
+++ b/turris-academy/tos3migration/theme/turris_bg_4_3.png