Return to README CVS log

Up to [local] / openbsd / sxxu

Annotation of openbsd/sxxu/README, Revision 1.2

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
        !            43: processed by the install.siteXX after install.
        !            44:
        !            45: If a role/install.site exists, this WILL overwrite the install.siteXX that
        !            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: