% Personal notes provided with "%". Think of it as a potential audio overlay.

\documentclass[a4paper,portrait,english]{beamer}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{url}
\usepackage{lmodern}
\setcounter{tocdepth}{1}

\date{2008-09-30}
\institute[\textsf{NFWS2008}]{Presented at NFWS 2008}
\usetheme{CambridgeUS}

\setbeamercolor*{palette primary}{fg=blue!50!black,bg=gray!20!white}
\setbeamercolor*{palette secondary}{fg=blue!50!black,bg=gray!40!white}
\setbeamercolor*{palette tertiary}{bg=blue!50!black,fg=white}
\setbeamercolor{titlelike}{bg=gray!20!white,fg=blue!50!black}
\setbeamerfont{block title}{family=\sffamily}
\setbeamercolor{block title}{use=structure,fg=white,bg=structure.fg!75!black}
\setbeamercolor{block title alerted}{use=alerted text,fg=white,bg=alerted text.fg!75!black}
\setbeamercolor{block title example}{use=example text,fg=white,bg=example text.fg!75!black}
\setbeamercolor{block body}{parent=normal text,use=block title,bg=block title.bg!10!bg}
\setbeamercolor{block body alerted}{parent=normal text,use=block title alerted,bg=block title alerted.bg!10!bg}
\setbeamercolor{block body example}{parent=normal text,use=block title example,bg=block title example.bg!10!bg}

\begin{document}

\title{An Introduction to Xtables-addons}

\author{Jan\ Engelhardt}

\frame{
	\titlepage
}

\frame{
	\frametitle{Table of Contents}
	\tableofcontents
}

% First of all, a bit of history.

\section{patch-o-matic}

\subsection{Description}

