head	1.134;
access;
symbols
	ENGLISH_POLICE_AFTER:1.121
	ENGLISH_POLICE_BEFORE:1.77
	SYSADMIN_FORWARD:1.129
	RC1MICHAEL:1.121;
locks; strict;
comment	@# @;


1.134
date	2003.04.02.10.04.28;	author thl;	state Exp;
branches;
next	1.133;

1.133
date	2003.01.21.11.19.12;	author ms;	state Exp;
branches;
next	1.132;

1.132
date	2003.01.19.11.15.16;	author rse;	state Exp;
branches;
next	1.131;

1.131
date	2002.09.23.11.06.54;	author rse;	state Exp;
branches;
next	1.130;

1.130
date	2002.09.19.09.28.28;	author rse;	state Exp;
branches;
next	1.129;

1.129
date	2002.09.19.08.02.12;	author rse;	state Exp;
branches;
next	1.128;

1.128
date	2002.04.06.13.15.59;	author rse;	state Exp;
branches;
next	1.127;

1.127
date	2002.04.05.22.13.42;	author rse;	state Exp;
branches;
next	1.126;

1.126
date	2002.04.05.22.06.07;	author rse;	state Exp;
branches;
next	1.125;

1.125
date	2002.04.05.22.01.31;	author rse;	state Exp;
branches;
next	1.124;

1.124
date	2002.04.05.21.22.08;	author rse;	state Exp;
branches;
next	1.123;

1.123
date	2002.04.05.21.20.53;	author rse;	state Exp;
branches;
next	1.122;

1.122
date	2002.04.05.21.20.02;	author rse;	state Exp;
branches;
next	1.121;

1.121
date	2002.04.05.18.07.16;	author ms;	state Exp;
branches;
next	1.120;

1.120
date	2002.04.05.18.01.45;	author ms;	state Exp;
branches;
next	1.119;

1.119
date	2002.04.05.17.52.57;	author ms;	state Exp;
branches;
next	1.118;

1.118
date	2002.04.05.17.31.02;	author ms;	state Exp;
branches;
next	1.117;

1.117
date	2002.04.05.17.16.41;	author ms;	state Exp;
branches;
next	1.116;

1.116
date	2002.04.05.16.40.55;	author rse;	state Exp;
branches;
next	1.115;

1.115
date	2002.04.05.16.35.54;	author rse;	state Exp;
branches;
next	1.114;

1.114
date	2002.04.05.16.21.17;	author rse;	state Exp;
branches;
next	1.113;

1.113
date	2002.04.05.16.16.08;	author rse;	state Exp;
branches;
next	1.112;

1.112
date	2002.04.05.15.57.49;	author ms;	state Exp;
branches;
next	1.111;

1.111
date	2002.04.05.15.55.29;	author ms;	state Exp;
branches;
next	1.110;

1.110
date	2002.04.05.15.29.41;	author rse;	state Exp;
branches;
next	1.109;

1.109
date	2002.04.05.15.23.57;	author rse;	state Exp;
branches;
next	1.108;

1.108
date	2002.04.05.15.14.02;	author rse;	state Exp;
branches;
next	1.107;

1.107
date	2002.04.05.15.08.41;	author ms;	state Exp;
branches;
next	1.106;

1.106
date	2002.04.05.15.03.19;	author ms;	state Exp;
branches;
next	1.105;

1.105
date	2002.04.05.14.45.49;	author ms;	state Exp;
branches;
next	1.104;

1.104
date	2002.04.05.14.24.35;	author rse;	state Exp;
branches;
next	1.103;

1.103
date	2002.04.05.14.21.53;	author ms;	state Exp;
branches;
next	1.102;

1.102
date	2002.04.05.14.05.16;	author ms;	state Exp;
branches;
next	1.101;

1.101
date	2002.04.05.13.27.39;	author cs;	state Exp;
branches;
next	1.100;

1.100
date	2002.04.05.13.26.13;	author rse;	state Exp;
branches;
next	1.99;

1.99
date	2002.04.05.13.24.35;	author rse;	state Exp;
branches;
next	1.98;

1.98
date	2002.04.05.13.17.28;	author rse;	state Exp;
branches;
next	1.97;

1.97
date	2002.04.05.13.13.22;	author rse;	state Exp;
branches;
next	1.96;

1.96
date	2002.04.05.13.04.46;	author ms;	state Exp;
branches;
next	1.95;

1.95
date	2002.04.05.12.49.15;	author ms;	state Exp;
branches;
next	1.94;

1.94
date	2002.04.05.12.42.47;	author ms;	state Exp;
branches;
next	1.93;

1.93
date	2002.04.05.12.28.51;	author ms;	state Exp;
branches;
next	1.92;

1.92
date	2002.04.05.10.53.16;	author ms;	state Exp;
branches;
next	1.91;

1.91
date	2002.04.05.10.04.39;	author ms;	state Exp;
branches;
next	1.90;

1.90
date	2002.04.05.10.01.27;	author ms;	state Exp;
branches;
next	1.89;

1.89
date	2002.04.05.10.00.06;	author ms;	state Exp;
branches;
next	1.88;

1.88
date	2002.04.05.08.30.05;	author rse;	state Exp;
branches;
next	1.87;

1.87
date	2002.04.04.19.39.24;	author ms;	state Exp;
branches;
next	1.86;

1.86
date	2002.04.04.17.00.46;	author ms;	state Exp;
branches;
next	1.85;

1.85
date	2002.04.04.11.58.54;	author rse;	state Exp;
branches;
next	1.84;

1.84
date	2002.04.04.07.15.54;	author thl;	state Exp;
branches;
next	1.83;

1.83
date	2002.04.03.19.24.20;	author ms;	state Exp;
branches;
next	1.82;

1.82
date	2002.04.03.17.04.55;	author rse;	state Exp;
branches;
next	1.81;

1.81
date	2002.04.03.16.36.25;	author ms;	state Exp;
branches;
next	1.80;

1.80
date	2002.04.03.15.51.43;	author ms;	state Exp;
branches;
next	1.79;

1.79
date	2002.04.03.15.43.18;	author ms;	state Exp;
branches;
next	1.78;

1.78
date	2002.04.03.15.11.32;	author ms;	state Exp;
branches;
next	1.77;

1.77
date	2002.04.03.14.45.18;	author rse;	state Exp;
branches;
next	1.76;

1.76
date	2002.04.03.14.39.44;	author rse;	state Exp;
branches;
next	1.75;

1.75
date	2002.04.03.14.23.26;	author rse;	state Exp;
branches;
next	1.74;

1.74
date	2002.04.03.14.02.18;	author rse;	state Exp;
branches;
next	1.73;

1.73
date	2002.04.03.13.48.07;	author rse;	state Exp;
branches;
next	1.72;

1.72
date	2002.04.03.13.35.37;	author rse;	state Exp;
branches;
next	1.71;

1.71
date	2002.04.03.13.28.12;	author rse;	state Exp;
branches;
next	1.70;

1.70
date	2002.04.03.12.42.06;	author rse;	state Exp;
branches;
next	1.69;

1.69
date	2002.04.03.12.41.47;	author rse;	state Exp;
branches;
next	1.68;

1.68
date	2002.04.03.12.04.05;	author rse;	state Exp;
branches;
next	1.67;

1.67
date	2002.04.03.10.04.25;	author rse;	state Exp;
branches;
next	1.66;

1.66
date	2002.04.02.20.07.55;	author thl;	state Exp;
branches;
next	1.65;

1.65
date	2002.04.02.20.05.40;	author thl;	state Exp;
branches;
next	1.64;

1.64
date	2002.04.02.18.23.22;	author rse;	state Exp;
branches;
next	1.63;

1.63
date	2002.04.01.11.35.52;	author rse;	state Exp;
branches;
next	1.62;

1.62
date	2002.03.28.22.07.09;	author thl;	state Exp;
branches;
next	1.61;

1.61
date	2002.03.28.21.59.38;	author thl;	state Exp;
branches;
next	1.60;

1.60
date	2002.03.28.21.34.30;	author thl;	state Exp;
branches;
next	1.59;

1.59
date	2002.03.28.21.10.08;	author rse;	state Exp;
branches;
next	1.58;

1.58
date	2002.03.28.21.03.52;	author rse;	state Exp;
branches;
next	1.57;

1.57
date	2002.03.28.21.02.08;	author rse;	state Exp;
branches;
next	1.56;

1.56
date	2002.03.28.20.56.33;	author thl;	state Exp;
branches;
next	1.55;

1.55
date	2002.03.28.20.55.44;	author rse;	state Exp;
branches;
next	1.54;

1.54
date	2002.03.28.20.40.43;	author rse;	state Exp;
branches;
next	1.53;

1.53
date	2002.03.28.18.01.04;	author cs;	state Exp;
branches;
next	1.52;

1.52
date	2002.03.28.17.25.16;	author rse;	state Exp;
branches;
next	1.51;

1.51
date	2002.03.28.17.22.02;	author rse;	state Exp;
branches;
next	1.50;

1.50
date	2002.03.28.17.14.15;	author cs;	state Exp;
branches;
next	1.49;

1.49
date	2002.03.28.15.52.53;	author thl;	state Exp;
branches;
next	1.48;

1.48
date	2002.03.28.15.49.06;	author cs;	state Exp;
branches;
next	1.47;

1.47
date	2002.03.28.15.25.49;	author thl;	state Exp;
branches;
next	1.46;

1.46
date	2002.03.28.14.55.01;	author thl;	state Exp;
branches;
next	1.45;

1.45
date	2002.03.28.14.39.09;	author thl;	state Exp;
branches;
next	1.44;

1.44
date	2002.03.28.14.26.47;	author rse;	state Exp;
branches;
next	1.43;

1.43
date	2002.03.28.13.38.23;	author rse;	state Exp;
branches;
next	1.42;

1.42
date	2002.03.28.13.21.07;	author rse;	state Exp;
branches;
next	1.41;

1.41
date	2002.03.28.12.38.10;	author rse;	state Exp;
branches;
next	1.40;

1.40
date	2002.03.28.12.14.37;	author thl;	state Exp;
branches;
next	1.39;

1.39
date	2002.03.28.10.52.35;	author thl;	state Exp;
branches;
next	1.38;

1.38
date	2002.03.28.10.49.48;	author thl;	state Exp;
branches;
next	1.37;

1.37
date	2002.03.28.10.44.14;	author thl;	state Exp;
branches;
next	1.36;

1.36
date	2002.03.28.10.35.11;	author thl;	state Exp;
branches;
next	1.35;

1.35
date	2002.03.28.08.37.06;	author thl;	state Exp;
branches;
next	1.34;

1.34
date	2002.03.28.08.35.04;	author thl;	state Exp;
branches;
next	1.33;

1.33
date	2002.03.27.20.14.20;	author rse;	state Exp;
branches;
next	1.32;

1.32
date	2002.03.27.20.13.16;	author rse;	state Exp;
branches;
next	1.31;

1.31
date	2002.03.27.14.56.50;	author thl;	state Exp;
branches;
next	1.30;

1.30
date	2002.03.27.14.19.37;	author thl;	state Exp;
branches;
next	1.29;

1.29
date	2002.03.27.13.02.02;	author thl;	state Exp;
branches;
next	1.28;

1.28
date	2002.03.27.10.35.38;	author thl;	state Exp;
branches;
next	1.27;

1.27
date	2002.03.27.10.12.43;	author thl;	state Exp;
branches;
next	1.26;

1.26
date	2002.03.27.10.04.22;	author thl;	state Exp;
branches;
next	1.25;

1.25
date	2002.03.27.09.13.54;	author thl;	state Exp;
branches;
next	1.24;

1.24
date	2002.03.27.08.31.11;	author thl;	state Exp;
branches;
next	1.23;

1.23
date	2002.03.26.22.13.00;	author rse;	state Exp;
branches;
next	1.22;

1.22
date	2002.03.26.21.46.54;	author rse;	state Exp;
branches;
next	1.21;

1.21
date	2002.03.26.20.03.20;	author rse;	state Exp;
branches;
next	1.20;

1.20
date	2002.03.26.20.01.12;	author rse;	state Exp;
branches;
next	1.19;

1.19
date	2002.03.26.17.21.14;	author thl;	state Exp;
branches;
next	1.18;

1.18
date	2002.03.26.13.53.43;	author thl;	state Exp;
branches;
next	1.17;

1.17
date	2002.03.26.09.28.49;	author thl;	state Exp;
branches;
next	1.16;

1.16
date	2002.03.25.14.40.59;	author thl;	state Exp;
branches;
next	1.15;

1.15
date	2002.03.25.12.17.16;	author rse;	state Exp;
branches;
next	1.14;

1.14
date	2002.03.25.12.12.56;	author rse;	state Exp;
branches;
next	1.13;

1.13
date	2002.03.25.08.53.45;	author cs;	state Exp;
branches;
next	1.12;

1.12
date	2002.03.24.12.52.24;	author rse;	state Exp;
branches;
next	1.11;

1.11
date	2002.03.24.11.55.58;	author rse;	state Exp;
branches;
next	1.10;

1.10
date	2002.03.22.16.41.33;	author rse;	state Exp;
branches;
next	1.9;

1.9
date	2002.03.22.16.10.23;	author rse;	state Exp;
branches;
next	1.8;

1.8
date	2002.03.22.10.14.47;	author rse;	state Exp;
branches;
next	1.7;

1.7
date	2002.03.22.10.12.02;	author rse;	state Exp;
branches;
next	1.6;

1.6
date	2002.03.22.10.08.27;	author rse;	state Exp;
branches;
next	1.5;

1.5
date	2002.03.22.09.58.47;	author cs;	state Exp;
branches;
next	1.4;

1.4
date	2002.03.22.09.21.01;	author rse;	state Exp;
branches;
next	1.3;

1.3
date	2002.03.21.19.03.11;	author rse;	state Exp;
branches;
next	1.2;

1.2
date	2002.03.21.19.01.23;	author rse;	state Exp;
branches;
next	1.1;

1.1
date	2002.03.21.18.55.44;	author rse;	state Exp;
branches;
next	;


desc
@@


1.134
log
@correct spelling of "privileges"
@
text
@
Package Once, Use Everywhere
============================

Cross-platform Unix software packaging with OpenPKG 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You might prefer Open Source software for its well-known advantages, but
sometimes regret the downside of its associated open and distributed
development when trying to apply it manually to your work environment.
To keep a work environment stable and secure, it's often necessary to
locate the latest version of an application on the Internet and collect
its most recent patches containing security and bug fixes. However,
there is often no single location for these files. After the search
finishes, a system administrator must build and install the new binaries
on every Unix box in the network, and might find that the application
needs slight tweaking on each of them. Then after a round of laborious
build manipulation, it might not be clear that the application will run
as intended on each of the different platforms. If the application is a
daemon even more work awaits, because most Unix flavors have their own
method of starting and stopping daemons.

If the previous operation succeeds after all, the system administrator
might be left to wonder why it is necessary to clutter up the system
with residual installation files and how do the vendors think the
residue should be removed? Also, if the C</var> file system later runs
out of disk space due to an overgrown application log, do the vendors
think that the responsibility lies with the system administrator to
implement log file rotation himself? Such redundant basic tasks can and
should be avoided.

What can a system administrator do when facing obstacles like these?
He might start by sticking with vendor packages only. Unfortunately,
there may be several different Unix variants to administer. Worse yet,
no existing vendor packaging facility supports multiple installation of
an application, a feature useful for multiple project coexistence on a
single machine and independent package testing. Another missing feature
regards the management of coexisting packaged and unpackaged software.
Finally, if the system administrator wants a software installation and
configuration guide for his vacation replacement, he might as well give
up. This is usually impossible, because every vendor packaging approach
is different and cannot be uniformly applied across all major Unix
platforms.

OpenPKG to the rescue 
---------------------

OpenPKG is a Open Source software project initiated by Cable & Wireless,
a leading international Internet Service Provider (ISP).
The project began in November 2000, and has grown to be a collaborative
software development effort managed and maintained by many. The project
aims to create a modular and flexible Unix subsystem for cross-platform
software packaging and installation.

More specifically, the goals of OpenPKG stem from the historical problem
often faced in the daily operation of an ISP. The major Unix platforms
in operation at ISPs include FreeBSD, Linux and Solaris. To satisfy the
demands of such a diverse computing environment, the installation and
maintenance of software packages across these platforms greatly benefits
from a unified and consistent approach.

OpenPKG is not limited to the three major platforms just mentioned,
however. As summarized in Table_1, OpenPKG has more ambitious goals. To
achieve such cross-platform portability, OpenPKG provides a subsystem on
top of the underlying Unix system as shown in Figure_1. It covers every
essential server software component from shells, editors, compilers,
and up to network daemons and add-on applications. Hence, the intended
target community consists of system administrators faced with a large
and diverse set of Unix servers.

Internally, OpenPKG leverages the existing packaging technology of
the popular RedHat Package Manager (RPM). However, the RPM software
included with OpenPKG is specially extended to become more unique and
self-contained. The more than 400 available OpenPKG packages are really
just RPM packages under the hood, but were developed from scratch in a
OpenPKG standard approach. The packages are clean and robust, because
they follow strict style guidelines and environment requirements.

To meet these OpenPKG guidelines and standards, a package must be built
from pristine vendor sources in a non-root temporary environment.
It has to work in an arbitrary file system location, has to follow
a strict file system layout, and must be self-contained within its
OpenPKG instance. Furthermore, the package must be independent from
external Unix facilities, has to install with a reasonable and ready
to go configuration, and has to use log file rotations and other such
administrative wonders.

These well specified package-building guidelines yield several benefits
to OpenPKG users. OpenPKG users can install an instance (the OpenPKG
subsystem and user-chosen packages) under any file system location,
and even install multiple such instances on a single Unix system.
Incidentally, the main OpenPKG project environment is hosted on a
machine with six other ongoing software projects, each with their own
dedicated OpenPKG instance. To separately satisfy each project's needs,
the associated OpenPKG instance serves every required software component
from Postfix to BIND, and INN to Apache. Each project can therefore run
in its own isolated environment, much like on a virtual machine.

Covering the whole OpenPKG package lifecycle 
--------------------------------------------

OpenPKG follows an approach of minimum OS intrusion and maximum
standalone presence. It tries hard to smooth out the differences between
the underlying vendor solutions. Sometimes this means that it has to
break with well known standards in order to provide a cleaner solution.
This is the most reasonable approach, and leads to a consistent
cross-platform solution.

A question often asked is, "why does OpenPKG use RPM as the underlying
packaging technology when other alternatives exist?" There are indeed
other similar packaging technologies available to projects like
OpenPKG, with the most prominent alternatives to RPM being the Debian
C<dpkg>/C<apt> combination, FreeBSD ports, and System V C<pkgadd>.
According to some, RPM may not be the greatest packaging system since
sliced bread. However, RPM along with its OpenPKG extensions is the only
solution covering the I<whole> package lifecycle in a fully consistent
way.

To elaborate, the OpenPKG package lifecycle starts with fetching,
unpacking, patching, and building the source package from pristine
vendor sources. It goes on to build the binary package in an
unprivileged environment, and finishes its life term with the
installation, upgrade, and uninstallation of the binary package on the
target OpenPKG instance. This all works in a self-contained environment,
and is driven by concise yet complete package specifications (RPM
C<.spec> files). So, to finally answer the question, OpenPKG adopts RPM
as its underlying packaging technology because no other can fulfill
these steep requirements.

It is important to note that OpenPKG is primarily about packaging, not
porting. A requirement of the OpenPKG packaging philosophy is that the
vendor software be portable to begin with. Minor platform porting issues
are fixed by the OpenPKG packagers, but fundamental changes are not
considered. In fact, the main reason for some platforms lacking full
OpenPKG support is that the amount of overhead in building software on
them is not within reason.

It may surprise some that OpenPKG officially discourages the use of
binary packages, and only provides them for bootstrapping (development
tools not available) and emergency (tight time constraints) purposes.
Experience has shown that installing binary packages built from source
packages on the target machine outperforms other binary methods in
respect to security and robustness.

There are simply too many subtle differences between most build and
install systems that can influence the binary at run time and cause
trouble. Some important run time parameters, such as the maximum size
of shared memory segments, are compiled into the binary on the build
machine. Among many examples of such a run time build dependency is
a situation in which an Apache package is built with mod_ssl and MM.
The dependency details of such a combination are overwhelming, when
sorting out the run time parameters. To avoid such trouble, OpenPKG
believes that the only reasonable solution is to always start with
source packages.

Bootstrapping OpenPKG for the first time 
----------------------------------------

The OpenPKG bootstrapping process is wrapped into a shell script that
when run, will create a new instance of OpenPKG. This process is as
self contained as possible, and requires a minimum amount of operating
system support and tools to unpack and compile itself. In the best case,
the script will search the C<$PATH> for the development tools C<tar>,
C<make> and C<cc> and use them in its processing. If any of these tools
are missing, an alternative approach exists in which a shell script
containing binaries provides the missing tools.

The first step in bootstrapping involves dedicating a unique
file system prefix to the instance along with user and
group ids. The generic bootstrap building script called
C<openpkg->I<version>C<->I<release>C<.src.sh> requires these arguments
and creates a platform specific bootstrap installation script named
C<openpkg->I<version>C<->I<release>C<.>I<arch>C<->I<os>C<->I<id>C<.sh>.
When run, this script installs the OpenPKG instance under the specified
prefix with all files owned by the user and group (Figure_2). This
bootstrapping process links the OpenPKG instance with the underlying
Unix system in a very mild way with only a few anchor points. Subsequent
package installations do not touch the system at all, and if OpenPKG
itself is uninstalled, the anchor points vanish.

After creating a self-contained hierarchy the bootstrap process
registers itself as C<openpkg>, and can thus be upgraded or treated just
like any other package. To make upgrade an already bootstrapped OpenPKG
instance easier, C<.rpm> versions of the bootstrap package are available
as well.

A step by step example of a complete installation and uninstallation of
an OpenPKG instance with a RSYNC server package is given in Listing_4.
To understand the RPM commands used, see the quick reference in Table_3.

OpenPKG file system layout 
--------------------------

Every file system standard sucks. OpenPKG's file system aims to suck
less (Figure_2). Basically, its package area resembles the traditional
layout found under C</usr> on most popular Unix systems. Additionally,
it contains its own RPM package management information in a sub area for
purposes of self-containment plus a local area for adding unpackaged
components.

OpenPKG does break with tradition in one aspect of its file system
layout, however. It unconventionally uses a separate subdirectory of
I<prefix>C</etc/>, I<prefix>C</share/> and I<prefix>C</var/> for each
installed package. These subdirectories are easy to manage, because
each is named after its associated package. This provides for a better
structure than the usual mess of files, and every OpenPKG package
adheres to this layout scheme (even when requiring a lot of effort to
override the different vendor package intentions).

Looking again at the RSYNC example in Listing_4, you can conclude right
away that the RSYNC configuration is in I<prefix>C</etc/rsync/>, and it
logs to somewhere in I<prefix>C</var/rsync/>. Such ease of maintenance
makes backups easier, moving whole instances without hassle, and more.

Managing OpenPKG packages 
-------------------------

When building packages, the temporary files are placed into
subdirectories of I<prefix>C</RPM/> by default. A package builder can
obtain the necessary subdirectory access by either being a member
of the associated OpenPKG group, logging in under the user id of
the OpenPKG instance, or logging in as root. A carefully written
C<~/.rpmmacros> file can alternatively redirect the paths to a specified
location (see the default macros C<%_sourcedir>, C<%_specdir>,
C<%_builddir>, C<%_tmppath>, C<%_rpmdir>, C<%_srcrpmdir> in
I<prefix>C</etc/openpkg/rpmmacros>) and this way allow even an arbitrary
user to build packages.

To build a binary package I<pkg-bin> from a source package I<pkg-src>,
use C<rpm --rebuild >I<pkg-src>. OpenPKG's RPM will read the
C<.spec> information of the I<pkg-src>, build the package based
on the information, and place the resulting binary package in
I<prefix>C</RPM/PKG/>I<pkg-bin>.

To finally install the binary package so that it becomes part of the
OpenPKG instance, just use C<rpm -Uvh >I<pkg-bin>. Strictly speaking
this upgrades the package. To RPM, installation is nothing more than the
special case of upgrading from nothing.

As a side note, some packages provide alternative build variants through
boolean variables named C<with_>I<name>. To determine which variables
are available (if any at all), run "C<rpm -qpi >I<pkg-src>C< | grep
with_>". To build a binary package using such variables, add C<--define
"with_>I<name>C< > I<value>C<"> to the C<rpm --rebuild> command to
override the default value.

RPM is very clever when it comes to keeping configuration files during
an upgrade, as shown in Table_2. An old configuration file is kept if
the system administrator stuck to default configuration which remained
the same, or if the configuration was changed but coincidentally
matches the default configuration of the new package. In practice, a
administrator-changed configuration must be reapplied in few cases of
package upgrade. In any case, should a configuration file not be kept,
RPM saves the old configuration file with the extension C<.rpmsave>
before saving a new default in its place. This ensures that changes to a
default configuration can be recovered and reapplied so that an upgraded
package runs correctly. Should a new default configuration file replace
an old one that retains its original (but old) RPM default, RPM will rename
it with the extension C<.rpmorig>.

To make this delightful mechanism work properly, the configuration files
of each package have to be explicitly tagged. OpenPKG packages all
follow this principle, which further contributes to OpenPKG's robust
nature. OpenPKG's RPM does the intuitive right thing by making sure that
a changed configuration file is kept in place if possible and if not,
then preserves it for manual consideration and application.

Finally, after the installation of a package, you can query a lot of
its information. The command C<rpm -qi >I<pkg-name> summarizes a single
installed package, while C<rpm -qa> lists the names of all installed
packages. C<rpm -qlv >I<pkg-name> lists all the files associated with a
package and C<rpm -qf >I<prefix>/I<path>/I<to>/I<file> reveals to which
package the given file belongs. You can even check a package's integrity
using C<rpm -V >I<pkg-name> to verify which files have been tampered
with or somehow munged. For more details on this refer to Table_3.

The OpenPKG run-command facility 
--------------------------------

You might have noticed that in the previous example installation of
RSYNC, the server was started using the command C</usr/opkg/etc/rc
rsync start>. The workhorse behind this simple statement is
the powerful OpenPKG run-command facility, executed with
I<prefix>C</etc/rc>. Run-commands for every package are conveniently
named I<prefix>C</etc/rc.d/rc.>I<pkg-name>. What each of them offers
is the functionality of several shell script segments encapsulated in
a single file. The sections of a run-command file are identified by
left-aligned labels prefixed with 'C<%>'. Listing_2 shows C<rc.rsync> as
an example.

The C<rc> command takes I<pkg-name> as the first argument and one or
more section labels as additional arguments. The run command segments
corresponding with the desired section labels are then extracted from
the C<rc.>I<pkg-name> file and executed in the order given on the
command line. The reserved package name C<all> serves as a wildcard and
refers to all installed OpenPKG packages, causing the processing of all
run-command files in a specified order. In this case, the run-command
facility will order the run-command processing according to the priority
field (C<-p >I<number>) of the given section label in each run-command
file. Another popular field in a section label is C<-u >I<user>, which
directs the script code to execute with the privileges of I<user>.

Most sections in a run-command file have arbitrary labels intended to
be used as command line arguments to the run-command facility. However,
some sections have special meaning. The section labels of these are
reserved names used internally by the run-command facility. For example,
the C<%common> section functions as a library and contains script code
useful to some or all of the other sections. Its script code is run
before any other script code.

Just like its cousin, the C<%common> section, the C<%config> section
can appear only one time in each run-command file. It contains
variables used to configure the behavior of the other sections
residing in the same run-command file. This means that the logging
and enabling variables in a C<%config> section will only affect the
associated package, for example. Such variables can be overridden in
I<prefix>C</etc/rc.conf> in a per-hierarchy scope, however. Technically,
the run-command facility assembles a large script file from the
C<%config> section, the I<prefix>C</etc/rc.conf> file, the C<%common>
section, and finally the user-defined section given as an argument (in
that order). The fat script it then executed.

The sections C<%monthly>, C<%weekly>, C<%daily>, C<%hourly> and
C<%quarterly> also have special meaning, as the OpenPKG bootstrap
process sets up C<cron> jobs to execute them accordingly. Another label
often seen is C<%env>, which is intended to be used with the C<--eval>
option explained below.

Regarding configuration through variables, it should be mentioned
that the C<rc.>I<pkg-name> file is intentionally not tagged as a
configuration file and will be overwritten on updates with no questions
asked. The I<prefix>C</etc/rc.conf> file is tagged as a configuration
file and is intended for overriding variables.

With OpenPKG, all daemon packages are released with scripts that
recognize the value of a variable I<pkg-name>C<_enable> (default value
"C<yes>"). Setting this variable to "C<no>" disables all run-commands of
the daemon in question. As seen with the RSYNC server example, this can
be quite useful when installing a package just to get a client piece.
Should the server piece not be of interest, then a simple variable
shuts it off completely. Similarly, to disable the automatic startup
of all daemons in a hierarchy, just add a C<openpkg_runall="no"> to
I<prefix>C</etc/rc.conf>. In this case, daemons can still be started
manually. This feature may be of interest to system administrators
wanting control over daemons with finer granularity.

