path: root/trunk/doc/README

Simplepkg: installation manager and metapackage system
------------------------------------------------------

Author: Silvio Rhatto <rhatto at riseup.net>
Licence: GPL

Simplepkg is a non-intrusive package management system running on top of pkgtool.
It uses templates -- lists of installed packages, scripts and configuration files
-- allowing the creation of installation profiles that can be used do install a
complete and configured slackware system in another partition or to create chroot
environments. The same templating scheme extends slackware packaging system, adding
metapackages: a list of packages installed or removed with a single command.

Documentation
-------------

  English documentation: README | http://slack.sarava.org/node/15
  Portuguese documentation: REAMDE.pt_BR | http://slack.sarava.org/node/12

Description
-----------

All GNU/Linux distributions comes with a well developed packaging system. The question now
is how pratical is the way to install, configure and control any changes in a system.

As an example, suppose you should keep a list of about 200 slackware machines, some
of them used as desktops, others as mail or webservers. If you lost some hardrives
or usually need to re-install or update some of those boxes.

Using the slackware installation cd and configuring by hand all the time you got a crash
is a time loss activity and you'll never know if something remained missconfigured. An
alternative is to keep a complete backup of a machine or some parts of the tree, but for
a large number of different boxes this procedure costs a lots of resources.

Simplepkg offers an alternative sollution for this and other problems related to installation
management, allowing you to keep templates of each machine and install a custom slackware
system with just one or a few commands. Creating and upgrading chroot and vservers is easy
with simplepkg.

Architecture
------------

Simplepkg is a set of scripts wrote in the KISS philosophy. Its a pretty simple system, composed
by the following commands:

   - mkjail: build a slackware jail/installation in a folder
   - metapkg: install or remove a metapackage
   - templatepkg: create or update a package list of an installation template
   - lspkg: show installed packages and its contents
   - jail-upgrade: upgrade all or some of the jails/installations 
   - jail-update: update all configuration files of a template
   - rebuildpkg: rebuild a package based on its /var/log/packages entry
   - simplaret: package retrieval tool
   - createpkg: donwload, compile and package creationg script based on http://slack.sarava.org/slackbuilds

Simplepkg configs are placed at /etc/simplepkg. Templates are .template files containing an one-by-line
package list. A template can be something like this:

  aaa_base
  aaa_elflibs
  apache
  bash
  bin
  coreutils
  findutils

Slackware's tagfile format can be used too as a template.

Installation
------------

The latest version of simplepkg is locate at http://slack.sarava.org/packages/noarch/.
Install it with the usual way:

  installpkg simplepkg-VERSION-noarch-BUILD.tgz

If you have a working swaret on your system, add this line on you swaret.conf:

  REPOS_ROOT=SlackMidiataticaNoarch%http://slack.sarava.org/packages/noarch

and then issue those commands:

  swaret --update
  swaret --install simplepkg

Configuration
-------------

As an example, we'll create a jail based on the packages installed in your slackware
system. Edit the config file /etc/simplepkg/simplepkg.conf:

  # /etc/simplepkg/simplepkg.conf
  JAIL_ROOT="/vservers" # where jails are placed
  SIMPLARET="simplaret" # package grabber program (can be swaret if you have it installed)
  SIMPLARET_CLEAN="1" # clean package cache before installation
  SIMPLARET_DELETE_DOWN="1" # clean package cache after the installation
  SIMPLARET_UPDATE="0" # issue an simplaret --update before install the jail
  SIMPLARET_PURGE_WEEKS="N" # delete packages older than N weeks from the cache
  PATCHES_DIR="/storage/package/patches" # where patches are placed
  DEFAULT_ARCH="i386"
  DEFAULT=VERSION="10.2"
  STORAGE="/storage/packages" # where simplepkg store packages
  PASSIVE_FTP="1"

You should also put in /etc/simplepkg/repos.conf all package repositories you use, like this:

  ROOT-i386="http://slack.sarava.org/packages/slackware"
  REPOS-i386="slack-sarava%http://slack.sarava.org/packages/slackware/slackware-10.2/"
  ROOT-x86_64-10.2="http://darkstar.ist.utl.pt/pub/slamd64/"
  REPOS-x86_64-10.2="slamd-sarava%http://slack.sarava.org/packages/slamd64/slamd64-10.2/"

Instead of simplaret you can use swaret to fetch packages and them your swaret.conf must
be configured to use the same place as STORAGE to the package cache. In this case you cant
keep installations and jails with multiple arquitetures and for that reason the use of
simplaret is recommended.

Creating jails and replicating installations
--------------------------------------------

  templatepkg my-slackare
  mkjail jail my-slackware

