<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE>Coda File System User and System Administrators Manual: Installing a Coda Server </TITLE>
<LINK HREF="manual-8.html" REL=next>
<LINK HREF="manual-6.html" REL=previous>
<LINK HREF="manual.html#toc7" REL=contents>
</HEAD>
<BODY>
<A HREF="manual-8.html">Next</A>
<A HREF="manual-6.html">Previous</A>
<A HREF="manual.html#toc7">Contents</A>
<HR>
<H2><A NAME="InstallSvr"></A> <A NAME="s7">7. Installing a Coda Server </A></H2>
<P>
<H2><A NAME="ss7.1">7.1 Introduction</A>
</H2>
<P>
<P>A Coda cell is a set of servers which all believe one member of the
set to be the master, or SCM server. All modifications to important
Coda databases should be made on the SCM, otherwise the SCM plays the
role of an ordinary Coda server. The
<CODE>updateclt</CODE>/<CODE>updatesrv</CODE>
daemons will then propagate
changes from the SCM to the other servers.
<P>The first server setup must be the SCM. This chapter is divided into
three sections: installing the binaries, configuring the system using
the configuration script <CODE>vice-setup</CODE> (for both SCM and non-SCM
servers) and finally, a detailed look at what needs to be done to
setup a server manually. Before beginning, we have provided some
overview information to assist in setting up the server.
<P>
<H3>Recoverable Virtual Memory</H3>
<P>
<P>To help ensure that data is not lost or left in inconsistent state
between server restarts, Coda uses <EM>Recoverable Virtual Memory</EM>
(RVM) which is a transaction system that maintains the system state of
the Coda server meta data. RVM is a data logging transaction system
which writes modifications into the RVM log and upon truncation or
restart incorporates such modifications into the RVM data file. Both
log and data file for RVM are ideally held on raw partitions.
<P><EM>NOTE:</EM> this should not be confused with Virtual Memory.
<P>Upon startup, the Coda servers use RVM to restore the Coda system state.
To efficiently use this feature, you should have dedicated disk partitions
for optimal performance the log partition ideally on its own disk.
However, a disk sharing the log partition with other disk partitions or
the use of a log file may be used at corresponding loss of optimal
performance. See section
<A HREF="#RVMInitialization">XXX</A> for more
details on RVM.
<P>
<H3>Server Disk Organization</H3>
<P>
<P>Coda servers require a minimum of 2 disk partitions for optimal
performance (one raw partition for the RVM Log, one raw partition for
RVM Data and one regular UNIX filesystem to hold file data store in Coda),
data security and protection from accidental deletion. For additional
performance gains the RVM Log partition should be on its own disk to
avoid head movement latencies which reduces disk seek times on log
operations. Optionally, <CODE>/vice</CODE> can be a separate partition for
the same reasons it is advantages to have <CODE>/var</CODE> as a separate
partition.
<P>However, other configuration may be used such as having
the RVM Data and Log information stored as regular UNIX files at a loss in
performance and data security. Also, if more than one Storage Area Data
is needed on a Coda Server (the default directory is called <CODE>/vicepa</CODE>),
the additional storage areas must be separate partitions (different
partition from <CODE>/vicepa</CODE> the default, initial storage area for data
under Coda) and mounted as <CODE>/vicepb</CODE>, for example.
<P>
<P>The table below shows a possible partitioning of disks on Coda servers with
their respective purpose, mount points, typical sizes and consistency
check program. Please note that the sizes of these partitions were
taken from one of the Coda servers at CMU-SCS: the actual sizes may
vary at other installations.
<CENTER><TABLE BORDER><TR><TD>
<BR>
<B>Partition</B></TD><TD><B>Storage Purpose</B></TD><TD><B>Mounted</B></TD><TD><B>Typical Size</B></TD><TD><B>Whether fscked</B></TD></TR><TR><TD>
hda2</TD><TD>RootandUser File System</TD><TD>/</TD><TD>650MB</TD><TD>Yes</TD></TR><TR><TD>
hda5</TD><TD>Var file system</TD><TD>/var</TD><TD>100MB</TD><TD>Yes</TD></TR><TR><TD>
hda3</TD><TD>Vice File System</TD><TD>/vice</TD><TD>300MB</TD><TD>Yes</TD></TR><TR><TD>
hdc1</TD><TD>RVM Log</TD><TD>Not</TD><TD>12MB</TD><TD>No</TD></TR><TR><TD>
sda1</TD><TD>RVM Data</TD><TD>Not</TD><TD>130MB</TD><TD>No</TD></TR><TR><TD>
sda2</TD><TD>Coda FS Data0</TD><TD>/vicepa</TD><TD>1.6GB</TD><TD>Yes</TD></TR><TR><TD>
sda3</TD><TD>Coda FS Data1</TD><TD>/vicepb</TD><TD>1.6GB</TD><TD>Yes</TD></TR><TR><TD>
sda5</TD><TD>Coda FS Data2</TD><TD>/vicepc</TD><TD>1.6GB</TD><TD>Yes</TD></TR><TR><TD>
<CAPTION>Example of Partitions for a Coda Server</CAPTION>
</TD></TR></TABLE></CENTER>
<P>
<P>
<H2><A NAME="ss7.2">7.2 Obtaining Coda</A>
</H2>
<P>Currently, the binary and source packages are available via ftp from
<P>(
<A HREF="ftp://ftp.coda.cs.cmu.edu/pub/coda">ftp://ftp.coda.cs.cmu.edu/pub/coda</A>/<platform>)
<P>as well as the Coda Project's local Coda servers
(<CODE>/coda/project/release/objs</CODE>/<platform>)
for CMU users. The platform layout for finding the Coda binaries relative
to the base directory indicated above is:
<P>
<BLOCKQUOTE><CODE>
<PRE>
linux/<coda-release>/{i386,sparc,coda-fs-module,SRPMS} # For Linux
freebsd/<coda-release>/<OS_RELEASE_VERSION>/i386 # For FreeBSD
netbsd/<coda-release>/<OS_RELEASE_VERSION>/i386 # For NetBSD
</PRE>
</CODE></BLOCKQUOTE>
<P>Where <coda_release> refers to the Coda version and
<OS_RELEASE_VERSION> is the version of the Operating System.
For example, if you want Coda release 4.3.13 for i386 FreeBSD 2.2.5,
the correct platform directory is: <CODE>fbsd/4.3.13/2.2.5/i386/</CODE>. For
i386 Linux, it is: <CODE>linux/4.3.13/i386/</CODE>, and for i386 NetBSD 1.3,
it is: <CODE>netbsd/4.3.13/1.3/i386/</CODE>. For more information on the layout,
please check the document <CODE>LAYOUT</CODE> available in the top-level of
the locations listed above for obtaining Coda. However, the following
files are needed by the various platforms:
<P>
<DL>
<P>
<DT><B>Linux</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
coda-debug-server-<release>.i386.rpm
coda-doc-<release>.i386.rpm
coda-debug-backup-<release>.i386.rpm
</PRE>
</CODE></BLOCKQUOTE>
<P>
</DL>
<P>Note that the Coda Project supports the glibc (GNU C Library) version
of Red Hat (5.X and higher). Support for the older Linux standard Lib
C is no longer provided although Coda is known to run on many other
Linux systems.
<P>
<DL>
<P>
<DT><B>FreeBSD and NetBSD</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
coda-server-<release>.tgz
coda-doc-<release>.tgz
</PRE>
</CODE></BLOCKQUOTE>
<P>
</DL>
<P>
<H2><A NAME="ss7.3">7.3 Installing and Configuring A Coda Server</A>
</H2>
<P>
<P>Currently, Linux, NetBSD and FreeBSD are supported (CMU-MACH is no
longer supported). For Linux, the Red Hat Package Management tool
is supported. The package system of FreeBSD 2.X and higher as well
as NetBSD 1.3+ is now supported.
<P><EM>TIP</EM>: Always check the INSTALL.<platform> on
(
<A HREF="ftp://ftp.coda.cs.cmu.edu/pub/coda">ftp://ftp.coda.cs.cmu.edu/pub/coda</A>/<platform>)
for last minute changes and updates that have not yet found their way
into the manual.
<P>
<H3>Installing the Coda Server Binaries and Documentation</H3>
<P>
<P>Currently, server excutables for the supported platforms are installed
into the following directories:
<P>
<DL>
<P>
<DT><B>Linux</B><DD><P>installs files/binaries in <CODE>/etc</CODE>, <CODE>/usr/bin</CODE>
and <CODE>/usr/sbin</CODE>.
<P>
<DT><B>FreeBSD</B><DD><P>installs files/binaries in <CODE>/usr/local/etc</CODE>,
<CODE>/usr/local/bin</CODE> and <CODE>/usr/local/sbin</CODE>
<P>
<P>
<DT><B>NetBSD</B><DD><P>installs files/binaries in <CODE>/usr/pkg/etc</CODE>,
<CODE>/usr/pkg/bin</CODE> and <CODE>/usr/pkg/sbin</CODE>
<P>
</DL>
<P>
<P>
<P><EM>NOTE:</EM>Please make sure your PATH environment variable is set properly
for your platform. That is, ensure FreeBSD has <CODE>/usr/local/{bin,sbin}</CODE>
and NetBSD has <CODE>/usr/pkg/{bin,sbin}</CODE> in its default search paths.
Linux installs Coda into the default system paths, so Linux shouldn't need
its default seach path modified.
<P>
<P>There is one directory used by all platfroms: <CODE>/vice</CODE> which is
used to store the supporting Coda configuration and Coda databases. It
does not need to be in the PATH.
<P>
Specific steps to install the binaries and documentation are:
<P>
<DL>
<P>
<DT><B>Linux</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
rpm -Uvh coda-debug-server-<release>.i386.rpm
rpm -Uvh coda-doc-<release>.i386.rpm
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DT><B>NetBSD and FreeBSD</B><DD><P>The installation procedure is identical for both platforms (we assume you are
using GNU tar which is the default tar for both platforms):
<BLOCKQUOTE><CODE>
<PRE>
pkg_add coda-server-<OS_RELEASE_VERSION>-<coda_release>.tgz
tar zxfv coda-doc-<release>.tgz -C /usr/share
</PRE>
</CODE></BLOCKQUOTE>
Please note that NetBSD uses a different location for NetBSD
packages (/usr/pkg instead of /usr/local). Please make
sure /usr/pkg/{bin,sbin} are in your paths under NetBSD.
</DL>
<P>
<H3>Configuring A Coda Server</H3>
<P>
<P>Server setup is similar for all platforms.
<P>
<H3>Before Beginning</H3>
<P>
<P>
<A NAME="BeforeBegining"></A>
The <CODE>/vice</CODE> directory will be created by the setup script automatically
if it does not already exist. However, if your root partition does not have
enough additional space (e.g. the SrvLog file can become huge +10MB under
certain circumstances), you will need to create a partition
to be mount as <CODE>/vice</CODE>, format the partition as normal UNIX file system,
create the mount point <CODE>/vice</CODE>, add the partition and mount information
to <CODE>/etc/fstab</CODE> and mount it by hand <EM>BEFORE</EM> running the setup
script.
<P>Alternatively, <CODE>/vice</CODE> may be a symbolic link to a directory
on an existing partition with enough space but it also must be created
before running the setup script, <CODE>vice-setup</CODE>. Sub-directories
needed under <CODE>/vice</CODE> will be created by <CODE>vice-setup</CODE>.
<P>Also note that the setup of an SCM differs in some important
ways from a non-SCM setup. So, when <CODE>vice-setup</CODE> asks:
<EM>Will this machine will be the SCM?</EM> it is very important
this question is answered correctly.
<P>Only one SCM should be setup per Coda Cell and Coda does not support
multiple-homing cells at this time.
<P>While <CODE>vice-setup</CODE> sets up things that are common for
both the SCM and non-SCM servers, the setup of scripts called
by answering yes to the <EM>Is this the SCM?</EM> are:
<P>
<DL>
<DT><B>SCM Setup</B><DD><P><CODE>vice-setup</CODE>
<BLOCKQUOTE><CODE>
<PRE>
vice-setup-scm
vice-setup-user
vice-setup-rvm
vice-setup-srvdir
</PRE>
</CODE></BLOCKQUOTE>
</DL>
The set of scripts called by answering no are:
<DL>
<DT><B>non-SCM Setup</B><DD><P><CODE>vice-setup</CODE>
<BLOCKQUOTE><CODE>
<PRE>
vice-setup-rvm
vice-setup-srvdir
</PRE>
</CODE></BLOCKQUOTE>
in the order listed above.
</DL>
<P>
<H3>Setting Up A Coda Server</H3>
<P>
<P>If this is the first (or only) server being setup for a Coda cell, it must
be setup as the ``SCM'' by answering yes to the question when asked by
<CODE>vice-setup</CODE>.
The SCM coordinates the sync'ing of Coda database and global configuration
files needed to keep track of data stored in Coda. The SCM also coordinates
the authentication of a Coda user.
<P>If you are adding a non-SCM server which keeps
copies of databases, but does not distribute them to the rest of the
machines comprising a Coda Cell answer no to the question.
<P>Other than the distinctions indicated above, the SCM plays no
special role in a Coda cell and can actually be down for a short time
without denying service in a multiple-machine cell site. However, is
extremely important to only have one SCM
<P><EM>NOTE:</EM> that running
a server seriously dips into system virtual memory. Running a
Coda server, a Coda client <EM>and</EM> X11, the Coda Group
as observed that a slightly over 64MB of available VM is
needed. The command <CODE>top</CODE> gives information
on memory, cpu and process usage. Therefore, we recommend
not running a Coda client on a Coda server and only run X when
performing server maintenance if X is convenient to use.
<P>Whether setting up an SCM Coda server or adding a server to an existing
Coda Cell, make sure the following items are taken care before running the
setup script:
<P>
<OL>
<LI>an empty directory ( /vicepa ) where the file server will put user files.
If more than one storage are are is needed for file space on an existing
server, such as needed <CODE>/vicepb</CODE>, additional space
must be a separate partition from <CODE>/vicepa</CODE>.</LI>
<LI>a raw partition for RVM metadata (you can use a file but this will
be slow on a medium to large server) This partition
must be around 4% of the total size of the files you wish
to store under /vicepa (e.g. on a 3.3GB server we use around
130M of rvm data). Consider 10M to be the minimum. </LI>
<LI>a LOG partition, preferably on a disk by itself. This
needs not be large (12MB is large enough for a 3.3GIG partition
which is the largest default configuration provided by
<CODE>vice-setup-rvm</CODE> script). </LI>
<LI>two secret tokens of _exactly_ 8 characters (eg elephant).
The RVM files involve the journalling/transactional aspects
of Coda and communicating this information between servers
and via the loop-back device when the SCM updates itself. The tokens
are used to secure intra-server communication.</LI>
<LI>If the root partition is not large enough to hold <CODE>/vice</CODE>,
having alternative measures setup as outlined in
<A HREF="#BeforeBegining">Before Begining</A>.</LI>
</OL>
<P>Once you have the above items available, run:
<P><CODE>vice-setup </CODE>
<P>This provides several useful ``canned'' configuration for setting up
a Coda server. It does a number of things ``behind the scenes'' as well
(such as setting up the directory <CODE>/vice</CODE> if it doesn't exist
and populating it with the sub-directories <CODE> backup db srv vol bin</CODE>)
while asking the following questions:
<P>
<DL>
<P>
<DT><B>Enter a random token for auth2 authentication :</B><DD><P>This must be _exactly_ eight characters in length. This requirement
is due to a bug that hasn't been completely fix yet.
<DT><B>Enter a random token for volutil authentication :</B><DD><P>This must be _exactly_ eight characters in length and different
that the auth2 token. This requirement is due to a bug that has not
been completely fixed yet.
<P>
<DT><B>Do you want to start the server at boot time? (y/n)</B><DD><P>Answering yes to this question creates the file
<CODE>/vice/srv/STARTFROMBOOT</CODE>
which must be present for either <CODE>rc.vice</CODE> or <CODE>vice.init</CODE>
to start the server at boot time. Removal of this file will prevent the Coda
server from starting automatically at boot time.
<P>
<DT><B>Is this the master server, aka the SCM machine? (y/n)</B><DD><P>For the first Coda machine being setup in a Coda cell, the answer must
be "yes". If you are adding a server to an existing Coda cell, the
answer must be "no".
<P>
</DL>
<P>If you have answered ``no'' to the above question, you will be asked
for the HOSTNAME of an existing SCM:
<P>
<P>If you have answered ``yes'' to the above question, you will see
the message:
<BLOCKQUOTE><CODE>
<PRE>
An initial administrative user "admin" with password "changeme" now exists
</PRE>
</CODE></BLOCKQUOTE>
. and pick up at the question <EM>Are you ready
to setup up RVM?</EM>
<P>If you have answered ``no'' to the above question, you will be asked
for the HOSTNAME of an existing SCM:
<DL>
<P>
<DT><B>Enter the hostname of the SCM machine :</B><DD><P>This question is only asked if the machine is not the SCM. The hostname
entered must be that of the SCM which distributes the Coda cells'database and
global configuration files.
<P>
</DL>
<P>
<DL>
<P>
<DT><B>Are you ready to set up RVM? [yes/no]</B><DD><P>Answer yes to this question or the setup will abort.
<P>
<DT><B>What is your log partition?</B><DD><P>RVM is the Recoverable Virtual Memory used to keep a copy of Coda Virtual
memory on local disk.
While this can be a file, it is strongly recommended that it
be a small partition on a dedicated disk.
If you have set aside, for example, /dev/sdc1 under Linux as
the log partition, enter the partitions' device name at the prompt. If you
are setting up a *BSD system, you must enter the raw partition name.
For example, if you are going to use <CODE>/dev/sd2e</CODE> you must enter
the raw device name <CODE>/dev/rsd2e</CODE>.
The maximum template size we provide for and have tested is 30MB.
<P>
<DT><B>What is your log size? (enter as e.g. '12M')</B><DD><P>The log partition keeps transaction records for Coda volume updates
that may not have been writen to the Coda data partition yet. We
have not extensively tested values above 30MB and don't recommend more
than this. 12M is a good value for a small to medium sized server. The
value may be entered as, <CODE>12M</CODE> or <CODE>12288</CODE> for 12 mega-bytes.
<CODE>Please see section
<A HREF="#RVMDatapartition">The Data Partition</A> for a more detailed explanation</CODE>
<P>
<DT><B>What is your data partition (or file)?</B><DD><P>This allows you to specify a partition or file. We strongly recommend
a partition which can reside with other system partitions. Remember,
if you use a partition, you are using it "raw" . it does not contain
a file system of any kind. Again, if you are using Linux, you may
enter a block device name such as <CODE>/dev/sdc1</CODE>. If you are
using a *BSD system, you must enter a raw device such as
<CODE>/dev/rsd2e</CODE>.
<P>
<DT><B>What is the size of you data partition (or file) [22M,44M, 90M, 130M]: "</B><DD><P>This specifies the the size of the RVM data partition. It must
be typed exactly as <CODE>22M</CODE>, <CODE>44M</CODE> , <CODE>90M</CODE> , or
<CODE>130M</CODE> . These are associated with default parameters that
must be feed to <CODE>codasrv</CODE> when it is started. The following table
provides the log size to total data storage conversion:
<UL>
<LI><CODE>22M</CODE> is good for up to 500MB</LI>
<LI><CODE>44M</CODE> is good for up to 1.0GIG</LI>
<LI><CODE>90M</CODE> is good for up to 2.2GIG</LI>
<LI><CODE>130M</CODE> is good for up to 3.3GIG</LI>
</UL>
For a detailed explanation of the trade off between different
Data log sizes vs. Data Storage Space, please see the section
<A HREF="#RVMLogpartition">The Log Partition</A>.
<P>
<DT><B>Proceed, and wipe out old data? [y/N]</B><DD><P>
<DL>
<DT><B>WARNING</B><DD><P>if you have entered erronous entries for RVM log
and RVM data partitions, you could damage your system. Be sure you
entered correct information!
</DL>
This is the last chance before any action is taken by the setup script.
Enter <CODE>y</CODE> to commit or <CODE>N</CODE> to abort.
<P>
<DT><B>Where shall we store your data [/vicepa]?</B><DD><P>Older development versions of coda require <CODE>/vicepa</CODE> to be present.
This version does not. You give a name other than the default we
suggest. However, we strongly advise not calling it <CODE>/code</CODE> as
that can be confused with venus.
<P>
</DL>
<P>Once you successfully complete <CODE>vice-setup</CODE>:
<P>
<DL>
<P>
<DT><B>And an SCM server is being setup</B><DD><P>you are ready to start the update server, the update client and
the auth server, as well as the fileserver by typing:
<DL>
<P>
<DT><B>For Linux:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
/etc/rc.d/init.d/update.init start
/etc/rc.d/init.d/auth2.init start
/etc/rc.d/init.d/codasrv.init start
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DT><B>For FreeBSD:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
/usr/local/sbin/auth2 &
/usr/local/sbin/updateclnt -h `cat /vice/db/scm` -q coda_udpsrv &
/usr/local/sbin/updatesrv -p /vice/db &
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DT><B>For NetBSD:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
/usr/pkg/sbin/auth2 &
/usr/local/sbin/updateclnt -h `cat /vice/db/scm` -q coda_udpsrv &
/usr/local/sbin/updatesrv -p /vice/db &
</PRE>
</CODE></BLOCKQUOTE>
<P>
</DL>
<P>One final step is needed to make the SCM server function. Use
the root volume you specified in vice-setup in place of
your-root-volume. This step creates the volume, which will
be mountable by the client software.
<BLOCKQUOTE><CODE>
<PRE>
createvol_rep your-root-volume E0000100 /vicepa
</PRE>
</CODE></BLOCKQUOTE>
<P>Once you have done this, check that the server has started by viewing the
log:
<BLOCKQUOTE><CODE>
<PRE>
xterm -e tail -f /vice/srv/SrvLog &
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DT><B>If this is a non-SCM server</B><DD><P>You should start auth2, updatesrv and updateclnt
first by typing:
<DL>
<P>
<DT><B>For Linux:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
/etc/rc.d/init.d/update.init start
/etc/rc.d/init.d/auth2.init start
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DT><B>For FreeBSD:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
/usr/local/sbin/auth2 -chk &
/usr/local/sbin/updateclnt -h `cat /vice/db/scm` -q coda_udpsrv &
/usr/local/sbin/updatesrv -p /vice/db &
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DT><B>For NetBSD:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
/usr/pkg/sbin/auth2 -chk &
/usr/pkg/sbin/updateclnt -h `cat /vice/db/scm` -q coda_udpsrv &
/usr/pkg/sbin/updatesrv -p /vice/db &
</PRE>
</CODE></BLOCKQUOTE>
<P>
</DL>
<P>This will cause the new server to first obtain the current server
files such as <CODE>/vice/db/ROOTVOLUME</CODE> and <CODE>/vice/db/VRList</CODE>
as well as others needed for this server to participate in the
Coda cell. Once these files have been retrieved, you may start the
server manually for the first type by typing:
<P>
<DL>
<P>
<DT><B>For Linux:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
/usr/sbin/startserver &
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DT><B>For FreeBSD:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
/usr/local/sbin/startserver &
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DT><B>For NetBSD:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
/usr/pkg/sbin/startserver &
</PRE>
</CODE></BLOCKQUOTE>
<P>
</DL>
<P>Once you have done this, check that the server has started by viewing the
log:
<BLOCKQUOTE><CODE>
<PRE>
xterm -e tail -f /vice/srv/SrvLog &
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<EM>NOTE:</EM> the above distinction between SCM and non-SCM server
is non-trival.
<P>If the <CODE>codasrv</CODE> process started correctly, you should see
``File Server started'', if not you need look at the messages in the SrvLog
to determine what went wrong. If the messages are not helpful, you
should kill the server (<EM>NOTE:</EM>The server is designed to continue to
stay up so gdb can be attached for debugging):
<BLOCKQUOTE><CODE>
<PRE>
kill -9 `cat /vice/srv/pid`
</PRE>
</CODE></BLOCKQUOTE>
and then you can restart the server with:
<BLOCKQUOTE><CODE>
<PRE>
startserver -d 10 &
</PRE>
</CODE></BLOCKQUOTE>
<H3>Basic Trouble Shooting and Misc.</H3>
<P>However, assuming that the server came up, also make sure updatesrv
and updateclnt are running by using either <CODE>top</CODE> or <CODE>ps</CODE>.
<P>
<DL>
<DT><B>NOTE:</B><DD><P>you need the package bc (binary calculator on the server).
you can either obtain from our ftp site or a mirror
site containing your operating system and contrib software.
<P>
<DT><B>NOTE2:</B><DD><P>E0000100 is the Volume Storage Group set up for you
by vice-setup when setting up an SCM. With more servers
you can define other groups in /vice/db/VSGDB.
</DL>
<P>Once this is complete, you should setup a client
machine and run Venus and point <CODE>venus</CODE> point to this server.
Setting up
a client machine with <CODE>venus</CODE> is covered in the next chapter.
Once you have tested and verified the Coda server works from a client,
you are ready to adduser more volumes and users!
<P><B>NOTE:</B> A current limitation of the current vice-setup-user script is
that the initial admin account needed is assigned a Coda uid of 500.
In order for a client to authenticate a user, that user must exist
with the same corresponding user-id in the UNIX password file.
If you need to change the admin account uid to suite local uid space,
please edit the script <CODE>vice-setup-user</CODE>, change the default
Coda uid to the needed value and re-run the script. This only applies
if you are setting up the SCM.
<P>Otherwise, if this is a non-SCM server, you might consider setting up
a singlely replicated volume on the new server to test it.
<P>
<H2><A NAME="ss7.4">7.4 Underneath vice-setup</A>
</H2>
<P>
<P>The sections contained here describe what <CODE>vice-setup</CODE> does for
you. This information is useful for those who either wish to customize
our default vice-setup script or wish to have a custom server setup
outside the scope of Coda's setup script..
<P>
<H3>RVM Initialization</H3>
<P>
<A NAME="RVMInitialization"></A> <P>RVM initialization requires the selection of several parameters, each
of which involve tradeoffs. Although the
RVM log and data can be kept as regular UFS files, <B>this is not
recommended</B>: Raw partitions have much stronger data consistency
guarantees as well performance advantages.
It is probably best to plan out the RVM partitions on
paper first, taking into consideration both the effect on RVM
performance as well as overall disk usage if you choose not to
use the values provided in the <CODE>vice-setup</CODE> script.
<P>
<H3>The Log Partition</H3>
<P>
<A NAME="RVMLogpartition"></A> <P>The size of the log device is based on available space and issues
involving truncation. Larger logs provide a longer accessible history
of operations, are truncated less frequently, but each truncation will
take a longer period of time. Shorter logs truncate more often, but
each truncation takes less time. Log size is also strongly related to
server startup time as well. We use a 90M log size, on a
storage size roughly 3.2GIG spread between two UNIX partitions.
(We suggest leaving a little space at the
end of the RVM log partition for safety, as RVM automatically adds
about one extra page to the amount you specify). Our <CODE>vice-setup</CODE>
script provides for several default values, the largest of which is
130MB. If you decide to follow the recommendation and use a dedicated
partition, creating a 130MB partition will leave plenty of room to expand
even if your initial use only suggests a size of 22M, for example..
<P>The log is initialized with <B>rvmutl</B>. At
<B>rvmutl</B>s prompt, use the command <B>i</B>, and
then specify the size of the log segment. In specifying the size, you
can use M for megabyte and K for kilobyte. For example, to initialize
a log on partition 0g to eight megabytes:
<P>
<BLOCKQUOTE><CODE>
<PRE>
# @B(rvmutl)
* i
Enter name of log file or device: /dev/sdc1
Enter length of log data area: 22M
* q
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3>The Data Partition</H3>
<P>
<A NAME="RVMDatapartition"></A> <P>The data segment contains the meta-data of the system such as
volume headers, Coda directories, vmond lists, resolution logs, etc.
The size of the data segment depends on the amount of disk space for file
data, i.e. the size of the /vicep? partitions. As a rule of thumb, you will
need about 3-5% of the total file data space for recoverable
storage. We currently use 4% as a good value under most circumstances.
In our systems the data segment is 90Meg for approximately 3.2 gigabytes of
disk space. By making it smaller, you can reduce server startup time.
However, if you run out of space on the RVM Data partition, you will be
forced to reinitialize the system, a costly penalty. So, plan accordingly.
<P>In initializing (or reinitializing), you need to pick several parameters.
The first is the starting address of the recoverable segment in your
address space. On our servers we start the RVM segment at 0x20000000
for both Linux and BSD based systems on Intel architecture.
The second is the amount of space to give the recoverable heap. The
heap will obviously grow over use, so plan accordingly. Our heap
space is 0x1000000. We suggest that for the last parameters you use
1Meg (0x100000) for the static area, use 80 free lists (or nlists),
and a chunksize of 32. These numbers will work well
with the internal structure of the fileserver and are provided as the
default vales in the setup script <CODE>vice-setup</CODE>.
<P>To perform the data initialization, run the program
<B>rdsinit</B>. <B>rdsinit</B> takes two parameters,
the names of the RVM log and data devices. For example, to initialize
one of our Intel based servers:
<P>
<BLOCKQUOTE><CODE>
<PRE>
# rdsinit /dev/hdc1 /dev/sdb1
Enter the length of the device /dev/hdc1:119070700
Going to initialize data file to zero, could take awhile.
done.
rvm_initialize succeeded.
starting address of rvm: 0x20000000
heap len: 0x1000000
static len: 0x100000
nlists: 80
chunksize: 32
rds_zap_heap completed successfully.
rvm_terminate succeeded.
</PRE>
</CODE></BLOCKQUOTE>
<P><EM>NOTE:</EM> the use of the decimal value for the length of the device
and the use of hex values for the address and lengths of the next
three values.
<P>
<H3>Update Monitor</H3>
<P>The update monitor is used to propagate changes to the Coda server databases
to all servers from the SCM. Client update processes run on all the Coda
servers and connect to a server udpate process running on the SCM.
The server process uses the file <CODE>/vice/db/files</CODE> to determine which
files should be kept consistent on all the servers. See the
<EM>updateclnt</EM>(8) and <EM>updatesrv</EM>(8) man pages for more details.
<P>Create the file <CODE>/vice/db/files</CODE> on the SCM. Currently our
<CODE>/vice/db/files</CODE> looks like this:
<P>
<BLOCKQUOTE><CODE>
<PRE>
VLDB
auth2.pw
auth2.tk
pro.db
servers
hosts
vice.pdb
vice.pcf
volutil.tk
VRDB
files
VSGDB
dumplist
scm
ROOTVOLUME
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3>Authentication Database</H3>
<P>
<P>Coda uses an authentication database that is separate from the UNIX password
file. This database is maintained by the SCM. When someone authenticates
to Coda, their password is checked against this database and that person is
issued a token if they successfully authenticate. This section describes
how to initialize the authentication database.
<P>
<H3>On the SCM</H3>
<P>If the server you are installing is the SCM, you must set up the initial
authentication database. Make sure you add at least one user to the
<CODE>System:Administrators</CODE> group. You need to do the following:
<P>
<UL>
<LI>Create or modify an appropriate user file in the Vice format
<B>user_coda (5)</B>. An example of <CODE>user.coda</CODE> can be
found in the directory <CODE>/vice/db</CODE> as
well as in Appendix
<A HREF="manual-18.html#ExampleFiles">XXX</A>.</LI>
<LI>Create or modify an appropriate group.coda file in the Vice format
<B>group.coda (5)</B>. It is vital that you add at least one user
from the <CODE>user.coda</CODE> file to the group
<CODE>System:Administrators</CODE>. An example of <CODE>group.coda</CODE> can be
found in the directory <CODE>/vice/db</CODE> as
well as in Appendix
<A HREF="manual-18.html#ExampleFiles">XXX</A>. </LI>
<LI>
<CODE>/usr/sbin/pwd2pdb -u user.coda -g group.coda > vice.pdb</CODE></LI>
<LI><CODE>/vice/bin/pcfgen vice.pdb</CODE> which will create vice.pcf.</LI>
<LI>Create a file /vice/db/passwd.coda, owned by root, readable only by root,
with the initial passwords for
users in the Vice passwd file format (passwd_coda (5)). The format of
the passwd.coda file should be as follows:
<CODE>uid<TAB>actual cleartext password<TAB>any desired info</CODE>.
The information field could be the full name of the
user. Name this file <CODE>/vice/db/passwd.coda</CODE>. Then run the command
<CODE>initpw -k "drseuss " </vice/db/passwd.coda > /vice/db/auth2.pw</CODE>
This command produces the file <CODE>auth2.pw</CODE> in the format:
<CODE>uid<TAB>encrypted password<TAB>Desired info</CODE>.
Note: "drseuss " is an encryption key to prevent accidental disclosure
of the passwords to the system administrators. In future versions of
coda we will store a sites specific encryption key in a configuration file.
Note that all future changes of the password must be made through the
au(1) program, and not by repeating this procedure since that would
overwrite any passwords changed by users after initialization.
New passwords must be <EM>exactly</EM> 8
characters long. To add additional users, please see Section
<A HREF="manual-11.html#AddUsers">XXX</A>. </LI>
<LI>You also must choose a password for the servers to use in generating the
<EM>secret</EM> token (see Chapter
<A HREF="manual-5.html#SysOvr">SysOvr</A>
) for more information.
This secret token is used for secure communication.
Put the password in <CODE>/vice/db/auth2.tk</CODE>.</LI>
<LI>Create the ticket file
<CODE>/vice/db/volutil.tk</CODE>, used for secure communication among
the servers. This file should contain a single word which will be used to
encrypt messages between the server and server applications. The file
should be present on all servers. The UpdateMon presently takes care of
propagating them from the SCM.</LI>
</UL>
<P>
<H3>On Servers OTHER than the SCM</H3>
<P>
<P>On servers other than the SCM, the <B>Update</B> monitor will
ensure that the proper database files are propogated from the SCM.
However, you must copy the file <CODE>/vice/db/volutil.tk</CODE>
to the new server for the <B>Update</B> monitor to work.
<P>
<H3>Creating the Volume Storage Group DataBase (SCM only)</H3>
<P>
<P>Every combination of servers setup expects to use as a VSG which
must be given a multicast address in <CODE>/vice/db/VSGDB</CODE>.
This file must be created by hand; please refer to <B>VSGDB (5)</B>
in Appendix
<A HREF="manual-19.html#ManPages">XXX</A> for more details.
<P>
<H2><A NAME="ss7.5">7.5 Starting the File Server</A>
</H2>
<P>We have provided a script called <CODE>startserver</CODE>
which reads in the file <CODE>/vice/srv.conf</CODE> which contains the
startup information needed by <CODE>codasrv</CODE>. The syntax of
<CODE>/vice/srv.conf</CODE> is:
<BLOCKQUOTE><CODE>
<PRE>
-rvm <log_partition> <data_partition> <size_of_log_partition>
</PRE>
</CODE></BLOCKQUOTE>
The <CODE>vice-setup-rvm</CODE> contains the canned default value
for the corresponding value entered through <CODE>vice-setup</CODE>.
Should you deviate from one of these canned default values, you will
need to either create or modify the <CODE>/vice/srv.conf</CODE> file
to indicate the correct data size of the data partition. For example,
one of CMU's Coda servers contains:
<BLOCKQUOTE><CODE>
<PRE>
-rvm /dev/hdc1 /dev/sda1 119070700
</PRE>
</CODE></BLOCKQUOTE>
<P>You should be careful to specify the correct partitions
for the RVM log, data segment, and size of the data segment.
<P>Once this file has been correctly edited, you can start the server with
<B>startserver&</B>.
<P>
<H3><A NAME="RootVolume"></A> Creating the Root Volume </H3>
<P>If you are installing any server other than the SCM, please use the
instructions in section
<A HREF="manual-10.html#CreateVol">XXX</A> to create new
volumes on this server.
<P>The root of the Coda file system must reside on the /vicepa partition
for correct functioning. Since the SCM probably also acts as a
server, place the root of the Coda file system in the /vicepa
partition on the SCM. Create the root volume by using either one
of the following commands
<P><CODE>% createvol_rep codaroot <VSG_ENTRY> /vicepa</CODE>
<P><CODE>% createvol codaroot <hostname> /vicepa</CODE>
<P>the former is for replicated root volume, where <VSG_ENTRY> is
the entry in the <CODE>VSGDB</CODE> for the volume storage group for this
volume; the later is for non-replicated root volume, where
<hostname> is the name of the host which hosts the root volume.
Since it is likely that the root will be cloned and read-only
replicated, you might wish to create this volume as singly replicated
for simplicity.
<P>
<P>These commands will create the <CODE>/vice/db/VLDB</CODE>, <CODE>/vice/db/VRDB</CODE>,
<CODE>/vice/vol/VolumeList</CODE>, <CODE>/vice/vol/BigVolumeList</CODE>,
and the <CODE>/vice/vol/AllVolume</CODE> files.
<P>Create or modify the file <CODE>/vice/db/ROOTVOLUME</CODE> to contain the
volume name (E.g. <CODE>codaroot</CODE>) corresponding to the root volume as
listed in the file <CODE>/vice/vol/VRList</CODE>.
<P>
<H3>Creating a readonly root</H3>
<P>You may wish for the root to be readonly. To do this, first create a root
volume as above. Start a venus which can talk to this server. Setup the
directory structure you want in your root volume. Once you are
satisfied with the structure, clone the volume and
dump it to a disk file with the the <CODE>volutil</CODE> program. Now restore
the dump file to the servers in the desired VSG for the readonly volume.
Be sure to specify the volumeId and the volume Name for the new volume:
<P><CODE>% volutil restore <filename> /vicepa <newrootname> <volid></CODE>
<P>Then modify the <CODE>/vice/db/ROOTVOLUME</CODE> file to contain the new
rootvolume name, <newrootname>.
<P>
<P>
<P>
<P>
<P>
<P>
<P>
<HR>
<A HREF="manual-8.html">Next</A>
<A HREF="manual-6.html">Previous</A>
<A HREF="manual.html#toc7">Contents</A>
</BODY>
</HTML>
distrib
>
Mandriva
>
8.2
>
i586
>
media
>
contrib
>
by-pkgid
>
211238da6d926d1ca4390483bb29f586
>
files
>
42
