aboutsummaryrefslogtreecommitdiff
path: root/trunk/doc/README
blob: 80f0286c35bf4392af2bd27ecb3ea2fe6f0564d5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
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/trac/wiki/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/trac/wiki/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/trac/wiki/Simplepkg and its mailing list address is
http://listas.sarava.org/wws/info/slack.