No empty .Rs/.Re

[netbsd-mini2440.git] / sbin / newbtconf / newbtconf.8

.\"     $NetBSD: newbtconf.8,v 1.18 2004/08/31 17:08:06 uwe Exp $
.\"
.\" Copyright (c) 1999 Darren Reed.  All rights reserved.
.\"
.\" 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. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the 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 REGENTS 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 REGENTS 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 September 30, 2005
.Dt NEWBTCONF 8
.Os
.Sh NAME
.Nm newbtconf
.Nd multiple boot-up configurations
.Sh SYNOPSIS
.Nm
.Ar new-conf-name
.Op Ar orig-conf-name
.Nm
.Cm init
.Nm
.Cm revert
.Sh DESCRIPTION
.Nm
is used to set up the system in such a way that the user is offered a
selection of environments in which to boot the system up into.
The most obvious application being for laptops to provide a network
and non-network environment after a successful boot into multi-user mode.
.Ss Background
In order to accomplish this task, the files usually associated with
establishing the current system's running configuration are replaced with
symbolic links which are adjusted with each boot to point to the appropriate
file for the desired run-time environment.
This is accomplished by directing all of the symbolic links through a
directory which itself is a symbolic link
.Pq Pa /etc/etc.current ,
to the destination files.
At each bootup, the selection made changes which directory
.Pa /etc/etc.current
points to.
.Pp
Through doing this and reloading
.Pa /etc/rc.conf
in
.Pa /etc/rc
after the link has
been established, the resulting run-time configuration is effectively
controlled without the need to directly edit any files.
The default boot-up environment is selected by manually directing which
configuration directory
.Pa /etc/etc.default
points to.
As opposed to
.Pa /etc/etc.current
(which is updated
with every boot),
.Pa /etc/etc.default
is not automatically updated.
.Ss Getting Started
By default,
.Nx
only has one boot-up configuration - that set in the
file
.Pa /etc/rc.conf .
In order to initialize the system for operating in a
manner which supports multiple boot configurations,
.Nm
must be run with an argument of
.Sq init .
This will create two symbolic links
.Pa /etc/etc.current
and
.Pa /etc/etc.default
to the directory
.Pa /etc/etc.network .
The following files are all moved into
that directory and symbolic links put in their place, in
.Pa /etc ,
pointing to
.Pa /etc/etc.current/\*[Lt]filename\*[Gt] :
.Bd -literal -offset indent
/etc/defaultdomain
/etc/fstab
/etc/ifconfig.*
/etc/inetd.conf
/etc/mrouted.conf
/etc/mygate
/etc/myname
/etc/netstart
/etc/nsswitch.conf
/etc/ntp.conf
/etc/rc.conf
/etc/rc.conf.d
/etc/resolv.conf
.Ed
.Pp
To test that this has been performed correctly, reboot your system into
.Nx .
After the kernel has autoconfigured and tty flags have been set,
a prompt should appear, preceded by the following like, looking like this:
.Bd -literal
[network]
Which configuration [network] ?
.Ed
.Pp
The []'s are used to indicate the default configuration, which can be
selected by just pressing return.
If there were other configurations available at this stage, you would
have 30 seconds to enter that name and press
.Sy RETURN .
.Ss Multiple Configurations
Once an initial configuration has been set up, we can proceed to set up further
run time environments.
This is done by invoking
.Nm
with the name of the new configuration to be created.
By default, this step
will use the current configuration files as the basis for this setup unless
a second parameter is given - that of the configuration to use as the basis
for the new one.
Upon completion, a new directory,
.Pa /etc/etc.\*[Lt]newname\*[Gt] ,
will have been created,
priming the directory with the appropriate files for editing.
For example, if we do
.Nm
.Ar nonet network
it would create a directory named
.Pa /etc/etc.nonet
and copy all the files from
.Pa /etc/etc.network
into that directory.
Upon rebooting, we should see:
.Bd -literal
[network] nonet
Which configuration [network] ?
.Ed
.Pp
To set up the system for booting into the
.Dq nonet
configuration, the files in
.Pa /etc/etc.nonet
need be edited.
.Pp
If you wanted to make
.Dq nonet
the default configuration when booting, you
would need delete the symbolic link
.Pa /etc/etc.default
and create a new symbolic link (with the same name) to
.Pa /etc/etc.nonet .
Booting up after having made such a change would
result in the following being displayed:
.Bd -literal
network [nonet]
Which configuration [nonet] ?
.Ed
.Ss \&No Network
Assuming that we performed the above command successfully, in order to
successfully configure
.Nx
to not configure interfaces (or generate no
errors from attempting to do so), the following settings (at least) should
be used in
.Pa /etc/etc.nonet/rc.conf :
.Bd -literal
auto_ifconfig=NO
net_interfaces=NO
.Ed
.Pp
Of course other networking services, such as NTP, routed, etc, are all
expected to be
.Dq NO .
In general, the only setting that should be
.Dq YES
is syslogd, and perhaps cron (if your cron scripts don't
need the network) or screenblank/wscons (if applicable).
Other actions such as deleting any NFS mounts from
.Pa /etc/etc.nonet/fstab
would also need to be undertaken.
.Ss Reverting multiple boot configurations
Multiple boot configurations can be deactivated by running
.Nm
with an argument of
.Cm revert .
All the symlinks mentioned above are then removed and the files they point to
are copied to their default place.
This effectively makes the currently selected
configuration the only one active.
The symbolic links
.Pa /etc/etc.current
and
.Pa /etc/etc.default
are also removed so upon rebooting no configuration selection menu is
displayed.
Note that the previously created configurations (in
.Pa /etc/etc.\*[Lt]name\*[Gt] )
are not removed.
.Sh FILES
.Bl -tag -width /etc/mrouted.current -compact
.It Pa /etc/etc.current
Symbolic link to current config directory.
.It Pa /etc/etc.default
Symbolic link to default config directory.
.Pp
.It Pa /etc/defaultdomain
These files all become symbolic links.
.It Pa /etc/fstab
.It Pa /etc/ifconfig.*
.It Pa /etc/inetd.conf
.It Pa /etc/mrouted.conf
.It Pa /etc/mygate
.It Pa /etc/myname
.It Pa /etc/netstart
.It Pa /etc/nsswitch.conf
.It Pa /etc/ntp.conf
.It Pa /etc/rc.conf
.It Pa /etc/rc.conf.d
.It Pa /etc/resolv.conf
.El
.Sh SEE ALSO
.Xr rc.conf 5 ,
.Xr rc 8
.Sh HISTORY
The
.Nm
program first appeared in
.Nx 1.5 .
.Sh AUTHORS
.An -nosplit
This shell script was written by
.An Darren Reed
.Aq darrenr@NetBSD.org
with initial input from
.An Matthew Green
.Aq mrg@NetBSD.org
on how to approach this problem.
.Sh BUGS
It presently does not display a count down timer whilst waiting for input
to select which configuration and nor does it abort said timer when a key
is first pressed.
.Pp
The management of the overall collection of multiple configurations is much
more manual than it ought to be.
A general system configuration tool needs to be written to ease their
management.