binpatchng

NAME

binpatchng - a make based framework to build binary patches for OpenBSD handable with the pkg_*-Tools.

SYNOPSIS

.include "bsd.binpatch.mk"

DESCRIPTION

What is binpatchng

binpatchng is a framework for creating binary patches for OpenBSD on all platforms in a semi-automatic way. It is derived from binpatch for OpenBSD as released in Version 1.0 by Gerardo Santana. It can automatically download the source patches published on http://www.openbsd.org/errata.html, apply them, build them, and package the result into binary patches that can be installed (and uninstalled) using the OpenBSD pkg_* tools, pkg_add(1) and pkg_delete(1). Since the binary patches are installed with the pkg tools, they are also shown when pkg_info(1) is run. The source patch is included in the package description and can be displayed with pkg_info(1).

Why binary patches

Binary patches is a convenient way to keep your servers up to date with security and reliability patches. Unlike the traditional method of patching the source tree, applying binary patches doesn't need extra disk space to hold the whole source tree, compilers or a powerful enough CPU to build the programs patched in a reasonable period of time. Especially looking at environments where more than just a few machines need to be kept up-to-date a solution is needed where patches can easily be pushed from a master to N clients.

Using binpatchng

The binpatchng framework resemblances the OpenBSD ports subsystem in many ways. It's no coincidence since binpatch took ideas from the OpenBSD ports subsystem.

binpatchng is a make script with routines that automate downloading, applying, building and packaging binary patches. Using binpatch means executing the following tasks: maintenance, building and installation.

Maintenance and building are not intended for end users of binary patches. If you are insterested only on installing a binary patch you can safely skip the following two sections.

Maintenance

The magic in binpatch must be invoked by a custom Makefile that informs binpatch about the patches available and how they should be built. It's similar as making a port, where you need to write a Makefile with directions about how a port must be built. A sample self-documented Makefile is included in this distribution. After editing a Makefile, we have to build the patched files.

This is the sequence of targets:

init: "fake" install of a complete OpenBSD system
extract: unpacks the OpenBSD sources
patch: downloads the patch given from the master site and applies it
build: builds the programs/libraries affected
plist: creates the PLIST with the names of the files modified
package: creates the final package

The binpatch directory structure must be like this:

binpatch/
	|
	+--- Makefile
	|
	+--- bsd.binpatch.mk
	|
	+--- distfiles/
	|	|
	|	+--- i386/  (installation sets here)
	|	|
	|	+--- src.tar.gz
	|	|
	|	+--- sys.tar.gz
	|
	+--- packages/
	|
	+--- patches/
	|	|
	|	+--- common/
	|	|
	|	+--- i386/
	|
	+--- pkg/
	|	|
	|	+--- COMMENT-i386-001 (COMMENT files with comments wrt patch)
	|	|
	|	+--- DESC-i386-001 (DESCR files with the source patch here)
	|	|
	|	+--- PLIST-i386-001 (PLIST files here)
	|
	+--- work-binpatch-4.2/
		|
		+--- fake/
		|
		+--- obj/
		|
		+--- src/
		|
		+--- work/

All directories are created by binpatch. Building the patches files is as easy as:

# make PATCH="001" build

or:

# make PATCH="001"

since build is the default target. build will run all the previous steps needed. After that, run the plist target: # make PATCH="001" plist You'll get a PLIST file under pkg with the name of the modified files. Builders of binary patches will use this file to package binary patches. WARNING: binpatch is not aware of any dependency between patches. You have to build them sequentially. DO NOT clean anything.

3.2 Building a binary patch

# make PATCH="001" package

That's it. This will create a binpatch-${OSREV}-${ARCH}-001.tgz file under the pkg directory.

If one wants to create simple tarballs with the binary patches, instead of packages installable with the pkg_* tools, one can pass the option "MODE=TGZ" to the make calls:

# make PATCH="001" MODE="TGZ" package

However, this must be done throughout the 'plist' as well as the 'package' steps. This can be set permanently by editing the file 'binpatch.settings'.

Installation

From within the binpatch subdirectory and after building the binary patch:

# make PATCH="001" install

or if you got the binary patch from somewhere else:

# pkg_add binpatch-${OSREV}-${ARCH}-001.tgz

If you just created tarballs:

# tar xzpf binpatch-${OSREV}-${ARCH}-001.tgz -C /

If you use the binary patch packages, you can also uninstall patches (rollback):

# pkg_delete binpatch-${OSREV}-${ARCH}-001

If a new kernel is installed by the binary patches, you can boot the rollback kernel (previous working kernel) from the boot loader with:

> boot kernelname.rollback

DOWNLOAD

Version 1.1 of binpatchng: binpatchng-1.1.tar.gz.

LICENSE

binpatchng is released under the 3-Clause BSD License. See COPYRIGHT.TXT.

BUGS

Please report to mail address listed below.

AUTHORS

Felix Kronlage - fkr at puffy-at-work.org