The OpenPKG run-command facility has many other interesting features.
Use C<rc --query >I<variable> to see the effective value of any
configured variable, or use C<rc --config> to see a complete list of
all available variables with their default and effective values. Last
but not least the run-command facility offers a very handy feature to
allow packages to extend the user shell environment. For instance the
bootstrap package C<openpkg> uses this to add the OpenPKG instance
into your C<PATH>, C<MANPATH>, C<INFOPATH>, etc. Just execute C<eval
`>I<prefix>C</etc/rc --eval openpkg env`> to perform this environment
extension for your current shell session.

OpenPKG RPM vs. RedHat RPM 
--------------------------

As mentioned, OpenPKG is based on a uniquely adjusted and extended
RPM-based packaging facility which allows for very concise and
clean package specifications and building of I<every> package in
an unprivileged environment. Is this any different than what the
RedHat, SuSE, or Mandrake implementations offer? To understand the
added value of the OpenPKG implementation, let's take as example the
OpenPKG packaging of the RSYNC program. The OpenPKG packaging consists
of three files: the RPM specification (C<rsync.spec>, Listing_1),
the run-commands (C<rc.rsync>, Listing_2), and the default daemon
configuration (C<rsync.conf>, Listing_3). In comparison with the
RPM-based RSYNC package of other vendors, the OpenPKG RPM-based package
is full featured yet very concise and clean. This is due to the use of
OpenPKG's RPM extensions and strict style guidelines.

To offer more portable and concise shell scripting, OpenPKG's RPM
implementation uses GNU shtool. All manual installation and patching
is done with the C<shtool> command. A companion tool, C<rpmtool>,
complements C<shtool> with RPM and OS-specific features. The C<rpmtool>
allows all OpenPKG packages to generate their file list (C<%files>) on
the fly and makes the packaging information smaller. It reduces the
required maintenance when vendor version updates occur as well.

OpenPKG's RPM additionally provides a set of local macros (C<%{l_xxx}>)
to abstract system specifics and also help in removing redundancy from
packaging specifications. For example, the C<%{l_prefix}> is the file
system I<prefix> of the associated OpenPKG instance. Using OpenPKG's
local macros offers a clear advantage, because packages no longer need
hard-coded path prefixes and can therefore be built for arbitrary
OpenPKG instances.

Macros exist for the most often used build variables. The C<%{l_cc}>
macro expands to either I<prefix>C</bin/cc> (in case the OpenPKG C<gcc>
package is installed) or defaults to just C<cc>. The same goes for
C<%{l_cflags -O}>: it expands to the optimized C compiler flags. In
case C<gcc> is installed, it expands to "C<-O2 -pipe>". Otherwise,
it expands to just C<-O> by default. The variables C<%{l_make}> and
C<%{l_mflags}> work together in a similar way. If C<%{l_make}> points
to a known C<make> which supports parallel building and the underlying
system has more than one CPU, then C<%{l_mflags -O}> expands to the
necessary flags to leverage the system's multiple processing power. For
example, on a 2 CPU FreeBSD 4.x machine with BSD make, C<%{l_mflags
-O}> expands to C<-j4 -B> while on a 4 CPU Linux machine with GNU make,
C<%{l_mflags -O}> expands to C<--no-print-directory -j8>.

Many packages also deploy a tricky OpenPKG-specific package build
option feature based on RPM's C<%define> macro and C<Provides>
header: A package specification C<foo.spec> can contain zero or more
"C<%option> I<opt-name> I<opt-default-value>" lines which expand to both
a "C<%ifndef> I<opt-name> C<%define> I<opt-name> I<opt-default-value>
C<%endif>" construct and a "C<Provides: foo::>I<opt-name> =
I<opt-value>" header definition. First, this allows the package itself
to conditionally build with variations through the use of following
'C<%if "%{>I<opt-name>C<}" == ">I<opt-value>C<"> ... C<%endif>'
constructs inside the C<foo.spec> file. The compared effective option
value is either I<opt-default-value> or the I<opt-override-value> from
a "C<--define '>I<opt-name> I<opt-override-value>C<'>" command line
option. Second, the resulting source RPM can be queried with "C<rpm -qp
--provides>" or "C<rpm -qpi>" in order to lookup the provided options
and their default values. The same can be done for the binary RPM to
lookup the options and their effective values which were used to built
the package. Third, another package depending on C<foo> usually just
uses "[C<Build>]C<PreReq:> ... C<foo>". In OpenPKG it also can depend on
a particular build variation of C<foo> by using "[C<Build>]C<PreReq:> ...
C<foo>, C<foo::>I<opt-name>C< = >I<opt-value>". The consequent of this
functionality provides both a clean, precise and flexible packaging.

Additionally, all OpenPKG packages follow I<exactly> the same style
as the RSYNC example (see Listing_1, Listing_2, and Listing_3). The
header order, indentation, etc. is standardized, and allows developers
to easily query and even semi automatically edit package information
directly from the source. Incidentally, the indices on the OpenPKG FTP
server and the OpenPKG release engineering procedures are auto generated
by exploiting this standard scheme.

I<Every> OpenPKG package is able to build in an unprivileged (non-root
user) environment and with read-only access to an OpenPKG instance.
This allows safe (no development system intrusion) and precise (no
trashed or missing files) packaging. Such security and precision
is achieved by consistently using the C<BuildRoot> feature of RPM
for I<all> packages. In short, this means that when rolling a binary
package the software is redirected to install into a shadow area
(I<prefix>C</RPM/TMP/>I<pkg-name>C<-root/>I<prefix>). The package is
then made from the shadow area just as if it were located in the real
file system location (I<prefix>). This important improvement to the
standard RPM behavior may sound trivial and easy to achieve, but is
actually one of the trickiest steps in packaging software for OpenPKG.
Sometimes (as with RSYNC), it is just a matter of overriding variables
(C<prefix> in the example) on the C<make install> step. Other times the
solution is more involved. For some OpenPKG packages it takes a lot of
effort to find a reasonable way to redirect the vendor installation to
the C<BuildRoot> location, but the extra effort is always worthwhile and
results in safer and more precise packaging.

Finally, OpenPKG's RPM implementation provides proxy packages, a tricky
and appealing mechanism for reusing the packages of a master OpenPKG
instance. Proxy packages can reside in multiple slave OpenPKG instances,
and allow the system administrator to avoid redundant building and
maintaining of the same software package in multiple OpenPKG instances.
For example, C<gcc> is typically required by many packages at build
time. A C<gcc> OpenPKG package is usually needed in every OpenPKG
instance. A savvy system administrator will install a single C<gcc>
package in a master OpenPKG instance and then only proxy packages
(pointing to the real C<gcc>) in the other OpenPKG instances by running
I<slave-prefix>C</bin/rpm --makeproxy> on the C<gcc> binary RPM of
the master instance. OpenPKG's RPM will then produce a binary RPM
package for the slace instance, containing a shadow tree resembling the
contents of the master instance. The shadow tree is technically nothing
more than symbolic links to the master (non-proxy) package's files
and directories. This mechanism can save a lot of time and storage,
however it should only be applied to packages with global configuration
dependencies only or with no configuration dependencies at all.

Integrating unpackaged software 
-------------------------------

No matter how many packages OpenPKG provides, the world will always have
appealing yet unpackaged software. Ambitious system administrators can
package the software themselves for local purposes and even contribute
such new packages to the OpenPKG community. Alternatively, the C<local>
subdirectory of an OpenPKG instance exists for the purpose of containing
unpackaged software, and can be instrumental in integrating a base of
OpenPKG packages with other unpackaged software in an easy to maintain
way. OpenPKG also provides a corresponding C<lsync> tool to aid such
integration.

To integrate unpackaged software into an OpenPKG instance, each
unpackaged software component may be installed into the C<bin>,
C<sbin>, C<man>, C<info>, C<include> and C<lib> subdirectories of
I<prefix>C</local/PKG/>I<pkg-name>C</> and then virtually linked into
the corresponding top-level directories under I<prefix>C</local/> by
running I<prefix>C</sbin/lsync>. This easy to administer strategy
leads to a very clean and maintainable OpenPKG instance, even with
its new coexisting unpackaged software in I<prefix>C</local/>.
This especially makes it easy to uninstall a package. Just remove
I<prefix>C</local/PKG/>I<pkg-name>C</> with all its contents and run
C<lsync> again.

This strategy even allows for installation of different
versions of the same software. Just install into
I<prefix>C</local/PKG/>I<pkg-name>C<->I<version>C</> and add a
symbolic link pointing from I<prefix>C</local/PKG/>I<pkg-name>C</> to
this directory. This works, because C<lsync> skips subdirectories of
I<prefix>C</local/PKG/> with version numbers attached. To upgrade an
older C<foo-0.7.41> to C<foo-0.7.42>, just repeat the installation
in the same way, altering the symlink I<prefix>C</local/PKG/foo> to
point to C<foo-0.7.42> instead and running C<lsync> again. C<lsync>
will automatically update symlinks, creating new links if required and
removing outdated dangling ones. As might be guessed, it is just as
easy to go back to the old version if the new one keeps dumping core or
something like that. For an example of such multiple unpackaged software
installation see Figure_3.

OpenPKG release engineering 
---------------------------

A carefully crafted release process is part of the OpenPKG project, and
the fruits of the whole project are available to the public according
to Open Source standards. All sources (package specifications, source
patches, website sources, the handbook, this article, etc) are located
in a publicly readable central CVS repository, which can be browsed
anonymously by conventional C<cvs> commands or through the website
for added convenience. Additionally, all developer commits to this
repository are tracked and summarized with postings to public mailing
lists and public newsgroups. People can easily follow all developments
by subscribing to the list or reading the newsgroup.

For stability and to reduce conflicts between development milestones,
OpenPKG has three release branches (which technically directly
map to CVS branches.) These are OpenPKG-SOLID, OpenPKG-STABLE and
OpenPKG-CURRENT. OpenPKG-SOLID is the security update branch of the last
public OpenPKG release. OpenPKG-STABLE is the stable branch from whose
contents the next public release is made. OpenPKG-CURRENT is the current
state of the development branch, and contains packages of beta-grade
stability. In any case, the branch from which a package was built can
easily be determined by the OpenPKG RPM file name, because they follow
a consistent naming scheme: I<pkg-name>C<->I<version>C<->I<YYYYMMDD>
(for CURRENT), I<pkg-name>C<->I<version>C<->I<N>C<.>I<YYYYMMDD> (for
I<N>-STABLE), I<pkg-name>C<->I<version>C<->I<N>C<.>I<M>C<.>I<X> (for
I<N.M.X>-SOLID). Once such a source RPM file is built, the new binary
RPM file name contains even more information, such as operating system,
hardware, and the OpenPKG instance prefix.

The OpenPKG developer team is very fast in keeping OpenPKG-CURRENT
packages up to date and in sync with the latest vendor versions. This
is due to the fact that the versions of all externally available vendor
sources are automatically tracked on a daily basis. An OpenPKG package
for a new vendor software version is often available before the software
is even announced on Freshmeat.net.

Finally, OpenPKG takes security very seriously. Experience has shown
that "security through obscurity" does not work, and that public
disclosure leads to quicker and better solutions to security problems.
In that vein, OpenPKG tries to release fixed packages as fast as
possible after a vulnerability was discovered. The OpenPKG security
release and advisory process notifies the community by publishing
official security advisories in the security section of the website and
on the mailing lists.

Conclusion 
----------

OpenPKG is an Open Source software project founded by Cable & Wireless
Germany in November 2000. The implementation relies on RPM 4 for
its basic packaging mechanism, but offers more than RPM alone. To
meet its goal of becoming a modular and flexible Unix subsystem for
cross-platform software packaging and installation, OpenPKG includes
tricky bootstrapping logic that installs a customized implementation of
RPM 4 on any of the supported target platforms.

OpenPKG is in production use since April 2001 at Cable & Wireless
Germany, a large ISP. Since its public release in January 2002,
OpenPKG users have profited from an increase of 220 to over 450 software
packages. The project is continuously improved by a diverse team of
developers who also daily update and add packages.

The base of OpenPKG software packages is expected to increase even more,
partly due to the ease of writing specifications and building packages.
Most OpenPKG users find it deceivingly simple to build a basic package.
New users interested in such packaging can use the RSYNC example in this
article as a blueprint. Accordingly, package contributions are always
appreciated by the members of the OpenPKG project.

To make OpenPKG even more attractive, work is underway on a front end
which will simplify and control the installation process according to
build and install dependencies. OpenPKG is also fulfilling plans to
satisfy the desktop user by offering more X11-dependent packages like
KDE. For faster execution and even more flexibility, a further enhanced
run-command processor is also under development. Shared library support
is under investigation, too. Lastly, we are looking forward to upgrading
OpenPKG to use the forthcoming RPM 4.1 version.

References
----------

OpenPKG:
U<http://www.openpkg.org/>
U<ftp://ftp.openpkg.org/>

OpenPKG Community Forums:
U<mailto:openpkg-users@@openpkg.org>
U<mailto:openpkg-dev@@openpkg.org>
U<nntp://news.openpkg.org/openpkg.users>
U<nntp://news.openpkg.org/openpkg.dev>

RPM
U<http://www.rpm.org/>
U<ftp://ftp.rpm.org/pub/rpm/>

About the authors 
-----------------

Ralf S. Engelschall is a computer scientist and Open Source software
hacker, leading the software development department at Cable & Wireless
Germany. He is the author of well-known software like Apache mod_ssl,
GNU Pth, and GNU Shtool and the founder of Open Source software projects
like OpenSSL, OpenPKG, and OSSP.
He can be contacted at: rse@@engelschall.com

Thomas Lotterer is a network professional and consultant working as
a Unix software developer at Cable & Wireless Germany. He gained
experience in cross-platform system integration and software
distribution by working previously as a system administrator and
technical trainer. Today, Thomas works actively on the OpenPKG and OSSP
projects.
He can be contacted at: thomas@@lotterer.net

Michael Schloh von Bennewitz is a software engineer at Cable & Wireless
Germany, where he works on the network and user interface logic of ISP
tools and technologies. He is an active contributor to both the OpenPKG
and OSSP projects. With fingers blazing, Michael listened to classical
music while writing parts of this article to go even faster.
He can be contacted at: michael@@schloh.com

Christoph Schug is a senior Unix system administrator at Cable &
Wireless Germany. He leads the hosting department and is responsible
for all managed servers at the Munich data center. His revolutionary
ideas and visions often result in additional lines in Ralf's TODO list.
When not in the office, Christoph might be found in the Alps steering
the screaming and smoking tires of his Miata MX-5 roadster.
He can be contacted at: chris@@schug.net

______________________________________________________________________________


Figure_1: The OpenPKG subsystem principle
------------------------------------------------------------------------------
article.principle.fig
------------------------------------------------------------------------------

Figure_2: The OpenPKG file system layout
------------------------------------------------------------------------------
article.layout.fig
------------------------------------------------------------------------------

Figure_3: File system layout of non-OpenPKG software installed
------------------------------------------------------------------------------
article.layout-local.fig
------------------------------------------------------------------------------

Listing_1: OpenPKG packaging for rsync (rsync.spec: RPM specification)
------------------------------------------------------------------------------
#   package information
Name:         rsync
Summary:      Remote Filesystem Synchronization
URL:          http://rsync.samba.org/
Vendor:       Andrew Tridgell & Paul Mackerras
Packager:     The OpenPKG Project
Distribution: OpenPKG [BASE]
Group:        Filesystem
License:      GPL
Version:      2.5.5
Release:      1.2.0

#   list of sources
Source0:      http://rsync.samba.org/ftp/rsync/rsync-%{version}.tar.gz
Source1:      rsync.conf
Source2:      rc.rsync

#   build information
Prefix:       %{l_prefix}
BuildRoot:    %{l_buildroot}
BuildPreReq:  OpenPKG, openpkg >= 1.2.0
PreReq:       OpenPKG, openpkg >= 1.2.0
AutoReq:      no
AutoReqProv:  no

%description
    Rsync is a replacement for rcp(1) that has many more features.
    Rsync uses the "rsync algorithm" which provides a very fast method
    for bringing remote files into sync. It does this by sending just
    the differences in the files across the link, without requiring
    that both sets of files are present at one of the ends of the link
    beforehand. At first glance this may seem impossible because the
    calculation of differences between two files normally requires
    local access to both files.

%prep
    #   unpack vendor sources
    %setup -q

%build
    #   configure vendor sources
    CC="%{l_cc}" \
    CFLAGS="%{l_cflags -O}" \
    ./configure \
        --prefix=%{l_prefix} \
        --disable-debug \
        --with-included-popt

    #   build vendor sources
    %{l_make} %{l_mflags -O}

