diff options
Diffstat (limited to 'tags/0.5/doc/README')
| -rw-r--r-- | tags/0.5/doc/README | 428 |
1 files changed, 428 insertions, 0 deletions
diff --git a/tags/0.5/doc/README b/tags/0.5/doc/README new file mode 100644 index 0000000..47143ca --- /dev/null +++ b/tags/0.5/doc/README @@ -0,0 +1,428 @@ +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 + - 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 +--------------------------- + +The opposite operation of jail-commit also is possible: suppose you edited some config files in your system but +suddenly wants to go back and copy all config files from a template to your jail. To do that, just use the command + + jail-update /mnt/hda2 my-slackware + +Storing templates inside a Subversion repository +------------------------------------------------ + +In order to increase once more the control and flexibility of template contents, simplepkg can also handle templates +inside a subversion repository. To do that, edit first the config gile /etc/simplepkg/simplepkg.conf and set the +parameter TEMPLATES_UNDER_SVN to "yes". + +Then, create a fresh subversion repository to keep your templates with a command like that: + + svnadmin create /var/svn/simplepkg --fs-type fsfs + +Then, you just need to import your templates with + + templatepkg -e file:///var/svn/simplepkg + +From now jail-commit will commit automatically any template changes to the svn repository. If, in the other hand, +you wish to grab the changes from the svn repository to your local copy, use + + templatepkg -s + +In case you want to import a template folder from an existing repository, use + + templatepkg -i file:///var/svn/simplepkg + +where file:///var/svn/simplepkg is the repository path. + +Upgrading jails +--------------- + +Jail and installed system upgrading is done through simplaret and also supports /etc/simplepkg/jailist file. +For more info on how it works, take a look at simplaret own documentation. + +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. + +Creating a package from a template +---------------------------------- + +If, for any reason, you wish to build a package from an existing template, try the command + + templatepkg -p template-name + +Although that should work smoothly, its not the recommended behaviour, as simplepkg was designed +to deal easily with templates and repositories. + +Building packages +----------------- + +Until now, we just showed simplepkg applications used to manage installations and packages. +But simplepkg can also create packages using createpkg script: it downloads, builds and +packages software that has an available script from a SlackBuild in a repository, working +like a slackware ports system. + +Createpkg works with any SlackBuild repository but works better and is well integrated if +they are compliant with the standards from + + http://slack.sarava.org/wiki/Main/SlackBuilds + +Specifically, createpkg was built to use slackbuilds from http://slack.sarava.org/slackbuilds +through a subversion repository. + +To fetch all scripts from slack.sarava.org, type + + createpkg --sync + +Then, you can list all available script using + + createpkg --list + +To search for a script, use something like + + createpkg --search latex2html + +This searches for a SlackBuild for the program "latex2html". If you want to build that package, +just type + + createpkg latex2html + +The resulting package should be available at /tmp or at the folder specified by the environment +variable $REPOS. To create and install the package, type + + createpkg --install latex2html + +If the package has dependencies listed in a slack-required file that aren't installed in the +system, then createpkg will try to process then before the desired package's SlackBuild: if +the dependencies aren't available in the SlackBuild tree, then createpkg will call simplaret +and try to install the package from a binary repository. If you want to avoid createpkg's +dependency checking, just use it with the flag --no-deps. + +For more information about createpkg, type + + createpkg --help + +or take a look at http://slack.sarava.org/wiki/Main/SlackBuilds. + +Auxiliar applications +--------------------- + +Simplepkg comes also with the following tools: + + - lspkg: show installed packages and its contents + - rebuildpkg: rebuild a package based on its /var/log/packages entry + - repos: creates and manages binary repositories + - mkbuild: app to build slackware build scripts + +The command lspkg is used to show installed packages. Also, 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/. + +For their time, scripts repos and mkbuild are used, respectivelly, to create and manage binary repositories +and to create SlackBuild scripts. + +Configuration parameters +------------------------ + +Simplepkg's config file is /etc/simplepkg/simplepkg.conf and it keeps parameters used by all scripts. +In this section, we won't cover any parameter that's just used by simplaret, whose settings are covered +in its own documentation. + + - JAIL_ROOT: Where jails are placed by mkjail. Default: "/vservers". + + - ADD_TO_JAIL_LIST: Wheter mkjial should add new jails to /etc/simplepkg/jailist. Default is "1" (enabled). + + - TEMPLATES_UNDER_SVN: Set to yes if your templates will be placed in a subversion repository. Default + is "no" (disabled). + + - TEMPLATE_FOLDER: Where your templates will be located. Default is "/etc/simplepkg/templates" and + dont change it except you know what you're doing. + + - TEMPLATE_STORAGE_STYLE: This variable controls in which folder / subfolder your templates will + be stored. Default value is "own-folder" and you'll just need to change that if you're storing + your templates using an old simplepkg format and wants to keep compatibilty. + +Its important to note that all boolean parameters in the config file can be set either to "1" or "yes" +to enable and "0" or "no" to disable. + +Additional information +---------------------- + +Simplepkg was written by Silvio Rhatto (rhatto at riseup.net) and is released under GPL license. The code +can be obtained from the subversion repository: + + svn checkout svn://slack.sarava.org/simplepkg + +Simplepkg's wiki is http://slack.sarava.org/wiki/Main/SimplePKG and its mailing list address is +http://listas.sarava.org/wws/info/slack. + |