diff options
Diffstat (limited to 'tags/0.5/doc/README')
| -rw-r--r-- | tags/0.5/doc/README | 428 |
1 files changed, 0 insertions, 428 deletions
diff --git a/tags/0.5/doc/README b/tags/0.5/doc/README deleted file mode 100644 index 47143ca..0000000 --- a/tags/0.5/doc/README +++ /dev/null @@ -1,428 +0,0 @@ -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. - |