diff options
Diffstat (limited to 'sysutils/sysbuild/files/sysbuild.8')
| -rw-r--r-- | sysutils/sysbuild/files/sysbuild.8 | 439 |
1 files changed, 439 insertions, 0 deletions
diff --git a/sysutils/sysbuild/files/sysbuild.8 b/sysutils/sysbuild/files/sysbuild.8 new file mode 100644 index 00000000000..39e53ba107a --- /dev/null +++ b/sysutils/sysbuild/files/sysbuild.8 @@ -0,0 +1,439 @@ +.\" $NetBSD: sysbuild.8,v 1.1.1.1 2002/11/28 19:57:29 jmmv Exp $ +.\" +.\" sysbuild - Automatic NetBSD system builds +.\" Copyright (c) 2002, Julio Merino <jmmv@netbsd.org> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Neither the name of The NetBSD Foundation nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" 3. Neither the name of author nor the names of its contributors may +.\" be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 16, 2002 +.Dt SYSBUILD 8 +.Os +.Sh NAME +.Nm sysbuild +.Nd Automates +.Nx +release and kernel builds +.Sh SYNOPSIS +.Nm +.Op Fl ms +.Op Fl c Ar conf +.Ar target +.Op Ar target_args ... +.Sh DESCRIPTION +The +.Nm +utility automates the building process of a +.Nx +release and all related stuff (like kernels), everything working as an +unprivileged, special user. +It should be clear enough that this program does not add any kind of +magic to the existing build mechanisms of the +.Nx +operating system; it just makes things easier if you want to automate +them (for example, to run them from a +.Xr cron 8 +job). +.Pp +The following options are recognized: +.Bl -tag -width indent +.It Fl c Ar conf +Specify the name of the configuration file. +This is not a full name; it is just a symbolic name. +See +.Sx CONFIGURATION +for for information. +.It Fl m +Capture all output and send it by mail to the +.Va MAILTO +user specified in the configuration file. +.It Fl s +Automatically change privileges using +.Xr su 1 . +By default the program will +exit if user credentials for the specified target are incorrect. +.El +.Sh EXIT STATUS +Returns 0 on success, 1 if any error happened. +.Sh TARGETS +.Nm +behavior is controlled through a target. +A target specifies what the program should do when executed. +The following targets are recognized: +.Bl -tag -width ident +.It build-kernels +Automatically build all kernels listed in the +.Va KERNCONF +variable. +.Pp +Each kernel name listed in this variable is configured, cleaned, +depended and built inside its own directory, which is in turn placed in +.Pa $BUILDDIR/kernels . +Note that kernel configuration files must be stored inside the +directory pointed to by +.Va KERNCONFDIR . +.Pp +This target requires +.Ql @SYSBUILD_USER@ +privileges. +.It build-release +Build a full release of the system. +A release is formed by all compressed system sets, installation floppy +disks and standard kernels. +.Pp +Release files are placed inside the directory pointed by +.Va RELEASEDIR . +During the build, +.Va BSDOBJDIR +is set to +.Pa $BUILDDIR/obj +and +.Va DESTDIR +is set to +.Pa $BUILDDIR/root . +.Pp +Depends on +.Ql clean . +.Pp +This target requires +.Ql @SYSBUILD_USER@ +privileges. +.It build-sets +Build compressed system sets only. +If you want the sets to install them later on your own system, this is +the recommended target, as building a release takes much more time. +.Pp +Depends on +.Ql clean . +.Pp +This target requires +.Ql @SYSBUILD_USER@ +privileges. +.It clean +Cleanup all work areas. +This will unconditionally clean all the stuff located under the +directory specified by +.Va BUILDDIR , +but will not destroy the main directory hierarchy inside it. +.Pp +This target requires +.Ql @SYSBUILD_USER@ +privileges. +.It clean-srcs Op Ar dir ... +Cleanup permissions of all source files inside the directories +specified by +.Va CVSDIRS , +or the ones specified by the optional list +.Ar dir . +All files are set to +.Va CVSDIRS_OWNER +owner and +.Va CVSDIRS_GROUP +group. +Optional permissions can be provided through +.Va CVSDIRS_PERMS , +which are set on all files using +.Xr chown 8 . +.Pp +This target requires +.Ql root +privileges. +.It config Op Ar conf +Edit the default configuration file or the one specified by +.Ar conf , +if given (remember that these are symbolic names, not full paths). +This will run +.Xr vi 1 +if no editor is specified by the +.Ev EDITOR +variable. +.Pp +If the specified configuration file does not exist, a sample one is +copied from +.Pa @EGDIR@/default.conf . +.Pp +This command is interactive, so output cannot be captured with +.Fl m . +.Pp +This target requires +.Ql root +privileges. +.It destroy +Completely remove the work area specified by +.Va BUILDDIR . +You should run this target before deinstalling this program. +.It etcupdate +Extract the compressed +.Pa etc.tgz +file, generated during the +.Ql build-sets +or the +.Ql build-release +stages, in a temporary place and then run +.Xr etcupdate 8 +over it to update your +.Pa /etc +directory. +.Pp +This command is interactive, so output cannot be captured with +.Fl m . +.Pp +This target requires +.Ql root +privileges. +.It init +Initialize the work directory specified in +.Va BUILDDIR +plus all the subdirectories required inside it. +Should be run once, after configuring the program with the +.Ql config +target (or when creating new configuration files). +.Pp +This target requires +.Ql root +privileges. +.It install-kernel Op Ar kernel +Install the first kernel specified in the +.Va KERNCONF +variable or the one supplied by the +.Ar kernel +argument. +.Pp +This target requires +.Ql root +privileges. +.It install-sets +Install built system sets, placed inside +.Pa $RELEASEDIR/binary/sets . +Only sets specified in the +.Va SETS +variable are installed. +.Pp +This target requires +.Ql root +privileges. +.It update-srcs Op Ar dir ... +Use +.Xr cvs 1 +to update all source trees specified by +.Va CVSDIRS , +or the ones specified by the optional +.Ar dir +arguments. +.Pp +This target requires +.Ql @SYSBUILD_USER@ +privileges. +.El +.Sh CONFIGURATION +.Nm +supports multiple configuration files. +This is specially useful if you usually need to build different +versions of +.Nx , +that is, one configuration for each version. +.Pp +Configuration files are directly stored inside +.Pa @SYSBUILD_HOMEDIR@ , +and have a +.Ql .conf +extension. +The symbolic name of the configuration file (the one used with the +.Ar -c +flag) is formed by the name of the configuration file, without the +path and without the extension. +For example, the default configuration file (used when no other one is +specified) is named +.Pa @SYSBUILD_HOMEDIR@/default.conf , +but you could use +.Fl c Ar default +to select it. +You should not worry about where these files are stored, as the +.Ql config +target will take care of it. +.Pp +The sample configuration file (copied to all new configurations +created) is well documented and contains some reasonable +defaults. +Even though, a list of all known variables is provided here, +for reference: +.Bl -tag -width indent +.It BUILDDIR +The directory which holds all working stuff (object files, temporary +root, etc.). +You will need lots of space in this directory if you want +to build full releases. +.It CVSDIRS +White-space separated list of directories that are updated using +.Xr cvs 1 +when executing the +.Ql update-srcs +target. +.It KERNCONF +White-space separated list of kernels that are built with the +.Ql build-kernels +target. +The first one is the kernel that will be installed when running +.Ql install-kernel . +.It KERNCONFDIR +Directory which holds kernel configuration files. +Defaults to +.Pa @SYSBUILD_HOMEDIR@ . +.It RELEASEDIR +Base directory which will hold release files. +.It MAILTO +User who will receive all logs by mail when using the +.Fl m +flag. +.It MAIL_CMDLOG +If set to +.Ql yes , +mail the entire log of commands to the user specified in +.Va MAILTO +(if using the +.Fl m +flag). +If set to +.Ql no , +logs are left in +.Pa /tmp . +A summary of the process is always sent, regardless of this variable. +Remember that logs can become very big! +.It SETS +White-space separated list of compressed sets that should be +extracted in the machine while running +.Ql install-sets . +.It SRCDIR +Path to +.Nx +source directory tree, usually +.Pa /usr/src . +.El +.Sh SEE ALSO +.Xr crontab 1 , +.Xr cvs 1 , +.Xr mk.conf 5 , +.Xr cron 8 , +.Xr etcupdate 8 , +.Pa /usr/src/BUILDING +.Sh CRON JOBS +.Xr cron 8 +is our best friend to schedule these CPU tasks. +You can, for example, set a task to build a release while you are +sleeping, another to install it and when you get up you just have to +run the interactive +.Ql etcupdate +target to finish the process. +.Pp +To make this even easier, the +.Ql @SYSBUILD_USER@ +comes with a sample crontab file, with several (disabled) entries, +ready to be edited. +You should note that the +.Fl m +flag is a good choice for unattended tasks, because you will get a +report by mail when they finish. +.Pp +To edit it, simply type: +.Pp +.Dl crontab -e -u @SYSBUILD_USER@ +.Sh EXAMPLES +To initialize +.Nm +for the first time: +.Pp +.Dl sysbuild config +.Dl sysbuild init +.Pp +Once you have configured it properly, you can execute the following, as +.Ql root , +to build your kernels and system sets. +Note that the +.Fl s +flag will automatically downgrade privileges. +.Pp +.Dl sysbuild -s build-kernels +.Dl sysbuild -s build-sets +.Pp +And then, as +.Ql root , +you can install the results: +.Pp +.Dl sysbuild install-kernel +.Dl sysbuild install-sets +.Pp +Or, if you want to update all your source trees: +.Pp +.Dl sysbuild clean-srcs +.Dl sysbuild -s update-srcs +.Pp +The first command should be only required once, the first time you +want to do this task. +.Pp +Note that where we are using the +.Fl s +you could as well become the +.Ql @SYSBUILD_USER@ +user using +.Xr su 1 +and execute the command from there. +Read +.Sx SECURITY CONSIDERATIONS +for more details on this. +.Sh SECURITY CONSIDERATIONS +The unprivileged user +.Ql @SYSBUILD_USER@ +account is disabled by default. +This means that root can access it through +.Xr su 1 , +but no other user will be able to run +.Nm +properly. +If you want anybody to be able to use it, just set a password for the +account, give it to the user, and tell him to use the +.Fl s +flag. +.Sh NOTES +This program will only work in +.Nx 1.6 +and above. +Some targets may work in previous versions, but do not expect it to +work fine. +.Sh AUTHORS +.An Julio Merino Aq jmmv@netbsd.org +.Sh TO DO +There are many other things to do, but are left for future releases. +Here is a small list with some ideas: +.Bl -bullet -width indent +.It +Add support for X11R6 unprivileged builds. +This will require the use of +.Xr mount_union 8 +because X11R6 build system creates object files together with sources. +.It +Support building for multiple architectures. +.It +Add an update flag, so that the user can avoid automatic cleans before +builds. +.El |