% $Header: /mit/netbsd/doc/other/RCS/netbsd-admin.tex,v 1.5 1999/07/14 14:49:21 deberg Exp $

\documentstyle[fullpage,ifthen]{article}
\pagestyle{empty}
\setlength{\parskip}{.05in}

% Extract RCS values, defining \rcsRevision and \rcsLocker.
\def\rcs$#1: #2 ${\expandafter\def\csname rcs#1\endcsname{#2}}
\def\rcsnull$#1: #2${\expandafter\def\csname rcsnull#1\endcsname{#2}}
\rcs$Revision: 1.5 $
\rcsnull$Locker:  $

% If the file is checked out, write ``Draft'' on the output in big letters.
\ifthenelse{\equal{\rcsnullLocker}{}}{}{\special{header=texdraft.ps}}

\begin{document}

\begin{center}
{\huge Administrating NetBSD-Athena 8.2}
\end{center}
\bigskip

\small

\noindent These instructions explain how to administrate your
NetBSD-Athena system.  Topics covered include making your machine
private, changing your root password, enabling remote access and other
services, adding new users, and sharing a DOS partition.  Please note
that nearly all of the instructions must be run as root.  If you
encounter any problems administrating your system, please send mail to
{\tt netbsd-help@mit.edu}.

\subsection*{{\tt PUBLIC} and {\tt AUTOUPDATE}}

The NetBSD-Athena installation, like the installation for Sun and SGI
Athena workstations, configures your machine as a public workstation.
This means that periodically the reactivate script will erase most local
changes and restore the default settings, including the root password.
Many people may wish to disable this behavior.  To do so, edit {\tt
/etc/athena/rc.conf} and set {\tt PUBLIC} to {\tt false}.  When {\tt
PUBLIC} is {\tt false}, the machine is no longer a public workstation.
The reactivate script will still run updates when necessary, but it will
preserve local changes.

Your NetBSD-Athena system is also configured to automatically update to
new releases of NetBSD-Athena.  You should probably leave this enabled
to receive patches as they are released.  If, for some reason, you want
to disable this behavior, you can edit {\tt /etc/athena/rc.conf} and set
{\tt AUTOUPDATE} to {\tt false}.  If you have configured a custom kernel
for your machine but wish to take automatic updates, you should touch
{\tt /netbsd.custom}.  If that file exists, the autoupdate will not
overwrite your custom kernel, but will upgrade other files as necessary.

\subsection*{Changing the root password}

After installing NetBSD-Athena, your root password is set to the current
public root password.  You can run {\tt tellme root} to determine what
the password is.  To change your password, run (as root) passwd.  Note
that if your system is configured as a public workstation, the
reactivate script will reset it to the default.  {\em If you configure
your machine as a private system, you should change the root password
from the default.}

\subsection*{Enabling services}

NetBSD-Athena uses the {\tt mkserv} program to configure various
workstation services.  Note that running {\tt mkserv} will automatically
configure the workstation to not be {\tt PUBLIC}.

\subsubsection*{Enabling remote access}

If you want the ability to login to your system remotely, then you must
enable remote access.  To do so, run {\tt mkserv remote}.  This will ask
you a few questions about which users should have access, and then
enable inbound telnet and ssh connections.

You will probably want to install a srvtab file on your machine,
otherwise inbound telnet connections will not be encrypted.  If you
don't already have one, email {\tt accounts@mit.edu} and request a
srvtab for your hostname.  Follow the directions in the reply, and
install the srvtab file in {\tt /etc/athena/srvtab}.

\subsubsection*{Enabling discuss}

The {\tt mkserv} command also allows you to setup a discuss server, by
running {\tt mkserv discuss}.  Contact SIPB ({\tt netbsd-help@mit.edu},
x3-7788) for more information about running a discuss server.

\subsection*{Adding/removing users}