%install
    #   perform vendor installation
    rm -rf $RPM_BUILD_ROOT
    %{l_make} %{l_mflags} install \
        prefix=$RPM_BUILD_ROOT%{l_prefix} \
        exec_prefix=$RPM_BUILD_ROOT%{l_prefix}

    #   post-adjust vendor installation
    strip $RPM_BUILD_ROOT%{l_prefix}/bin/* >/dev/null 2>&1 || true
    mv $RPM_BUILD_ROOT%{l_prefix}/man/man5/rsyncd.conf.5 \
       $RPM_BUILD_ROOT%{l_prefix}/man/man5/rsync.conf.5

    #   provide default (deamon) configuration
    %{l_shtool} mkdir -f -p -m 755 \
       $RPM_BUILD_ROOT%{l_prefix}/etc/rsync
    %{l_shtool} install -c -m 644 \
        -e 's;@@l_prefix@@;%{l_prefix};g' \
        -e 's;@@l_nusr@@;%{l_nusr};g' \
        -e 's;@@l_ngrp@@;%{l_ngrp};g' \
        -e 's;@@version@@;%{version};g' \
        %{SOURCE rsync.conf} $RPM_BUILD_ROOT%{l_prefix}/etc/rsync/
    %{l_shtool} install -c -m 644 /dev/null \
        $RPM_BUILD_ROOT%{l_prefix}/etc/rsync/rsync.passwd
    %{l_shtool} mkdir -f -p -m 755 \
        $RPM_BUILD_ROOT%{l_prefix}/var/rsync

    #   provide run-command script
    %{l_shtool} mkdir -f -p -m 755 \
        $RPM_BUILD_ROOT%{l_prefix}/etc/rc.d
    %{l_shtool} install -c -m 755 \
        -e 's;@@l_prefix@@;%{l_prefix};g' \
        -e 's;@@l_musr@@;%{l_musr};g' \
        -e 's;@@l_mgrp@@;%{l_mgrp};g' \
        %{SOURCE rc.rsync} $RPM_BUILD_ROOT%{l_prefix}/etc/rc.d/

    #   determine binary package files
    %{l_rpmtool} files -v -ofiles -r$RPM_BUILD_ROOT \
        %{l_files_std} '%config %{l_prefix}/etc/rsync/rsync.*'

%files -f files

%clean
    rm -rf $RPM_BUILD_ROOT
------------------------------------------------------------------------------

Listing_2: OpenPKG packaging for rsync (rc.rsync: run-commands)
------------------------------------------------------------------------------
#!@@l_prefix@@/lib/openpkg/bash @@l_prefix@@/etc/rc

%config
    rsync_enable="yes"
    rsync_flags=""
    rsync_log_numfiles="5"
    rsync_log_minsize="512K"
    rsync_log_complevel="9"

%common
    rsync_cfgfile="@@l_prefix@@/etc/rsync/rsync.conf"
    rsync_logfile="@@l_prefix@@/var/rsync/rsync.log"
    rsync_pidfile="@@l_prefix@@/var/rsync/rsync.pid"

%start -p 200 -u root
    if opServiceEnabled rsync; then
        @@l_prefix@@/bin/rsync $rsync_flags \
             --daemon --config=$rsync_cfgfile
    fi

%stop -p 200 -u root
    if opServiceEnabled rsync; then
        if [ -f $rsync_pidfile ]; then
            kill -TERM `cat $rsync_pidfile`
        fi
    fi

%restart -u root
    if opServiceEnabled rsync; then
        if [ -f $rsync_pidfile ]; then
            kill -TERM `cat $rsync_pidfile`
            sleep 2
        fi
        @@l_prefix@@/bin/rsync $rsync_flags \
             --daemon --config=$rsync_cfgfile
    fi

%reload -u root
    if opServiceEnabled rsync; then
        if [ -f $rsync_pidfile ]; then
            kill -HUP `cat $rsync_pidfile`
        fi
    fi

%daily -u root
    if opServiceEnabled rsync; then
        shtool rotate -f \
            -n ${rsync_log_numfiles} \
            -s ${rsync_log_minsize} \
            -d -z ${rsync_log_complevel} \
            -o @@l_musr@@ -g @@l_mgrp@@ -m 644 \
            -E "kill -HUP `cat $rsync_pidfile`" \
            $rsync_logfile
    fi

%env
    if opServiceEnabled rsync; then
        if [ -f "@@l_prefix@@/bin/ssh" ]; then
            RSYNC_RSH="@@l_prefix@@/bin/ssh"
            export RSYNC_RSH
        fi
    fi
------------------------------------------------------------------------------

Listing_3: OpenPKG packaging for rsync (rsync.conf: default configuration)
------------------------------------------------------------------------------
secrets file       = @@l_prefix@@/etc/rsync/rsync.passwd
lock file          = @@l_prefix@@/var/rsync/rsync.lck
pid file           = @@l_prefix@@/var/rsync/rsync.pid
log file           = @@l_prefix@@/var/rsync/rsync.log

max connections    = 20
timeout            = 60
strict modes       = yes
use chroot         = yes
read only          = yes
ignore nonreadable = yes
transfer logging   = yes
log format         = "%o %h [%a] %m (%u) %f %l"
dont compress      = *.bz2 *.gz *.zip *.z *.rpm *.deb *.tgz *.iso
list               = no
uid                = @@l_nusr@@
gid                = @@l_ngrp@@

[pub]
comment            = Public area of @@l_prefix@@ OpenPKG instance
path               = @@l_prefix@@/pub/
exclude            = .*
read only          = yes
list               = yes
------------------------------------------------------------------------------

Listing_4: RSYNC server in 10 minutes
------------------------------------------------------------------------------
user$ cd /tmp
user$ ftp ftp.openpkg.org
Connected to ftp.openpkg.org.
220 ftp.openpkg.org OpenPKG Anonymous FTP Server ready.
Name (ftp.openpkg.org): anonymous
331 Anonymous login ok, send your email address as your password.
Password: you@@example.com
230- [...] Welcome to OpenPKG.org! [...]
230 Anonymous access granted, restrictions apply.
ftp> bin
200 Type set to I.
ftp> cd release/1.1/SRC
ftp> get openpkg-1.2.0-1.2.0.src.sh
ftp> bye
221 Goodbye.
user$ sh openpkg-1.2.0-1.2.0.src.sh \
      --prefix=/usr/opkg --user=opkg --group=opkg
user$ su -
root# sh openpkg-1.2.0-1.2.0.*-uo.sh
root# su - opkg
opkg$ /usr/opkg/bin/rpm --rebuild \
      ftp://ftp.openpkg.org/release/1.2/SRC/rsync-2.5.5-1.2.0.src.rpm
opkg$ exit
root# /usr/opkg/bin/rpm -Uvh /usr/opkg/RPM/PKG/rsync-*.rpm
root# su - opkg
root# /usr/opkg/etc/rc rsync start
root# exit
user$ /usr/opkg/bin/rsync rsync://localhost/
pub             Public area of /usr/opkg OpenPKG instance
user$ su -
root# /usr/opkg/etc/rc rsync stop
root# /usr/opkg/bin/rpm -e rsync openpkg
root# exit
user$ rm -f openpkg-1.2.0-1.2.0.*
------------------------------------------------------------------------------

Listing_5: Installation of non-OpenPKG software
------------------------------------------------------------------------------
$ mkdir -p /usr/opkg/local/PKG/foo-0.7.42/SRC
$ cd /usr/opkg/local/PKG/foo-0.7.42/SRC
$ /usr/opkg/lib/openpkg/curl -o foo-0.7.42.tar.gz \
  ftp://ftp.example.com/foo-0.7.42.tar.gz
$ gunzip <foo-0.7.42.tar.gz | tar xf -
$ cd foo-0.7.42
$ ./configure --prefix=/usr/opkg/local/PKG/foo-0.7.42
$ make
$ make install
$ cd /usr/opkg/local/PKG
$ ln -s foo-0.7.42 foo
$ /usr/opkg/sbin/lsync
------------------------------------------------------------------------------

Table_1: OpenPKG Unix platform support
------------------------------------------------------------------------------
Unix Platform                 Support
============================= =======
FreeBSD 4.7                   full
FreeBSD 5.0                   full
Debian GNU/Linux 2.2          full
Debian GNU/Linux 3.0          full
Sun Solaris 8                 full
Sun Solaris 9                 full
Sun Solaris 2.6/7             partial
RedHat Linux 7.x              partial
RedHat Linux 8.x              partial
NetBSD 1.5.x, 1.6             none*
OpenBSD 2.9                   none*
HP-UX 10.20                   none*
Compaq Tru64 5.0              none*
Caldera OpenUNIX 8.0          none*
IBM AIX 4.x                   none*
SGI IRIX 6.x                  none*
* Works, but not regularly tested
------------------------------------------------------------------------------

Table_2: RPM handling of configuration files
------------------------------------------------------------------------------
old in   old on     new in   new on 
package  filesystem package  filesystem approach
======== ========== ======== ========== ===========================================
X        X          X        X          keep old config
X        X'         X'       X'         keep old config
X        X'         X        X'         keep old config
X        X          Y        Y          install new config
X        X'         Y        Y          install new config, preserve X' as .rpmsave
-        X          Y        Y          install new config, preserve X  as .rpmorig
------------------------------------------------------------------------------

Table_3: OpenPKG Administration Commands (Quick Reference)
------------------------------------------------------------------------------
$ <prefix>/bin/rpm -Uvh <pkg-src>                unpack source package
$ <prefix>/bin/rpm -bb <pkg-spec>                build binary package from unpacked sources
$ <prefix>/bin/rpm --clean --rmsource <pkg-spec> cleanup after building binary package
$ <prefix>/bin/rpm --rebuild <pkg-src>           build binary package from source package

# <prefix>/bin/rpm -Uvh <pkg-bin>                install/upgrade package
# <prefix>/bin/rpm -Uvh --nodeps <pkg-bin>       install/upgrade package (ignore dependencies)
# <prefix>/bin/rpm -Uvh --force <pkg-bin>        install/upgrade package (no checks at all)
# <prefix>/bin/rpm -Uvh --oldpackage <pkg-bin>   install/downgrade package
# <prefix>/bin/rpm -Fvh <pkg-bin>                upgrade package (if already installed only)

# <prefix>/bin/rpm -e <pkg-name>                 uninstall/erase package
# <prefix>/bin/rpm -e --nodeps <pkg-name>        uninstall/erase package (ignore dependencies)

$ <prefix>/bin/rpm -qpi <pkg-bin>                list information about binary package
$ <prefix>/bin/rpm -qplv <pkg-bin>               list all files a binary package will install
$ <prefix>/bin/rpm -qa                           list all installed packages and their versions
$ <prefix>/bin/rpm -qi <name>                    list information about an installed package
$ <prefix>/bin/rpm -qlv <name>                   list all files a package has installed
$ <prefix>/bin/rpm -qf <prefix>/...              list package owning a particular file
$ <prefix>/bin/rpm -qc <name>                    list all config files of an installed package

$ <prefix>/bin/rpm --checksig <pkg-rpm>          verify integrity and origin of a package
$ <prefix>/bin/rpm -Va                           check the integrity of all packages
$ <prefix>/bin/rpm -V <name>                     check the integrity of a particular package
$ <prefix>/bin/rpm -Va --nofiles                 check all package dependencies only

$ <prefix>/etc/rc --config                       show all %config variables and values
$ <prefix>/etc/rc --query <variable>             query a particular %config variable
# <prefix>/etc/rc <pkg_name> start               start a particular package
# <prefix>/etc/rc <pkg_name> stop                stop  a particular package
# <prefix>/etc/rc <pkg_name> stop start          restart a particular package
# <prefix>/etc/rc all stop start                 restart all packages
$ eval `<prefix>/etc/rc --eval all env`          setup shell environment of all packages 

Legend: #          command has to be executed with     root privileges
        $          command should be executed withough root privileges
        <prefix>   e.g. /usr/opkg
        <pkg-name> e.g. rsync
        <pkg-spec> e.g. rsync.spec
        <pkg-rpm>  e.g. rsync-2.5.5-1.2.0.*.rpm
        <pkg-src>  e.g. rsync-2.5.5-1.2.0.src.rpm
        <pkg-bin>  e.g. rsync-2.5.5-1.2.0.ix86-freebsd4.7-uo.rpm
------------------------------------------------------------------------------

Table_4: OpenPKG summary 
------------------------------------------------------------------------------
- Open source software
- Cross-platform solution for FreeBSD, Linux, Solaris and others
- Subsystem on top of underlying Unix system
- Minimal OS intrusion
- Fully self-contained with minimum OS dependencies
- Primarily targeted at server environments
- Based on a customized RPM 4
- Support for entire package lifecycle
- Build and run-time dependency control
- Builds software from pristine vendor sources
- All RPM package specifications written from scratch
- Clear and concise specifications follow a strict style
- Supports integration of unpackaged software also
- Tricky bootstrapping with no requirement for a preinstalled RPM
- Strict and consistent file system layout
- All packages installed with reasonable preconfiguration
- Users benefits from packager's knowledge
- Cryptographically signed packages
- Package integrity verification
- Support for building packages as unprivileged user
- Installation under arbitrary file system prefix
- Allows multiple instances on the same host
- Fully uninstalls packages
- Powerful package queries
- Flexible run-command facility
- Mature technology in production use since April 2001
- Variety of over 450 packages available
------------------------------------------------------------------------------

@


1.133
log
@Updated platforms and level of support.
@
text
@d979 2
a980 2
Legend: #          command has to be executed with     root priviledges
        $          command should be executed withough root priviledges
d1010 1
a1010 1
- Support for building packages as unpriviledged user
@


1.132
log
@update article to reflect OpenPKG 1.2
@
text
@d910 1
a910 1
FreeBSD 4.x                   full
d914 1
a915 1
Sun Solaris 8                 full
d917 1
d919 8
a926 8
RedHat Linux 7.x              partial
NetBSD 1.6                    partial
OpenBSD 2.9                   partial
HP/UX 10.20                   partial
Compaq Tru64 5.0              partial
Caldera OpenUNIX 8.0          not yet
IBM AIX 4.x                   not yet
SGI IRIX 6.x                  not yet
@


1.131
log
@add missing trailing slash
@
text
@d405 22
d572 1
a572 1
OpenPKG users have profited from an increase of 220 to over 400 software
d586 5
a590 6
satisfy the desktop user by offering X11-dependent packages for Gtk,
Qt, Gimp, Mozilla, and many others. For faster execution and even more
flexibility, a further enhanced run-command processor is also under
development. Shared library support is under investigation, too. Lastly,
we are looking forward to upgrading OpenPKG to use the forthcoming RPM
4.1 version.
d647 1
a647 1
article.principle.eps
d652 1
a652 1
article.layout.eps
d657 1
a657 1
article.layout-local.eps
d672 1
a672 1
Release:      1.1.0
d682 2
a683 2
BuildPreReq:  OpenPKG, openpkg >= 1.1.0
PreReq:       OpenPKG, openpkg >= 1.1.0
d866 1
a866 1
ftp> get openpkg-1.1.0-1.1.0.src.sh
d869 1
a869 1
user$ sh openpkg-1.1.0-1.1.0.src.sh \
d872 1
a872 1
root# sh openpkg-1.1.0-1.1.0.*-uo.sh
d875 1
a875 1
      ftp://ftp.openpkg.org/release/1.1/SRC/rsync-2.5.5-1.1.0.src.rpm
d887 1
a887 1
user$ rm -f openpkg-1.1.0-1.1.0.*
d911 1
a911 1
FreeBSD 5.0                   partial
a913 2
RedHat Linux 7.x              full
RedHat Linux 6.x              partial
d917 2
d983 3
a985 3
        <pkg-rpm>  e.g. rsync-2.5.5-1.1.0.*.rpm
        <pkg-src>  e.g. rsync-2.5.5-1.1.0.src.rpm
        <pkg-bin>  e.g. rsync-2.5.5-1.1.0.ix86-freebsd4.6-uo.rpm
d1016 1
a1016 1
- Variety of over 400 packages available
@


1.130
log
@take over corrections send to SysAdmin
@
text
@d479 1
a479 1
symbolic link pointing from I<prefix>C</local/PKG/>I<pkg-name> to
@


1.129
log
@flush pending changes which were sent to SysAdmin
@
text
@d165 2
a166 2
are not present, an alternative approach exists in which the binary
version of the shell script is used instead.
d258 1
a258 1
an old one that retains its original (but old) RPM default, RPM renames
d272 1
a272 1
package and C<rpm -qf>I<prefix>/I<path>/I<to>/I<file> reveals to which
d284 1
a284 1
I<prefix>C</etc/rc>. Run commands for every package are conveniently
d342 1
a342 1
of all daemons in a hierarchy, just add a C<openpkg_ignall="yes"> to
d418 1
a418 1
for all packages. In short, this means that when rolling a binary
d501 1
a501 1
repository are tracked and summarized with postings to a public mailing
@


1.128
log
@Deutschland -> Germany
@
text
@d74 1
a74 1
self-contained. The more than 300 available OpenPKG packages are really
d550 1
a550 1
OpenPKG users have profited from an increase of 220 to over 300 software
d626 1
a626 1
article.principle.fig
d631 1
a631 1
article.layout.fig
d636 1
a636 1
article.layout-local.fig
d647 1
a647 1
Distribution: OpenPKG [REL]
d650 1
a650 1
Version:      2.5.4
d889 4
a892 2
FreeBSD 4.x/5.0-C             full
Debian GNU/Linux 2.2/3.0pre   full
d895 1
d898 1
a898 1
NetBSD 1.5.x                  partial
d964 1
a964 1
        <pkg-bin>  e.g. rsync-2.5.5-1.1.0.ix86-freebsd4.5-uo.rpm
d995 1
a995 1
- Variety of over 300 packages available
@


1.127
log
@final text layouting and line breaking
@
text
@d48 2
a49 2
OpenPKG is a Open Source software project initiated by Cable & Wireless
Deutschland, a leading international Internet Service Provider (ISP).
d541 1
a541 1
Deutschland in November 2000. The implementation relies on RPM 4 for
d549 1
a549 1
Deutschland, a large ISP. Since its public release in January 2002,
d614 1
a614 1
Wireless Deutschland. He leads the hosting department and is responsible
@


1.126
log
@polish About authors section
@
text
@d10 34
a43 31
development when trying to apply it manually to your work environment. To
keep a work environment stable and secure, it's often necessary to locate the
latest version of an application on the Internet and collect its most recent
patches containing security and bug fixes. However, there is often no single
location for these files. After the search finishes, a system administrator
must build and install the new binaries on every Unix box in the network, and
might find that the application needs slight tweaking on each of them. Then
after a round of laborious build manipulation, it might not be clear that the
application will run as intended on each of the different platforms. If the
application is a daemon even more work awaits, because most Unix flavors have
their own method of starting and stopping daemons.

If the previous operation succeeds after all, the system administrator might
be left to wonder why it is necessary to clutter up the system with residual
installation files and how do the vendors think the residue should be removed?
Also, if the C</var> file system later runs out of disk space due to an
overgrown application log, do the vendors think that the responsibility lies
with the system administrator to implement log file rotation himself? Such
redundant basic tasks can and should be avoided.

What can a system administrator do when facing obstacles like these? He might
start by sticking with vendor packages only. Unfortunately, there may be
several different Unix variants to administer. Worse yet, no existing vendor
packaging facility supports multiple installation of an application, a feature
useful for multiple project coexistence on a single machine and independent
package testing. Another missing feature regards the management of coexisting
packaged and unpackaged software. Finally, if the system administrator wants a
software installation and configuration guide for his vacation replacement, he
might as well give up. This is usually impossible, because every vendor
packaging approach is different and cannot be uniformly applied across all
major Unix platforms.
d49 3
a51 3
Deutschland, a leading international Internet Service Provider (ISP). The
project began in November 2000, and has grown to be a collaborative software
development effort managed and maintained by many. The project
d55 43
a97 41
More specifically, the goals of OpenPKG stem from the historical problem often
faced in the daily operation of an ISP. The major Unix platforms in operation
at ISPs include FreeBSD, Linux and Solaris. To satisfy the demands of such a
diverse computing environment, the installation and maintenance of software
packages across these platforms greatly benefits from a unified and consistent
approach.

OpenPKG is not limited to the three major platforms just mentioned, however.
As summarized in Table_1, OpenPKG has more ambitious goals. To achieve such
cross-platform portability, OpenPKG provides a subsystem on top of the
underlying Unix system as shown in Figure_1. It covers every essential server
software component from shells, editors, compilers, and up to network daemons
and add-on applications. Hence, the intended target community consists of
system administrators faced with a large and diverse set of Unix servers.

Internally, OpenPKG leverages the existing packaging technology of the popular
RedHat Package Manager (RPM). However, the RPM software included with OpenPKG
is specially extended to become more unique and self-contained. The more than
300 available OpenPKG packages are really just RPM packages under the hood,
but were developed from scratch in a OpenPKG standard approach. The packages
are clean and robust, because they follow strict style guidelines and
environment requirements.

To meet these OpenPKG guidelines and standards, a package must be built from
pristine vendor sources in a non-root temporary environment. It has to work in
an arbitrary file system location, has to follow a strict file system layout,
and must be self-contained within its OpenPKG instance. Furthermore, the
package must be independent from external Unix facilities, has to install
with a reasonable and ready to go configuration, and has to use log file
rotations and other such administrative wonders.

These well specified package-building guidelines yield several benefits to
OpenPKG users. OpenPKG users can install an instance (the OpenPKG subsystem
and user-chosen packages) under any file system location, and even install
multiple such instances on a single Unix system. Incidentally, the main
OpenPKG project environment is hosted on a machine with six other ongoing
software projects, each with their own dedicated OpenPKG instance. To
separately satisfy each project's needs, the associated OpenPKG instance
serves every required software component from Postfix to BIND, and INN to
Apache. Each project can therefore run in its own isolated environment, much
like on a virtual machine.
d102 6
a107 5
OpenPKG follows an approach of minimum OS intrusion and maximum standalone
presence. It tries hard to smooth out the differences between the underlying
vendor solutions. Sometimes this means that it has to break with well known
standards in order to provide a cleaner solution. This is the most reasonable
approach, and leads to a consistent cross-platform solution.
d110 19
a128 17
packaging technology when other alternatives exist?" There are indeed other
similar packaging technologies available to projects like OpenPKG, with the
most prominent alternatives to RPM being the Debian C<dpkg>/C<apt>
combination, FreeBSD ports, and System V C<pkgadd>. According to some, RPM may
not be the greatest packaging system since sliced bread. However, RPM along
with its OpenPKG extensions is the only solution covering the I<whole> package
lifecycle in a fully consistent way.

To elaborate, the OpenPKG package lifecycle starts with fetching, unpacking,
patching, and building the source package from pristine vendor sources. It
goes on to build the binary package in an unprivileged environment, and
finishes its life term with the installation, upgrade, and uninstallation of
the binary package on the target OpenPKG instance. This all works in a
self-contained environment, and is driven by concise yet complete package
specifications (RPM C<.spec> files). So, to finally answer the question,
OpenPKG adopts RPM as its underlying packaging technology because no other
can fulfill these steep requirements.
d131 24
a154 22
porting. A requirement of the OpenPKG packaging philosophy is that the vendor
software be portable to begin with. Minor platform porting issues are fixed by
the OpenPKG packagers, but fundamental changes are not considered. In fact,
the main reason for some platforms lacking full OpenPKG support is that the
amount of overhead in building software on them is not within reason.

It may surprise some that OpenPKG officially discourages the use of binary
packages, and only provides them for bootstrapping (development tools not
available) and emergency (tight time constraints) purposes. Experience has
shown that installing binary packages built from source packages on the target
machine outperforms other binary methods in respect to security and
robustness.

There are simply too many subtle differences between most build and install
systems that can influence the binary at run time and cause trouble. Some
important run time parameters, such as the maximum size of shared memory
segments, are compiled into the binary on the build machine. Among many
examples of such a run time build dependency is a situation in which an Apache
package is built with mod_ssl and MM. The dependency details of such a
combination are overwhelming, when sorting out the run time parameters.
To avoid such trouble, OpenPKG believes that the only reasonable
solution is to always start with source packages.
d159 13
a171 12
The OpenPKG bootstrapping process is wrapped into a shell script that when run,
will create a new instance of OpenPKG. This process is as self
contained as possible, and requires a minimum amount of operating system
support and tools to unpack and compile itself. In the best case, the script
will search the C<$PATH> for the development tools C<tar>, C<make> and C<cc>
and use them in its processing. If any of these tools are not present, an
alternative approach exists in which the binary version of the shell script is
used instead.

The first step in bootstrapping involves dedicating a unique file system prefix
to the instance along with user and group ids. The generic bootstrap building script
called C<openpkg->I<version>C<->I<release>C<.src.sh> requires these arguments
d173 17
a189 16
C<openpkg->I<version>C<->I<release>C<.>I<arch>C<->I<os>C<->I<id>C<.sh>. When
run, this script installs the OpenPKG
instance under the specified prefix with all files owned by the user and group
(Figure_2). This bootstrapping process links the OpenPKG instance with the
underlying Unix system in a very mild way with only a few anchor points.
Subsequent package installations do not touch the system at all, and if
OpenPKG itself is uninstalled, the anchor points vanish.

After creating a self-contained hierarchy the bootstrap process registers
itself as C<openpkg>, and can thus be upgraded or treated just like any other
package. To make upgrade an already bootstrapped OpenPKG instance easier,
C<.rpm> versions of the bootstrap package are available as well.

A step by step example of a complete installation and uninstallation of an
OpenPKG instance with a RSYNC server package is given in Listing_4. To
understand the RPM commands used, see the quick reference in Table_3.
d194 2
a195 2
Every file system standard sucks. OpenPKG's file system aims to suck less
(Figure_2). Basically, its package area resembles the traditional
d197 2
a198 2
it contains its own RPM package management information in a sub area
for purposes of self-containment plus a local area for adding unpackaged
d201 2
a202 2
OpenPKG does break with tradition in one aspect of its file system layout,
however. It unconventionally uses a separate subdirectory of
d204 10
a213 10
installed package. These subdirectories are easy to manage, because each is
named after its associated package. This provides for a better
structure than the usual mess of files, and every OpenPKG package adheres to
this layout scheme (even when requiring a lot of effort to override the
different vendor package intentions).

Looking again at the RSYNC example in Listing_4, you can conclude right away
that the RSYNC configuration is in I<prefix>C</etc/rsync/>, and it logs to
somewhere in I<prefix>C</var/rsync/>. Such ease of maintenance makes backups
easier, moving whole instances without hassle, and more.
d218 7
a224 6
When building packages, the temporary files are placed into subdirectories of
I<prefix>C</RPM/> by default. A package builder can obtain the necessary
subdirectory access by either being a member of the associated OpenPKG group,
logging in under the user id of the OpenPKG instance, or logging in as root.
A carefully written C<~/.rpmmacros> file can alternatively redirect the paths
to a specified location (see the default macros C<%_sourcedir>, C<%_specdir>,
d229 10
a238 9
To build a binary package I<pkg-bin> from a source package I<pkg-src>, use
C<rpm --rebuild >I<pkg-src>. OpenPKG's RPM will read the C<.spec> information
of the I<pkg-src>, build the package based on the information, and place the
resulting binary package in I<prefix>C</RPM/PKG/>I<pkg-bin>.

To finally install the binary package so that it becomes part of the OpenPKG
instance, just use C<rpm -Uvh >I<pkg-bin>. Strictly speaking this upgrades the
package. To RPM, installation is nothing more than the special case of
upgrading from nothing.
d241 35
a275 34
boolean variables named C<with_>I<name>. To determine which variables are
available (if any at all), run "C<rpm -qpi >I<pkg-src>C< | grep with_>". To
build a binary package using such variables, add C<--define "with_>I<name>C< >
I<value>C<"> to the C<rpm --rebuild> command to override the default
value.

RPM is very clever when it comes to keeping configuration files
during an upgrade, as shown in Table_2. An old configuration file is kept if
the system administrator stuck to default configuration which remained the
same, or if the configuration was changed but coincidentally matches the
default configuration of the new package. In practice, a administrator-changed
configuration must be reapplied in few cases of package upgrade. In any case,
should a configuration file not be kept, RPM saves the old configuration file
with the extension C<.rpmsave> before saving a new default in its place. This
ensures that changes to a default configuration can be recovered and reapplied
so that an upgraded package runs correctly. Should a new default configuration
file replace an old one that retains its original (but old) RPM default, RPM
renames it with the extension C<.rpmorig>.

To make this delightful mechanism work properly, the configuration files of
each package have to be explicitly tagged. OpenPKG packages all follow this
principle, which further contributes to OpenPKG's robust nature. OpenPKG's RPM
does the intuitive right thing by making sure that a changed configuration
file is kept in place if possible and if not, then preserves it for manual
consideration and application.

Finally, after the installation of a package, you can query a lot of its
information. The command C<rpm -qi >I<pkg-name> summarizes a single installed
package, while C<rpm -qa> lists the names of all installed packages. C<rpm
-qlv >I<pkg-name> lists all the files associated with a package and C<rpm
-qf>I<prefix>/I<path>/I<to>/I<file> reveals to which package the given file belongs.
You can even check a package's integrity using C<rpm -V >I<pkg-name> to verify
which files have been tampered with or somehow munged. For more details on
this refer to Table_3.
d280 10
a289 9
You might have notices that in the previous example installation of RSYNC, the
server was started using the command C</usr/opkg/etc/rc rsync start>.
The workhorse behind this simple statement is the powerful OpenPKG
run-command facility, executed with I<prefix>C</etc/rc>. Run commands
for every package are conveniently named I<prefix>C</etc/rc.d/rc.>I<pkg-name>.
What each of them offers is the functionality of several shell script segments
encapsulated in a single file. The sections of a run-command file are
identified by left-aligned labels prefixed with 'C<%>'. Listing_2 shows
C<rc.rsync> as an example.
d293 35
a327 32
corresponding with the desired section labels are then extracted from the
C<rc.>I<pkg-name> file and executed in the order given on the command line.
The reserved package name C<all> serves as a wildcard and refers to all
installed OpenPKG packages, causing the processing of all run-command files in
a specified order. In this case, the run-command facility will order the
run-command processing according to the priority field (C<-p >I<number>) of
the given section label in each run-command file. Another popular field in a
section label is C<-u >I<user>, which directs the script code to execute with
the privileges of I<user>.

Most sections in a run-command file have arbitrary labels intended to be used
as command line arguments to the run-command facility. However, some sections
have special meaning. The section labels of these are reserved names used
internally by the run-command facility. For example, the C<%common> section
functions as a library and contains script code useful to some or all of the
other sections. Its script code is run before any other script code.

Just like its cousin the C<%common> section, the C<%config> section can appear
only one time in each run-command file. It contains variables used to
configure the behavior of the other sections residing in the same run-command
file. This means that the logging and enabling variables in a C<%config>
section will only affect the associated package, for example.  Such variables
can be overridden in I<prefix>C</etc/rc.conf> in a per-hierarchy scope,
however. Technically, the run-command facility assembles a large script file
from the C<%config> section, the I<prefix>C</etc/rc.conf> file, the C<%common>
section, and finally the user-defined section given as an argument (in that
order). The fat script it then executed.

The sections C<%monthly>, C<%weekly>, C<%daily>, C<%hourly> and C<%quarterly>
also have special meaning, as the OpenPKG bootstrap process sets up Cron jobs
to execute them accordingly. Another label often seen is C<%env>, which is
intended to be used with the C<--eval> option explained below. 
d335 11
a345 10
With OpenPKG, all daemon packages are released with scripts that recognize
the value of a variable I<pkg-name>C<_enable> (default value "C<yes>").
Setting this variable to "C<no>" disables all run-commands of the daemon in
question. As seen with the RSYNC server example, this can be quite useful when
installing a package just to get a client piece. Should the server piece not
be of interest, then a simple variable shuts it off completely.  Similarly, to
disable the automatic startup of all daemons in a hierarchy, just add a
C<openpkg_ignall="yes"> to I<prefix>C</etc/rc.conf>. In this case, daemons can
still be started manually. This feature may be of interest to system
administrators wanting control over daemons with finer granularity.
d349 4
a352 4
configured variable, or use C<rc --config> to see a complete list of all
available variables with their default and effective values. Last but
not least the run-command facility offers a very handy feature to allow
packages to extend the user shell environment. For instance the
d361 13
a373 12
As mentioned, OpenPKG is based on a uniquely adjusted and extended RPM-based
packaging facility which allows for very concise and clean package
specifications and building of I<every> package in an unprivileged
environment. Is this any different than what the RedHat, SuSE, or Mandrake
implementations offer? To understand the added value of the OpenPKG
implementation, let's take as example the OpenPKG packaging of the
RSYNC program. The OpenPKG packaging consists of three files: the RPM
specification (C<rsync.spec>, Listing_1), the run-commands (C<rc.rsync>,
Listing_2), and the default daemon configuration (C<rsync.conf>, Listing_3).
In comparison with the RPM-based RSYNC package of other vendors, the OpenPKG
RPM-based package is full featured yet very concise and clean. This is due to
the use of OpenPKG's RPM extensions and strict style guidelines.
d376 27
a402 25
implementation uses GNU shtool. All manual installation and patching is done
with the C<shtool> command. A companion tool, C<rpmtool>, complements
C<shtool> with RPM and OS-specific features. The C<rpmtool> allows all OpenPKG
packages to generate their file list (C<%files>) on the fly and makes the
packaging information smaller. It reduces the required maintenance when vendor
version updates occur as well.

OpenPKG's RPM additionally provides a set of local macros (C<%{l_xxx}>) to
abstract system specifics and also help in removing redundancy from packaging
specifications. For example, the C<%{l_prefix}> is the file system I<prefix> of
the associated OpenPKG instance. Using OpenPKG's local macros offers a clear
advantage, because packages no longer need hard-coded path prefixes and can
therefore be built for arbitrary OpenPKG instances.

Macros exist for the most often used build variables. The C<%{l_cc}> macro
expands to either I<prefix>C</bin/cc> (in case the OpenPKG C<gcc> package is
installed) or defaults to just C<cc>. The same goes for C<%{l_cflags -O}>: it
expands to the optimized C compiler flags. In case C<gcc> is installed, it
expands to "C<-O2 -pipe>". Otherwise, it expands to just C<-O> by default. The
variables C<%{l_make}> and C<%{l_mflags}> work together in a similar way. If
C<%{l_make}> points to a known C<make> which supports parallel building and
the underlying system has more than one CPU, then C<%{l_mflags -O}> expands to
the necessary flags to leverage the system's multiple processing power. For
example, on a 2 CPU FreeBSD 4.x machine with BSD make, C<%{l_mflags -O}>
expands to C<-j4 -B> while on a 4 CPU Linux machine with GNU make,
d405 26
a430 23
Additionally, all OpenPKG packages follow I<exactly> the same style as
the RSYNC example (see Listing_1, Listing_2, and Listing_3). The header order,
indentation, etc. is standardized, and allows developers to easily query and
even semi automatically edit package information directly from the source.
Incidentally, the indices on the OpenPKG FTP server and the OpenPKG release
engineering procedures are auto generated by exploiting this standard scheme.

I<Every> OpenPKG package is able to build in an unprivileged (non-root user)
environment and with read-only access to an OpenPKG instance. This allows safe
(no development system intrusion) and precise (no trashed or missing files)
packaging. Such security and precision is achieved by consistently using the
C<BuildRoot> feature of RPM for all packages. In short, this means that when
rolling a binary package the software is redirected to install into a shadow
area (I<prefix>C</RPM/TMP/>I<pkg-name>C<-root/>I<prefix>). The package is then
made from the shadow area just as if it were located in the real file system location
(I<prefix>). This important improvement to the standard RPM behavior may sound
trivial and easy to achieve, but is actually one of the trickiest steps in
packaging software for OpenPKG. Sometimes (as with RSYNC), it is just a matter
of overriding variables (C<prefix> in the example) on the C<make install>
step. Other times the solution is more involved. For some OpenPKG packages it
takes a lot of effort to find a reasonable way to redirect the vendor
installation to the C<BuildRoot> location, but the extra effort is always
worthwhile and results in safer and more precise packaging.
d455 8
a462 7
appealing yet unpackaged software. Ambitious system administrators can package
the software themselves for local purposes and even contribute such new
packages to the OpenPKG community. Alternatively, the C<local> subdirectory of
an OpenPKG instance exists for the purpose of containing unpackaged software,
and can be instrumental in integrating a base of OpenPKG packages with other
unpackaged software in an easy to maintain way. OpenPKG also provides a
corresponding C<lsync> tool to aid such integration.
d466 9
a474 9
C<sbin>, C<man>, C<info>, C<include> and C<lib> subdirectories
of I<prefix>C</local/PKG/>I<pkg-name>C</> and then virtually
linked into the corresponding top-level directories under
I<prefix>C</local/> by running I<prefix>C</sbin/lsync>. This easy to
administer strategy leads to a very clean and maintainable OpenPKG
instance, even with its new coexisting unpackaged software in
I<prefix>C</local/>. This especially makes it easy to uninstall
a package. Just remove I<prefix>C</local/PKG/>I<pkg-name>C</> with
all its contents and run C<lsync> again.
d494 42
a535 39
A carefully crafted release process is part of the OpenPKG project, and the
fruits of the whole project are available to the public according to Open
Source standards. All sources (package specifications, source patches, website
sources, the handbook, this article, etc) are located in a publicly readable
central CVS repository, which can be browsed anonymously by conventional
C<cvs> commands or through the website for added convenience.
Additionally, all developer commits to this repository are tracked and
summarized with postings to a public mailing lists and public newsgroups.
People can easily follow all developments by subscribing to the list or
reading the newsgroup.

For stability and to reduce conflicts between development milestones, OpenPKG
has three release branches (which technically directly map to CVS branches.)
These are OpenPKG-SOLID, OpenPKG-STABLE and OpenPKG-CURRENT. OpenPKG-SOLID is
the security update branch of the last public OpenPKG release. OpenPKG-STABLE
is the stable branch from whose contents the next public release is made.
OpenPKG-CURRENT is the current state of the development branch, and contains
packages of beta-grade stability. In any case, the branch from which a package
was built can easily be determined by the OpenPKG RPM file name, because they
follow a consistent naming scheme: I<pkg-name>C<->I<version>C<->I<YYYYMMDD>
(for CURRENT), I<pkg-name>C<->I<version>C<->I<N>C<.>I<YYYYMMDD> (for I<N>-STABLE),
I<pkg-name>C<->I<version>C<->I<N>C<.>I<M>C<.>I<X> (for I<N.M.X>-SOLID). Once such
a source RPM file is built, the new binary RPM file name contains even more
information, such as operating system, hardware, and the OpenPKG instance
prefix.

The OpenPKG developer team is very fast in keeping OpenPKG-CURRENT packages up
to date and in sync with the latest vendor versions. This is due to the fact
that the versions of all externally available vendor sources are automatically
tracked on a daily basis. An OpenPKG package for a new vendor software version
is often available before the software is even announced on Freshmeat.net.

Finally, OpenPKG takes security very seriously. Experience has shown that
"security through obscurity" does not work, and that public disclosure leads
to quicker and better solutions to security problems. In that vein, OpenPKG
tries to release fixed packages as fast as possible after a vulnerability was
discovered. The OpenPKG security release and advisory process notifies the
community by publishing official security advisories in the security section
of the website and on the mailing lists.
d541 12
a552 12
Deutschland in November 2000. The implementation relies on RPM 4 for its basic
packaging mechanism, but offers more than RPM alone. To meet its goal of
becoming a modular and flexible Unix subsystem for cross-platform software
packaging and installation, OpenPKG includes tricky bootstrapping logic that
installs a customized implementation of RPM 4 on any of the supported target
platforms.

OpenPKG is in production use since April 2001 at Cable & Wireless Deutschland,
a large ISP. Since its public release in January 2002, OpenPKG users have
profited from an increase of 220 to over 300 software packages. The project
is continuously improved by a diverse team of developers who also daily update
and add packages.
d555 15
a569 14
partly due to the ease of writing specifications and building packages. Most
OpenPKG users find it deceivingly simple to build a basic package. New users
interested in such packaging can use the RSYNC example in this article as a
blueprint. Accordingly, package contributions are always appreciated by the
members of the OpenPKG project.

To make OpenPKG even more attractive, work is underway on a front end which
will simplify and control the installation process according to build and
install dependencies. OpenPKG is also fulfilling plans to satisfy the desktop
user by offering X11-dependent packages for Gtk, Qt, Gimp, Mozilla, and many
others. For faster execution and even more flexibility, a further
enhanced run-command processor is also under development. Shared library
support is under investigation, too. Lastly, we are looking forward to
upgrading OpenPKG to use the forthcoming RPM 4.1 version.
d598 6
a603 5
Thomas Lotterer is a network professional and consultant working as a Unix
software developer at Cable & Wireless Germany. He gained experience in
cross-platform system integration and software distribution by working
previously as a system administrator and technical trainer. Today, Thomas
works actively on the OpenPKG and OSSP projects. 
d608 3
a610 3
tools and technologies. He is an active contributor to both the OpenPKG and
OSSP projects. With fingers blazing, Michael listened to classical music while
writing parts of this article to go even faster. 
d613 6
a618 6
Christoph Schug is a senior Unix system administrator at Cable & Wireless
Deutschland. He leads the hosting department and is responsible for all
managed servers at the Munich data center. His revolutionary ideas and visions
often result in additional lines in Ralf's TODO list. When not in the office,
Christoph might be found in the Alps steering the screaming and smoking tires
of his Miata MX-5 roadster. 
@


1.125
log
@more semantical polishing
@
text
@d561 5
a565 5
hacker, leading the software development department at Cable &
Wireless Germany. He is the author of well-known software like Apache
mod_ssl, GNU Pth, and GNU Shtool and the founder of Open Source
software projects like OpenSSL, OpenPKG, and OSSP. He can be contacted at:
rse@@engelschall.com
d568 1
a568 1
software developer at Cable & Wireless Deutschland. He gained experience in
d571 2
a572 2
works actively on the OpenPKG and OSSP projects. He can be contacted at:
thomas@@lotterer.net
d575 1
a575 1
Deutschland, where he works on the network and user interface logic of ISP
d578 2
a579 2
writing parts of this article to go even faster. He can be contacted at:
michael@@schloh.com
d586 2
a587 1
of his Miata MX-5 roadster :) He can be contacted at: chris@@schug.net
@


1.124
log
@ok, now that Michael is finished, the [edited] tags can be removed
@
text
@d310 5
a314 5
Regarding configuration through variables, it should be mentioned that
the C<rc.>I<pkg-name> file is not tagged as a configuration file and will be
overwritten on updates with no questions asked. Because the
I<prefix>C</etc/rc.conf> file is tagged as a configuration file, it is a
better candidate for user-defined variables.
d316 1
a316 1
With OpenPKG, most daemon packages are released with scripts that recognize
d327 10
a336 10
The OpenPKG run-command facility has many other interesting features. Use C<rc
--query >I<variable> to see the effective value of any configured variable, or
use C<rc --config> to see a complete list of all available variables with
their default and effective values. Last but not least the run-command
facility offers a very handy feature to allow packages to extend the user
shell environment. The bootstrap package C<openpkg> can thus include the
intuitively correct hierarchy into your C<PATH>, C<MANPATH>, C<INFOPATH>, etc,
only by using the run-command facility. Just execute C<eval
`>I<prefix>C</etc/rc --eval >I<pkg-name>C< env`> to see this environment
extension for yourself.
d346 2
a347 2
implementation, let's take as example the OpenPKG packaging of the excellent
RSYNC program. The OpenPKG example consists of three files: the RPM
d375 1
a375 1
C<%{l_make}> points to a known make(1) which supports parallel building and
d396 1
a396 1
made from the shadow area just as if it were the real file system location
d406 9
a414 9
Finally, OpenPKG's RPM implementation provides proxy packages, a tricky and
appealing mechanism for reusing the packages of a master OpenPKG instance.
Proxy packages can reside in multiple slave OpenPKG instances, and allow the
system administrator to avoid redundant building and maintaining of the same
software package in multiple OpenPKG instances. For example, C<gcc> is
typically required by many packages at build time. A C<gcc> OpenPKG package
would hypothetically be needed in every OpenPKG instance were it not for
OpenPKG's proxy packages. A savvy system administrator will install a single
C<gcc> package in a master OpenPKG instance and then only proxy packages
d416 8
a423 7
I<slave-prefix>C</bin/rpm --makeproxy> on the binary RPM of the master
instance. OpenPKG's RPM will then produce another binary RPM package,
containing a shadow tree resembling the contents of the master instance. The
shadow tree is technically nothing more than symbolic links to the master
(non-proxy) package's files and directories. This mechanism can save a lot of
time and storage, however it should only be applied to packages with global
configuration dependencies only or with no configuration dependencies at all.
d431 1
a431 1
packages to the OpenPKG community. Alternatively, the "local" subdirectory of
d437 26
a462 21
To integrate unpackaged software into an OpenPKG instance, each unpackaged
software component may be installed into its dedicated
I<prefix>C</local/PKG/>I<pkg-name>C</> directory and then virtually linked to
its parent C<bin>, C<sbin>, C<man>, C<info>, C<include> and C<lib> directories
by running I<prefix>C</sbin/lsync>. This easy to administer strategy leads to
a very clean and maintainable OpenPKG instance, even with its new coexisting
unpackaged software in I<prefix>C</local/>.

This strategy even allows for installation of different versions of the same
software. Just install into
I<prefix>C</local/PKG/>I<pkg-name>C<->I<version>C</> and add a symbolic link
pointing from I<prefix>C</local/PKG/>I<pkg-name> to this directory. This
works, because C<lsync> skips subdirectories of I<prefix>C</local/PKG/> with
version numbers attached. To upgrade an older C<foo-X.X.X> to C<foo-0.7.42>,
just repeat the installation in the same way, altering the symlink
I<prefix>C</local/PKG/foo> to point to C<foo-0.7.42> instead and running
C<lsync> again. C<lsync> will automatically update symlinks, creating new
links if required and removing outdated dangling ones. As might be guessed, it
is just as easy to go back to the old version if the new one keeps dumping
core or something like that. For an example of such multiple unpackaged
software installation see Figure_3.
d471 6
a476 5
central CVS repository, which can be browsed by conventional cvs commands or
through the website for added convenience. Additionally, all developer commits
to this repository are tracked and summarized with postings to a public
mailing list and public newsgroups. People can easily follow all developments
by subscribing to the list or reading the newsgroup.
d487 2
a488 3
(CURRENT), I<pkg-name>C<->I<version>C<->I<N>C<.>I<YYYYMMDD> (I<N>-STABLE),
I<pkg-name>C<->I<version>C<->I<N>C<.>I<M>C<.0> (I<N.M>-RELEASE),
I<pkg-name>C<->I<version>C<->I<N>C<.>I<M>C<.>I<X> (I<N.M.X>-SOLID). Once such
d505 1
a505 1
of the website.
d534 5
a538 5
user by offering X11-dependent packages like gimp, qt, freetype, and many
others. For faster run time program manipulation, an enhanced run-command
processor is also under development. Shared library support is under
investigation, too. Lastly, we are looking forward to upgrading OpenPKG to use
the forthcoming RPM 4.1 version.
@


1.123
log
@no, System V is correct
@
text
@d5 1
a5 1
Cross-platform Unix software packaging with OpenPKG [edited]
d42 1
a42 1
OpenPKG to the rescue [edited]
d94 1
a94 1
Covering the whole OpenPKG package lifecycle [edited]
d146 1
a146 1
Bootstrapping OpenPKG for the first time [edited]
d179 1
a179 1
OpenPKG file system layout [edited]
d203 1
a203 1
Managing OpenPKG packages [edited]
d262 1
a262 1
The OpenPKG run-command facility [edited]
d338 1
a338 1
OpenPKG RPM vs. RedHat RPM [edited]
d424 1
a424 1
Integrating unpackaged software [edited]
d458 1
a458 1
OpenPKG release engineering [edited]
d501 1
a501 1
Conclusion [edited]
d551 1
a551 1
About the authors [edited]
d925 1
a925 1
Table_4: OpenPKG summary [edited]
@


1.122
log
@polishing semantics
@
text
@d107 1
a107 1
combination, FreeBSD ports, and SystemV [FIXME should this read Solaris? FIXME]C<pkgadd>. According to some, RPM may
@


1.121
log
@Some small remaining edits.
@
text
@d150 1
a150 1
will create a new instance of OpenPKG on a machine. This script is as self
d159 1
a159 1
to the instance along with user and group ids. The generic bootstrap script
d161 1
a161 1
and creates a platform specific bootstrap script named
d163 1
a163 1
run, this binary version of the first shell script installs the OpenPKG
d193 1
a193 1
named after its associated parent package. This provides for a better
d206 1
a206 1
When building packages, the resulting files are placed into subdirectories of
d213 2
a214 1
I<prefix>C</etc/openpkg/rpmmacros>).
d223 1
a223 1
package. To OpenPKG, installation is nothing more than the special case of
d229 2
a230 2
build a binary package using such variables, add C<--define "with_>I<name>C<
>I<value>"> to the C<rpm --rebuild> command to override the default
d257 1
a257 1
-qf>I<prefix>/I<path/to/file> reveals to which package the given file belongs.
d568 7
a580 7

Michael Schloh von Bennewitz is a software engineer at Cable & Wireless
Deutschland, where he works on the network and user interface logic of ISP
tools and technologies. He is an active contributor to both the OpenPKG and
OSSP projects. With fingers blazing, Michael listened to classical music while
writing parts of this article to go even faster. He can be contacted at:
michael@@schloh.com
@


1.120
log
@Even more spelling and grammar corrections.
@
text
@d107 1
a107 1
combination, FreeBSD ports, and SystemV C<pkgadd>. According to some, RPM may
d575 5
a579 5
Deutschland. He works primarily on the network and user interface logic of
ISP-oriented tools and technologies. He is an active contributor to both the
OpenPKG and OSSP projects. With blazing fingers, Michael listened to classical
music while writing parts of this article to go even faster. He can be
contacted at: michael@@schloh.com
@


1.119
log
@Some spelling and grammar mistakes fell through the cracks.
@
text
@d225 1
a225 1
As a sidenote, some packages provide alternative build variants through
d245 1
a245 1
To make this delighful mechanism work properly, the configuration files of
d354 1
a354 1
implementationi uses GNU shtool. All manual installation and patching is done
d359 1
a359 1
version updates occurr as well.
d383 2
a384 2
indentaion, etc. is standardized, and allows developers to easily query and
even semiautomatically edit package information directly from the source.
d386 1
a386 1
engineering procdedures are autogenerated by exploiting this standard scheme.
d391 1
a391 1
packaging. Such security and precion is achieved by consistently using the
d400 1
a400 1
step. Othertimes the solution is more involved. For some OpenPKG packages it
d450 1
a450 1
I<prefix>C</local/PKG/foo> to point to C<foo-0.7.42> instead and runnning
d513 1
a513 1
profitted from an increase of 220 to over 300 software packages. The project
d524 1
a524 1
To make OpenPKG even more attractive, work is underway on a frontend which
@


1.118
log
@Add my piece of history ;-)
@
text
@d25 1
a25 1
Also, if the C</var> filesystem later runs out of disk space due to an
d27 1
a27 1
with the system administrator to implement logfile rotation himself? Such
d34 1
a34 1
useful for multiple project coexistance on a single machine and independant
d55 1
a55 1
diverse computing environment, the installation and maintainance of software
d77 1
a77 1
an arbitrary filesystem location, has to follow a strict filesystem layout,
d80 1
a80 1
with a reasonable and ready to go configuration, and has to use logfile
d83 1
a83 1
These well specified package building guidelines yield several benefits to
d85 1
a85 1
and user-chosen packages) under any filesystem location, and even install
d99 1
a99 1
vendor solutions. Sometimes this means that it has to break with well-known
d125 1
a125 1
the OpenPKG packagers, but fundemental changes are not considered. In fact,
d158 1
a158 1
The first step in bootstrapping involves dedicating a unique filesystem prefix
d179 2
a180 2
OpenPKG filesystem layout [edited]
-------------------------
d182 1
a182 1
Every filesystem standard sucks. OpenPKG's filesystem aims to suck less
d185 1
a185 1
it contains its own RPM packag management information in a subarea
d189 1
a189 1
OpenPKG does break with tradition in one aspect of its filesystem layout,
d194 1
a194 1
structure than the usual mess of files, and every OpenPKG package adhers to
d200 1
a200 1
somewhere in I<prefix>C</var/rsync/>. Such ease of mainenance makes backups
d363 1
a363 1
specifications. For example, the C<%{l_prefix}> is the filesystem I<prefix> of
d395 1
a395 1
made from the shadow area just as if it were the real filesystem location
d589 1
a589 1
Figure_2: The OpenPKG filesystem layout
d940 1
a940 1
- Strict and consistent filesystem layout
d946 1
a946 1
- Installation under arbitrary filesystem prefix
@


1.117
log
@'The OpenPKG run-command facility' edited.

PR:
Submitted by:
Reviewed by:
Approved by:
Obtained from:
@
text
@d574 7
@


1.116
log
@No, no, I definetely don't want to read that the bootstrap is a shell
script. It's a lot more and just wrapped into a single shell script.
Anything else reads like a script-kiddie approach with a 100-line shell
script.
@
text
@d261 1
a261 1
The OpenPKG run-command facility
d264 1
a264 1
In the previous test installation of RSYNC, you might have noticed the
d267 6
a272 5
run-command facility, executed with I<prefix>C</etc/rc>. Run-commands
for every package are stored as I<prefix>C</etc/rc.d/rc.>I<pkg-name>, a
collection of shell scripts in a single file organized by sections which
are identified by left-aligned labels prefixed with a 'C<%>'. Have a
look at the C<rc.rsync> in Listing_2 for a real-life example.
d275 32
a306 24
more section labels as additional arguments. The scripts are then
extracted from the C<rc.>I<pkg-name> file and executed in the order
given on the command line. The reserved package name C<all> refers
to executing the given sections for all installed packages. Order is
determined by the priority given at a section label using the option
C<-p >I<number> where small numbers are executed first. Another option
available to the section label is C<-u >I<user> which causes C<rc>
to execute the script with the realm of I<user>.

Some sections have special meaning. The C<%common> section has the function
of a library and contains code useful to many or all of the other
sections. It is included in every script before it is run.

The C<%config> section contains variables which are used to configure
the default behavior of other sections in a per-package context. Variables can
be overridden in I<prefix>C</etc/rc.conf> in a per-hierarchy scope. The
complete script executed by C<rc> is assembled from C<%config> section,
wholly I<prefix>C</etc/rc.conf> file, C<%common> section and the actual
section given at the C<rc> command
line, in that order.

Sections labeled C<%monthly>, C<%weekly>, C<%daily>, C<%hourly> and
C<%quarterly> are also special as the bootstrap sets up Cron jobs to
execute them accordingly. Another label often seen is C<%env> which is
d310 26
a335 25
the C<rc.>I<pkg-name> file is not flagged as a config file and will be
overwritten on updates with no questions asked. Be sure to put your
variables in I<prefix>C</etc/rc.conf>, which is tagged being a config
file.

that most daemon packages ship with scripts supporting a variable
I<pkg-name>C<_enable> (default value "C<yes>") which, if turned into
"C<no>" will disable all run-commands of the daemon. Back to the RSYNC
example, this can be useful if you installed the package just to get the
C<rsync> client program and do not want to run an RSYNC server.

Additionally you can disable the automatic startup of all
daemons in a hierarchy by adding a C<openpkg_ignall="yes"> to
I<prefix>C</etc/rc.conf>. However, all daemons can still be started
manually.

The run-command facility has other features as well. Use C<rc --query
>I<variable> to see the effective value of any configured variable or
run C<rc --config> to see a complete list of all available variables,
their defaults and currently effective values. Last but not least the
run-command facility offers a very handy feature to allow packages to
extend your shell environment. For instance, the bootstrap package
C<openpkg> uses this for including the hierarchy into your C<PATH>,
C<MANPATH>, C<INFOPATH>, etc. Just execute C<eval `>I<prefix>C</etc/rc
--eval >I<pkg-name>C< env`> to extend your environment.
@


1.115
log
@add two commas because although I'm not grammatically sure, the sentence
is not very understandable without them. And use "dependency details"
for more clear understanding.
@
text
@d149 1
a149 1
The OpenPKG bootstrapping process is managed by a shell script that when run,
@


1.114
log
@typo plus add hint to the consistent way of RPM, because others also
cover the _whole_ lifecycle in some or another way. RPM does it all
with a single API, with just a single .spec, etc. While the others have
hundrets of scripts and Makefiles and whatever.
@
text
@d138 2
a139 2
important run time parameters such as the maximum size of shared memory
segments are compiled into the binary on the build machine. Among many
d141 4
a144 4
package is built with mod_ssl and MM. The details of such a combination are
overwelming, when sorting out the run time parameters. To avoid such trouble,
OpenPKG believes that the only reasonable solution is to always start with
source packages.
@


1.113
log
@yes, we build as non-root...
@
text
@d108 1
a108 1
not be the greates packaging system since sliced bread. However, RPM along
d110 1
a110 1
lifecycle.
@


1.112
log
@Consistently make all instances of [de|un]installation one or the other. I
have chosen 'uninstallation' as the winner, though this is an arbitrary
choice. If RPM has an official standard word for this then we should use that
instead.
@
text
@d114 1
a114 1
goes on to create (FIXME unpriviliged?? what??) the binary package, and
@


1.111
log
@'Covering the whole OpenPKG package lifecycle' edited.
@
text
@d175 1
a175 1
A step by step example of a complete installation and deinstallation of an
d873 2
a874 2
# <prefix>/bin/rpm -e <pkg-name>                 deinstall/erase package
# <prefix>/bin/rpm -e --nodeps <pkg-name>        deinstall/erase package (ignore dependencies)
@


1.110
log
@fix one more typo
@
text
@d94 1
a94 1
Covering the whole OpenPKG package lifecycle
d97 48
a144 43
OpenPKG follows a minimal OS intrusion and maximum standalone approach.
It especially tries hard to smooth out the differences between the
underlying vendor solutions. Sometimes this means that it has to
break well known defacto standards in order to provide a cleaner
solution. This is the only reasonable approach leading to a consistent
cross-platform solution.

The main question asked is: why has OpenPKG chosen RPM as the underlying
packaging technology over alternatives, with the most prominent being
Debian's C<dpkg>/C<apt> couple, FreeBSD ports, and SystemV C<pkgadd>?
The reason is that, although RPM is not the greatest since sliced bread,
at least with the OpenPKG extensions added, it covers the I<whole>
lifecycle of a package. This starts by fetching, unpacking, patching and
building from the pristine vendor sources, followed by the unprivileged
creation of a resulting binary package, and ending in the installation,
upgrading and deinstallation of the binary package on the target OpenPKG
instance. This all works in a self-contained environment and is driven
by single and concise all in one package specifications, the RPM C<.spec>
files. No other existing packaging tool provides an equally good balance
in fulfilling all these requirements.

Keep in mind that OpenPKG is primarily about packaging, not porting. So,
it is a prerequisite to the whole process that the vendor software is
already portable enough. Minor platform porting issues are fixed by the
OpenPKG packagers, but do not expect fundamental changes. The inability
to build a software on all major platforms with an acceptable amount of
work is the number one reason why not all platforms are fully supported
by OpenPKG.

A surprising point with OpenPKG is the fact that the project officially
discourages the use of binary packages and only provides and recommends
them for bootstrapping (no development tools available) and emergency
(tight time constraints) situations. RPM fortunately supports this very
well, too. Experience showed that the only safety for robustness and
security is to build software on the target machine.

If you're in doubt, think about subtle differences between build and
install systems which cause trouble because they influence the binary
run time based on settings (e.g. maximum size of shared memory segments)
determined under compile time on the build machine. A prominent example
is Apache with mod_ssl and MM. And this is just a single example. There
are a lots of more we could tell you about. The only reasonable solution
is always to start from source packages.
@


1.109
log
@1x typo, 1x better word, 1x administrator
@
text
@d72 1
a72 1
are clean and robust, because the follow strict style guidelines and
@


1.108
log
@Use a little bit more magic numbers.

Approved by: cs
@
text
@d54 1
a54 1
at ISPs include FreeBSD, Linux and Solaris. To satisfy the demans of such a
d56 1
a56 1
packages across these platforms greatly benefits from a unified and systematic
d65 1
a65 1
system admins faced with a large and diverse set of Unix servers.
@


1.107
log
@Insert 'OpenPKG' into all titles where it makes sense. This makes sections
even more independent.
@
text
@d433 1
a433 1
version numbers attached. To upgrade an older C<foo-X.X.X> to C<foo-1.5.3>,
d435 1
a435 1
I<prefix>C</local/PKG/foo> to point to C<foo-1.5.3> instead and runnning
d809 7
a815 7
$ mkdir -p /usr/opkg/local/PKG/foo-0.8.15/SRC
$ cd /usr/opkg/local/PKG/foo-0.8.15/SRC
$ /usr/opkg/lib/openpkg/curl -o foo-0.8.15.tar.gz \
  ftp://ftp.example.com/foo-0.8.15.tar.gz
$ gunzip <foo-0.8.15.tar.gz | tar xf -
$ cd foo-0.8.15
$ ./configure --prefix=/usr/opkg/local/PKG/foo-0.8.15
d819 1
a819 1
$ ln -s foo-0.8.15 foo
@


1.106
log
@'Filesystem layout' edited.
@
text
@d94 2
a95 2
Covering whole package lifecycle
--------------------------------
d174 2
a175 2
Filesystem layout [edited]
-----------------
d198 2
a199 2
Managing packages [edited]
-----------------
d256 2
a257 2
Run-command facility
--------------------
d442 2
a443 2
Release engineering [edited]
-------------------
@


1.105
log
@'Managing packages' edited.
@
text
@d174 1
a174 1
Filesystem layout
d177 5
a181 5
Every filesystem standard sucks. OpenPKG's tries to suck less
(Figure_2). Basically its package area just resembles the traditional
layout you find under C</usr> on most popular systems. Additionally,
it contains its own RPM packaging management information in a subarea
for self-containment reasons plus a local area for adding unpackaged
d184 8
a191 7
Unlike the traditional layout, for configuration and data files,
OpenPKG consistently uses subdirectories with the package name below
I<prefix>C</etc/>, I<prefix>C</share/> and I<prefix>C</var/> to better
structure the usual mess with the large amount of those files. 
Every package has been rigorously forced to conform to this layout,
although for some packages it required lots of effort to override the
different vendor package intentions.
d193 4
a196 5
As a result, you immediately can conclude that RSYNC's configuration
is under I<prefix>C</etc/rsync/> and it logs to somewhere under
I<prefix>C</var/rsync/>. In general this all means maintainance is
simplified, backups can be made easier and even whole instances can be
moved without hassle.
@


1.104
log
@fix headline scheme
@
text
@d198 1
a198 1
Managing packages [in progress]
d227 28
a254 26
RPM is very clever when it comes to keeping or sweeping configuration
files during an upgrade, as shown in Table_2. The old config is kept
in three cases: if you sticked with defaults and defaults remain the
same, or if you coincidentally changed the config to the defaults of
the new package, or if the defaults didn't change and you would reapply
your changes anyway. The new config is installed, if you sticked with
defaults and defaults changed. The new config is installed and your
changes saved with extension C<.rpmsave>, if the defaults and with
them possibly the structure changed. This ensures your changes can be
recovered and the upgraded package runs correctly. The new config is
installed and your old config is saved with extension C<.rpmorig>, If no
previous default config existed at all but the new package provides one.
To make this work properly, configuration files have to be explicitly
tagged as those and this has been done for all OpenPKG packages.
In other words, OpenPKG's RPM does the intuitive right thing by making
sure that a changed configuration file is kept in place if possible and
if not possible, it is at least preserved for manual consideration. 

After installation of packages, you can query lots of information about
them. For instance, C<rpm -qa> gives you a list of installed packages,
C<rpm -qi >I<pkg-name> lists a summary about an installed package, C<rpm
-qlv >I<pkg-name> lists all files contained in a package and C<rpm
-qf>I<prefix>/I<path/to/file> tells you to which package the given file
belongs. Additionally, you can check a package's integrity using C<rpm
-V >I<pkg-name> and verify which files have been tampered with. For more
details, refer to Table_3.
@


1.103
log
@'Managing packages' in progress interflush committal.
@
text
@d840 1
a840 1
Table_2: RPM Handling of Configuration Files
@


1.102
log
@'Integrating unpackaged software' edited.
@
text
@d198 1
a198 1
Managing packages
d201 6
a206 6
When building packages, by default files are placed into subdirectories
of I<prefix>C</RPM/>, therefore you need write access to those
by being a member of the related OpenPKG group, login as the
OpenPKG instance user itself or login as root. Alternatively, you
can create a C<~/.rpmmacros> file and redirect the paths to your
own locations (see default macros C<%_sourcedir>, C<%_specdir>,
d210 14
a223 8
To build a binary package I<pkg-bin> from a source package I<pkg-src>
using the C<.spec> defaults use C<rpm --rebuild >I<pkg-src>. The result
is I<prefix>C</RPM/PKG/>I<pkg-bin>.

Some packages provide alternative build variants through boolean
variables named C<with_>I<name>. To determine which variables are
available, if any at all, run "C<rpm -qpi >I<pkg-src>C< | grep
with_>". To build using these options, add C<--define "with_>I<name>C<
a226 4
To install a binary package just use C<rpm -Uvh >I<pkg-bin>. Strictly
speaking this upgrades or installs a package. Installation is just the
special case of upgrading from nothing.

d431 1
a431 1
version numbers attached. To upgrade an older C<foo-X.X.X> to C<foo-0.8.16>,
@


1.101
log
@adjusted version of foo
@
text
@d404 1
a404 1
Integrating unpackaged software
d407 8
a414 7
No matter how many packages OpenPKG provides, there will always be
software which is still not packaged. If you are a highly skilled
admin, you can try to package it yourself for local purposes and
even contribute it to the OpenPKG community. Alternatively, you can at
least use the local area of an OpenPKG instance to integrate it in an
unpackaged but still easy to maintain way. For this OpenPKG offers the
local area and its corresponding C<lsync> tool.
d416 7
a422 5
The idea is to install each software component into its dedicated
I<prefix>C</local/PKG/>I<pkg-name>C</> directory and run
I<prefix>C</sbin/lsync> for virtually linking the C<bin>, C<sbin>,
C<man>, C<info>, C<include> and C<lib> from there into the top-level
ones under I<prefix>C</local/>.
d424 13
a436 15
This especially allows you to install different versions
of the same software in parallel. Just install into
I<prefix>C</local/PKG/>I<pkg-name>C<->I<version>C</> and add a
symbolic link pointing from I<prefix>C</local/PKG/>I<pkg-name> to
this directory. This works, because C<lsync> skips subdirectories of
I<prefix>C</local/PKG/> with version numbers attached. An example
installation can be seen in Figure_3.

If you consider some day to upgrade to C<foo-1.5.3> just
repeat the installation in the same way, alter the symlink
I<prefix>C</local/PKG/foo> to point to C<foo-1.5.3> instead and re-run
C<lsync> again. C<lsync> will automatically update symlinks upon
activation, creating new links if required and remove outdated dangling
ones. As you might already guess, it is as easy to go back to the old
version if the new one keeps dumping core.
@


1.100
log
@use better headline
@
text
@d429 1
a429 1
If you consider some day to upgrade to C<foo-0.8.16> just
d431 1
a431 1
I<prefix>C</local/PKG/foo> to point to C<foo-0.8.16> instead and re-run
@


1.99
log
@use more consistent order of tables, listings and figures
@
text
@d837 1
a837 1
Table_2: RPM handling of config files <prefix>/etc/<pkg-name>/*
@


1.98
log
@replace old listing with new figure
@
text
@d172 1
a172 1
understand the RPM commands used, see the quick reference in Table_4.
d250 1
a250 1
details, refer to Table_4.
a556 19
Table_1: OpenPKG Unix platform support
------------------------------------------------------------------------------
Unix Platform                 Support
============================= =======
FreeBSD 4.x/5.0-C             full
Debian GNU/Linux 2.2/3.0pre   full
RedHat Linux 7.x              full
RedHat Linux 6.x              partial
Sun Solaris 8                 full
Sun Solaris 2.6/7             partial
NetBSD 1.5.x                  partial
OpenBSD 2.9                   partial
HP/UX 10.20                   partial
Compaq Tru64 5.0              partial
Caldera OpenUNIX 8.0          not yet
IBM AIX 4.x                   not yet
SGI IRIX 6.x                  not yet
------------------------------------------------------------------------------

d567 5
a763 44
Table_2: RPM handling of config files <prefix>/etc/<pkg-name>/*
------------------------------------------------------------------------------
old in   old on     new in   new on 
package  filesystem package  filesystem approach
======== ========== ======== ========== ===========================================
X        X          X        X          keep old config
X        X'         X'       X'         keep old config
X        X'         X        X'         keep old config
X        X          Y        Y          install new config
X        X'         Y        Y          install new config, preserve X' as .rpmsave
-        X          Y        Y          install new config, preserve X  as .rpmorig
------------------------------------------------------------------------------

Table_3: OpenPKG summary [edited]
------------------------------------------------------------------------------
- Open source software
- Cross-platform solution for FreeBSD, Linux, Solaris and others
- Subsystem on top of underlying Unix system
- Minimal OS intrusion
- Fully self-contained with minimum OS dependencies
- Primarily targeted at server environments
- Based on a customized RPM 4
- Support for entire package lifecycle
- Build and run-time dependency control
- Builds software from pristine vendor sources
- All RPM package specifications written from scratch
- Clear and concise specifications follow a strict style
- Supports integration of unpackaged software also
- Tricky bootstrapping with no requirement for a preinstalled RPM
- Strict and consistent filesystem layout
- All packages installed with reasonable preconfiguration
- Users benefits from packager's knowledge
- Cryptographically signed packages
- Package integrity verification
- Support for building packages as unpriviledged user
- Installation under arbitrary filesystem prefix
- Allows multiple instances on the same host
- Fully uninstalls packages
- Powerful package queries
- Flexible run-command facility
- Mature technology in production use since April 2001
- Variety of over 300 packages available
------------------------------------------------------------------------------

d818 20
a837 1
Figure_3: File system layout of non-OpenPKG software installed
d839 9
a847 1
article.layout-local.fig
d850 1
a850 1
Table_4: OpenPKG Administration Commands (Quick Reference)
d895 31
@


1.97
log
@fix semantic, but perhaps English is again destroyed?
@
text
@d427 1
a427 1
installation can be seen in Listing_5.
d876 1
a876 1
Listing_6: File system layout of non-OpenPKG software installed
d878 1
a878 33
FIXME: This has to be redrawn in XFig to be a real figure in order
       to consume less size and be even more compact. It should
       NOT be integrated into Figure_2 (THL & RSE)
  /
  `-- prefix/
      `-- local/
          |-- PKG/
          |   |-- foo@@ (symlink -> foo-1.5.3)
          |   `-- foo-1.5.3/
          |       |-- bin/
          |       |   `-- foo
          |       `-- man/
          |           `-- man1/
          |               `-- foo.1
          |-- README
          |-- bin/
          |   `-- foo@@ (symlink -> ../PKG/foo/bin/foo)
          |-- etc/
          |-- include/
          |-- info/
          |-- lib/
          |-- man/
          |   |-- man1/
          |   |   `-- foo.1@@ (symlink -> ../../PKG/foo/man/man1/foo.1)
          |   |-- man2/
          |   |-- man3/
          |   |-- man4/
          |   |-- man5/
          |   |-- man5/
          |   |-- man7/
          |   |-- man8/
          |   `-- man9/
          `-- sbin/
@


1.96
log
@Changed each case of 'admin' to 'system administrator' according to Ralf's
(administrator) and Michael's (system) taste.
@
text
@d401 2
a402 2
time and storage, however it should only be applied to packages with no global
or configuration dependencies.
@


1.95
log
@Correct compound words and prefixes.
@
text
@d14 4
a17 4
location for these files. After the search finishes, an admin must
build and install the new binaries on every Unix box in the network, and might
find that the application needs slight tweaking on each of them. Then after a
round of laborious build manipulation, it might not be clear that the
d22 2
a23 2
If the previous operation succeeds after all, the admin might be left
to wonder why it is necessary to clutter up the system with residual
d27 2
a28 2
with the admin to implement logfile rotation himself? Such redundant
basic tasks can and should be avoided.
d30 11
a40 11
What can an admin do when facing obstacles like these? He might start
by sticking with vendor packages only. Unfortunately, there may be several
different Unix variants to administer. Worse yet, no existing vendor packaging
facility supports multiple installation of an application, a feature useful
for multiple project coexistance on a single machine and independant package
testing. Another missing feature regards the management of coexisting packaged
and unpackaged software. Finally, if the admin wants a software
installation and configuration guide for his vacation replacement, he might as
well give up. This is usually impossible, because every vendor packaging
approach is different and cannot be uniformly applied across all major Unix
platforms.
d389 14
a402 13
admin to avoid redundant building and maintaining of the same software package
in multiple OpenPKG instances. For example, C<gcc> is typically required by
many packages at build time. A C<gcc> OpenPKG package would hypothetically be
needed in every OpenPKG instance were it not for OpenPKG's proxy packages. A
savvy admin will install a single C<gcc> package in a master OpenPKG instance
and then only proxy packages (pointing to the real C<gcc>) in the other
OpenPKG instances by running I<slave-prefix>C</bin/rpm --makeproxy> on the
binary RPM of the master instance. OpenPKG's RPM will then produce another
binary RPM package, containing a shadow tree resembling the contents of
the master instance. The shadow tree is technically nothing more than symbolic
links to the master (non-proxy) package's files and directories. This
mechanism can save a lot of time and storage, however it should only be 
applied to packages with no global or configuration dependencies.
@


1.94
log
@Corrected english usage. Review this! It is possible that this correction
changes or reverses the original author's intended logic. If so, then change
the logic back to its correct form without using an incorrect english
construction, please.

Rule:
When only one negation (no *) follows a single conjunction (with **) and
precedes multiple adjective/noun tuples (***), it must logically belong to the
first tuple. If negations and affirmations must be mixed, then the sentence
needs contradiction words such as 'but' or 'however'.

Case in question:
...to packages with no global or configuration dependencies.
               **   *  ***       ***

Incorrect example:
The woman owns cars, boats, or no bikes.
The woman owns cars, no boats, or bikes.

Correct examples:
The woman owns no cars, boats, or bikes.
The woman owns cars, boats, but no bikes.
@
text
@d36 1
a36 1
and non-packaged software. Finally, if the admin wants a software
d69 1
a69 1
is specially extended to become more unique and self contained. The more than
d78 1
a78 1
and must be self contained within its OpenPKG instance. Furthermore, the
d97 1
a97 1
OpenPKG follows a minimal OS intrusion and maximum stand-alone approach.
d100 1
a100 1
break well known de-facto standards in order to provide a cleaner
d114 1
a114 1
by single and concise all-in-one package specifications, the RPM C<.spec>
d136 1
a136 1
determined under compile-time on the build machine. A prominent example
d180 2
a181 2
it contains its own RPM packaging management information in a sub-area
for self-containment reasons plus a local area for adding non-packaged
@


1.93
log
@OpenPKG RPM vs. RedHat RPM edited.
@
text
@d401 1
a401 1
applied to packages with global or no configuration dependencies.
@


1.92
log
@'The first time' -> 'Bootstrapping OpenPKG for the first time' edited.
@
text
@d135 1
a135 1
run-time based on settings (e.g. maximum size of shared memory segments)
d318 1
a318 1
OpenPKG RPM vs. RedHat RPM
d321 40
a360 41
As already said, OpenPKG is based on an adjusted and unique RPM-based
packaging facility which allows you to use very concise and clean
package specifications and to build I<every> package in an
unprivileged environment. What is the fuzz about this? Isn't this
the same as with any other RedHat, SuSE or Mandrake RPM package?

Let's look at an example, the OpenPKG packaging for the excellent
RSYNC program. It consists of three files: the RPM specification
(C<rsync.spec>, Listing_1), the run-commands (C<rc.rsync>, Listing_2),
and the default daemon configuration (C<rsync.conf>, Listing_3).

If you compare this to the RPM-based RSYNC packages of other vendors,
you should recognize that although this package is full-featured, it
is still very consise and clean. This is due to the use of OpenPKG's
extensions and strict style guidelines.

First, OpenPKG uses GNU shtool for portable and concise shell scripting.
For instance, all manual installation and patching is done with the
C<shtool> command. Second, there is a companion tool, C<rpmtool>,
which complements C<shtool> with RPM- and OS-specific features. This
allows for instance all OpenPKG packages to generate their file list
(C<%files>) on-the-fly and this way make the packaging information
smaller and reduces the required maintainance on vendor version updates.
Third, OpenPKG's RPM provides a set of local macros (C<%{l_xxx}>) which
abstract system specifics and also help in removing redundancy from
the packaging specifications. For instance the C<%{l_prefix}> is the
filesystem I<prefix> of the involved OpenPKG instance. This way all
packages do not have hard-coded path prefixes and hence can be build for
arbitrary OpenPKG instances.

The C<%{l_cc}> macro expands to either I<prefix>C</bin/cc> (in case the
OpenPKG C<gcc> package is installed) or defaults to just C<cc>. The
same for C<%{l_cflags -O}>: it expands to optimized C compiler flags.
In case C<gcc> is installed, it expands to "C<-O2 -pipe>", else it
defaults to just C<-O>. Similarily for C<%{l_make}> and C<%{l_mflags}>:
if C<%{l_make}> points to a known make(1) which supports parallel
building and the underlying system has more than one CPUs, C<%{l_mflags
-O}> expands to the necessary flags to leverage from SMP. For instance,
on a 2 CPU FreeBSD 4.x machine with BSD make, C<%{l_mflags -O}> expands
to C<-j4 -B> while on a 4 CPU Linux machine with GNU make, C<%{l_mflags
-O}> expands to C<--no-print-directory -j8>.
d363 38
a400 43
this example shows, i.e., everything is fixed: the order of headers, the
indentations, etc. This allows the developers to easily query and even
semi-automatically edit package informations directly from the source.
For example, the indices on the FTP server are autogenerated this way
and the release engineering procedures were mostly automated.

I<Every> OpenPKG package is able to build in a fully unprivileged
(non-root user) environment and with read-only access to an OpenPKG
instance. This allows safe (no development system intrusion) and
precise packaging (no trash or missing files). This is achieved by
consistently enforcing and using the C<BuildRoot> feature of RPM
for all packages. In short, this means that for rolling a binary
package, the software is redirected to install into a shadow area
(I<prefix>C</RPM/TMP/>I<pkg-name>C<-root/>I<prefix>) and then packaged
from there as it would have been installed in the real filesystem
location (I<prefix>). 

This is a very important step and sounds trivial to achieve, but
actually is one of the trickiest parts in packaging a software for
OpenPKG. Sometimes (as in the case of RSYNC) it is just a matter of
overriding variables (C<prefix> in the example) on the C<make install>
step, but sometimes it gets really hairy. For some OpenPKG packages it
required a lot of effort to find a reasonable way to redirect the vendor
installation procedure to the C<BuildRoot> area. But it is worth the
effort, because this results in safe and precise packaging.

Finally, another feature which is provided by OpenPKG's RPM environment:
using proxy packages. This is a tricky mechanism of reusing packages
in a master OpenPKG instance from multiple slave instances in order to
avoid the necessity of having to build and maintain the package there,
too. A classical example is C<gcc>, because this package is often
required by other packages under build-time, but if you have multiple
OpenPKG instances on a single machine, you want to avoid having to build
and install C<gcc> into each instance individually. 

Instead you can build it once for a master instance, then create proxy
versions for all other instances by running I<slave-prefix>C</bin/rpm
--makeproxy> on the binary RPM from the master instance. The result are
other binary RPMs which consist of a shadow tree for the slave instance
resembling the contents of the master instance. Technically speaking
this means that it consists of the same directory structure, but with
all contained files replaced by symbolic links. Keep in mind that
although this mechanism safes lots of time, it can be only reasonably
d452 1
a452 1
the security update branch of the last public OpenPKG release.  OpenPKG-STABLE
d507 1
a507 1
others. For faster run-time program manipulation, an enhanced run-command
d535 2
a536 2
mod_ssl, GNU Pth and GNU Shtool and the founder of Open Source
software projects like OpenSSL, OpenPKG and OSSP. He can be contacted at:
@


1.91
log
@Changed almost all instances of 'administrator' to 'admin' because the
magazine is called 'Sysadmin'. This is a questionable committal, because some
might think that 'administrator' sounds more professional.
@
text
@d141 2
a142 2
The first time
--------------
d144 8
a151 7
The bootstrapping process is wrapped into a shell script that
initially creates a new instance of OpenPKG on a machine. While it is
as much self-contained as possible it requires a minimum amount of
operating system support and tools to unpack and compile itself. 
Basically this means you need C<tar>, C<make> and C<cc> in your C<$PATH>.
The absence of those development tools is the number one reason
to start over with binary packages first.
d153 11
a163 10
You dedicate a filesystem prefix to every instance along
with user and group. The generic bootstrap script called
C<openpkg->I<version>C<->I<release>C<.src.sh> requires these as
arguments and creates a platform specific bootstrap script named
C<openpkg->I<version>C<->I<release>C<.>I<arch>C<->I<os>C<->I<id>C<.sh>
which in turn installs the OpenPKG instance under the specified prefix
with all files owned by the user and group (Figure_2). This installation
process linked the OpenPKG instance with the underlying Unix system with
a few anchoring points only. Subsequent package installations will not
touch the system at all.
d165 4
a168 4
The bootstrap registers itself in the new hierarchy as the package
C<openpkg>. This way it can be upgraded like any other package. You
might notice that for this C<.rpm> versions of the bootstrap package
exist as well.
d170 3
a172 4
A step by step example of a complete test installation and
deinstallation of an OpenPKG instance with a contained RSYNC server is
given in Listing_4. To understand the involved RPM commands used, see
the quick reference in Table_4.
@


1.90
log
@I decided that [styled] was a really stupid label, so I replaced this scheme
with [edited]. It should be clearer what is ready to go now.
@
text
@d14 1
a14 1
location for these files. After the search finishes, an administrator must
d22 1
a22 1
If the previous operation succeeds after all, the administrator might be left
d27 1
a27 1
with the administrator to implement logfile rotation himself? Such redundant
d30 1
a30 1
What can an administrator do when facing obstacles like these? He might start
d36 1
a36 1
and non-packaged software. Finally, if the administrator wants a software
d65 1
a65 1
system administrators faced with a large and diverse set of Unix servers.
d413 1
a413 1
administrator, you can try to package it yourself for local purposes and
@


1.89
log
@Cross-platform Unix software packaging with OpenPKG edited.
@
text
@d5 1
a5 1
Cross-platform Unix software packaging with OpenPKG [styled]
d42 1
a42 1
OpenPKG to the rescue [styled]
d441 1
a441 1
Release engineering [styled]
d484 1
a484 1
Conclusion [styled]
d534 1
a534 1
About the authors [styled]
d795 1
a795 1
Table_3: OpenPKG summary [styled]
@


1.88
log
@use a single sentence here because I think it reads more round
@
text
@d5 1
a5 1
Cross-platform Unix software packaging with OpenPKG
d8 13
a20 3
You prefer Open Source software for well known reasons. But when you
try applying it manually to your real life environment you sometimes
discover the downside of open and distributed development.
d22 7
a28 15
First, you have to locate the latest application version on the Internet
and collect its most recent patches covering important security fixes.
Why isn't there a single location? Then bring it all together and build
and install it on every Unix box in your network just to find out the
application needs some slightly different tweaking on each to build and
run. Is this really the administrators job? If the application is a
daemon, you quickly get bothered because every Unix flavour has its own
custom method of starting and stopping them. Why was this never unified?
If you finally succeeded, you are wondering why it was necessary to
clutter up your whole system with all the installation files. How to the
hell do the vendors think this can ever be removed? Finally, after one
month of operation, you have to discover that your C</var> filesystem
runs out of disk space because the application log files filled it
up entirely. Does the administrator really have to reinvent logfile
rotation himself?
d30 11
a40 11
Now you learned your lession and next time try to stick with vendor
packages only. Unfortunately you have lots of different Unix flavors
to administrate, hence faced with different packaging mechanism. Even
worse, if you think about testing situations or separated project
environments, no vendor packaging facility supports installation of
an application multiple times. Or provides reasonable support for
installing packaged and non-packaged software side-by-side? Finally,
wouldn't it be nice to have a software installation and configuration
guide for your vacation replacement which equally can be applied across
all Unix platforms? Usually impossible, because every vendor packaging
mechanism is different.
@


1.87
log
@'OpenPKG to the rescue' and 'Release engineering' edited.
@
text
@d538 2
a539 2
mod_ssl, GNU Pth and GNU Shtool. He also founded the Open Source
software projects OpenSSL, OpenPKG and OSSP. He can be contacted at:
@


1.86
log
@Conclusion further improved.
@
text
@d40 1
a40 1
OpenPKG to the rescue
d46 1
a46 1
development effort managed and maintained by many individuals. The project
d50 41
a90 32
Daily operation at an ISP demands unification of the installation
and maintainance of software packages across the three major Unix
platforms FreeBSD, Linux and Solaris -- but OpenPKG is no longer
limited to just these as summarized in Table_1. To achieve this goal it
provides a cross-platform subsystem on top of the underlying Unix system
(Figure_1). It covers every essential server software component --
ranging from shells, over editors and compilers, up to network daemons
and add-on applications. Hence, the intended target community currently
are system administrators faced with a large and diverse set of Unix
servers.

The leveraged packaging technology is based on the popular RedHat
Package Manager (RPM), with additional extensions and add-ons which
complement it into a unique self-contained packaging facility. On top
of this you can install over 300 individual OpenPKG RPM packages. All
of them were developed from scratch in a clean-room approach, following
strict style guidelines and environment requirements.

For instance, a package has to be buildable from pristine vendor sources
in a non-root temporary environment, has to work in an arbitrary
filesystem location, has to follow a strict filesystem layout, has to
be self-contained within its OpenPKG instance, has to be independent
from external Unix facilities, has to install with a reasonable and
ready-to-go pre-configuration, has to use logfile rotations, etc.

As a result, OpenPKG allows you to install subsystem instances under
arbitrary filesystem prefixes and even multiple times on a single Unix
system. For instance, the OpenPKG project environment is hosted on a
machine with six other projects and each one has its own dedicated
OpenPKG instance containing every required software component -- from
Postfix, over BIND to INN and Apache. This way each project runs in its
own isolated environment, much like on a virtual machine.
d439 1
a439 1
Release engineering
d442 20
a461 20
The OpenPKG project results are not only available as Open Source,
the project is also driven in an open and transparent way. First, all
sources (package specifications, source patches, website sources, the
handbook, this article, etc) are located in a publically readable
central CVS repository. This can be even browsed through the website by
anyone who is interested. Additionally, all developer commits to this
repository are tracked and summarized with postings to a public mailing
list and public newsgroups. This way people can easily follow all
development steps.

For stability and conflict-free development reasons there are always
three release branches (which technically directly map to CVS branches) of
OpenPKG available at any time: OpenPKG-SOLID, OpenPKG-STABLE and
OpenPKG-CURRENT. The first is the security update branch of the
latest release version, the second is the stable branch from which
the next release version is made, and the third is the current state of
the development branch. The branch from which a package was built
can be easily determined, because the OpenPKG RPM files follow a
consistent naming scheme: I<pkg-name>C<->I<version>C<->I<YYYYMMDD> (CURRENT),
I<pkg-name>C<->I<version>C<->I<N>C<.>I<YYYYMMDD> (I<N>-STABLE),
d463 18
a480 16
I<pkg-name>C<->I<version>C<->I<N>C<.>I<M>C<.>I<X> (I<N.M.X>-SOLID).

The OpenPKG developer team is very fast in keeping OpenPKG-CURRENT
packages up-to-date with the latest vendor versions. This is due to the
fact that all externally available vendor sources are automatically
version tracked on a daily basis. This way an OpenPKG package for a
new software version is often available before the software was even
announced on Freshmeat.net.

Finally, OpenPKG takes security very seriously. Experience has shown
that "security through obscurity" does not work. Public disclosure
allows for more rapid and better solutions to security problems. In that
vein, OpenPKG tries to as fast as possible provide fixed packages for
releases after a vulnerability was discovered and notifies the community
by publishing official Security Advisories. The website has more details
on the whole release engineering process.
@


1.85
log
@annotate with my job, triggered by my boss ;)
@
text
@d482 5
a486 6
OpenPKG's first historical achievement occurred in April 2001 when it was
first used in a production environment of a large ISP, namely Cable & Wireless
Deutschland. Some 220 packages were available in January 2002 when OpenPKG was
released to the public as a mature product, and the number of available
packages reached 300 a few months later. The project is continuously improved
by a diverse team of developers who also daily update and add packages.
d490 2
a491 2
OpenPKG users will find it deceivingly simple to build a basic package. Those
interested in doing so can use the RSYNC example in this article as a
@


1.84
log
@rc.d/ vs. rc.conf being config files or not
@
text
@d526 5
a530 4
hacker, living in Munich, Germany. He is the author of well-known
software like Apache mod_ssl, GNU Pth and GNU Shtool. He also
founded the Open Source software projects OpenSSL, OpenPKG and OSSP.
He can be contacted at: rse@@engelschall.com
@


1.83
log
@Conclusion styled.
@
text
@d260 3
a262 2
to execute the script with the realm of I<user>. Note there are some
sections with special meaning. The C<%common> section has the function
d266 2
a267 2
The C<%config> section contains variables which can be used to configure
the behavior of other sections in a per-package context. Variables can
d279 6
a284 1
Regarding configuration through variables, it should be mentioned
@


1.82
log
@Sorry, I want to veto, Michael: I _AM_ a computer scientist and do not
just _WORK_ as one ;) So lets stick with the old variant of the first
sentence.
@
text
@d465 1
a465 1
Conclusion
d468 7
a474 7
When the OpenPKG project was born in November 2000, the hardest work
after deciding to use RPM was the creation of the bootstrap process. The
first use in a production environment was in April 2001 at the hosting center
of a large ISP. Some 220 packages have already been created when OpenPKG
was released to the public in January 2002 as a mature product with 167
packages included. The project is continuously improved and packages are
updated and added daily. 
d476 6
a481 3
Building packages on your own is not as difficult as you might think.
You can start with the shown RSYNC example as the blueprint for your new
package. Your package contribution is much appreciated.
d483 15
a497 7
Currently work is underway on a frontend which will simplify the
installation process and handle build- and install-dependencies fully
automatically. We also plan to expand OpenPKG to reach out to the
desktop with the first X11-dependent packages already in place. There
is also ongoing development on a further enhanced run-command facility.
Shared library support is under investigation, too. Last but not least
we are looking forward to upgrade to the forthcoming RPM 4.1 version.
@


1.81
log
@About the authors styled.
@
text
@d508 5
a512 5
Ralf S. Engelschall works as a computer scientist and Open Source software
hacker in Munich, Germany. He is the author of well-known software like Apache
mod_ssl, GNU Pth, GNU Shtool. Ralf also founded the Open Source software
projects known as OpenSSL, OpenPKG and OSSP. He can be contacted at:
rse@@engelschall.com
@


1.80
log
@Consistent capitalization in titles and undertitles.
@
text
@d505 1
a505 1
About the authors
d508 5
a512 5
Ralf S. Engelschall is a computer scientist and Open Source software
hacker, living in Munich, Germany. He is the author of well-known
software like Apache mod_ssl, GNU Pth, GNU Shtool. He is also the
founder of the Open Source software projects OpenSSL, OpenPKG and OSSP.
He can be contacted at: rse@@engelschall.com
d514 6
a519 6
Thomas Lotterer is a network professional and consultant working as Unix
software developer at Cable & Wireless Germany. Previously working as
system administrator and technical trainer, he has years of experience
in cross-platform system integration and software distribution. He
works actively on the OpenPKG and OSSP projects.
He can be contacted at: thomas@@lotterer.net
d521 6
a526 7
Christoph Schug is senior Unix system administrator at Cable & Wireless
Germany. Leading the hosting department he is responsible for all
managed servers at the Munich data center. When not just having
revolutionary ideas and visions which often result in some lines in
Ralf's TODO file you can encounter him in the Alps with screaming and
smoking tires of his Miata MX-5 roadster :)
He can be contacted at: chris@@schug.net
@


1.79
log
@OpenPKG summary styled.
@
text
@d5 1
a5 1
Cross-Platform Unix Software Packaging with OpenPKG
d162 1
a162 1
Filesystem Layout
d505 1
a505 1
About the Authors
d532 1
a532 1
Table_1: OpenPKG Unix Platform Support
d551 1
a551 1
Figure_1: The OpenPKG Subsystem Principle
d556 1
a556 1
Figure_2: The OpenPKG Filesystem Layout
d766 1
a766 1
Table_3: OpenPKG Summary [styled]
@


1.78
log
@Testing the water (ooh it is cold.)
@
text
@d766 1
a766 1
Table_3: OpenPKG Summary
d771 2
a772 2
- Minimal OS intrusion only
- Fully self-contained, minimum OS dependencies
d774 1
a774 1
- Based on RPM 4 with custom extensions
d776 2
a777 2
- Dependencies for build- and run-time
- Focuses on building software from pristine vendor sources
d779 6
a784 6
- Clean, consise, non-redundant specifications following strict style
- Support for integrating unpackaged software into the environment
- Tricky bootstrapping with no requirement for pre-installed RPM
- Strict and consistent filesystem layout across all packages
- All packages are installed with reasonable preconfiguration
- Users benefits from built-in packager's knowledge
d789 2
a790 2
- Allows multiple instances on the same Unix system
- Fully uninstallable packages
d794 1
a794 1
- Currently over 300 packages available
@


1.77
log
@strip down and polish
@
text
@d40 2
a41 2
OpenPKG comes to the rescue
---------------------------
d43 6
a48 6
OpenPKG is an Open Source software project, initiated in November
2000 by Cable & Wireless Deutschland, part of a leading international
Internet Service Provider (ISP). The project is jointly managed by a
group of individuals and is a collaborative software development and
packaging effort aimed at creating a modular and flexible cross-platform
Unix subsystem.
d855 1
a855 1
       be NOT integrated into Figure_2 (THL & RSE)
d912 1
a912 1
$ <prefix>/bin/rpm --checksig <pkg-rpm>          verify integrity and origin of package
@


1.76
log
@more polishing
@
text
@d814 2
a815 1
user$ sh openpkg-1.1.0-1.1.0.src.sh --prefix=/usr/opkg --user=opkg --group=opkg
d819 2
a820 1
opkg$ /usr/opkg/bin/rpm --rebuild ftp://ftp.openpkg.org/release/1.1/SRC/rsync-2.5.5-1.1.0.src.rpm
d822 1
a822 1
root# /usr/opkg/bin/rpm -Uvh /usr/opkg/RPM/PKG/rsync-2.5.5-1.1.0.*-uo.rpm
d930 3
a932 3
        <pkg-rpm>  e.g. rsync-2.5.4-1.1.0.*.rpm
        <pkg-src>  e.g. rsync-2.5.4-1.1.0.src.rpm
        <pkg-bin>  e.g. rsync-2.5.4-1.1.0.ix86-freebsd4.5-uo.rpm
@


1.75
log
@try to finalize the text
@
text
@d227 3
d515 1
a515 1
software developer at Cable & Wireless Germany.  Previously working as
d517 1
a517 1
in cross-platform system integration and software distribution.  He
d521 4
a524 4
Christoph Schug is senior unix system administrator at Cable & Wireless
Germany. Leading the hosting department he is responsible for all managed
servers at Cable & Wireless Munich data center. When not just having
revolutionary ideas and visions which often result in /some/ lines in
a763 6

In other words, OpenPKG's RPM does the intuitive right thing by making
sure that a changed configuration file is kept in place if possible and
if not possible, it is at least preserved for manual consideration. So
config file changes in <prefix>/etc/<pkg-name>/ are never lost and most
of the time not even have to be upgraded manually.
d771 2
a772 2
- Minimal OS intrusion, only passwd, group, shells, crontab, PAM
- Fully self contained, minimum OS dependencies
d776 1
a776 1
- Dependencies for build and runtime
d778 3
a780 3
- RPM package specifications written from scratch
- Clean, consise, non-redundandant specs following strict style
- Support for lsyncing unpackaged software into the environment
d784 2
a785 2
- Users benefit from built-in porting knowledge
- Signed packages
d787 6
a792 5
- Support for unpriviledged user
- Arbitrary prefix allows multiple instances on the same Unix system
- Uninstallable packages
- Powerful queries
- Flexible Run-command facility
d852 2
a853 1
       to consume less size and be even more compact.
@


1.74
log
@one more issue
@
text
@a7 2
FIXME!

d12 11
a22 9
First, you have to locate the latest application version 
on the Internet and collect its most recent patches covering important
security fixes. Then bring it all together and build and install it
on every Unix box in your network just to find out the application
needs some slightly different tweaking on each to build and run. If the
application is a daemon, you quickly get bothered because every Unix
flavour has its own custom method of starting and stopping them. If you
finally succeeded, you are wondering why it was necessary to clutter up
your whole system with all the installation files. Finally, after one
d24 3
a26 2
runs out of disk space because the application log files are never
rotated. Doesn't this sound familiar to you?
@


1.73
log
@flush even more work
@
text
@d106 8
@


1.72
log
@flush more work
@
text
@d453 1
a453 1
Conclusion [thl]
d458 5
a462 6
first use in a production environment was April 2001 at a large ISP
site. Some 220 packages have already been created when OpenPKG was
released to the public in January 2002 as a mature product with 167
packages included. The successful project is continuously improved and
packages are updated and added daily. Your contribution is much
appreciated!
d464 3
a466 13
Currently work is underway on a frontend which should simplify the
installation process and handle build- and install-dependencies
automatically. It reads RPM information from RDF files and the
user interface and installation backend will communicate through a
client/server architecture to allow distributed management of OpenPKG
instances. We plan to expand OpenPKG packages to reach out to the
desktop with the first X11-dependent packages already in place. Some
packages will be split into smaller, independent pieces for rapid
deployment. We're already working on a run-command facility written in
C which should replace the current shell script implementation. Shared
library support is under investigation. Last but not least, we work
closer with RedHat than ever and are looking forward to absorb their
forthcoming v4.0.4 and v4.1 releases of RPM.
d468 7
a474 5
###
Building packages on your own is not as difficult as you might think.
And of course we are always open for your contribution to the project.
you might think of it being the
blueprint of a package.
@


1.71
log
@more work, more work, ...
@
text
@d412 1
a412 1
Release engineering [rse]
d421 3
a423 3
CVS are tracked and summarized with postings to a public mailing list
(U<mailto:openpkg-cvs@@openpkg.org>). This way people can easily follow
all development steps.
d425 2
a426 2
For stability and conflict-free development reasons, there are always
three branches (which technically directly map to CVS branches) of
d430 1
a430 1
release version are made, and the third is the current state of
d433 4
a436 3
consistent naming scheme: C<foo->I<V>C<->I<YYYYMMDD> (CURRENT),
C<foo->I<V>C<->I<N.YYYYMMDD> (STABLE), C<foo->I<V>C<->I<N.M>C<.0>
(RELEASE), C<foo->I<V>C<->I<N.M.X> (SOLID).
d443 1
a443 1
announced on Freshmeat.
d448 4
a451 5
vein, OpenPKG tries to as fast as possible provide fixed packages after
a vulnerability was discovered and notified the community by publishing
official Security Advisories.

The website has more details on the whole release engineering process.
@


1.70
log
@remove tag for English Police ;)
@
text
@d379 2
a380 2
Building a package [cs]
------------------
d382 29
a410 57
Building packages on your own is not as difficult as you might think.
And of course we are always open for your contribution to the project.
First of all take a second or two and make yourself familiar with to
structure of a so called C<.spec> file (Listing_1), you might think of it being the
blueprint of a package. If you are familiar with Unix development most
of the sections should be obvious or you should a least have an idea
how it might work. Going into detail there are some features of RPM
to make life easier as variables like C<%{version}> do which are automatically
set according to the C<Version:> field helping you to avoid redundancy. 

One of the most important parts is the one headlined by "build
information". This section describes package prerequisites and conflicts
for both build and run time. There are also some magic macros like
C<%setup> which support you uncompressing source tarballs but there are
also others not mentioned here, e.g. to apply patches. Nevertheless
you should spend some time reading documentation (FIXME reference to
Maximum RPM and alike). Don't hesitate to take a look at existing
C<.spec> files cause many typical packaging problems have already been
worked around. One of the hardest thing while packaging software is to
convince to original install mechanism not to put all the stuff to its
final destination but to relocate it to temporary location specified
by C<$RPM_BUILD_ROOT>. On this location a file list is generated by
C<rpmtool> which specifies the content of the package.

FIXME: should we *realy* describe *everything* right here step by step?
       I think there is enough said for "Ottonormalverbraucher" and we
       should reference to our web site.

Let's face reality [cs]
------------------

Not always is it desirable to package a piece of software
if you are quite sure you will never ever use it on another box. Even for this
rare case OpenPKG offers some goodies to keep thing clean and separated.
Under C</sw/local> you will find a hierarchy with all the directories
you are familiar with like C<bin>, C<include>, C<lib>, C<man> and so on. But
instead of messing up all over again it is designated to install software
into separate and dedicated directories under
I<prefix/>C<local/PKG/>I<name>C<->I<version>. This way it is possible to install
different versions of the same software in parallel. To choose which version
to use simply add a symbolic link pointing to the one you want, for example
I<prefix/>C<local/PKG/foo> pointing to I<prefix/>C<local/PKG/foo-3.27>. 

In order to active everything simply invoke C<lsync> which will scan
the I<prefix/>C<local/PKG> for directory entries without version numbering. After
that all programs, man pages and other stuff will be symlinked under
I<prefix/>C<local/bin>, I<prefix/>C<local/man> and so on (Figure FIXME). This
implies that all the pieces of software have got their own C<bin>,
C<man>, etc. Very often you can accomplish that by configuring a piece
of software using C<configure --prefix=>I<prefix/>C<local/PKG/foo-3.27>. See
Listing_5 "Installation of non-OpenPKG software" for a more detailed example. If you consider some day
to upgrade to C<foo-3.30> just repeat installation in the same way,
alter symlink C<foo> to make it point to C<foo-3.30> and re-run C<lsync>
again. C<lsync> will automatically update symlinks upon activation, creating new links
if required and remove outdated dangling ones. As you might already
guess it is easy to go back to the old version if the new one keeps
dumping core all the time. This is left as an excercise for the reader.
d479 6
d837 7
a843 11
$ mkdir -p <prefix>/local/PKG/foo-3.27/SRC
$ cd <prefix>/local/PKG/foo-3.27/SRC
$ wget ftp://ftp.foo.net/download/foo-3.27.tar.gz
$ tar -xvzf foo-3.27.tar.gz
foo-3.37/
foo-3.37/INSTALL
foo-3.37/README
foo-3.37/Makefile
[...]
$ cd foo-3.37
$ ./configure --prefix=<prefix>/local/PKG/foo-3.27 --enable-bla
d846 3
a848 3
$ cd <prefix>/local/PKG
$ ln -s foo-3.27 foo
$ lsync
@


1.69
log
@more work for our English Police ;)
@
text
@d288 1
a288 1
OpenPKG RPM vs. RedHat RPM [rse]
@


1.68
log
@flush more work from RSE and THL of this day
@
text
@d298 3
a300 4
I<rsync> program by Andrew Tridgell and Paul Mackerras. It consists
of three files: the RPM specification (C<rsync.spec>, Listing_1),
the run-commands (C<rc.rsync>, Listing_2), and the default daemon
configuration (C<rsync.conf>, Listing_3).
d302 1
a302 1
If you compare this to the RPM-based rsync packages of other vendors,
d304 2
a305 2
is both very consise and clean. This is due to the use of
OpenPKG's extensions and strict style guidelines.
d308 7
a314 7
For instance all manual installation and patching is done with shtool.
Second, there is a companion program, rpmtool, which complements
shtool with RPM- and OS-specific features. This allows for instance
all OpenPKG packages to generate their file list (C<%files>)
on the fly and this way make the packaging information smaller and
reduces the required maintainance on vendor version updates. Third,
OpenPKG' RPM provides a set of local macros (C<%{l_xxx}>) which
d316 10
a325 11
the packaging specifications. For instance the C<%{l_prefix}>
is the filesystem prefix of the involved OpenPKG instance. This
way all packages do not have hard-coded path prefixes and hence
can be build for arbitrary OpenPKG instances.

The C<%{l_cc}> macro expands to either
I<prefix>C</bin/cc> (in case the OpenPKG "gcc" package
is installed) or falls back to just C<cc>. The same for
C<%{l_cflags -O}>: it expands to optimized C compiler flags. In
case of gcc it expands to C<-O2 -pipe>, else it falls back to
just C<-O>. Similar for C<%{l_make}> C<%{l_mflags}>:
d327 21
a347 22
building and the underlying system has more than 1 CPU, C<%{l_mflags
-O}> expands to the necessary flags to leverage from SMP. For
instance, on a 2 CPU FreeBSD 4.x machine with BSD make, C<%{l_mflags
-O}> expands to C<-j4 -B>, on a 4 CPU Linux machine with
GNU make, C<%{l_mflags -O}> expands to C<--no-print-directory
-j8>.

Additionally, all OpenPKG packages follow I<exactly> the same
style as this example shows, i.e., everything is fixed: the order of
headers, the indentations, etc. This allows the developers to easily
query and even semi-automatic edit package informations directly from
the source. For example, the indices on the FTP server are autogenerated
this way and the release engineering procedures were mostly
automatized.

I<Every> OpenPKG package is able to build in a fully
unprivileged (non-root user) environment and with read-only access /*FIXME this is different from what thl currenly writes*/ to
an OpenPKG instance. This allows safe (no development system intrusion)
and precise packaging (no trash or missing files). This is achieved by
consistently enforcing and using the "BuildRoot" feature of RPM for all
packages. In short this means that for rolling a binary package, the
software is redirected to install in a shadow area and then packages
d349 20
a368 18
location of the OpenPKG instance. This is a very important step and
sounds trivial to achieve, but actually is one of the trickiest parts in
packaging a software for OpenPKG. Sometimes (as in this "rsync" example)
it is just a matter of overriding Make variables (C<prefix> in the
example) on the C<make install> step, but sometimes it gets hairy.
For some OpenPKG packages it costed a lot of time to find a reasonable
way to redirect the vendor installation procedure to the BuildRoot
area. But it is worth the effort, because results in safe and precise
packaging.

