Return to README CVS log

Up to [local] / openbsd / sxxu

Annotation of openbsd/sxxu/README, Revision 1.4

1.2       andrew      1: sxxu - siteXX utility - a tool to help build OpenBSD siteXX files
                      2:
1.4     ! andrew      3: This was inspired by siteXYtools from mongers.org, but it seemed like it
        !             4: needed a few additional features to make it easier to do more common tasks.
        !             5:
        !             6:
1.2       andrew      7: For more information on siteXX files see:
                      8: http://www.openbsd.org/faq/faq4.html#site
                      9:
                     10:
                     11: The goals of sxxu are to help you:
                     12: * Keep configuration for your systems in a source control
                     13: * Recover from a disaster more quickly
                     14: * Do a matching install on a secondary system so you can
                     15:   o Upgrade between versions of OpenBSD with the ability to revert
                     16:   o Replace aging hardware
                     17:   o Build a test environment before pushing changes to a production system
                     18:
                     19: sxxu is meant to be a simple utility for installing systems.  It does not have
                     20: the ability to continue to push changes out to already installed systems.  For
                     21: that functionality there are many more powerful solutions.  I do wonder if it
                     22: would be possible to patch sysmerge to support some way of migrating these
                     23: files.
                     24:
                     25: Some of the problems sxxu tries to solve:
                     26: * duplication of common configuration for each system
                     27: * permissions easily get broken when configuration is in source control
                     28:
                     29:
                     30: USAGE: sxxu [-kmR] [-w WRKDIR]  [machine1 [machine2 [...]]]
                     31:   -k : Keep WRKDIR
                     32:   -m : rebuild mtree files
                     33:   -R : don't Recurse into Roles
                     34:   -w : specify the WRKDIR
                     35:
                     36:
                     37: DETAILS:
                     38:
                     39: In the basedir, each directory is considered a "role", the common directory is
                     40: merged into each role by default and any directory named role-* does not
                     41: generate a tgz by default.
                     42:
                     43: Any of the directory structure not in the siteXX directory is treated as a
                     44: normal siteXX that will extract to the root of your system after the install.
                     45:
                     46: Special files are kept in the siteXX directories.  These special files are
1.3       andrew     47: processed by the install.sxxu after install.
1.2       andrew     48:
1.3       andrew     49: If a role/install.site exists, this WILL overwrite the install.sxxu that
1.2       andrew     50: would have processed these special files.
                     51:
                     52: Create a directory structure for your system:
                     53:
                     54: basedir/
                     55:  |-common
                     56:  |---siteXX
                     57:  |-machine1
                     58:  |---siteXX
                     59:  |-machine2
                     60:  |---etc
                     61:  |---siteXX
                     62:  |-role-imap
                     63:  |---siteXX
                     64:  |---var
                     65:  |-----sendmail
                     66:
                     67:
                     68: Special files and directories inside the siteXX directory:
                     69:     roles:
                     70:       Contains a list of "roles" (directories in the basedir) to merge into
                     71:       this configuration.  The common directory is automatically included in
                     72:       all configurations.
                     73:
                     74:     mtree:
                     75:       An mtree(8) spec file for permissions on the files in this role. It gets
                     76:       applied before the files are put into the archive. See below for notes
                     77:       on how to create and update.
                     78:
                     79:     siteXXrc: xxx
                     80:       A ksh script that is included before running the *_list commands and
                     81:       the individual install.site files for each role.
                     82:
                     83:     pkg_path:
                     84:       A list (one per line) of sites to add to the PKG_PATH environment.
                     85:
                     86:     *_list:
                     87:       A list of arguments to commands to be run.  For example if pkg_add_list
                     88:       containing "rsync nrpe check_hw_sensors" will attempt to run
                     89:       pkg_add rsync nrpe check_hw_sensors.
                     90:
                     91:       The command is executed for each line of the file.
                     92:
                     93:       You can set environment variables in the siteXXrc file for arguments.
                     94:       Setting "pkg_add_args='-i'" in a siteXXrc would make the above command
                     95:       pkg_add -i rsync nrpe check_hw_sensors
                     96:
                     97:     patches/:
                     98:         All patches in this dir need to be relative to the root of the system
                     99:         where the tgz was extracted.
                    100:
                    101:     packages/:
                    102:         Package files that will get installed.  Completely separate from
                    103:         pkg_add_list above.  It does inherit pkg_path and pkg_add_args.
                    104:
                    105:     install.site:
                    106:         Your script that gets run after all the above things have been done.
                    107:
                    108: MTREE:
                    109:
                    110: You can use sxxu -m to generate mtree spec files.  This will generate the
                    111: files with the permissions that are gotten after copying and applying the
                    112: existing mtree file.
                    113:
                    114: You can get some more advanced features with some other switches.
                    115:
                    116:   # sxxu -kRw /tmp/sxxu-work
                    117:
                    118: will extract all roles including those named role-* into /tmp/sxxy-work
                    119: without following the included roles.  At that point you can change
                    120: permissions in the work directory as you see fit, then when you are ready,
                    121: from the place where your source files are you would run
                    122:
                    123:   $ sxxu -mw /tmp/sxxu-work
                    124:
                    125: which will regenerate the mtree specs with the permissions you have set.
                    126:
                    127: