Creating Packages/Install files

Contents

Starting point

This guide is dedicated to packaging Net Responsibility for different platforms. I've only done packaging for Ubuntu, so that's my starting point. Note that I'll only discuss Net Responsibility related things to keep in mind while packaging, rather than the actual packaging steps and how it's done in different environments.

Compile from scratch

First you need to download the source code (the tarball, not the trunk) and make sure Net Responsibility is correctly compiled, installed and running on the platform you're building for. Compilation instructions may be found here. If you're getting stuck here you may consult the Installation board on our forum. Note that you may specify some installation directories explicitly with arguments such as —prefix —pkgdatadir —with-initdir —with-databasedir —with-piddir etc.

About automated package software

We encourage any packager to make and maintain packages, but please do not use automated packaging software where one can't control everything that happens in the packaging process. It is also never a good idea to convert packages to another format (such as deb to rpm), if you want to publish the packages to a broader target.

POCO C++ Library

Net Responsibility heavily relies on the POCO C++ library, so first check if it is available as a package for your platform. It has to be version 1.4.0 or later. If it isn't, you'll need to either create a separate package, or include the library in your Net Responsibility package. For most platforms alternative one is preferable, and then make Net Responsibility depend on that package.

Install scripts

During the installation step, some essential actions are performed, wrapped up in three scripts. These scripts are called postinst, prerm and postrm. The two first are found in the directory ./scripts. However you may have to tweak them a bit to suit your needs. If there is a template for writing them in your environment, it's recommended to use that as your base, and then insert all the code needed from the scripts shipped with Net Responsibility. Make sure you understand how the script is called (which arguments are specified). This may be more or less unique for every package format. If your package format doesn't use these scripts, you still need to make sure all steps are performed in the right order somehow.

Postinst script

The postinst script is run right after all files are in place. It's purpose is to, if not done before, configure Net Responsibility, make the software start on boot and shut down on halt (install the init script), and start an instance of Net Responsibility.

Specific directories

Open up scripts/postinst in your favorite text editor. The first lines to pay attention to looks like this:

pkgdatadir=$1
initdir=$2

Pkgdatadir is the folder that contains important data files used by Net Responsibility. In Debian it's found at /usr/share/net-responsibility. Initdir is the folder where your system puts init scripts. I will shortly explain a little more what the init scripts are. This postinst script is called by make with two arguments, the paths to both pkgdatadir and initdir. However, your package manager may call the postinst in a very different way, and then the variables $1 and $2 can't be used for this purpose. In that case you'll have to specify the correct paths using another technique. In most Linux distros you may specify a hardcoded path. Correct me if I'm wrong here. If you know where the data files will be put, and where init scripts are stored, just specify them like this:

pkgdatadir=/usr/share/net-responsibility
initdir=/etc/init.d

On some platforms the paths may be specified during the installation process, and then you'll need to determine the correct path.

Next comes an if-statement. Here we check if Net Responsibility is already configured. That's done with the following command:

if ! [ -f $pkgdatadir/config.xml ]; then

If the file $pkgdatadir/config.xml is found, then we can assume Net Responsibility is configured correctly before. It is very important to do this kind if check, or else one will need to reconfigure every time one is upgrading or reinstalling the software.

Configure

The next thing to do, if Net Responsibility is not configured earlier, is to make the $pkgdatadir/reports dir. That's where the attached reports are temporarily stored. We also want to set up the users account and send an installation mail to the accountability partners. In the regular installation from source this is done with these two lines:

mkdir $pkgdatadir/reports
net-responsibility --install

That's fine, since we can assume our users are in a terminal when installing the software. However, the packages are installed differently. We cannot assume direct interaction with the user. Therefore it is always preferred to use the package manager's configuration utility, if there is one. Debian for example, is using debconf. Then the username and password is asked early in the installation process, unless config.xml is found, and stored in a database. Later in the postinst, these values are loaded and explicitly specified to Net Responsibility like so:

db_get net-responsibility/username || true
username="$RET"
db_get net-responsibility/password || true
password="$RET"
if [ "$username" != "" ] && [ "$password" != "" ]; then
  net-responsibility --install --username=$username --password=$password
fi

You don't need to understand every command, more the concept. Store the values in $username and $password and run:

net-responsibility --install --username=$username --password=$password

If the username and password is stored in a database, you need to clear out that information as soon as you're done with the configuration.

Note: If you're package format doesn't provide any configuration utility, you need to tell the user to run "net-responsibility —install" after the package is installed!

Init script