The easiest way to control who can log into your NetBSD-Athena system is
to use {\tt /etc/athena/access}.  Each line in {\tt /etc/athena/access}
specifies an account and its access privileges.  A line should contain a
username, some whitespace, and then a list of access flags.  Flags
include ``l'' for local login access, ``r'' for remote login access, and
``L'' if the account should be considered local (suppressing
Athena-specific login activities for this account).  Using the access
file to add non-local users eliminates the need to edit {\tt
/etc/master.passwd} and similar files.  

Adding a local user (with the ``L'' flag) still requires a password
file entry, along with a local home directory.  To add a local user,
\begin{enumerate}
        \item run {\tt vipw} and add a line for the new local user.  If
        the user has an Athena account, you may want to specify the same
        userid and groupid as the Athena account.  (Run {\tt hesinfo
        {\sl username} passwd} to determine these numbers.)  
        
        \item run {\tt passwd {\sl username}} to set the local password
        for the user.

        \item run {\tt grep {\sl username} /etc/master.passwd $>>$
        /etc/master.passwd.local} to add the user to the local password
        file.
\end{enumerate}

Users familiar with older methods of controlling remote access should
note that {\tt /etc/noremote} and {\tt /etc/nocreate} are ignored when
using {\tt /etc/athena/access}.  For more information, run {\tt man
access} on your system.  Note that if you give remote access to users,
you will also need to enable remote access to your system.  Also note
that the contents of {\tt /etc/athena/access} will be lost if the
workstation is configured to be PUBLIC.

\subsection*{Other configuration variables}

There are other useful variables in {\tt /etc/athena/rc.conf} (mostly
Athena related) and {\tt rc.conf} (NetBSD related).  If {\tt SYNCCONFIG}
is {\tt true}, any variables in {\tt /etc/athena/rc.conf} with a {\tt *}
in their comments will propagate down to NetBSD's {\tt /etc/rc.conf}, so
changes to those options in {\tt /etc/rc.conf} will go away after a
reboot.  On the other hand, if {\tt SYNCCONFIG} is {\tt false}, then
setting {\tt *}'d variables in {\tt /etc/athena/rc.conf} has no effect,
and those options must be set in {\tt /etc/rc.conf}.

You can change your machine's hostname, IP address, network interface
card, and NIC media selection by editing the first four entries of {\tt
/etc/athena/rc.conf} if {\tt SYNCCONFIG} is set.  If it's not, then set
the hostname in {\tt /etc/rc.conf}.  The network interface is determined
by the file {\tt /etc/ifconfig.ep0}, replacing {\tt ep0} with your
network device.  The contents of this file include the IP address and
NIC media selection.

If you plan on exporting filesystems with NFS, you will need to set {\tt
NFSSRV} to {\tt true} in {\tt /etc/athena/rc.conf} or {\tt /etc/rc.conf}
as appropriate.  You may also be interested in setting {\tt ipfilter},
{\tt ipmon}, {\tt apmd}, and others in {\tt /etc/rc.conf}.  Run {\tt man
rc.conf} for more information.

\subsubsection*{DOS partitions}

If you have a primary DOS partition on the same disk as your NetBSD
partition which you wish to be able to access from NetBSD, you can run
(as root):
\begin{verbatim}
add netbsd
dospart
\end{verbatim}
This will mount your partition on {\tt /dosc}.  If your DOS partitions
are extended, the {\tt dospart} utility will not configure them
properly.  Contact SIPB ({\tt netbsd-help@mit.edu}, x3-7788) for help
with extended partitions.

\subsection*{Using the NetBSD package system}