The previous commands creates a template called my-slackware from based on your installed
softwares listed in /var/log/packages and then creates a completely new slackware
tree with all those packages in the folder /vservers/jail (depending on the value of JAIL_ROOT from
your simplepkg.conf).

If you want that some config files get copied or some scripts executed after install this jail,
place in the folder /etc/simplepkg/my-slackware.d all your config files (preserving the file
system hierarchy, i.e, /etc/simplepkg/my-slackware/etc/apache/httpd.conf) and the scripts at
/etc/simplepkg/my-slackware.s/. The template vserver, which comes in the simplepkg package, has
an example script to use with mkjail.

You can specify an alternative destination for your jail with a command like

  ROOT=/mnt mkjail hda2 my-slackware

This does exactly what you think: installs slackware in /mnt/hda2 with exactly the same packages
you have on your system, replacing the need of the slackware installer!

In case no template specified, mkjail uses the one called /etc/simplepkg/default.template.

If you keep your jails in JAIL_ROOT with the same name as the template you used to create it, its
possible to use the command jail-update to copy all modifications made in the files which their
counterparts are placed at /etc/simplepkg/jail-name.d. Then you can copy all configuration files
you edited to the template folder and leave a crontab entry to everyday seek for changes and update
the template. When you issue the command

  jail-update

all jails listed in /etc/simplepkg/jaillist are updated. This command also updates the package list
of the template.

To add or remove packages from a template, you can just edit by hand the template file or use the
command templatepkg with the -a (append) flag, which adds just the new installed packages in the
template file. 

If you want to create a template from a jail, use

  templatepkg jail /vservers/jail

Metapackages
------------

Another use for the templates is the creation of metapackegs: new users have lots of difficulties
to track dependencies when installing a software. Using a template containing the name of all
packages needed by some program allow users to easily install it through the command

  metapkg --install program-name

This seems like swaret or slapt-get, with the only difference in the way metapkg deals with
dependence resolution. Slapt-get support the slack-required file, wich comes or not with the
package. Swaret has its own tool for dependence matching.

Simplepkg doesn't wish to substitute those two dependence checking modes, but offer an alternate
way to distribute packages where dependences are resolved without an specific tool or a change
in the package itself.

A metapackage, i.e, all installed packages from a template, can be removed with 

  metapkg --remove program-name

Upgrading jails
---------------

Both the main installation (your root system) and your jails are upgraded with the command
jail-upgrade: just adjust simplepkg.conf's PATCHES_DIR to where you store slackware patches
(that can be rsync'ed everyday) and do a

  jail-upgrade

This will upgrade your main system and all jails living in JAIL_ROOT. To specify another
folder, use

  ROOT=/otherroot jail-upgrade

If you want to upgrade just one specific jail,

  jail-upgrade jail-name

To use a patches folder other than PATCHES_DIR, e.g when you have jails with different
slackware versions, use
 
  PATCHES=/alternative/patches/folder jail-upgrade jail-name

Different archs and versions
----------------------------

Simplepkg was idealized to permit a template to create jails from any architecture and version
of a slackware-like system. Upgrading tasks also are unified. This feature just works if you
use simplaret and not swaret as the package retrieval tool.

As another example, to create an slack 10.1 installation (assuming your /etc/simplepkg/repos.conf with
the right configuration), just type

  VERSION=10.1 mkjail my-jail server-template 

Different archs can be used too. If you have a x86_64 system and wants to install a slack 10.2
in a partition, try something like

  ARCH=i386 VERSION=10.2 ROOT=/mnt mkjail hda2 my-slackware

Note that the templates are arch and version independent, as they just contain package names,
configuration files and scripts. For this reason, the commands templatepkg, metapkg, lspkg and
jail-update can be used normaly.

To upgrade jails with othes archs and versions, jail-upgrade checks this information through
/etc/slackware-version for each jail and applies the correspondent patches grabed from
simplaret (see the proper documentation).

By this way, doesn't matter which versions and archs each of your jails has, jail-upgrade remains
the same since your patches are sorted by arch an version, as explained in simplaret documentation
found at http://slack.sarava.org/node/17.

Auxiliar applications: rebuildpkg and createpkg
-----------------------------------------------

Simplepkg comes with an additional helper tool that recover installed packages which the original
.tgz file was lost. The command rebuildpkg rebuilds a package from their entry in /var/log/packages.
As an example,

  rebuildpkg coreutils

rebuilds the coreutils package using the files, scripts and metainformations stored in
/var/log/packages/ and /var/log/scripts/.

If you want to build you own packages using the scripts available from http://slack.sarava.org/slackbuilds,
use the createpkg script:

  createpkg package-name

Source
------

Source code for simplepkg and its package builder can be fetched via subversion:

  svn checkout svn://slack.sarava.org/simplepkg