Finally, another feature which is provided by OpenPKG's RPM environment
to package developers: making proxy packages. This is a tricky mechanism
of reusing packages in a master OpenPKG instance from multiple slave
instances in order to avoid the necessity of having to build and
maintain the package there, too. A classical example is "gcc": this
package is often required by other packages under build time, but if
you have multiple OpenPKG instances on a single machine you want to
avoid having to build and install "gcc" into each instance individually.
d370 8
a377 6
versions for all other instances by running C<rpm --makeproxy>
on the binary RPM for the master instance. The result are other binary
RPMs which consist of a shadow tree in the slave instance resembling the
contents of the master instance. In detail is means that it consists of
the same directory structure, but with all contained files replaced by
symbolic links.
@


1.67
log
@flush RSE and THL work of this forenoon
@
text
@d166 4
a169 4
structure the usual mess with the large amount of those files. Every
package was forced to fully conform to this layout, although for some
packages it required lots of effort to override the different vendor
package intentions.
d177 2
a178 2
Applying a package [thl]
------------------
d180 47
a226 51
To build a binary package from source with C<.spec> defaults
use C<rpm --rebuild >I<pkg-src>. By default this places files
into subdirectories of I<prefix>C</RPM/>, therefore you need
write access to those by being a member of the related OpenPKG
group, login as the OpenPKG instance user itself or login as root.
Alternatively, you can create a C<~/.rpmmacros> file and redirect
the paths to your own locations (see default macros C<%_sourcedir>,
C<%_specdir>, C<%_builddir>, C<%_tmppath>, C<%_rpmdir>, C<%_srcrpmdir>
in I<prefix>C</etc/openpkg/rpmmacros>).