\frame{
	patch-o-matic (Aug\ 2002--2003) and p.o.m.-ng (Nov\ 2003--2007)

	\begin{itemize}

	\item package to hold extensions not merged yet in mainline\pause\\

	and those that would never go in anyway.

	% Like ipt_ROUTE...

	\pause

	\item development playground~--\\ convenient patch scripts (at that
	time)

	% Nowadays we use git, but earlier on, when git (and bitkeeper) was
	% still a hurdle, we quilted away happily.
	% (Quilt, that's a tool to manapge patches.)

	\end{itemize}

}

\subsection{Pitfalls}

\frame{
	\frametitle{Pitfalls}

	\begin{itemize}

	\item people patched lots of it in\\

	{\small Despite the warning\\

	\begin{quote}
	{}``Each patch is a new feature: many have minimal impact,
	some do not. Almost every one has bugs, so I don't recommend
	applying them all!''
	\end{quote}
	}

	\begin{itemize}

	\item in retrospect, they certainly had bugs

	\end{itemize}

	\pause

	\item distributions {\footnotesize (Debian, PLD Linux, OpenWRT)}
	patched a few features in sometimes

	\begin{itemize}

		% \item duplicated patching efforts

		\item maintenance cost of carrying and updating the patches

		\item usually split over two packages (\textsf{kernel},
		\textsf{iptables})

		% I for example wanted pure diffs and had to generate them
		% from the POM tree, which was really cumbersome. Extract
		% Linux tree, quilt all files, apply the POM tree in some
		% way, quilt refresh, continue with next patch.

	\end{itemize}

	\end{itemize}

}

\subsection{Patching}

\frame{
	\frametitle{Patching}

	\begin{itemize}

	\item can create merging conflicts when patches are applied

	\begin{itemize}

		\item patch not updated for most recent kernel

		\item patches can conflict among themselves

	\end{itemize}

	\pause

	\item possibility of incorrect conflict resolution by a novice user

	\pause

	\item the patch might even apply cleanly

	\end{itemize}

	but the resulting source code may still have flaws.

}

\frame{

	What could be wrong here?

	\begin{exampleblock}{A sample match function that never matches}
	{\footnotesize {\texttt{\textbf{static int}
		throw\_away\_match(\textbf{const struct}
		sk\_buff~\textbf{{*}}skb,\\
	~~~~\textbf{const struct} net\_device~\textbf{{*}}in,
		\textbf{const struct} net\_device~\textbf{{*}}out,\\
	~~~~\textbf{const struct} xt\_match~\textbf{{*}}match,
		\textbf{const void~{*}}matchinfo, \textbf{int} offset,\\
	~~~~\textbf{unsigned int} protoff, \textbf{int~{*}}hotdrop)\\
	\{\\
	~~~~~~~~\textbf{if} (uncorrectable\_error)\\
	~~~~~~~~~~~~~~~~{*}hotdrop = 1;\\
	~~~~~~~~\textbf{return} 0;\\
	\}}}}
	\end{exampleblock}

	% It looks good so far, right? Since the extension is a new file
	% usually (in patch form as well as POM tree), there are no
	% conflicts.

	\pause

	\begin{alertblock}{ABI/API mismatch}
	Newer kernels require \texttt{bool~{*}}. Dereferencing
	\texttt{hotdrop} here causes a write of 4~bytes into a memory region
	that is just 1~byte usually.
	\end{alertblock}

}

\subsection{Code quality}

\frame{
	\frametitle{Code quality}

	There's more! Code was often plagued with various issues~-- though
	this is a result of the particular developer, not POM.

	\begin{itemize}

	\item variable-width types

	\item unaligned access

	\item endian correctness

	\item running sparse is advised (\texttt{make C=1}), as is review

	\end{itemize}

}

\frame{
	\frametitle{Size mismatch}

	% Size mismatches are probably the issue that I felt struck users
	% most over time.
	%
	% Many an extension in the mainline kernel were also affected which
	% have been completely fixed by 2.6.19, some earlier.

	\begin{alertblock}{Types with variable width across different
	arches}

	\texttt{\small \textbf{struct} ipt\_ipmark\_target\_info~\{\\
	~~~~~~~~\textbf{unsigned long} andmask, ormask;\\
	~~~~~~~~\textbf{char} addr;\\
	\};}

	\end{alertblock}

	\begin{itemize}

	\item will fail in mixed-bitness environments {\footnotesize
	(commonly done on sparc64)} unless additional compat code is present

	\item often went unnoticed because most people used x86 32-bit
	installs

	\end{itemize}

	\begin{block}{Kernel message}

	\texttt{\small x\_tables: connmark match: invalid size 24 != 12}

	\end{block}

	\begin{exampleblock}{Solution}

	{\small \textbf{Only} use \texttt{char},
	\texttt{\_\_u8}/\texttt{16}/\texttt{32}/\texttt{64} (and signed
	variants) types and structs/unions/arrays of these. {\footnotesize For
	exceptions, see the Documentation.}}

	\end{exampleblock}

}

\frame{
	\frametitle{Alignment violation}

	\begin{alertblock}{Unaligned access}

	\texttt{\small
	\textbf{\#define get\_u16(X, O) ({*}(const \_\_u16~{*})((X) + O))}\\
	~\\
	\textbf{if} (get\_u32(payload, 33) == \_\_constant\_htonl(0x71182b1a) \&\& \\
	~~~~get\_u16(payload, 147) == \_\_constant\_htonl(0xf792)) \{\\
	~~~~~~~~printk(KERN\_INFO \char`\"{}got	WinMX\textbackslash{}n\char`\"{});\\
	~~~~~~~~\textbf{return} IPP2P\_WINMX {*} 100 + 4;\\
	\}}

	\end{alertblock}

	\begin{itemize}

	\item often goes unnoticed because x86 handles it transparently

	\end{itemize}

	\begin{block}{Resulting oops on sparc64}

	\texttt{\small Kernel unaligned access at TPC{[}79c344]
	search\_winmx+0x123/0x789}

	\end{block}

	\begin{exampleblock}{Safe version}

	\texttt{\small \textbf{\#define get\_u16(X, O)
	get\_unaligned((const \_\_u16~{*})((X) + O))}}

	\end{exampleblock}

}

\subsection{Summary}

\frame{

	\begin{itemize}

	% Common problems are, when mainline has received updates, that the
	% extension carries

	\item wrong argument types, wrong number of arguments or
	order of these in a call/function head

	\pause

	% That may not be big of a deal since the compiler warns us about
	% these things, but...

	\item resulting compiler warnings ignored by the novice user\\
	({}``it compiles? ship it!'')

	\pause

	% This leads to silent corruption, and most likely an unhappy user
	% when the machine suddenly gets stuck in unexpected ways.

	\item silent corruption, kernel oops and an unhappy
	user.

	~\\

	\texttt{~~~~~~~~~~~~~~~~~~~~\textasciicircum{}\_\_\textasciicircum{}~\\
	\textbackslash{}|/~\_\_\_\_~\textbackslash{}|/~~~~~~~~(xx)\textbackslash{}\_\_\_\_\_\_\_~\\
	\char`\"{}@'/~..~\textbackslash{}`@\char`\"{}~~~~~~~~(\_\_)\textbackslash{}~~~~~~~)\textbackslash{}/\textbackslash{}~\\
	/\_|~\textbackslash{}\_\_/~|\_\textbackslash{}~~~~~~~~~U~~||-{}-{}-{}-w~|~\\
	~~~\textbackslash{}\_\_U\_/~~~~~~~~~~~~~~~||~~~~~||\\
	(sparc64)~~~~~~~~~~~(parisc)}\\

	\end{itemize}

}

\subsection{Maintenance}

\frame{
	\frametitle{Maintenance}

	\begin{itemize}

	\item extensions had to be updated whenever the kernel API
	changed\pause\\

	\textit{every single} extension~-- more than 30 during prime time

	\pause

	\item frowned-upon \texttt{\#if} forest to make code work across
	APIs of multiple versions

	\item workarounds replicated among all extensions~--\\
	that is, if they were updated at all

	\end{itemize}

}

\frame{

	\begin{alertblock}{\textbf{\#if} forest example}

	{\footnotesize \texttt{\textbf{\#if LINUX\_VERSION\_CODE >= KERNEL\_VERSION(2,6,23)}\\
	static bool ipt\_acc\_checkentry(const char~{*}tablename,\\
	\textbf{\#else}\\
	static int ipt\_acc\_checkentry(const char~{*}tablename,\\
	\textbf{\#endif}\\
	\textbf{\#if LINUX\_VERSION\_CODE >= KERNEL\_VERSION(2,6,16)}\\
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~const void~{*}e,\\
	\textbf{\#else}\\
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~const struct ipt\_entry~{*}e,\\
	\textbf{\#endif}\\
	\textbf{\#if LINUX\_VERSION\_CODE >= KERNEL\_VERSION(2,6,17)}\\
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~const struct xt\_target~{*}target, \\
	\textbf{\#endif}\\
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~void~{*}targinfo,\\
	\textbf{\#if LINUX\_VERSION\_CODE < KERNEL\_VERSION(2,6,19)}\\
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~unsigned int targinfosize,\\
	\textbf{\#endif}\\
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~unsigned int hook\_mask)}}

	\end{alertblock}

}

\subsection{Conclusion}

\frame{
	\frametitle{Conclusion}

	\begin{itemize}

	\item code updates do not scale

	% And as we have seen,

	\item patching the kernel source may incur traps

	\pause

	\item recompiling the kernel takes its time

	% 2–3 hours for AMD Athlon XP 2000+ (sinlge K7 core)
	% still 15 minutes on AMD Opteron 270 (four K8 cores)
	%
	% And if you are providing different kernel flavors like some
	% distributions do (e.g. normal and PAE) and/or multi-arch builds,
	% time required for a full build accumulates quickly.

	\item voids the automatic stable/security updates your distro provides

	% because you are rolling your own.

	\end{itemize}

}

\subsection{Recent activities}

\frame{

	\begin{itemize}

	\item a lot of extensions got marked as deleted in the VCS
	(May~2006)

	\begin{itemize}

		\item {\footnotesize some were merged since 2.6.14
		(Oct~2005) already}\\

		{\tiny \textsf{mport}/\textsf{multiport}, \textsf{iprange},
		\textsf{NETMAP}, \textsf{comment}, \textsf{goto},
		\textsf{NETLINK}/\textsf{NFQUEUE}, \textsf{unclean}(partial)}

		\item {\footnotesize FYI: Linux 2.6.17 released in
		June~2006}

	\end{itemize}

	\item user demand for non-standard extensions still there

	\pause

	\item more extensions found their way into mainline later

	\begin{itemize}

		\item {\tiny 2006: \textsf{nth}, \textsf{quota},
		\textsf{random}}

		\item {\tiny 2007: \textsf{TRACE},
		\textsf{connrate}/\textsf{rateest}, \textsf{connlimit},
		\textsf{time}, \textsf{u32}}

	\end{itemize}

	%% merge date
	%% 2002-00-00 mport, obsoleted by multiport
	%% 2003-08-24 iprange
	%% 2003-08-24 NETMAP
	%% 2004-09-23 comment
	%% 2005-08-21 goto
	%% 2005-08-29 NETLINK, obsoleted by NFQUEUE
	%% 2006-00-00 unclean, partially merged in Netfilter
	%%[7^]
	%% 2006-05-12 **DELETION MARK DAY**
	%% 2006-05-29 nth, superseded by statistic
	%% 2006-05-29 quota
	%% 2006-05-29 random, superseded by statistic
	%% 2007-07-07 TRACE
	%% 2007-07-07 u32
	%% 2007-07-14 connlimit
	%% 2007-09-28 time
	%% 2007-12-04 connrate, obsoleted by merge of rateest
	%%[8^]
	%% 2008-01-29 TARPIT [Xt-a]
	%% 2008-03-18 geoip [Xt-a]
	%% 2008-03-27 ipp2p [Xt-a]
	%% 2008-04-02 condition [Xt-a]
	%% 2008-04-09 IPMARK [Xt-a]
	%% 2008-09-01 fuzzy [Xt-a]
	%% 2009-03-08 ipv4options [Xt-a]
	%%[6^]
	%% 9998-99-99 expire
	%% 9998-99-99 IPV4OPTIONS
	%% 9998-99-99 osf
	%% 9998-99-99 pool
	%% 9998-99-99 psd
	%% 9998-99-99 rpc
	%% 9998-99-99 rsh
	%% 9998-99-99 TCPLAG
	%% 9998-99-99 XOR, (sample module?)
	%%[9^]
	%% 9999-99-99 ROUTE, obsoleted by iproute2+realm+MARK
	%% 9999-99-99 set, standalone package by now (ipset)
	%% 9999-99-99 tproxy, standalone package by now

	\item other extensions have gone into Xtables-addons\\

	\begin{itemize}

		\item {\tiny 2008: \textsf{IPMARK}, \textsf{TARPIT},
	        \textsf{condition}, \textsf{fuzzy}, \textsf{geoip},
	        \textsf{ipp2p}}

		\item {\tiny 2009: \textsf{ipv4options}}

	% So if you happened to use any of these extensions, these are the
	% locations of the most current code at the time of this workshop.

	\end{itemize}

	\end{itemize}

}

\frame{

	\begin{itemize}

	\item About 8 or so {}``left'' in the depths of the POM history.\\

	{\footnotesize No real demand for these.}

	% How do I define demand? User requests (mail, IRC) per time
	% quantum. This is purely subjective of course.

	\item (Update: Remaining code deleted December 2008)

	\end{itemize}

}

\section{Xtables-addons}

\subsection{Introduction}

\frame{
	\frametitle{What it is}

	{}``\textit{Xtables-addons is the successor to
	patch-o-matic(-ng). Likewise, it contains extensions that were not
	accepted in the main iptables package [so far]}''.\\

	% Originally it read "is the proclaimed successor" --
	% No contestants have spoken out, so I take it the proclamation has
	% been confirmed.

	~\\

	Same idea, different implementation.

	\pause

	~\\

	% If anyone wants to look through the code as I discuss things,
	% this is the URL to clone from. There is also a gitweb.

	\url{http://xtables-addons.sf.net/} {\footnotesize (homepage)}\\

	\url{git://xtables-addons.git.sf.net/gitroot/xtables-addons/xtables-addons}
	{\footnotesize (clone)}\\

	\url{http://xtables-addons.git.sf.net/} {\footnotesize (gitweb)}

}

\subsection{Implementation overview}

\frame{
	\frametitle{How it works}

	% In essence, what is different from patch-o-matic is:

	\begin{itemize}

	\item no patches (\texttt{.diff} files) or POM trees

	% POM trees are a combination of patches and sources. All
	% newly-created files are represented as-is, in a tree structure
	% following the Linux kernel source hierarchy.
	%
	% Files that already exist in the Linux kernel and will be touched
	% are posted as a patch.
	%
	% There is also a special patchfile type, the .ladd, which is raw
	% text (no diff), but applies to existing files; by merly appending
	% the raw text to the existing file in the kernel source.

	\item plain source code and Makefiles

	% The build environment usually includes Makefiles, Kconfig files and
	% headers. Redhat/Fedora and kernels of mine for openSUSE provide
	% such packages that are smaller than the full kernel source.

	\item only requires the kernel build environment, full source not
	needed

	{\footnotesize (\texttt{/lib/modules/\textbf{\$version}/build/})}

	\pause

	\item extensions built as modules

	\item no reboot, instant use~-- also perfect for development

	% as you can just use rmmod, fix the extension (unless you fried
	% your machine), compile and modprobe again.

	\item works with the distro-provided kernel\\

	\footnotesize{(i.\,e.\ not having to roll your own and miss out on
	distro kernel updates.)}

	\pause

	\begin{itemize}

		\item kernel 2.6.17 or up (2\textonequarter{} years old as of
		Oct 2008, so good coverage)

		% Some versions are only compile-tested, but that is still a
		% good achievement.

		\item minus points for distros doing excessive backports
		{\footnotesize (CentOS5)}~-- one needs to hand-tweak the
		Xt-a source and remove what has already been backported.

	\end{itemize}

	\end{itemize}	

}

\subsection{Implementation details}

\frame{
	\frametitle{Implementation}

	\begin{itemize}

	\item uses an extra API layer so that extensions remain relatively
	clean of version-related \texttt{\#if}s.\\

	% {\footnotesize (Other directives would remain present if the code
	% were in the kernel.)}

	\texttt{\small grep '\textasciicircum{}\#if LINUX\_VERSION' xt\_{*}.c\\
	8} {\footnotesize \textsf(for 15 extensions, 0.53/file)}

	% Other projects have a much higher clutter count, up to 22/file.
	% (But of course, they may also extend beyond < 2.6.17.)

	\item uses glue functions and macro-based redirection
	{\footnotesize (\texttt{compat\_xtables.[ch]})}

	% Function names are redefined using macros to carry a xtnu_ prefix,
	% which “redirects” function calls to the compat layer.

	% \item API is largely that of the latest Linux kernel

	% So

	\item most extensions need no more than {\small \texttt{\#include
	\char`\"{}compat\_xtables.h\char`\"{}}} as the last include
	directive

	% It must come last, so that the macro redefinition will not apply
	% to the kernel headers.

	\end{itemize}

}

\frame{
	\frametitle{Limitations}

	\begin{itemize}

	\item patching the kernel source, like header files (as
	\textsf{ACCOUNT}, \textsf{IMQ} and \textsf{layer7} require), is not
	within scope.

	\begin{itemize}

		\item but you could still make use of the glue code for the
		parts that do not patch existing files

	\end{itemize}

	\item compiling extensions into non-modular kernels seems possible,
	but no demand so far\\

	{\footnotesize (\texttt{cd linux/; ln -s ../xtables-addons;} and
	edit some kernel Makefile to descend into
	\texttt{xtables-addons/extensions/})}

	\end{itemize}

}

\subsection{Current state}

\frame{
	\frametitle{Current state}

	Problems with code resolved when it was imported into
	Xtables-addons.

	\begin{itemize}

	\item works in mixed-bitness environments\\

	{\footnotesize e.\,g.\ 64-bit kernel and 32-bit userspace}

	\item {\footnotesize (believed to be)} alignment- and
	endianess-correct\\

	{\footnotesize (unfortunate lack of non-x86 hardware to fully test)}

	\item added IPv6 support to some extensions

	\end{itemize}

}

\subsection{Extensions}

\frame{
	\frametitle{Extensions}

	{\footnotesize (By various authors.)}

	\begin{itemize}

	\item \textsf{condition}~-- match on a flag changable from
	userspace, e.\,g.\ (discrete) weather condition {\footnotesize (see
	other talk)}.

	\pause

	\item \textsf{geoip}~-- match on countries.\\

	% http://lwn.net/Articles/297545/

	{\small \begin{quote}``Microsoft and Google I can live without, but an
	internet without North Korea is no internet I want to be a part
	of!''\end{quote}\footnotesize{~~~~~~~~---\textsf{leoc} on LWN.net}}\\

	~\\

	\texttt{-A INPUT -m geoip -{}-src-cc KP -j ACCEPT}

	\pause

	\item \textsf{TEE}~-- reroute a copy of the packet

	\end{itemize}

}

\subsection{Extensions}

\frame{
	\frametitle{Extensions}

	\begin{itemize}

	\item \textsf{TARPIT}~-- hold TCP connection indefinitely. {\small Use
	this for port 25 if you do not run a receiving server.}

	\pause

	\item \textsf{DELUDE}~-- does TCP handshake, but close connections
 	afterwards. Thwarts nmap stealth scans. {\small (Also see
	\textsf{CHAOS} for combined portscanner countermeasures.)}

	% Chaostables was a small investigation project of mine how to
	% trigger nmap's workarounds it employs for oddities of some target
	% operating systems.

	\pause

	\item {\small (more added over time)}

	% The Xt-a package also has a number of sample modules (ECHO,
	% ipaddr) that serve as a description base to the "Writing your own
	% Netfilter modules" book.

	\item Sample modules for documentation

	\end{itemize}

}

\subsection{Availability}

\frame{
	\frametitle{Availability}

	\begin{itemize}

	\item As of 2009: Alpine Linux, CRUX, Debian, Gentoo, OpenWRT, Polish
	Linux Distribution (PLD), openSUSE, Shorewall, Slackware.

	\item presenter {\footnotesize (that's me)} has RPMs for openSUSE

	% tarballs:

	\item \url{http://freecode.com/projects/xtables-addons/}

	\end{itemize}

}
%\subsection{Future plans}
%
%\frame{
%	\frametitle{Future plans}
%
%	There are not really any plans at the moment.
%	The software package is in good shape.
%
%}

\subsection{Documentation}

\frame{

	\frametitle{Documentation}

	\begin{itemize}

	\item {}``Writing Netfilter modules''\\
	{\small Book in PDF format on \url{http://inai.de/}}

	\end{itemize}

}

\end{document}