diff options
Diffstat (limited to 'trunk/doc/README')
| -rw-r--r-- | trunk/doc/README | 296 |
1 files changed, 172 insertions, 124 deletions
diff --git a/trunk/doc/README b/trunk/doc/README index 50b0e9d..470b6ab 100644 --- a/trunk/doc/README +++ b/trunk/doc/README @@ -1,21 +1,19 @@ -Simplepkg: installation manager and metapackage system ------------------------------------------------------- +Simplepkg: installation manager and packaging 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. +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/node/15 - Portuguese documentation: REAMDE.pt_BR | http://slack.sarava.org/node/12 + English documentation: README | http://slack.sarava.org/simplepkg-en + Portuguese documentation: REAMDE.pt_BR | http://slack.sarava.org/simplepkg Description ----------- @@ -37,6 +35,13 @@ management, allowing you to keep templates of each machine and install a custom 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 ------------ @@ -44,27 +49,15 @@ Simplepkg is a set of scripts wrote in the KISS philosophy. Its a pretty simple 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 + - 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 - -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. + - repos: creates and manages binary repositories + - mkbuild: app to build slackware build scripts Installation ------------ @@ -74,134 +67,197 @@ 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: +Simplepkg usage +--------------- - REPOS_ROOT=SlackMidiataticaNoarch%http://slack.sarava.org/packages/noarch +The three main simplepkg uses are: -and then issue those commands: + - Package managemen + - Jail/installation creation and management + - Package creation - swaret --update - swaret --install simplepkg +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. -Configuration -------------- +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: -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. + - /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 -------------------------------------------- - templatepkg my-slackare - mkjail jail my-slackware +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: -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). + mkjail jail my-slackware -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. +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. -You can specify an alternative destination for your jail with a command like +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 -This does exactly what you think: installs slackware in /mnt/hda2 with exactly the same packages +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 called /etc/simplepkg/default.template. +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. -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 +Post-installation scripts +------------------------- - jail-update +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 -all jails listed in /etc/simplepkg/jaillist are updated. This command also updates the package list -of the template. + templatepkg -b my-slackware script-name.sh -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. +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: -If you want to create a template from a jail, use + #!/bin/bash + chroot $1/$2/ sbin/ldconfig - templatepkg jail /vservers/jail +Listing template contents +------------------------- -Metapackages ------------- +To list available templates or the template content, use commands such as -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 + templatepkg -l + templatepkg -l my-slackware - metapkg --install program-name +Removing files from a template +------------------------------ -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. +As you did to add files, you can easily remove then from a template, using a comand such as -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. + templatepkg -d my-slackware /etc/hosts -A metapackage, i.e, all installed packages from a template, can be removed with +This removes the file /etc/hosts from "my-slackware" template. - metapkg --remove program-name +Removing a template +------------------- -Upgrading jails ---------------- +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 -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 +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. - jail-upgrade +Suppose you have three slackware installations: the root system and two more: -This will upgrade your main system and all jails living in JAIL_ROOT. To specify another -folder, use + - /mnt/slackware-1 using "slackware-1" template + - /mnt/slackware-2 using "slackware-2" template - ROOT=/otherroot jail-upgrade +If your /etc/simplepkg/jailist has the following lines: -If you want to upgrade just one specific jail, + /mnt/slackware-1 + /mnt/slackware-2 - jail-upgrade jail-name +then the command -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 + 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 ---------------------------- @@ -224,14 +280,6 @@ Note that the templates are arch and version independent, as they just contain p 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 ----------------------------------------------- |