To alter the C<.spec> defaults
unpack the source using rpm -Uvh I<package>. This will "install"
aka unpack the source into C<%{l_prefix}/RPM/SRC/>I<package>C</>. This
is the place to edit the I<package>.spec file and then use rpm -bb
I<package>.spec to build the binary and place it into the same location
as a rebuild would have done. Introduced with version FIXME and
incorporated into OpenPKG v1.1 is a feature to define a variable along
with the rebuild process using C<--define> "I<variable> I<value>". This
affects the rebuild process without breaking it in two parts and editing
the C<.spec> file.

To install a binary package just use C<rpm -Uvh >I<package>.
Strictly speaking this upgrades a package and installation is just the
special case of upgrading from nothing. RPM is very clever when it comes to
keeping or sweeping configuration settings during an upgrade, as shown
in Table_2 "RPM handling of config files". If you sticked with
defaults and defaults remain the same or if you changed the same
settings to the same values as the author of the new package did or the
default didn't change then chances are you would change the same values
back again so the old config is kept. 

If you sticked with defaults and defaults changed RPM installs the new
config. If the defaults and with them possibly the structure changed so
it's better to verify changes manually then RPM installs the new config
and saves yours with extension C<.rpmsave>. If no previous defaults existed
at all but the new package provides some then it's better to integrate your
settings manually, so RPM installs the new config and saves yours with extension
C<.rpmorig>. To make this work properly, a package has to tag
configuration files and this has been done for all OpenPKG packages.