Next we come to the init script. Net Responsibility need to start every time the computer is booted. In many platforms this is done using an init script. The script shipped as default with Net Responsibility (scripts/init.d), is customized for Debian based systems. You may need to write your own for the specific platform you're targeting. The init script needs to get installed. It's good practice not to store the init script directly in the initdir. Instead it's stored as $pkgdatadir/init.d. So first you need to make a symlink to the initdir. Consult with your system's documentation on how to install the init script. In a regular make installation, the postinst script will try different commands and use the first one that seems to work. That procedure looks like this.

ln -s -f $pkgdatadir/init.d $initdir/net-responsibility
if command -v update-rc.d &>/dev/null # Debian, Ubuntu
then
  update-rc.d net-responsibility defaults
elif command -v chkconfig &>/dev/null # Red Hat, Fedora
then
  chkconfig --add net-responsibility
elif command -v rc-update &>/dev/null # Gentoo
then
  rc-update add net-responsibility default
elif command -v innserv &>/dev/null # OpenSuse
then
  innserv $initdir/net-responsibility
fi

Once you know which command you need, you won't have to run all these tests. Simply make the symlink and use your specific command to install the init script.

Start Net Responsibility

The last operation in the postinst script is to start an instance of Net Responsibility. Depending on your system it may be done with different commands. In Debian one is supposed to use "invoke-rc.d net-responsibility start". One can also use "net-responsibility —daemon" as done in the regular make installation.

That's it. You're done with the first script, only two left.

Prerm script

The prerm script is run when one is uninstalling Net Responsibility, before actually deleting the files. It is pretty similar to postinst. The $pkgdatadir and $initdir is handled the same way, so I won't go through them again.

The following two if-statements looks like follows:

if [ -f $initdir/net-responsiblity ]; then
  $initdir/net-responsibility stop
fi
if [ -f $pkgdatadir/config.xml ]; then		
  net-responsibility --uninstall
fi

First, if the symlink is found, we stop the running instance of Net Responsibility. The command to stop a daemon using the init script may look different on your platform. Debian uses "invoke-rc.d net-responsibility stop".

Second, if the config file exists (which means the software is configured), we need to send an uninstallation mail to be sent. That's done using the —uninstall argument.

The last operation is to uninstall the init script. That's usually done with the same command as you install it with, except you change some value or argument. In Debian it's done with "update-rc.d -f net-responsibility remove".

Postrm script

The last script to look at is postrm. Logically it's run after all files are removed. The only thing done is to remove some more files created either by the install scripts or by Net Responsibility itself. You won't find any postrm script in the scripts folder, instead you need to open Makefile.am. Near the end you'll find these lines:

postrm:
 -f $(piddir)/net-responsibility.pid
 -f $(pkgdatadir)/blacklist.xml
	rm -f $(pkgdatadir)/config.xml
	rm -rf $(pkgdatadir)/reports
	rm -f $(databasedir)/net-responsibility.db
	rm -f $(initdir)/net-responsibility

Copy and paste in your postrm script (except for the first line that specifies a make target - "postrm:"). Note that postrm may be run even when upgrading to a newer version. Therefore you may have to check if the package is really removed, or only upgraded. The arguments specified may tell you. You're familiar with $pkgdatadir and $initdir by now, but $piddir and $databasedir are new. Well, in Debian the postrm would look something like this:

rm -f /var/run/net-responsibility.pid
rm -f $pkgdatadir/blacklist.xml
rm -f $pkgdatadir/config.xml
rm -rf $pkgdatadir/reports
rm -f /var/log/net-responsibility.db
rm -f $initdir/net-responsibility

Edit Makefile

When building the package, your environment will probably use the makefile. Therefore you'll have to do some changes. Open up Makefile.am and delete all these lines:

install: install-am postinst

uninstall: prerm uninstall-am postrm

postinst:
	$(top_srcdir)/scripts/postinst $(pkgdatadir) $(initdir)

prerm:
	$(top_srcdir)/scripts/prerm $(pkgdatadir) $(initdir)

postrm:
	rm -f $(piddir)/net-responsibility.pid
	rm -f $(pkgdatadir)/blacklist.xml
	rm -f $(pkgdatadir)/config.xml
	rm -rf $(pkgdatadir)/reports
	rm -f $(databasedir)/net-responsibility.db
	rm -f $(initdir)/net-responsibility

.PHONY: prerm postinst postrm

All this information is now found in your own customized scripts, so just make sure they're invoked instead.

The next step

That's about it. Feel free to consult the mailing list responsibility-devel@lists.sourceforge.net for help, but keep in mind that you'll get better answers elsewhere for issues that has to do with your specific packaging environment. However we may be able to help each other a bit on the way. When trying to answer questions it is also a huge help to know which OS you're running and what kind of package you're trying to create.

We are interested in any package that is successfully built, as well as new init scripts.