NetBSD includes a ``package'' collection that includes many popular
third-party applications, system utilities, and games.  Much of this
collection is already available on Athena by adding the appropriate
locker, but you may still wish to install some of the software locally.
The package system allows you to either install prebuilt binaries, or
build the software yourself.  Information on how to use the package
collection is available at \\ {\tt
http://www.netbsd.org/Documentation/software/packages.html}.

\subsection*{Building a custom kernel}

The NetBSD-Athena installation uses a default kernel that supports most
common hardware.  If you have hardware not supported by the default
kernel, want to change various default system settings, or develop
kernel-level code, then you will need to build a new kernel.  You may
also want to remove unused drivers from the default kernel.  The kernel
prints out during the boot each driver that is used, so any device {\em
not} mentioned in the boot messages can be taken out.  You can view the
boot messages by running {\tt dmesg}.

The following procedure should get you started.

\begin{enumerate}

        \item To build a kernel, you'll need the kernel sources.
         There is a NetBSD 1.3.2 kernel source tree in AFS at {\tt
        /afs/dev.mit.edu/project/sipb/netbsd/1.3.2/src/sys/}, or you
         can fetch your own from 
% TeX kluge to avoid an overfull hbox. If you have a better way to fix
% this, please do so.
	\penalty-10000 {\tt ftp.netbsd.org:/pub/NetBSD/NetBSD-1.3.2/source} 

	\item Create a build directory, for example {\tt
         /var/tmp/build} (remember that /var/tmp gets automatically
         cleaned of old files, so you may want to put the build
         directory somewhere else for persistence).

        \item Create a configuration file.  NetBSD kernel options are
        specified in configuration files that can be found in the
        kernel source subdirectory {\tt
        arch/i386/conf}.  The configuration file for the
        default NetBSD-athena kernel is {\tt ATHENA}.  You may want to
        use this as a starting point.  Traditionally, the name of the
        configuration file is the all-caps version of the hostname that
        the kernel will run on.  For more information on configuration
        file options, see {\tt man 4 options} and {\tt man 8 config}.

        \item Configure the kernel.  In the directory with the new
        configuration file {\tt CONFIG\_NAME}, run
\begin{verbatim}
config -s <kernel source directory> -b <build directory> CONFIG_NAME
\end{verbatim}
        This populates your build directory with various files that
        direct the creation of the kernel.

        \item Build the kernel.  Change to the build directory and run 
\begin{verbatim}
make depend && make
\end{verbatim}
        The kernel should build.  If you get errors, contact SIPB
        (x3-7788, {\tt netbsd-help@mit.edu}).

        \item Install the kernel.  Save your old kernel (in case there
        are problems), and (as root) install the new kernel.
\begin{verbatim}
mv /netbsd /onetbsd
cp netbsd /
\end{verbatim}

        \item If your system doesn't boot with the new kernel, you can
        have it boot the old kernel by hitting a key at the bootloader
        prompt, and then typing ``{\tt boot onetbsd}.''

        \item If you use a custom kernel, you should touch the file {\tt
        /netbsd.custom} to prevent the autoupdate script from replacing
        your kernel.  If the update requires a new kernel, you will need
        to build a new custom kernel and run the update manually.  If
        you need assistance, contact SIPB (x3-7788, {\tt
        netbsd-help@mit.edu}).

\end{enumerate}

The above procedure builds a 1.3.2 kernel.  If you are interested in
building a kernel from the latest NetBSD sources, you'll need to fetch a
copy of the -current NetBSD source tree and follow roughly the same
procedure using that.  Note that building and running a -current kernel
may require you to build various other software packages.  If you plan
on using -current source, be sure to follow the {\tt
current-users@netbsd.org} mailing list.  You can also ask questions on
the netbsd zephyr class ({\tt zctl add netbsd $\backslash$*
$\backslash$*}, \ {\tt zwrite -c netbsd}).

\subsection*{Where to get more information}

Start with {\tt http://www.netbsd.org/}, the home site for NetBSD.  The
site contains information on using NetBSD, and also includes archives of
the various NetBSD-related mailing lists.

\bigskip
\noindent\rule{4in}{.01in}

\noindent
Document revision: \rcsRevision. The latest version of this document
may be obtained in person from the SIPB office (W20-557), or may be
printed out with: {\tt attach sipb; dvips -hduplex -P{\it printer}
/mit/sipb/doc/netbsd-admin.dvi}.

\end{document}