The output of C<rpm -qa> gives you a list of installed packages and
C<rpm -qi >I<package> lists detailed information about a installed
package. Configuration files for a given package can always be
found in C<%{l_prefix}/etc>I<package> and variable data like logfiles always
go into C<%{l_prefix}/var>I<package>. Packages have been rigorously forced
to conform to that specification. For a step by step example see
U<http://www.openpkg.org/tutorial.html>. You can also check a package's
integrity at any time using C<rpm -V> I<package> and verify which files
have been tampered with. Another useful query is C<rpm -qf>
I</full/path/to/a/file> which tells you to which package the given file
belongs.
d228 1
a228 1
Run-command facility [thl]
d231 2
a232 3
In the previous "Getting started" section we mentioned 
in Listing_4. If you worked it out you might have noticed the
server was started using the command C</usr/opkg/etc/rc bind start>.
d234 53
a286 53
run-command facility, executed with C<%{l_prefix}/etc/rc> which is
currently a shell script. Run-commands for every package are stored in
C<%{l_prefix}/etc/rc.d/rc.>I<package>, a collection of shell scripts in
a single file organized by sections which are identified by left-aligned
labels prefixed with a 'C<%>'. Have a look at the C<rc.rsync>, Listing_2
and enjoy.

The C<rc> command takes a I<package> name as the first argument and
one or more I<section> labels as additional arguments. The scripts are
then extracted from the C<rc.>I<package> file and executed in the order
given. The reserved package name "all" refers to executing the given
section(s) for all packages. Order is determined by the priority given
at a section label using C<-p> I<number> construct where small numbers
are executed first. Another option available to the section label is
C<-u> I<user> which causes C<rc> to execute the script with the realm
of I<user>. Note there are some sections with special meaning. The
C<%common> section has the function of a library and contains code
useful to many or all of the other sections. It is included in every
script before it is run. The C<%config> section contains variables which
can be used to configure the behavior of every section in a per-package
context.

Variables can also be placed into C<%{l_prefix}/etc/rc.conf> in
a per-hierarchy scope. The complete script executed by C<rc> is
assembled from C<%config> section, wholly C<%{l_prefix}/etc/rc.conf>
file, C<%common> section and the actual section given at the C<rc>
command line, in that order. Sections labeled C<%monthly>, C<%weekly>,
C<%daily>, C<%hourly> and C<%quarterly> are also special as the
bootstrap sets up cron jobs to execute them accordingly. Another
label often seen is C<%env> which is intended to be used with the
C<--eval> option explained below. Regarding configuration through
variables it should be mentioned that all scripts ship with a variable
I<package>C<_enable="yes"> which, when turned into "no" will disable the
start of the package's daemons at system startup time. Back to the BIND
example this can be useful if you installed the package
just to get the C<nslookup> and related utilities and don't care about
the server.

Introduced with OpenPKG 20020205 and available in v1.1 is a
feature to disable the automatic startup of all servers in a hierarchy
by adding a C<openpkg_ignall="yes"> to C<rc.conf>. However, all daemons
can still be started manually.

The run-command facility has other
features as well. Use C<rc --query> I<variable> to see the status of any
configured variable or run C<rc --config> to see a complete list of all
available variables, their defaults and currently effective values. Last
but not least the run-command facility offers a very handy feature to
modify your shell environment to include a hierarchies' PATH, MANPATH,
INFOPATH etc. Just execute C<rc --eval all env> and it creates a shell
script for you which can adjust your environment. Run it directly in
your shell using C<eval> and place the previously listed command in
backticks.
d934 1
@


1.66
log
@OpenPKG v1.0 did not fully support Sun Solaris 2.7
@
text
@d8 1
a8 2
(entry/hanger) [thl]
--------------
d11 27
a37 22
tried applying it to your real life environment you discovered the
downside of open and distributed development. First find the latest
version on the Internet, then collect the most recent patches covering
important security fixes. Bring it all together and build and install it
on every Unix box in your network just to find out the application needs
some different tweaking on each platform to make it build and run. Even
worse, if the software runs as a daemon you quickly get bothered because
every Unix flavour has its own custom method of starting and stopping
them.

Did you ever try to install BIND having tough time constraints
then blew up your machine? Desperately tried to run two completely
independent sendmails and postfix on the same box? Wouldn't it be nice
to install an additional apache for testing a new module without
touching the existing live installation? Saw a patch to a recent
security flaw and wanted to apply it to the different Unix flavours
running at your site? Wouldn't it be nice to write a installation and
configuration guide for your vacation replacement which equally works on
FreeBSD, Linux and Solaris? Just installed an application and wondered
why it cluttered up your C</etc> with config files? Successfully
installed a network daemon but a week later the C</var> filesystem
runs out of space because a logfile was never rotated?
d39 1
a39 1
OpenPKG comes to the rescue [rse]
d42 17
a58 15
OpenPKG is a Open Source software project, initiated in November
2000 by Cable & Wireless Deutschland, a leading international Internet Solution Provider. It is
a collaborative software development and packaging effort aimed at
creating a modular and flexible cross-platform Unix subsystem. The
project is jointly managed by a group of individuals.

The hosting team demanded unification of the installation and
maintainance of software packages across the three major Unix platforms
FreeBSD, Linux and Solaris -- but OpenPKG is no longer limited to just these
(see Table 1). To achieve this goal it provides a cross-platform subsystem on top
of the underlying Unix system, covering every essential server software
component -- ranging from shells, over editors and compilers, up to
network daemons and Web applications (see Figure 1). Hence, the intended
target community currently are system administrators faced with a large
and diverse set of Unix servers.
d61 12
a72 14
Package Manager (RPM), with additional extensions (rpmtool, shtool) and
add-ons (lsync, rc) which complement it into a unique self-contained
packaging facility. On top of this construct you can install over 300 individual
OpenPKG RPM packages. All these packages were developed from scratch in
a clean-room approach, following strict style guidelines and environment
requirements. 

For instance, a package has to be buildable for arbitrary filesystem
locations, has to be self-contained within its OpenPKG instance, has
to be independent from external Unix facilities, has to install with
a reasonable and ready-to-go pre-configuration, has to use logfile
rotations, has to be buildable from pristine vendor sources, has to
follow a strict filesystem layout, has to build as non-root in
a temporary environment, etc.
d77 4
a80 3
machine with 6 other projects and each one has its own dedicated OpenPKG
instance containing every required software component -- from
Postfix, over BIND to INN and Apache.
d82 1
a82 1
Covering whole package lifecycle [rse]
d85 5
a89 6
OpenPKG follows a minimal OS intrusion
and maximal stand-alone and self-containing approach. It especially
tries hard to smooth out the differences between the approaches of
the underlying vendor solutions. Sometimes this means that it
has to break well known de-facto standards in order to provide a
cleaner solution. This is the only reasonable approach leading to a consistent
d92 34
a125 47
The main question asked is why OpenPKG has chosen RPM as the underlying
packaging technology over alternatives, with the most prominent being Debian's
dpkg+apt, FreeBSD ports+pkg_xxx, SystemV pkgxxx? The reason is that,
although RPM is not a complete solution, with the OpenPKG extensions added, it covers
the I<whole> lifecycle of a package. This
starts by fetching, unpacking, patching and building from the pristine vendor
sources, followed by the unprivileged creation of a resulting binary
package, and ending in the installation, upgrading and deinstallation of
the binary package on the target OpenPKG instance. This all works in a
self-contained environment and is driven by single and concise all-in-one
package specification, the RPM C<.spec> file. No other existing packaging tool
allows this.

An outstanding point with OpenPKG is the fact that the project
officially discourages the use of binary packages and only provides and
recommends them for bootstrapping (no development tools available) and
emergency (tight time constraints) situations. RPM fortunately supports
this very well.
Experience showed that the only safety for robustness and security
is to build software on the target machine. 

If you're in  doubt, consider this real life example: a packager builds
a binary package for Apache with mod_ssl
and MM (for SSL/TLS support and shared memory based session caches) on his high-tuned developer machine.
The user installs this on his default Unix platform and wonders why the
application crashes because the session cache could not be created with
the maximum shared memory segment size. The reason is simply because
MM's Autoconf environment correctly determined the maximum shared memory
segment size on the developer's machine. 

Unfortunately, the developer previously installed a database
and tuned his system using an increased maximum shared memory size.
Because a cross-platform test for this maximum size cannot be done
under run-time, MM had to hard-code this size into the library under
build-time. The user has a default environment where the maximum number
is a lot smaller and hence the knowledge of MM and the reality are no
longer in sync. Bang! This is just one typical example. There are a lots
more we could tell you about. The only reasonable solution is to start always
from source packages.

Getting started [thl]
---------------

OpenPKG runs on many Unix flavours with focus on FreeBSD, Linux and
Solaris. Table 1 shows a detailed list of Unix platform support valid as
of version 1.0.  The bootstrapping process is a shell script that
initially creates a new instance of OpenPKG on a machine.  While it is
d127 49
a175 51
operating system support and tools to unpack and compile itself. The
required environment is listed in the OpenPKG handbook under
"Instructions to Bootstrap".

Especially when you build from source the need for a compiler should
be obvious. The absence of development tools is one of the
few reasons to favour binaries over source packages to bootstrap and
install a compiler. You dedicate a file system prefix to every instance
along with a user and group. OpenPKG v1.1 actually uses three users
as introduced by openpkg-20020221. A generic bootstrap script called
openpkg-I<version>-I<version>.src.sh takes prefix, user and group
as arguments and creates a platform specific bootstrap script named
openpkg-I<version>-I<version>.I<architecture>-I<platform>-I<id>.sh which
in turn does the actual installation including user and group creation.

We put every effort into the bootstrap logic so only it along with a exreme limited set of helperpackages will ever touch
the system configuration files outside the given prefix. 
Most of this anchoring is done during installation but some
helperpackages might reuse or extend the bootstrap functions to alter PAM configuration,
C</etc/shells> or they might tell you to tune the kernel manually, i.e.
modifying shared memory segment size. The bootstrap installs itself into
the new hierarchy as C<openpkg> package. You might notice that C<.rpm>
versions of the bootstrap exist as well. They can be used to upgrade
the C<openpkg> package at any time. A step by step example is given in
Listing_4 "BIND in 10 minutes". To understand the RPM commands used there
see the box "OpenPKG Administration Commands (Quick Reference)" and
U<http://www.openpkg.org/doc/quickref/openpkg.txt>.

Architecture [cs]
------------

Due to the flexibility Unix offers there's often a downside which every
administrator has to face with if he's not the one and only administrator of
a server: file system standards. The most common standard is that
there's is no standard. Depending on the predilection of the one
who installed a certain piece of software you will end in dozens
of possibilities. I know many administrators just pokeing around for some
minutes just looking for a simple config file. Has is been in C</etc>,
C</etc/mail>, C</usr/local/etc> or C</usr/local/postfix/etc>? Stop
looking around any further, use OpenPKG!

You will find all kind of configuration files under
I<prefix>C</etc/>I<package>. Thus you will easily find your postfix main
configuration under C</sw/etc/postfix/main.cf> assuming you installed
your OpenPKG instance under C</sw>. The same goes for log files.
Taking postfix as an example again you will find your mail logs under
C</sw/var/postfix/log>. Actually it takes some time to get used to those
path names breaking with every known Unix convention. But as consequence
of this you will find simplicity and unity across all of your servers
no matter who configured them and which platform is being used. It's all the
same. See Figure_2.
d180 11
a190 5
To build a binary package from source with C<.spec> defaults use
C<rpm --rebuild package>. This will place the binary RPM into
C<%{l_prefix}/RPM/PKG/>, therefore you need write access to that
location by being a member of the related OpenPKG group, login as the
OpenPKG user itself or login as root. To alter the C<.spec> defaults
d235 2
a236 2
In the previous "Getting started" section we mentioned the "BIND in
10 minutes" Listing_4. If you worked it out you might have noticed the
d557 15
a571 14
Unix Platform        Version     Amount of Support
==================== =========== ===================
FreeBSD              4.x/5.0-C   fully supported
Debian GNU/Linux     2.2/3.0pre  fully supported
RedHat Linux         6.x/7.x     fully supported
NetBSD               1.5.x       fully supported
Sun Solaris          8           fully supported
Sun Solaris          2.6/7       partially supported
OpenBSD              2.9         partially supported
HP/UX                10.20       partially supported
Compaq Tru64         5.0         partially supported
Caldera OpenUNIX     8.0         not yet supported
IBM AIX              4.x         not yet supported
SGI IRIX             6.x         not yet supported
d768 6
a773 5
#[tmp]
#comment           = The Temporary Filesystem
#path              = /tmp/
#exclude           = .*
#list              = no
d825 1
a825 1
Listing_4: BIND in 10 minutes
a826 1
user$ #pay attention you have a working C compiler in your PATH
d838 2
a839 2
ftp> cd release/1.0/UPD
ftp> get openpkg-1.0.1-1.0.1.src.sh
d842 1
a842 1
user$ sh openpkg-1.0.1-1.0.1.src.sh --prefix=/usr/opkg --user=opkg --group=opkg
d844 1
a844 11
root# sh openpkg-1.0.1-1.0.1.*-uo.sh
root# su - opkg
opkg$ /usr/opkg/bin/rpm --rebuild ftp://ftp.openpkg.org/release/1.0/SRC/bind-8.2.5-1.0.0.src.rpm
  Installing ftp://ftp.openpkg.org/release/1.0/SRC/bind-8.2.5-1.0.0.src.rpm
  error: failed build dependencies:
  make   is needed by bind-8.2.5-1.0.0
  flex   is needed by bind-8.2.5-1.0.0
  bison  is needed by bind-8.2.5-1.0.0
opkg$ /usr/opkg/bin/rpm --rebuild ftp://ftp.openpkg.org/release/1.0/SRC/make-3.79.1-1.0.0.src.rpm
opkg$ exit
root# /usr/opkg/bin/rpm -Uvh /usr/opkg/RPM/PKG/make-3.79.1-1.0.0.*-uo.rpm
d846 1
a846 1
opkg$ /usr/opkg/bin/rpm --rebuild ftp://ftp.openpkg.org/release/1.0/UPD/bison-1.30-1.0.1.src.rpm
d848 1
a848 1
root# /usr/opkg/bin/rpm -Uvh /usr/opkg/RPM/PKG/bison-1.30-1.0.1.*-uo.rpm
d850 1
a850 8
opkg$ /usr/opkg/bin/rpm --rebuild ftp://ftp.openpkg.org/release/1.0/SRC/flex-2.5.4a-1.0.0.src.rpm
opkg$ exit
root# /usr/opkg/bin/rpm -Uvh /usr/opkg/RPM/PKG/flex-2.5.4a-1.0.0.*-uo.rpm
root# su - opkg
opkg$ /usr/opkg/bin/rpm --rebuild ftp://ftp.openpkg.org/release/1.0/SRC/bind-8.2.5-1.0.0.src.rpm
opkg$ exit
root# /usr/opkg/bin/rpm -Uvh /usr/opkg/RPM/PKG/bind-8.2.5-1.0.0.*-uo.rpm
root# /usr/opkg/etc/rc bind start
d852 2
a853 1
user$ /usr/opkg/bin/dig @@localhost www.openpkg.org
d855 2
a856 2
root# /usr/opkg/etc/rc bind stop
root# /usr/opkg/bin/rpm -e bind flex bison make openpkg
d858 1
a858 4
user$ 
[thl verified: OK, took 9min on dev12; a similar example which includes descriptions
about sources vs. binary packages and install vs. upgrades can
be found at U<http://www.openpkg.org/tutorial.html]>
@


1.65
log
@thl first complete review
@
text
@a566 1
Sun Solaris          2.6/7/8     fully supported
d568 2
@


1.64
log
@fix spelling
@
text
@d74 1
a74 1
instance containing everything required software component -- from
d80 1
a80 1
All this is only possible because OpenPKG follows a minimal OS intrusion
d83 1
a83 1
the underlying vendor solutions. Sometimes this means that it even
d90 1
a90 1
dpkg+apt, FreeBSD ports+pkg_xxx, SysV pkgxxx? The reason is that,
d102 2
a103 2
officially discourages the use of binary packages and only provide and
recommend them for bootstrapping (no development tools available) and
d105 2
a106 2
this very well. The reason for this heavy decision is that
experience showed that the only safety for robustness and security
d114 1
a114 1
the maximum shared memory segment size? The reason is simply because
d118 2
a119 2
Unfortunately, because he is a developer and also plays with databases
and runs a tuned environment, his system used an increased maximum size.
d141 1
a141 1
be obvious. However, the absence of development tools is one of the
d151 4
a154 4
We put every effort into the bootstrap logic so only it will ever touch
the system configuration files outside the given prefix. Most if not
all of this anchoring is done during the installation but some add-on
packages might reuse the bootstrap functions to alter PAM configuration,
d160 1
a160 1
the box "BIND in 10 minutes". To understand the RPM commands used there
d184 3
a186 5
of this you will find simplicity and unity on all of your servers
whoevery configured them, whatever platform is being used. It's all the
same.

article.layout.fig
d206 3
a208 3
To install a binary package just use rpm -Uvh I<package>.
Strictly speaking this upgrades a package and installing is just the
special case upgrading from nothing. RPM is very clever when it comes to
d210 1
a210 1
in Table FIXME: "RPM handling of config files". If you sticked with
d213 2
a214 2
default didn't change so chances are you would change the same values
back again then the old config is kept. 
d219 5
a223 5
and saves yours as I<config>C<.rpmsave>. If no previous defaults existed
at all but the new package provides some, it's better to integrate your
settings manually, so RPM install the new config and saves yours as
I<config>C<.rpmorig>. To make this work properly, a package has to tag
configuration files and this has been done for OpenPKG packages.
d226 1
a226 1
rpm -qi I<package> lists detailed information about a installed
d228 2
a229 2
found in C<%{l_prefix}/etc> and variable data like logfiles always
go into C<%{l_prefix}/var>. Packages have been rigorously forced
d233 1
a233 1
have been tampered with. Finally, another useful query is C<rpm -qf>
d241 1
a241 1
10 minutes" box. If you worked it out you might have noticed the
d248 2
a249 2
labels prefixed with a 'C<%>'. Have a look at the "rc.rsync: run-commands"
box and enjoy.
d254 1
a254 1
given. The special "package" name I<all> refers to executing the given
d277 4
a280 1
start of the package's daemons at system startup time.
d282 1
a282 3
Back to the BIND example this can be useful if you installed the package
just to get the C<nslookup> and related utilities and don't care about
the server. Introduced with OpenPKG 20020205 and available in v1.1 is a
d285 3
a287 1
can still be started manually. The run-command facility has other
d304 1
a304 1
unprivileged environment. What is the fuzz about this? Isn't this not
d309 3
a311 3
of three files: the RPM specification (C<rsync.spec>, Listing 1),
the run-commands (C<rc.rsync>, Listing 2), and the default daemon
configuration (C<rsync.conf>, Listing 3).
d313 1
a313 1
If compare this to the RPM-based rsync packages of other vendors,
d351 1
a351 1
this way and the release engineering procedures were able to be mostly
d355 1
a355 1
unprivileged (non-root user) environment and with read-only access to
d394 1
a394 1
structure of a so called C<.spec> file (Listing 1), you might think of
d397 3
a399 3
how it might work. Going into detail you there are some features of RPM
to make life easier like variables like C<%{version}> which are automatically
set according to C<Version:> field helping you to avoid redundancy. 
d403 2
a404 2
for both build and run time. There are also same magic macros like
C<%setup> which support you uncompresses source tarballs but there are
d409 1
a409 1
worked around. One of the hardest thing while packaging software if to
d412 2
a413 2
by P<$RPM_BUILD_ROOT>. On this location a file list is generated by
P<rpmtool> which specifies the content of the package.
d422 2
a423 2
Not always it is desirable to package a piece of software
if you are quite sure you will always use once on a single box. Even for this
d429 1
a429 1
C</sw/local/PKG/>I<name>-I<version>. This way it is possible to install
d432 1
a432 1
C</sw/local/PKG/foo> pointing to C</sw/local/PKG/foo-3.27>. 
d435 1
a435 1
the C<PKG> for directory entries without version numbering. After
d437 1
a437 1
C</sw/local/bin>, C</sw/local/man> and so on (Figure FIXME). This
d440 2
a441 2
of software using C<configure --prefix=/cw/local/PKG/foo-3.27>. See
Listing Y FIXME for a more detailed example. If you consider some day
d444 4
a447 4
again. C<lsync> will automatically update to activation, make new links
if required and remove out-dated dangling ones. As you might already
guess is just as easy to go back to the old version if the new one keeps
dumping core all the time.
d511 1
a511 1
C which should replace the current shell script architecture. Shared
d560 1
a560 1
Table 1: OpenPKG Unix Platform Support
d577 1
a577 1
Figure 1: The OpenPKG Subsystem Principle
d582 1
a582 1
Figure 2: The OpenPKG Filesystem Layout
d587 1
a587 1
Listing 1: OpenPKG packaging for rsync (rsync.spec: RPM specification)
d685 1
a685 1
Listing 2: OpenPKG packaging for rsync (rc.rsync: run-commands)
d751 1
a751 1
Listing 3: OpenPKG packaging for rsync (rsync.conf: default configuration)
d778 1
a778 1
Table X: RPM handling of config files <prefix>/etc/<pkg-name>/*
d797 1
a797 1
Table X: OpenPKG Summary
d827 1
a827 1
Listing X: BIND in 10 minutes
d883 1
a883 1
Listing Y: Installation of non-OpenPKG software
d903 1
a903 1
Listing Y: File system layout of non-OpenPKG software installed
d939 1
a939 1
Table X: OpenPKG Administration Commands (Quick Reference)
@


1.63
log
@fix markup
@
text
@d82 1
a82 1
trieds hard to smooth out the differences between the approaches of
d84 1
a84 1
has to break well known defacto standards in order to provide a
d168 1
a168 1
admin has to face with if he's not the one and only administrator of
d172 1
a172 1
of possibilities. I know many admins just pokeing around for some
d235 1
a235 1
have been tampered with. Finally, another usefuly query is C<rpm -qf>
d265 1
a265 1
can be used to configure the behaviour of every section in a per-package
d274 1
a274 1
bootstrap sets up cronjobs to execute them accordingly. Another
d303 1
a303 1
unpriviledged environment. What is the fuzz about this? Isn't this not
d339 1
a339 1
-O}> expands to the necesseary flags to leverage from SMP. For
d345 1
a345 1
Additionally, all OpenPKG packages follow I<excactly> the same
d349 1
a349 1
the source. For example, the indizes on the FTP server are autogenerated
d354 1
a354 1
unpriviledged (non-root user) environment and with read-only access to
d374 1
a374 1
instances in order to avoid the necessarity of having to build and
d392 1
a392 1
First of all take a second or two and make yourself fimilar with to
d394 1
a394 1
blueprint of a package. If you are fimilar with Unix development most
d416 1
a416 1
       should refernce to our web site.
d425 1
a425 1
you are fimilar with like C<bin>, C<include>, C<lib>, C<man> and so on. But
@


1.62
log
@stick with the long/double dashes
@
text
@d199 1
a199 1
aka unpack the source into C<%{l_prefix}/RPM/SRC/I<package>>/. This
d204 1
a204 1
with the rebuild process using --define "I<variable> I<value>". This
d248 1
a248 1
C<%{l_prefix}/etc/rc.d/rc.I<package>>, a collection of shell scripts in
d250 1
a250 1
labels prefixed with a '%'. Have a look at the "rc.rsync: run-commands"
d255 1
a255 1
then extracted from the C<rc.I<package>> file and executed in the order
d258 1
a258 1
at a section label using C<-p I<number>> construct where small numbers
d260 1
a260 1
C<-u I<user>> which causes C<rc> to execute the script with the realm
d278 1
a278 1
C<I<package>_enable="yes"> which, when turned into "no" will disable the
d287 1
a287 1
features as well. Use C<rc --query I<variable>> to see the status of any
@


1.61
log
@lifecycle is singular; avoid numbers and brackets;
@
text
@d46 1
a46 1
FreeBSD, Linux and Solaris - but OpenPKG is no longer limited to just these
d49 1
a49 1
component - ranging from shells, over editors and compilers, up to
d74 1
a74 1
instance containing everything required software component - from
@


1.60
log
@a/an; ISP; mention hosting; fight dashes; proposal changing headline;
@
text
@d77 2
a78 2
Covering whole package lifecycles [rse]
---------------------------------
d82 1
a82 1
trieds hard to smooth the differences between the approaches of
d84 3
a86 3
has to break well-known de-facto standards in order to provide a
cleaner solution. But this is the only possibility for a consistent
cross-platform approach.
d89 5
a93 5
packaging technology, although lots of alternatives exists (Debian's
dpkg+apt, FreeBSD ports+pkg_xxx, SysV pkgxxx, etc)? The reason is that,
although RPM is also just a 90% solution, it covers (at least with
the OpenPKG extensions) the I<whole> lifecycle of a package. This
starts by fetching, unpacking, patching and building the pristine vendor
d96 4
a99 4
the binary package on the target OpenPKG instance. All this with a
self-contained environment and driven by single and concise all-in-one
package specification (RPM .spec file). No other packaging tool except
RPM allows this.
d109 3
a111 3
If you doubt, consider this real-life example: a packager builds on his
fine-tuned developer machine a binary package for Apache with mod_ssl
and MM (for SSL/TLS support and shared memory based session caches).
d119 1
a119 1
and runs a tuned environment, its system used an increased maximum size.
d124 2
a125 2
longer in sync. Bang! This is just a single example. There are lots of
more we could tell you. The only reasonable solution is to start always
@


1.59
log
@try to finish RelEng section
@
text
@d33 1
a33 2
runs out of space because a logfile was never rotated? OpenPKG comes to
the rescue!
d35 2
a36 2
What you see is what you get [rse]
----------------------------
d38 2
a39 2
OpenPKG is an Open Source software project, initiated in November
2000 by Cable & Wireless Deutschland, a large ISP in Germany. It is
d44 1
a44 1
It was created out of the demand to unify the installation and
d46 2
a47 2
FreeBSD, Linux and Solaris -- but is no longer limited to just these
(see Table 1). For this it provides a cross-platform subsystem on top
d49 3
a51 3
component -- ranging from shells, over editors and compilers, up to
network daemons and Web applications (see Figure 1). Hence, its current
primary target community are system administrators faced with a large
d57 1
a57 1
packaging facility. On top of this you can install over 300 individual
d74 1
a74 1
instance containing everything required software component -- from
@


1.58
log
@remember issue
@
text
@d452 1
a452 1
The OpenPKG project's results are not only available as Open Source,
d481 8
a488 3
[cs] how do we treat security issues, security advisory, signed package, package integrity
[cs] organisation of FTP server (release, current (= unstable)
[thl] release engineering U<http://www.openpkg.org/releng.html>
@


1.57
log
@break into more readable paragraphs
@
text
@d900 2
@


1.56
log
@live/life; apply to; start with statement not question; remove "Or";
@
text
@d117 11
a127 9
segment size on the developer's machine. Unfortunately, because he is a
developer and also plays with databases and runs a tuned environment,
its system used an increased maximum size. Because a cross-platform test
for this maximum size cannot be done under run-time, MM had to hard-code
this size into the library under build-time. The user has a default
environment where the maximum number is a lot smaller and hence the
knowledge of MM and the reality are no longer in sync. Bang! This is
just a single example. There are lots of more we could tell you. The
only reasonable solution is to start always from source packages.
d139 25
a163 21
"Instructions to Bootstrap" 
Especially when you build from source the need for a compiler should be
obvious. However, the absence of development tools is one of the few
reasons to favour binaries over source packages to bootstrap and install
a compiler.  You dedicate a file system prefix to every instance along
with a user and group. OpenPKG v1.1 actually uses three users as introduced by openpkg-20020221. A generic bootstrap script
called openpkg-I<version>-I<version>.src.sh takes prefix, user and group as
arguments and creates a platform specific bootstrap script named
openpkg-I<version>-I<version>.I<architecture>-I<platform>-I<id>.sh which in turn does the
actual installation including user and group creation. We put every afford into the bootstrap logic so
only it will ever touch the system configuration files outside the given
prefix. Most if not all of this anchoring is done during the
installation but some add-on packages might reuse the bootstrap
functions to alter PAM configuration, C</etc/shells> or they might tell you to tune the
kernel manually, i.e. modifying shared memory segment size. The
bootstrap installs itself into the new hierarchy as C<openpkg> package.
You might notice that C<.rpm> versions of the bootstrap exist as well.
They can be used to upgrade the C<openpkg> package at any time. A step by
step example is given in the box "BIND in 10 minutes".  To understand
the RPM commands used there see the box "OpenPKG Administration Commands
(Quick Reference)" and U<http://www.openpkg.org/doc/quickref/openpkg.txt>.
d169 9
a177 7
admin has to face with if he's not the one and only administrator of a
server: file system standards. The most common standard is that there's is
no standard. Depending on the predilection of the one who installed a certain
piece of software you will end in dozens of possibilities. I know many admins
just pokeing around for some minutes just looking for a simple config file.
Has is been in C</etc>, C</etc/mail>, C</usr/local/etc> or 
C</usr/local/postfix/etc>? Stop looking around any further, use OpenPKG!
d180 8
a187 7
configuration under C</sw/etc/postfix/main.cf> assuming you installed your
OpenPKG instance under C</sw>. The same goes for log files. Taking postfix
as an example again you will find your mail logs under C</sw/var/postfix/log>.
Actually it takes some time to get used to those path names breaking with
every known Unix convention. But as consequence of this you will find
simplicity and unity on all of your servers whoevery configured them, whatever
platform is being used. It's all the same.
d194 2
a195 2
To build a binary package from source with C<.spec> defaults use C<rpm
--rebuild package>. This will place the binary RPM into
d198 12
a209 10
OpenPKG user itself or login as root. To alter the C<.spec> defaults unpack
the source using rpm -Uvh I<package>. This will "install" aka
unpack the source into C<%{l_prefix}/RPM/SRC/I<package>>/. This is
the place to edit the I<package>.spec file and then use rpm -bb I<package>.spec to
build the binary and place it into the same location as a rebuild would
have done. Introduced with version FIXME and incorporated into
OpenPKG v1.1 is a feature to define a variable along with the rebuild
process using --define "I<variable> I<value>". This affects the
rebuild process without breaking it in two parts and editing the C<.spec>
file. To install a binary package just use rpm -Uvh I<package>.
d217 17
a233 16
back again then the old config is kept. If you sticked with defaults and
defaults changed RPM installs the new config.  If the defaults and with
them possibly the structure changed so it's better to verify changes
manually then RPM installs the new config and saves yours as
I<config>C<.rpmsave>. If no previous defaults existed at all but the new
package provides some, it's better to integrate your settings manually,
so RPM install the new config and saves yours as I<config>C<.rpmorig>.
To make this work properly, a package has to tag configuration files and
this has been done for OpenPKG packages.
The
output of C<rpm -qa> gives you a list of installed packages and rpm
-qi I<package> lists detailed information about a installed package.
Configuration files for a given package can always be found in
C<%{l_prefix}/etc> and variable data like logfiles always go into
C<%{l_prefix}/var>. Packages have been rigorously forced to
conform to that specification. For a step by step example see
d235 4
a238 4
integrity at any time using C<rpm -V> I<package> and verify which
files have been tampered with. Finally, another usefuly query is C<rpm
-qf> I</full/path/to/a/file> which tells you to which package the given
file belongs.
d243 6
a248 6
In the previous "Getting started" section we mentioned the "BIND in 10
minutes" box. If you worked it out you might have noticed the server was
started using the command C</usr/opkg/etc/rc bind start>. The workhorse
behind this simple statement is the powerful OpenPKG run-command
facility, executed with C<%{l_prefix}/etc/rc> which is currently a shell
script. Run-commands for every package are stored in
d251 27
a277 23
labels prefixed with a '%'.  Have a look at the "rc.rsync: run-commands"
box and enjoy.  The C<rc> command takes a I<package> name as the first
argument and one or more I<section> labels as additional arguments. The
scripts are then extracted from the C<rc.I<package>> file and executed
in the order given. The special "package" name I<all> refers to
executing the given section(s) for all packages. Order is
determined by the priority given at a section label using C<-p
I<number>> construct where small numbers are executed first. Another
option available to the section label is C<-u I<user>> which causes
C<rc> to execute the script with the realm of I<user>. Note there are
some sections with special meaning. The C<%common> section has the
function of a library and contains code useful to many or all of the
other sections. It is included in every script before it is run. The
C<%config> section contains variables which can be used to configure the
behaviour of every section in a per-package context. Variables can also
be placed into C<%{l_prefix}/etc/rc.conf> in a per-hierarchy scope. The
complete script executed by C<rc> is assembled from C<%config>
section, wholly C<%{l_prefix}/etc/rc.conf> file, C<%common> section and
the actual section given at the C<rc> command line, in that order. Sections labeled
C<%monthly>, C<%weekly>, C<%daily>, C<%hourly> and C<%quarterly> are also
special as the bootstrap sets up cronjobs to execute them accordingly.
Another label often seen is C<%env> which is intended to be used with
the C<--eval> option explained below.  Regarding configuration through
d280 17
a296 15
start of the package's daemons at system startup time. Back to the BIND
example this can be useful if you installed the package just to get the
C<nslookup> and related utilities and don't care about the server.
Introduced with OpenPKG 20020205 and available in v1.1 is a feature to
disable the automatic startup of all servers in a hierarchy by adding a
C<openpkg_ignall="yes"> to C<rc.conf>. However, all daemons can still be
started manually. The run-command facility has other features as well.
Use C<rc --query I<variable>> to see the status of any configured
variable or run C<rc --config> to see a complete list of all available
variables, their defaults and currently effective values. Last but not
least the run-command facility offers a very handy feature to modify
your shell environment to include a hierarchies' PATH, MANPATH, INFOPATH
etc. Just execute C<rc --eval all env> and it creates a shell script for
you which can adjust your environment. Run it directly in your shell
using C<eval> and place the previously listed command in backticks.
d399 15
a413 13
set according to C<Version:> field helping you to avoid redundancy. One of
the most important parts is the one headlined by "build information".
This section describes package prerequisites and conflicts for both build and
run time. There are also same magic macros like C<%setup> which support you
uncompresses source tarballs but there are also others not mentioned here,
e.g. to apply patches. Nevertheless you should spend some time reading
documentation (FIXME reference to Maximum RPM and alike). Don't hesitate to
take a look at existing C<.spec> files cause many typical packaging problems
have already been worked around. One of the hardest thing while packaging
software if to convince to original install mechanism not to put all the
stuff to its final destination but to relocate it to temporary location
specified by P<$RPM_BUILD_ROOT>. On this location a file list is generated
by P<rpmtool> which specifies the content of the package.
d432 16
a447 14
C</sw/local/PKG/foo> pointing to C</sw/local/PKG/foo-3.27>. In order to
active everything simply invoke C<lsync> which will scan the C<PKG> for
directory entries without version numbering. After that all programs, man
pages and other stuff will be symlinked under C</sw/local/bin>,
C</sw/local/man> and so on (Figure FIXME). This implies that all the pieces
of software have got their own C<bin>, C<man>, etc. Very often you can
accomplish that by configuring a piece of software using
C<configure --prefix=/cw/local/PKG/foo-3.27>. See Listing Y FIXME for a more
detailed example. If you consider some day to upgrade to C<foo-3.30> just
repeat installation in the same way, alter symlink C<foo> to make it
point to C<foo-3.30> and re-run C<lsync> again. C<lsync> will automatically
update to activation, make new links if required and remove out-dated dangling
ones. As you might already guess is just as easy to go back to the old
version if the new one keeps dumping core all the time.
d495 14
a508 12
appreciated!  Currently work is underway on a frontend which should
simplify the installation process and handle build- and
install-dependencies automatically.  It reads RPM information from RDF
files and the user interface and installation backend will communicate
through a client/server architecture to allow distributed management of
OpenPKG instances. We plan to expand OpenPKG packages to reach out to the desktop
with the first X11-dependent packages already in place. Some packages
will be split into smaller, independent pieces for rapid deployment.
We're already working on a run-command facility written in C which
should replace the current shell script architecture. Shared library
support is under investigation. Last but not least, we work closer
with RedHat than ever and are looking forward to absorb their
@


1.55
log
@use a two-column layout for better resembling the magazine
@
text
@d11 10
a20 10
You use Open Source software because you like its advantages? But if
you try to apply it in your real-live environment you often have to
discover its limitations? You know this: first you have to find the
latest version on the Internet and collect together the most recent
patches covering important security fixes. Then you have to bring it all
together and build and install it on every Unix box in your network,
just to find out the application needs under build time a little bit
of different tweaking on each platform. If it is even a server
application, you quickly get bothered because every Unix flavour has its
own custom method of starting and stopping them.
d22 1
a22 1
Or did you ever try to install BIND having tough time constraints
@


1.54
log
@fix displaying
@
text
@d137 1
a137 1
"Instructions to Bootstrap" U<http://www.openpkg.org/doc/handbook/openpkg.html#bstrap-instruct>.
d488 1
a488 1
==========
d505 1
a505 1
=================
@


1.53
log
@resolved conflict
@
text
@d874 1
a874 1
Figure Y: File system layout of non-OpenPKG software installed
@


1.52
log
@Yes, gzip is also nice, but we already have rsync printed in detail in
the article, so we should use rsync as an example because the reader
then sees more of a single package.
@
text
@d373 25
a397 2
reference a simple .spec file (rsync)
[rse] very concise RPM specifications with minimal redundancy
@


1.51
log
@first cut for RelEng section
@
text
@d373 1
a373 2
reference a simple .spec file (bash)
Thinking of gzip whould be a good example
@


1.50
log
@flush
@
text
@d408 29
a436 1
[rse] CVS usage, Shiela, openpkg-cvs
d438 1
a439 2
[cs] organisation of FTP server (release, current (= unstable)
[rse] automatic vendor source version tracking -> always up-to-date very fast
@


1.49
log
@RPM handling of config files
@
text
@d374 1
d377 2
a378 2
?compromise between RPM package and /usr/local install [cs]
------------------------------------------------------
d380 24
a403 1
[rse] lsync and the <prefix>/local area
d803 54
@


1.48
log
@# sync
@
text
@d198 18
a215 1
file. To install a binary package just use rpm -Uvh I<package>. The
d681 6
a686 6
X        X          X        X          keep old config, but re-install (happens if you sticked with defaults and defaults remain the same)
X        X'         X'       X'         keep old config, but re-install (happens if you changed the same settings to the same values as the author of the new package did)
X        X'         X        X'         keep old config (default didn't change so you chances are you would change the same values again if the default would have been applied)
X        X          Y        Y          install new config (happens if you sticked with defaults and defaults changed)
X        X'         Y        Y          install new config, preserve X' as .rpmsave (defaults and possibly structure changed so better verify changes manually)
-        X          Y        Y          install new config, preserve X  as .rpmorig (no previous but new default so better integrate your settings manually)
@


1.47
log
@OpenPKG Summary
@
text
@d162 18
a180 1
[cs] strict file system layout (configs in %{l_prefix}/etc, user/group ...)
@


1.46
log
@fixed typos; removed "And" at the beginning of every sentence
@
text
@d663 26
a688 17
- sub-system on top of underlying Unix system
- primarily targeted at server environments
- designed as cross-platform solution
- based on RPM 4 with custom extensions
- tricky bootstrapping procedure with no required RPM pre-installations
- support for RPM-packaged and non-packaged software
- support for multiple installation instances on same Unix system
- fully self-contained, minimal Unix system dependencies only
- minimal Unix system intrusion (4-point anchoring)
- mature technology in production use since one year
- focuses primarily on building software from pristine vendor source
- uses a strict and consistent filesystem layout across all packages
- RPM package specifications written from scratch, consice, strict style, no redundancy
- fully available as Open Source
- flexible run-time configuration and control through unique run-command facility
- all packages are installed with reasonable pre-configuration
- over 300 packages available
@


1.45
log
@Run-command facility
@
text
@d18 1
a18 1
of different tweaking on each platform. And if it is even a server
d97 1
a97 1
the binary package on the target OpenPKG instance. And all this with a
d123 2
a124 2
knowledge of MM and the reality are no longer in sync. Bang! And this is
just a single example. There are lots of more we could tell you. And the
d210 1
a210 1
executing the given section(s) for all packages where package order is
d217 1
a217 1
other sections. It is included in every script before it is run. And the
d221 1
a221 1
complete script executed by C<rc> is assembled in order C<%config>
d223 2
a224 2
the actual section given at the C<rc> command line. Sections labeled
C<%monthly> C<%weekly> C<%daily> C<%hourly> C<%quarterly> are also
d227 1
a227 1
the --eval option explained below.  Regarding configuration through
d230 1
a230 1
start of the package's daemons and system startup time. Back to BIND
d240 2
a241 2
least the run-command facility offery a very handy feature to modify
your shell environment to include a hierarchies PATH, MANPATH, INFOPATH
d243 1
a243 1
you which can adjust your environment. Run it directly in you shell
d302 1
a302 1
And I<every> OpenPKG package is able to build in a fully
d376 1
a376 1
support is under investigation. And last but not least, we work closer
@


1.44
log
@just polish a little bit while I poke around here
@
text
@d174 1
a174 1
unpack the source into %{l_prefix}/RPM/SRC/I<package>/. This is
d194 1
a194 1
Run-command facility [cs]
d197 48
a244 10
example explained: bind in 10min box, disabling server to get tools only
[rse] flexible and unique run-command facility (rc --eval, --config, --query)
[cs] flexible runtime configuration via rc.conf
sample rc file box

openpkg-20020221 and later
- support an "openpkg_ignall" variable for ignoring "all" type
  requests which can be used to disable an OpenPKG instance from
  startup/shutdown/cron but still being able to use it manually.

@


1.43
log
@more polishing
@
text
@d11 10
a20 9
You use open source software because you like it's advantages. But when
you try implementing it in real live environments you discovered it's
limitations. You need to find the latest version on the internet and
collect it together with the most recent patches and security fixes.
Then you need to bring it all together and push it out to every Unix box
just to find out the application needs a little bit different tweaking
on all of them. And when it comes to installing daemons you find out
soon every Unix flavour has it's own method starting them at system boot
time. 
d22 1
a22 1
Did you ever try to install BIND having tough time constraints
@


1.42
log
@bugfixes and shortening of lines
@
text
@d19 3
a21 1
time. Did you ever try to install BIND having tough time constraints
d701 1
a701 1
# <prefix>/bin/rpm -Uvh <pkg-src>                unpack source package
d703 1
a703 1
# <prefix>/bin/rpm --clean --rmsource <pkg-spec> cleanup after building binary package
d722 1
a722 1
# <prefix>/bin/rpm --checksig <pkg-rpm>          verify integrity and origin of package
d729 4
a732 4
$ <prefix>/etc/rc <pkg_name> start               start a particular package
$ <prefix>/etc/rc <pkg_name> stop                stop  a particular package
$ <prefix>/etc/rc <pkg_name> stop start          restart a particular package
$ <prefix>/etc/rc all stop start                 restart all packages
d735 8
a742 7
Legend: Variable   Example 
        <prefix>   /usr/opkg
        <pkg-name> bash
        <pkg-spec> bash.spec
        <pkg-rpm>  bash-2.05a-1.0.0.*.rpm
        <pkg-src>  bash-2.05a-1.0.0.src.rpm
        <pkg-bin>  bash-2.05a-1.0.0.ix86-freebsd4.5-uo.rpm
@


1.41
log
@No, no, no, the article.txt has to be the file which we finally send
to SysAdmin magazine, so we cannot clutter this with too much markup,
friends! We cannot see any longer the forrest because of too much trees.

The idea of a HTML preview version is certainly great, but, guys, real
hackers do this by investigating an hours and hacking together a small
Perl script which generates such a preview version out of the original
on-the-fly.

I've done this now for us. Run "make" and you get the preview in
article.html. Think a little bit longer next time before starting to
implement great ideas with bad solutions, please. Thanks.
@
text
@d364 1
a364 1
<p>
d371 1
a371 1
<p>
d422 1
a422 1
Release:      20020326
d432 2
a433 2
BuildPreReq:  OpenPKG, openpkg >= 20020206
PreReq:       OpenPKG, openpkg >= 20020206
d444 2
a445 2
    calculation of differences between two files normally requires local
    access to both files.
d540 1
a540 1
            kill -TERM `cat $rsync_pidfile ]; then
d550 1
a550 1
            kill -HUP `cat $rsync_pidfile ]; then
d557 4
a560 2
            -n ${rsync_log_numfiles} -s ${rsync_log_minsize} \
            -d -z ${rsync_log_complevel} -o @@l_musr@@ -g @@l_mgrp@@ -m 644 \
d594 5
a598 5
# [tmp]
# comment            = The Temporary Filesystem
# path               = /tmp/
# exclude            = .*
# list               = no
@


1.40
log
@fixed endtag bug; added some more tags; it should still be easy to remove all tags
@
text
@a0 4
<html>
<body>
<h1>Title</h1>
<h1>=====</h1>
d3 1
a3 3

<h2>Subtitle</h2>
<h2>========</h2>
d6 1
d8 2
a9 6
<table>
<tr>
<td width="60%">&nbsp;</td>
<td width="400">
<h3>(entry/hanger) [thl]</h3>
<h3>--------------</h3>
d28 2
a29 2
why it cluttered up your <tt>/etc</tt> with config files? Successfully
installed a network daemon but a week later the <tt>/var</tt> filesystem
d33 2
a34 2
<h3>What you see is what you get [rse]</h3>
<h3>----------------------------</h3>
d75 2
a76 2
<h3>Covering whole package lifecycles [rse]</h3>
<h3>---------------------------------</h3>
d90 1
a90 1
the OpenPKG extensions) the <i>whole</i> lifecycle of a package. This
d124 2
a125 2
<h3>Getting started [thl]</h3>
<h3>---------------</h3>
d134 1
a134 1
"Instructions to Bootstrap" <a href="http://www.openpkg.org/doc/handbook/openpkg.html#bstrap-instruct">http://www.openpkg.org/doc/handbook/openpkg.html#bstrap-instruct</a>.
d140 1
a140 1
called <tt>openpkg-<i>version</i>-<i>version</i>.src.sh</tt> takes prefix, user and group as
d142 1
a142 1
<tt>openpkg-<i>version</i>-<i>version</i>.<i>architecture</i>-<i>platform</i>-<i>id</i>.sh</tt> which in turn does the
d147 1
a147 1
functions to alter PAM configuration, <tt>/etc/shells</tt> or they might tell you to tune the
d149 3
a151 3
bootstrap installs itself into the new hierarchy as <tt>openpkg</tt> package.
You might notice that <tt>.rpm</tt> versions of the bootstrap exist as well.
They can be used to upgrade the <tt>openpkg</tt> package at any time. A step by
d154 1
a154 1
(Quick Reference)" and <a href="http://www.openpkg.org/doc/quickref/openpkg.txt">http://www.openpkg.org/doc/quickref/openpkg.txt</a>.
d156 2
a157 2
<h3>Architecture [cs]</h3>
<h3>------------</h3>
d162 2
a163 2
<h3>Applying a package [thl]</h3>
<h3>------------------</h3>
d165 3
a167 3
To build a binary package from source with <tt>.spec</tt> defaults use <tt>rpm
--rebuild package</tt>. This will place the binary RPM into
<tt>%{l_prefix}/RPM/PKG/</tt>, therefore you need write access to that
d169 4
a172 4
OpenPKG user itself or login as root. To alter the <tt>.spec</tt> defaults unpack
the source using <tt>rpm -Uvh <i>package</i></tt>. This will "install" aka
unpack the source into <tt>%{l_prefix}/RPM/SRC/<i>package</i>/</tt>. This is
the place to edit the <tt><i>package</i>.spec</tt> file and then use <tt>rpm -bb <i>package</i>.spec</tt> to
d176 5
a180 5
process using <tt>--define "<i>variable</i> <i>value</i>"</tt>. This affects the
rebuild process without breaking it in two parts and editing the <tt>.spec</tt>
file. To install a binary package just use <tt>rpm -Uvh <i>package</i></tt>. The
output of <tt>rpm -qa</tt> gives you a list of installed packages and <tt>rpm
-qi <i>package</i></tt> lists detailed information about a installed package.
d182 2
a183 2
<tt>%{l_prefix}/etc</tt> and variable data like logfiles always go into
<tt>%{l_prefix}/var</tt>. Packages have been rigorously forced to
d185 4
a188 4
<a href="http://www.openpkg.org/tutorial.html">http://www.openpkg.org/tutorial.html</a>. You can also check a package's
integrity at any time using <tt>rpm -V <i>package</i></tt> and verify which
files have been tampered with. Finally, another usefuly query is <tt>rpm
-qf <i>/full/path/to/a/file</i></tt> which tells you to which package the given
d191 2
a192 2
<h3>Run-command facility [cs]</h3>
<h3>--------------------</h3>
d205 2
a206 2
<h3>OpenPKG RPM vs. RedHat RPM [rse]</h3>
<h3>--------------------------</h3>
d210 1
a210 1
package specifications and to build <i>every</i> package in an
d215 4
a218 4
<i>rsync</i> program by Andrew Tridgell and Paul Mackerras. It consists
of three files: the RPM specification (<tt>rsync.spec</tt>, Listing 1),
the run-commands (<tt>rc.rsync</tt>, Listing 2), and the default daemon
configuration (<tt>rsync.conf</tt>, Listing 3).
d229 1
a229 1
all OpenPKG packages to generate their file list (<tt>%files</tt>)
d232 1
a232 1
OpenPKG' RPM provides a set of local macros (<tt>%{l_xxx}</tt>) which
d234 1
a234 1
the packaging specifications. For instance the <tt>%{l_prefix}</tt>
d239 13
a251 13
The <tt>%{l_cc}</tt> macro expands to either
<i>prefix</i><tt>/bin/cc</tt> (in case the OpenPKG "gcc" package
is installed) or falls back to just <tt>cc</tt>. The same for
<tt>%{l_cflags -O}</tt>: it expands to optimized C compiler flags. In
case of gcc it expands to <tt>-O2 -pipe</tt>, else it falls back to
just <tt>-O</tt>. Similar for <tt>%{l_make}</tt> <tt>%{l_mflags}</tt>:
if <tt>%{l_make}</tt> points to a known make(1) which supports parallel
building and the underlying system has more than 1 CPU, <tt>%{l_mflags
-O}</tt> expands to the necesseary flags to leverage from SMP. For
instance, on a 2 CPU FreeBSD 4.x machine with BSD make, <tt>%{l_mflags
-O}</tt> expands to <tt>-j4 -B</tt>, on a 4 CPU Linux machine with
GNU make, <tt>%{l_mflags -O}</tt> expands to <tt>--no-print-directory
-j8</tt>.
d253 1
a253 1
Additionally, all OpenPKG packages follow <i>excactly</i> the same
d261 1
a261 1
And <i>every</i> OpenPKG package is able to build in a fully
d272 2
a273 2
it is just a matter of overriding Make variables (<tt>prefix</tt> in the
example) on the <tt>make install</tt> step, but sometimes it gets hairy.
d288 1
a288 1
versions for all other instances by running <tt>rpm --makeproxy</tt>
d295 2
a296 2
<h3>Building a package [cs]</h3>
<h3>------------------</h3>
d301 2
a302 2
<h3>?compromise between RPM package and /usr/local install [cs]</h3>
<h3>------------------------------------------------------</h3>
d306 2
a307 2
<h3>Release engineering [rse]</h3>
<h3>-------------------</h3>
d311 1
a311 1
[thl] release engineering <a href="http://www.openpkg.org/releng.html">http://www.openpkg.org/releng.html</a>
d315 2
a316 2
<h3>Conclusion [thl]</h3>
<h3>----------</h3>
d339 2
a340 2
<h2>References</h2>
<h2>==========</h2>
d342 13
a354 13
OpenPKG:<br>
<a href="http://www.openpkg.org/">http://www.openpkg.org/</a><br>
<a href="ftp://ftp.openpkg.org/">ftp://ftp.openpkg.org/</a><br>
<p>
OpenPKG Community Forums:<br>
mailto:openpkg-users@@openpkg.org<br>
mailto:openpkg-dev@@openpkg.org<br>
nntp://news.openpkg.org/openpkg.users<br>
nntp://news.openpkg.org/openpkg.dev<br>
<p>
RPM<br>
<a href="http://www.rpm.org/">http://www.rpm.org/</a><br>
<a href="ftp://ftp.rpm.org/pub/rpm/">ftp://ftp.rpm.org/pub/rpm/</a><br>
d356 2
a357 2
<h2>About the Authors</h2>
<h2>=================</h2>
d379 1
a379 5
</td>
<td width="60%">&nbsp;</td>
</tr>
</table>
<pre>
d402 6
a407 1
<img src="article.principle.eps">
d599 1
a599 1
Box: RPM handling of config files <prefix>/etc/<pkg-name>/*
d618 1
a618 1
Box: OpenPKG Summary
d639 1
a639 1
Box: BIND in 10 minutes
d692 1
a692 1
be found at http://www.openpkg.org/tutorial.html]
d695 1
a695 1
Box: OpenPKG Administration Commands (Quick Reference)
d701 1
a701 1
------------------------------------------------------------------------------
d707 1
a707 1
------------------------------------------------------------------------------
d710 1
a710 1
------------------------------------------------------------------------------
d717 1
a717 1
------------------------------------------------------------------------------
d722 1
a722 1
------------------------------------------------------------------------------
d730 1
a730 1
------------------------------------------------------------------------------
d739 1
a739 3
</pre>
</body>
</html>
@


1.39
log
@teletype better matches look and feel of previous listed commands
@
text
@d197 1
a197 1
-qf <i>/full/path/to/a/file<i></tt> which tells you to which package the given
d351 13
a363 13
OpenPKG:
<a href="http://www.openpkg.org/">http://www.openpkg.org/</a>
<a href="ftp://ftp.openpkg.org/">ftp://ftp.openpkg.org/</a>

OpenPKG Community Forums:
mailto:openpkg-users@@openpkg.org
mailto:openpkg-dev@@openpkg.org
nntp://news.openpkg.org/openpkg.users
nntp://news.openpkg.org/openpkg.dev

RPM
<a href="http://www.rpm.org/">http://www.rpm.org/</a>
<a href="ftp://ftp.rpm.org/pub/rpm/">ftp://ftp.rpm.org/pub/rpm/</a>
d373 1
a373 1

d380 1
a380 1

@


1.38
log
@html'ified http and ftp links in main text for better verification
@
text
@d158 1
a158 1
bootstrap installs itself into the new hierarchy as "openpkg" package.
d160 1
a160 1
They can be used to upgrade the "openpkg" package at any time. A step by
@


1.37
log
@corrected two dot vs. dash mistakes
@
text
@d143 1
a143 1
"Instructions to Bootstrap" http://www.openpkg.org/doc/handbook/openpkg.html#bstrap-instruct.
d163 1
a163 1
(Quick Reference)" and http://www.openpkg.org/doc/quickref/openpkg.txt.
d194 1
a194 1
http://www.openpkg.org/tutorial.html. You can also check a package's
d320 1
a320 1
[thl] release engineering http://www.openpkg.org/releng.html
d352 2
a353 2
http://www.openpkg.org/
ftp://ftp.openpkg.org/
d362 2
a363 2
http://www.rpm.org/
ftp://ftp.rpm.org/pub/rpm/
@


1.36
log
@little bit html'ificaton to better find start/end tag inconsistencies
@
text
@d149 1
a149 1
called <tt>openpkg-<i>version</i>.<i>version</i>.src.sh</tt> takes prefix, user and group as
d151 1
a151 1
<tt>openpkg-<i>version</i>-<i>version</i>-<i>architecture</i>-<i>platform</i>-<i>id</i>.sh</tt> which in turn does the
@


1.35
log
@use italic for user defined input
@
text
@d1 4
a4 3

Title    
=====
d8 2
a9 2
Subtitle 
========
d13 6
a18 5
Text
====

(entry/hanger) [thl]
--------------
d42 2
a43 2
What you see is what you get [rse]
----------------------------
d84 2
a85 2
Covering whole package lifecycles [rse]
---------------------------------
d133 2
a134 2
Getting started [thl]
---------------
d165 2
a166 2
Architecture [cs]
------------
d171 2
a172 2
Applying a package [thl]
------------------
d200 2
a201 2
Run-command facility [cs]
--------------------
d214 2
a215 2
OpenPKG RPM vs. RedHat RPM [rse]
--------------------------
d304 2
a305 2
Building a package [cs]
------------------
d310 2
a311 2
?compromise between RPM package and /usr/local install [cs]
------------------------------------------------------
d315 2
a316 2
Release engineering [rse]
-------------------
d324 2
a325 2
Conclusion [thl]
----------
d348 2
a349 2
References
==========
d365 2
a366 2
About the Authors
=================
d388 5
a392 1

d747 3
a749 1

@


1.34
log
@specfile not package
@
text
@d177 3
a179 3
the source using <tt>rpm -Uvh package</tt>. This will "install" aka
unpack the source into <tt>%{l_prefix}/RPM/SRC/package/</tt>. This is
the place to edit the <tt>package.spec</tt> file and then use <tt>rpm -bb package.spec</tt> to
d185 1
a185 1
file. To install a binary package just use <tt>rpm -Uvh package</tt>. The
d187 1
a187 1
-qi package</tt> lists detailed information about a installed package.
d193 1
a193 1
integrity at any time using <tt>rpm -V package</tt> and verify which
d195 1
a195 1
-qf /full/path/to/a/file</tt> which tells you to which package the given
@


1.33
log
@remember one more interesting point
@
text
@d179 1
a179 1
the place to edit the <tt>package.spec</tt> file and then use <tt>rpm -bb package</tt> to
@


1.32
log
@Hell, too much text, too much text. But ok, let us compress
it later after we cleaned up the whole article at once.
@
text
@d316 1
@


1.31
log
@Thomas Lotterer is ...
@
text
@d215 1
a215 1
As already known, OpenPKG is based on an adjusted and unique RPM-based
d227 4
a230 1
XXX
d232 69
a300 6
[rse] where OpenPKG RPM differes from RedHat/SuSE RPM usage: rpmtool,
shtool, %files generating (uninstall), %l_xxxx variables, strict style, no
auto-dependencies, etc.
[cs] build as non-root user, install as root
buildroot
[rse] proxy packages
@


1.30
log
@i forgot /etc/shells
@
text
@d305 6
a310 1
Thomas Lotterer is...
@


1.29
log
@fixed typos, added tags, rephrase; rse please fix the FIXME (i miss a date)
@
text
@d154 1
a154 1
functions to alter PAM configuration or they might tell you to tune the
@


1.28
log
@Conclusion - i really need a "strip" command
@
text
@d35 4
a38 3
why it cluttered up your /etc with config files? Successfully installed
a network daemon but a week later the /var filesystem runs out of space
because a logfile was never rotated? OpenPKG comes to the rescue!
d69 1
a69 1
to not depend on minimal external Unix facilities, has to install with
d122 1
a122 1
developer and also plays with databases) and runs a tuned environment,
d140 2
a141 1
required environment is listed on http://www.openpkg.org/FIXME.
d146 2
a147 2
with a (actually three) user and group.  A generic bootstrap script
called openpkg-VERSION.VERSION.src.sh takes prefix, user and group as
d149 2
a150 2
openpkg-VERSION-VERSION-ARCH-PLAT-PREFIX.sh which in turn does the
actual installation. We put every efford into the bootstrap logic so
d157 1
a157 1
You might notice that .rpm versions of the bootstrap exists as well.
d172 1
a172 1
To build a binary package from source with .spec defaults use <tt>rpm
d176 1
a176 1
OpenPKG user itself or login as root. To alter the .spec defaults unpack
d179 8
a186 8
the place to edit the package.spec file and use "rpm -bb package" to
build the binary and place it into the same location as --rebuild would
have done. Introduced with OpenPKG-2002FIXME and incorporated into
OpenPKG v1.1 is a feature to define a variable along with the --rebuild
process using <tt>--define "variable value"</tt>. This affects the
rebuild process without breaking it in two parts and editing the .spec
file. To install a binary package use <tt>rpm -Uvh package</tt>.  The
output of <tt>rpm -qa</tt> is a list of installed packages and <tt>rpm
d191 2
a192 2
conform to that specification. For another step by step example see
http://www.openpkg.org/tutorial.html. You can check a package's
d206 6
d258 1
a258 1
When the OpenPKG project was born in november 2000, the hardest work
d260 1
a260 1
first use in a production environment was april 2001 at a large ISP
d262 2
a263 2
released to the public in january 2002 as a mature product with 167
packages included. The successful project is contiuously improved and
d270 1
a270 1
OpenPKG instances. We plan to expand OpenPKG packages to the desktop
a589 1
[thl FIXME user running --rebuild must belong to group opkg (i.e. user opkg) or must be root]
@


1.27
log
@embed am manifest important information
@
text
@d250 20
@


1.26
log
@Applying a package - quota exceeded again
@
text
@a249 7
[rse] born in November 2000, in production since April 2001, first release Januar 2002
successful in production since april 2001 at a large ISP.
ready to use as a mature product.
open to your contribution.
frontend (c/s, RDF), more packages (desktop, splitted)
technology enhancements (rc, shared libraries)
[rse] forthcoming: RPM 4.0.4/4.1, frontend, reimplemented rc, etc.
a541 1
[thl Pay attention you have a working C compiler in your PATH!]
d543 1
@


1.25
log
@Getting started - quota exceeded :-)
@
text
@d170 25
a194 3
rebuild, Uvh, -qa, -qi, -V bind
example: bind in 10min box
mention %{l_prefix}/etc, %{l_prefix}/var logs
@


1.24
log
@entry/hanger
@
text
@d133 27
a159 6
reference platform support box
[cs] required vendor packages as well as third party (ANDIrand, no
detailed package list but reference web site)
decision user/group, prefix
bootstrapping, example: bind in 10min box
[thl] quickref box, http://www.openpkg.org/doc/quickref/openpkg.txt
d526 1
a526 1
Box: BIND in 15 minutes
@


1.23
log
@flush my work
@
text
@d18 20
a37 1
keypoints addressed by short rhetorical questions
@


1.22
log
@flush my work of today's evening
@
text
@d151 7
a157 2
Let's look at an example (Listing 1), the OpenPKG RPM specification
(<tt>bash.spec</tt>) for GNU Bash.
d257 163
a419 1
Listing 1: OpenPKG RPM Specification for GNU Bash
d421 23
@


1.21
log
@ops, missing a header
@
text
@d5 1
a5 1
Cross-Platform Packaging
d10 1
a10 4
Applying RPM to arbitrary Unix platforms with OpenPKG
FIXME [thl] (it's not about RPM, RPM is only a means to an end)
Applying open source software to arbitrary Unix platforms using OpenPKG
(and to some extend software available in binary format only, too)
d23 38
a60 12
Open Source development model and result
article.principle.fig
[rse] targeted at server platforms (coming from an ISP ;)
target community, large installations, diverse Unix platforms, [cs] goal of the projects
[cs] all packages developed from scratch, strict style guide for spec files
[rse] RPM 4 based with extensions (rpmtool, bootstrap, lsync, etc.)
[rse] cross-platform (FreeBSD, Linux, Solaris and more)
[rse] support for multiple installation instances
[rse] over 300 packages
[rse] minimal OS intrusion
[rse] reasonable pre-configuration
logfile rotation
d65 45
a109 8
[cs] why did we choose RPM (and not ports, dpkg, ...)
RPM is a 90% solution covering whole package lifecycle
[rse] smoothing the differences between vendor approaches
[cs] project is focused on building from src (apache+mod_ssl+mm max shared
mem size determined under build time, differences between build and
install environments i.e. shared libraries, paths), not using binary
packages (except for bootstrapping i.e. no devtools available, emergency
tough time constraints)
d145 9
d230 26
a295 22
Box: OpenPKG Unix Platform Support
------------------------------------------------------------------------------
Unix Platform        Version     Amount of Support
==================== =========== ===================
FreeBSD              4.x/5.0-C   fully supported
Debian GNU/Linux     2.2/3.0pre  fully supported
RedHat Linux         6.x/7.x     fully supported
Sun Solaris          2.6/7/8     fully supported
NetBSD               1.5.x       fully supported
OpenBSD              2.9         partially supported
HP/UX                10.20       partially supported
Compaq Tru64         5.0         partially supported

[thl] FIXME why mention versions of unsupported platforms - why even mention
unsupported platforms? The only reason to mention no support is when it
doesn't work by design or to announce forthcoming support. Neither is the
case here.

Caldera OpenUNIX     8.0         not yet supported
IBM AIX              4.x         not yet supported
SGI IRIX             6.x         not yet supported
------------------------------------------------------------------------------
@


1.20
log
@use a consistent heading to get better optical structuring while hacking in parallel
@
text
@d50 1
d52 2
@


1.19
log
@structure and push down list
@
text
@d2 2
a3 1
Title:    
d7 2
a8 1
Subtitle: 
d11 1
a11 2

[thl] (it's not about RPM, RPM is only a means to an end)
d15 2
a16 1
Text:
d19 3
a21 1
  keypoints addressed by short rhetorical questions
d24 14
a37 12
  Open Source development model and result
  article.principle.fig
  [rse] targeted at server platforms (coming from an ISP ;)
  target community, large installations, diverse Unix platforms, [cs] goal of the projects
  [cs] all packages developed from scratch, strict style guide for spec files
  [rse] RPM 4 based with extensions (rpmtool, bootstrap, lsync, etc.)
  [rse] cross-platform (FreeBSD, Linux, Solaris and more)
  [rse] support for multiple installation instances
  [rse] over 300 packages
  [rse] minimal OS intrusion
  [rse] reasonable pre-configuration
  logfile rotation
d40 1
a40 8
  [cs] why did we choose RPM (and not ports, dpkg, ...)
  RPM is a 90% solution covering whole package lifecycle
  [rse] smoothing the differences between vendor approaches
  [cs] project is focused on building from src (apache+mod_ssl+mm max shared
  mem size determined under build time, differences between build and
  install environments i.e. shared libraries, paths), not using binary
  packages (except for bootstrapping i.e. no devtools available, emergency
  tough time constraints)
d42 8
d51 6
a56 6
  reference platform support box
  [cs] required vendor packages as well as third party (ANDIrand, no
  detailed package list but reference web site)
  decision user/group, prefix
  bootstrapping, example: bind in 10min box
  [thl] quickref box, http://www.openpkg.org/doc/quickref/openpkg.txt
d59 4
a62 2
  article.layout.fig
  [cs] strict file system layout (configs in %{l_prefix}/etc, user/group ...)
d65 5
a69 3
  rebuild, Uvh, -qa, -qi, -V bind
  example: bind in 10min box
  mention %{l_prefix}/etc, %{l_prefix}/var logs
d72 6
a77 4
  example explained: bind in 10min box, disabling server to get tools only
  [rse] flexible and unique run-command facility (rc --eval, --config, --query)
  [cs] flexible runtime configuration via rc.conf
  sample rc file box
d80 8
a87 6
  [rse] where OpenPKG RPM differes from RedHat/SuSE RPM usage: rpmtool,
  shtool, %files generating (uninstall), %l_xxxx variables, strict style, no
  auto-dependencies, etc.
  [cs] build as non-root user, install as root
  buildroot
  [rse] proxy packages
d90 4
a93 2
  reference a simple .spec file (bash)
  [rse] very concise RPM specifications with minimal redundancy
d96 3
a98 1
  [rse] lsync and the <prefix>/local area
d101 6
a106 4
  [cs] how do we treat security issues, security advisory, signed package, package integrity
  [thl] release engineering http://www.openpkg.org/releng.html
  [cs] organisation of FTP server (release, current (= unstable)
  [rse] automatic vendor source version tracking -> always up-to-date very fast
d109 48
a156 7
  [rse] born in November 2000, in production since April 2001, first release Januar 2002
  successful in production since april 2001 at a large ISP.
  ready to use as a mature product.
  open to your contribution.
  frontend (c/s, RDF), more packages (desktop, splitted)
  technology enhancements (rc, shared libraries)
  [rse] forthcoming: RPM 4.0.4/4.1, frontend, reimplemented rc, etc.
a320 32

References:

OpenPKG:
http://www.openpkg.org/
ftp://ftp.openpkg.org/

OpenPKG Community Forums:
mailto:openpkg-users@@openpkg.org
mailto:openpkg-dev@@openpkg.org
nntp://news.openpkg.org/openpkg.users
nntp://news.openpkg.org/openpkg.dev

RPM
http://www.rpm.org/
ftp://ftp.rpm.org/pub/rpm/

About the Authors:

Ralf S. Engelschall is a computer scientist and Open Source software
hacker, living in Munich, Germany. He is the author of well-known
software like Apache mod_ssl, GNU Pth, GNU Shtool. He is also the
founder of the Open Source software projects OpenSSL, OpenPKG and OSSP.
He can be contacted at: rse@@engelschall.com

Christoph Schug is senior unix system administrator at Cable & Wireless
Germany. Leading the hosting department he is responsible for all managed
servers at Cable & Wireless Munich data center. When not just having
revolutionary ideas and visions which often result in /some/ lines in
Ralf's TODO file you can encounter him in the Alps with screaming and
smoking tires of his Miata MX-5 roadster :)
He can be contacted at: chris@@schug.net
@


1.18
log
@BIND in 15 minutes
@
text
@d16 79
a94 1
...
@


1.17
log
@Platform Support
@
text
@a79 1

d81 1
d83 2
a84 2
$ cd /tmp
$ ftp ftp.openpkg.org
d98 37
a134 17
$ sh openpkg-1.0.1-1.0.1.src.sh --prefix=/usr/opkg --user=opkg --group=opkg
$ su -
# sh openpkg-1.0.1-1.0.1.*-uo.sh
# exit
$ /usr/opkg/bin/rpm --rebuild \
  ftp://ftp.openpkg.org/release/1.0/SRC/bind-8.2.5-1.0.0.src.rpm
$ su -
# /usr/opkg/bin/rpm -Uvh \
  /usr/opkg/RPM/PKG/bind-8.2.5-1.0.0.*-uo.rpm
# /usr/opkg/etc/rc bind start
# exit
$ /usr/opkg/bin/dig @@localhost www.openpkg.org
$ su -
# /usr/opkg/etc/rc bind stop
# /usr/opkg/bin/rpm -e bind bash openpkg
# exit
$ 
@


1.16
log
@RPM; config table
@
text
@d69 10
a78 4
Tru64                5.0         partially supported
OpenUNIX             8.0         still not supported
AIX                  4.x         still not supported
IRIX                 6.x         still not supported
@


1.15
log
@- the .rpmmacros box perhaps is too much so move it out at all
- the layout I'll provide as an external graphical figure
@
text
@d10 4
d23 6
a28 6
X        X          X        X          keep old config, but re-install
X        X'         X'       X'         keep old config, but re-install
X        X'         X        X'         keep old config
X        X          Y        Y          install new config
X        X'         Y        Y          install new config, preserve X' as .rpmsave
-        X          Y        Y          install new config, preserve X  as .rpmorig
@


1.14
log
@flush my work
@
text
@a13 57
Box: OpenPKG filesystem layout
------------------------------------------------------------------------------
<prefix>/
RPM
DB
PKG
SRC
TMP
bin
cgi
etc
include
info
lib
libexec
local
man
sbin
share
var
web
------------------------------------------------------------------------------

Box: Speed-up build times by using RAM based </tt>/tmp</tt> filesystem
------------------------------------------------------------------------------
All modern Unix platforms support RAM based filesystems. For performance

FIXME: this is not true for Linux 2.2 kernels

reasons it is always reasonable to mount such a filesystem under
<tt>/tmp</tt>. For OpenPKG's major platforms, this can be achieved with
the following entries in the system filesystem table:

<tt>
  # FreeBSD 4.x, /etc/fstab:
  /dev/ad0s1b /tmp mfs rw,async,noatime,nosuid,nodev 0 0

  # Linux (Kernel 2.4.x), /etc/fstab:
  tmpfs /tmp tmpfs size=64m,noatime 0 0

  # Solaris 8, /etc/vfstab:
  swap - /tmp tmpfs - yes -
</tt>

If such a <tt>/tmp</tt> is available, is is recommended to redirect
OpenPKG's RPM to place there all its temporary data while building
packages. This dramatically speeds up the build times. For this, just
create a <tt>~/.rpmmacros<tt> file in the home directory of the user
running <tt>rpm --rebuild</tt> or <tt>rpm -bb</tt>:

<tt>
  # ~/.rpmmacros -- OpenPKG RPM local macro definitions
  %_builddir  /tmp/openpkg-%{l_location}-%{l_whoami}
  %_tmppath   /tmp/openpkg-%{l_location}-%{l_whoami}
</tt>
------------------------------------------------------------------------------

@


1.13
log
@Solaris 8 should be called Solaris 8. This is the official name and release
number (and not 2.8). Also fixed other version numbers and added FIXME comment
@
text
@d14 23
d180 1
a180 1
$ <prefix>/bin/rpm -qpi <pkg-bin>                list information about binary package:
d184 1
a184 1
$ <prefix>/bin/rpm -qlv <name>                   list all files a package has installed:
d211 1
a211 1
OpenPKG
d214 6
@


1.12
log
@more food
@
text
@d17 3
d31 1
a31 1
  # Solaris 2.8, /etc/vfstab:
d93 1
a93 1
Debian GNU/Linux     2.x/3.0pre  fully supported
d95 1
a95 1
Sun Solaris          2.6/2.7/2.8 fully supported
@


1.11
log
@flush today's work
@
text
@d14 51
a64 1
Figure: OpenPKG Summary
d85 1
a85 1
Figure: OpenPKG Unix Platform Support
d102 1
a102 1
Figure: BIND in 15 minutes
d138 1
a138 1
Figure: OpenPKG RPM Commands Quick Reference
@


1.10
log
@flush my work for today
@
text
@d52 1
a52 1
Figure: BIND in 15 minutes with OpenPKG
d90 41
a130 27
# <prefix>/bin/rpm -Uvh <bin-rpm>              install/upgrade package
# <prefix>/bin/rpm -Uvh --nodeps <bin-rpm>     install/upgrade package (no dependency check)
# <prefix>/bin/rpm -Uvh --force <bin-rpm>      install/upgrade package (no checks at all)
# <prefix>/bin/rpm -Uvh --oldpackage <bin-rpm> install/downgrade package
# <prefix>/bin/rpm -Fvh <bin-rpm>              freshup existing package
# <prefix>/bin/rpm -e <pkg-name>               erase package
# <prefix>/bin/rpm -Uvh <src-rpm>              install source of a package
# <prefix>/bin/rpm -bb <pkg-spec>              build binary package from installed source
$ <prefix>/bin/rpm --rebuild <src-rpm>         rebuild binary package from source package
$ <prefix>/rpm -qpi <bin-rpm>                  list information about binary package:
$ <prefix>/rpm -qplv <bin-rpm>                 list all files a binary package will install
$ <prefix>/rpm -qa                             list all installed packages and their versions
$ <prefix>/rpm -qi <name>                      list information about an installed package
$ <prefix>/rpm -qlv <name>                     list all files a package has installed:
$ <prefix>/rpm -Va                             check the integrity of all packages
$ <prefix>/rpm -V <name>                       check the integrity of a particular package
$ <prefix>/rpm -Va --nofiles                   check all package dependencies only
$ <prefix>/etc/rc --config                     show all %config variables and values
$ <prefix>/etc/rc --query <variable>           query a particular %config variable
$ eval `<prefix>/etc/rc --eval all env`        setup shell environment of all packages 

Variable:  Example:
<prefix>   /usr/opkg
<pkg-name> bash
<pkg-spec> bash.spec
<src-rpm>  bash-2.05a-1.0.0.src.rpm
<bin-rpm>  bash-2.05a-1.0.0.ix86-freebsd4.5-uo.rpm
@


1.9
log
@start with the easier things like the stand-alone figures
@
text
@d14 38
@


1.8
log
@remember to have the Email addresses there, too.
@
text
@d14 67
@


1.7
log
@fill in most important references
@
text
@d30 1
d38 1
@


1.6
log
@use their official name for this article part
@
text
@d12 12
@


1.5
log
@Spam? No ;-)
@
text
@d12 1
a12 1
Biography of Authors:
@


1.4
log
@move stuff to brainstorm.txt
@
text
@d19 6
a24 1
Christoph Schug is Mr. TODO-list-spamming... <fill-it-in-yourself> ;)
@


1.3
log
@three more important points to address in the article
@
text
@d2 1
a2 2
Cross-Platform RPM with OpenPKG
===============================
d4 1
a4 2
TODO
----
d6 14
a19 11
- born in November 2001, in production since April 2001, first release Januar 2002
- cross-platform (FreeBSD, Linux, Solaris and more)
- RPM 4 based with extensions (rpmtool, bootstrap, lsync, etc.)
- over 300 packages
- support for multiple installation instances
- targeted at server platforms (coming from an ISP ;)
- smoothing the differences between vendor approaches
- reasonable pre-configuration
- very concise RPM specifications with minimal redundancy
- flexible and unique run-command facility
- minimal OS intrusion
@


1.2
log
@remember first points
@
text
@d16 3
@


1.1
log
@Open an area for the SysAdmin magazine article
and remember the current state.
@
text
@d5 12
@