path: root/trunk/doc/README

Simplepkg: installation manager and packaging system
----------------------------------------------------

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

Simplepkg is a non-intrusive management system running on top of pkgtool made of a
set of scripts which helps the sysadmin and developing cycles of an slackware system.
It can be used to create packages and repositories as long as the operational system
installation and config file change tracking.

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

  English documentation: README | http://slack.sarava.org/simplepkg-en
  Portuguese documentation: REAMDE.pt_BR | http://slack.sarava.org/simplepkg

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.

Package and installation management is not everything simplepkg can do. It can also be used
to create vservers, create packages and store system configuration files in a subversion
repository.

Simplepkg works with any (official or not) slackware port that follows the minimum system
guidelines.

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
   - templatepkg: create or update a package list of an installation template
   - lspkg: show installed packages and its contents
   - jail-commit: update all configuration files of a template
   - jail-update: jail-commit counterpart
   - 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
   - repos: creates and manages binary repositories
   - mkbuild: app to build slackware build scripts

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

Simplepkg usage
---------------

The three main simplepkg uses are:

  - Package managemen
  - Jail/installation creation and management
  - Package creation

Package management is made with simplaret app, whose behaviour is detailed in its own document.
The following sections will only show how simplepkg can be used to manage jails and template
and create packages.

Creating templates
------------------

Initially, simplepkg was built to help slackware install automation. To do that, it uses installation
templates -- lists of installed packages, post-installation scripts and config files -- allowing the
creation of installation profiles that can be used for system replication in other partition or even
custom chroot building.

Template creation is done with "templatepkg" script. To create a template called "my-slackware" containig
the installed package list of your slackware installation, just type

  templatepkg -c my-slackware

The -c (or --create) flag tells templatepkg to create the /etc/simplepkg/templates/my-slackware folder
with the following components:

  - /etc/simplepkg/templates/my-slackware/my-slackware.d: template config files
  - /etc/simplepkg/templates/my-slackware/my-slackware.s: post-installation scripts
  - /etc/simplepkg/templates/my-slackware/my-slackware.perms: metadata for config files
  - /etc/simplepkg/templates/my-slackware/my-slackware.template: installaed package list

This four components are enough to store all slackware installation characteristics: the package list
controls with applications are installed, the config file folder can contain all desired configurations
for any installed application and the post-installation scripts take care of all procedures that should
be executed exactly after the system installation. The my-slackware.perms file contains metadata for the
saved config files, i.e, permission and ownership.

If you want to build a template from a installation placed in another folder or partition thats not your
current root dir, just type something like

  templatepkg -c my-slackware /mnt/slackware

where /mnt/slackware is the place where this alternative system is installed. After created, the template
will contain just the installed package list or that folder. As the folder /var/log/packages of your
installation doesn't keep information about the package installation order, its recommended that you
manually edit the template's package list. To do that, just type

  templatepkg -e my-slackware

To add configuration files inside the template, type something like

  templatepkg -a my-slackware /etc/hosts

This should add /etc/hosts file to "my-slackware" template. Beyond just automatically copy the file
when you install a new system using this template, simplepkg can also take care of every change that
/etc/hosts can suffer on your system, such as file content or permission and ownership change. If you're
also storing your templates in a subversion repository, you'll be able to track all changes it ever had.

WARNING: avoid the storage in a template of config files that contains important security information
such as passwords or secret keys. The prefered place to put such stuff is a secured backup.

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

As long as your template was created and populated with the package list, configuration files and
post-installation scripts (what will be treated in another section), your can replicate your slackware
installation as simpler than typing the following command:

  mkjail jail my-slackware

This creates a fresh slackware tree at /vservers/jail with all packages listed in the template "my-slackware"
and all saved config files. The package installation is made by simplaret app, that should be properly configured.
The standard simplaret configuration should work for most situations.

If you want to install your jail in a place other than /vservers (this standard location can be changed through
simpleokg config file), say /mnt/hda2, just use something like that:

  ROOT=/mnt mkjail hda2 my-slackware

The above command 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 stored /etc/simplepkg/default, if exists. Simplepkg already
came if some pre-built templates at /etc/simplepkg/defaults/templates.

Post-installation scripts
-------------------------

Optionally, its possible to keep post-installation scripts inside a template. Such scripts are executed by mkjail
exactly after a jail is installed and the template config files copied. To create or edit a post-installation
script, just type

  templatepkg -b my-slackware script-name.sh

This adds the script-name.sh at "my-slackware" template. Mkjail passes two command line arguments to a post-install
script: the upward folder and the jail's name ("/mnt" and "hda2" from our previous example). Then, an example script
is something like that:

  #!/bin/bash
  chroot $1/$2/ sbin/ldconfig

Listing template contents
-------------------------

To list available templates or the template content, use commands such as

  templatepkg -l
  templatepkg -l my-slackware

Removing files from a template
------------------------------

As you did to add files, you can easily remove then from a template, using a comand such as

  templatepkg -d my-slackware /etc/hosts

This removes the file /etc/hosts from "my-slackware" template.

Removing a template
-------------------

To remove a template, just type

  templatepkg -r my-slackware

Updating a template
-------------------

Now that we just talked about creating templates and jails, its time to cover another application, this time
used to keep a template always updated. Jail-commit is a script that copies all config file changes (content,
permissions and ownership) from a installation to a simplepkg template.

For instance, if one wants to copy all changes from /mnt/hda2 jail into "my-slackware" template, he or she
just needs to type the following command:

  jail-commit /mnt/hda2 my-slackware

Not just the package list from "my-slackware" template is updated according the installed packages from
/mnt/hda2/var/log/packages: all config files from "my-slackware" template are compared it the ones from
the jail and in case of any difference they're copied from the jail back to the template. Permissions
and file ownership commit into the template works at the same way.

Jail-commit allows that a template to being kept always updated and mirroring the actual configuration
of an installed system. But if you want just to commit into the template just the installed package
list, simply type

  templatepkg -u my-template

To make life even easier, there's also a feature of keeping a list of all installed slackware system in
the box in the file /etc/simplepkg/jailist. This file, despite its use by simplaret (what is described
in its own text), allow jail-commit to run with no arguments.

Suppose you have three slackware installations: the root system and two more:

  - /mnt/slackware-1 using "slackware-1" template
  - /mnt/slackware-2 using "slackware-2" template 

If your /etc/simplepkg/jailist has the following lines:

  /mnt/slackware-1
  /mnt/slackware-2

then the command

  jail-commit

will update both "slackware-1" and "slackware-2" templates according, respectivelly, the contents of
/mnt/slackware-1 and /mnt/slackware-2. If you also have a template called "main", then jail-commit
will sync the contents of your root system with that template.

You can even add the following line at root's crontab

  20 4 * * * jail-commit

so all your templates get updated everyday. If your system is configured to send emails, then crontab's
jail-commit output you give a summary of yesterday changes your system suffered, both config file changes
and package additions and removals.

Restoring changes in a jail
---------------------------

A opera��o contr�ria ao que o jail-commit faz tamb�m � poss�vel: suponha que voc� mexeu na configura��o do sistema
mas se arrependeu das altera��es e deseja voltar a configura��o para o modo como ela se encontra no seu template,
basta usar o comando

  jail-update /mnt/hda2 my-slackware

[...]

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.

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