Return to README CVS log

Up to [local] / openbsd / sxxu

Annotation of openbsd/sxxu/README, Revision 1.3

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