close Warning:

Changes between Initial Version and Version 1 of CodaHOWTO/Configuration


Ignore:
Timestamp:
Feb 8, 2007, 1:08:23 PM (11 years ago)
Author:
jaharkes
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • CodaHOWTO/Configuration

    v1 v1  
     1[[TracNav(CodaHOWTO)]]
     2
     3= Configuring and starting Coda =
     4
     5''WARNING: CODA IS BARELY READY FOR PRODUCTION USE. THIS RELEASE IS JUST FOR THOSE INTERESTED IN EXPLORING THOSE FEATURES WHICH WORK. IT CONTAINS KERNEL CODE, AND SERVERS RUNNING WITH ROOT PRIVILEGES, AND COULD LEAD TO DATA LOSS.''
     6
     7To get Coda running you will go through 3 steps:
     8
     9 1. Get a Coda enabled kernel for the client. (The server does not need a special kernel)
     10 2. Configure and run the client cache manager Venus
     11 3. Configure and run the file server, authentication server and update servers
     12 4. Connect a client to your new server.
     13
     14== Getting a Coda enabled kernel == #Kernel
     15
     16Before you can use a Coda client you need a new filesystem driver in your kernel. For the most part this driver redirects requests to the user level cache manager venus . Precompiled modules exist for commonly used kernels. If no module exists for you, you'll find instructions below where to find it.
     17
     18=== Linux ===
     19
     20Get a coda-fs-module-k2.?.?-c?.?.?.arch.rpm rpm package and install it. k2.?.? should match your kernel version (use uname -a) and c?.?.? should match you Coda version.
     21
     22Linux kernels change often and many people have custom kernels for their environment. Our modules will generally only work on RedHat Linux kernels and you may have to build a module for your kernel. Look at the section building a kernel module.
     23
     24=== FreeBSD ===
     25
     26You may obtain a Coda lkm from your FreeBSD distribution:
     27
     28{{{
     29    cd /lkm
     30}}}
     31
     32Check if coda_mod.o is there already. Otherwise, you may obtain a Coda lkm from the Coda site:
     33
     34    `ftp://ftp.coda.cs.cmu.edu/pub/coda/freebsd/3.0-aout/i386/coda_mod.o`
     35
     36You then install the lkm with:
     37
     38{{{
     39    modload -v -e coda_mod -o /var/run/lkm.coda /lkm/coda_mod.o
     40}}}
     41
     42You can build support for the Coda VFS layer into your kernel. This is discussed later in the Building FreeBSD section.
     43
     44=== NetBSD ===
     45
     46NOTE: The GENERIC NetBSD kernel should have Coda enabled. Do an:
     47
     48{{{
     49    nm -o /netbsd | grep coda_open
     50}}}
     51
     52If this is present, you are done with this section. PROCEED NO FURTHER
     53
     54If you need to load an lkm it should be in the NetBSD distribution:
     55
     56{{{
     57    cd /usr/lkm
     58}}}
     59
     60Check if coda.o is there already. Otherwise, you may obtain a Coda lkm from the Coda site:
     61
     62    `ftp://ftp.coda.cs.cmu.edu/pub/coda/netbsd/current/i386/coda-1_3H.o`
     63
     64You then install the lkm with:
     65
     66{{{
     67    modload -v -e coda_lkmentry -o /var/run/lkm.coda /usr/lkm/coda-1_3H.o
     68}}}
     69
     70You can build support for the Coda VFS layer into your kernel, though this should be automatic. This is discussed later in the Building NetBSD section.
     71
     72=== Windows NT & XP ===
     73
     74The kernel module is part of the Coda client installer.
     75
     76== Linux and the BSD's: running Venus, the client cache manager == #Unix
     77
     78These are partial instructions on how to setup and configure the Coda filesystem. Refinements to the setup created here are discussed in http://ftp.coda.cs.cmu.edu/doc/html/manual.html You will probably not need these refinements in the first instance.
     79
     80The venus-setup script does all the hard work, it will setup the coda control files, create /dev/cfs0 to communicate with the kernel, ... It also initializes a directory for cache files. In your first Coda run we recommend a small cache, say 20MB. The cache size should be at least 10Meg, typically 60-200Meg is used. Do not go above 300Meg. All the files created will be placed under /usr/coda . You should make sure that there is enough space in the file system on which /usr/coda resides to hold a fully populated cache.
     81
     82{{{
     83    venus-setup <comma_separated_host_list> <cache_size_in_kb>
     84}}}
     85
     86venus-setup and venus (below) are in /usr/sbin . Make sure that /usr/sbin is in your path or that you use fully qualified pathnames. We strongly recommend that you initially try testserver.coda.cs.cmu.edu as the comma_separated_host_list first, and keep the cache size to 20000.
     87
     88NOTE: venus-setup will edit /etc/services to make sure some additional services are registered.
     89
     90The following assumes you are running X-Windows. However, you could run these commands from virtual consoles as well, by omitting the xterm -e in front of the commands below.
     91
     92Start Venus with:
     93
     94{{{
     95    venus &
     96}}}
     97
     98An -init flag can be given when venus is started; it flushes the local cache contents. venus-setup forces an init to happen when venus is first started. The -init flag can be given if Coda cannot recover it's cache after a crash, or after editing the vstab file manually.
     99
     100Observe the venus log with:
     101
     102{{{
     103    xterm -e tail -f /usr/coda/etc/console
     104}}}
     105
     106It will tell you when venus has started and give status.
     107
     108Type:
     109
     110{{{
     111    xterm -e codacon &
     112}}}
     113
     114to see the communications between the Venus and Vice.
     115
     116It is possible to see the upcalls from the kernel to Venus by turning up logging in Venus, but they are not very interesting. (To turn on minimal debugging, type:
     117
     118{{{
     119    vutil -d 1
     120    tail -f /usr/coda/coda.cache/venus.log
     121}}}
     122
     123To halt venus, type:
     124
     125{{{
     126    vutil shutdown
     127    umount /coda  (Linux only)
     128}}}
     129
     130Or you can kill -9 venus, if you must.
     131
     132NOTES for Linux users:
     133
     134    * Before restarting Venus /coda must be unmounted. If umounting /coda gives trouble, make sure to exit all process that hang on to the Coda filesystem, e.g. by having files open or being cd'd into /coda. A utility like lsof and fuser can help with this.
     135    * /proc/fs/coda has interesting Coda statistics.
     136    * You can enable kernel debugging with vutil -kdebug 4095 and call tracing with vutil ktrace 1 . The messages appear in /var/log/messages
     137
     138== Windows 95: Starting and Configuring a Coda client == #Windows
     139
     140During installation you will be prompted for the IP address of your Coda server(s). Enter this as indicated.
     141
     142All executables can be found in the directory C:\usr\coda\bin
     143CodaStart
     144
     145The CodaStart program is a Win32 windows-based application to control and observe the Windows 95 Coda client. It will be enhanced in the future. For now it provides a convenient way to start Venus.exe. It also displays the kernel-venus communication for debugging purposes. Printing the messages can be stopped by unticking the 'Monitor' check box. The button 'Reset' clears the display.
     146
     147 1. When you start Venus for the first time, or you want to reinitialize its cache, tick the 'Init Venus' check box. This will start Venus with the '-init' and '-cf 1500' flag set. To add or override flags use the 'Configure' button. Start Venus by clicking the left 'Start' button. The 'Status' message will tell you 'Running' when Venus starts.
     148 2. Coda will be mounted automatically on the drive specified in the C:\usr\coda\etc\vstab file. Vstab is created by the installer.
     149 3. To unmount, type cfs uk in a DOS window. This will cleanly shut down Venus as well.
     150 4. See 'Important Note' below, please.
     151
     152You are now ready to browse through the Coda filesystem using the explorer!
     153Important Note
     154
     155NOTE: In some installations the DPMI DOS Extender window suspends when it is not active. In this case untick the window property 'Properties- > Misc- > Background- > Always Suspend'. If it is unticked, ticking and unticking it again might help. Also untick the 'Termination' flag, to allow Coda to automatically shutdown, when the system shuts down. For your convenience tick the 'Close on Exit' check box in the 'Program' tab.
     156
     157== Codasrv -- Coda's file server == #Server
     158=== Configuring your server ===
     159
     160To set up an SCM server, you will run a script vice-setup . This script creates configuration files under the /vice directory and creates files and directories on your system for storage of file data and metatdata. To answer the questions vice-setup is asking you need to have the following thought through:
     161
     162 '''file space'''::
     163    an empty directory (viz /vicepa) where the fileserver will put files. There must be as much free space on this filesystem as the data you wish to store in Coda.
     164
     165 '''RVM metadata storage'''::
     166    a file or raw partition for RVM metadata. You can use a file but it will be quite slow on a larger server. This partition must be around 4% of the total size of the files you wish to store under /vicepa (e.g. on a 2GB server we use around 80M of rvm data). For first installations we recommend the default 22M options, and using files for RVM log and data. (NOTE: Windows NT Setup creates the file c:\coda\rvm\DATA. Use this for RVM metadata.)
     167
     168 '''virtual memory'''::
     169    The metadata, held in the RVM data file, is memory mapped. You need that amount of space as virtual memory on your system, in addition to virtual memory to run the server (   6MB) and other software.
     170
     171 '''RVM transaction log'''::
     172    a LOG file, preferably a raw partition on a disk by itself. This needs not be large, a few M's are fine. (NOTE: Windows NT Setup creates the file c:\coda\rvm\LOG. Use this for RVM transaction log.)
     173
     174 '''A server number'''::
     175    All servers in a coda cell need to have a unique number to identify them. The servername to identifier mappings have to be defined by the administrator in the file /vice/db/servers on the SCM. The format of this file is as follows:
     176
     177{{{
     178    servernameX.domain.name    1
     179    servernameY.domain.name    2
     180    ...
     181}}}
     182
     183There are currently several limitations to which identifiers are actually usable:
     184
     185 * all numbers must fit in a single byte.
     186 * 0 and -1 (255) are used in error conditions.
     187 * 127 is used to identify `replicated volumes'.
     188
     189This leaves us with a usable range of 1-126 and 128-254 for server identifiers.
     190
     191 '''secret tokens'''::
     192    two secret tokens of _exactly_ 8 characters (eg elephant).
     193
     194 '''Coda administrator'''::
     195    The uid and name for the user that will get administrative priviledges on the Coda Filesystem. This user should NOT be the root user (uid 0). The authentication password for this user will be set to `changeme', and can be changed later using either cpasswd -h < scm hostname > or au -h < scm hostname > cp .
     196
     197NOTE: you are now ready to run the setup script. We strongly recommend that you stick to default choices offered as configuring a server differently is quite difficult.
     198
     199Then run:
     200
     201{{{
     202    vice-setup
     203}}}
     204
     205and answer its questions. Note down the commands that vice-setup prints out for you at the end.
     206
     207Note: For Windows NT you will need the Cygwin B19 Shell which can be started from the "Start" menu. The shell uses the c:\coda directory as the root mountpoint "/".
     208
     209=== Running the Coda server ===
     210
     211Start the rpc2portmap server, update server, client and the auth server, as well as the fileserver by typing:
     212
     213 '''Linux'''::
     214{{{
     215        /etc/rc.d/init.d/auth2.init start
     216        /etc/rc.d/init.d/update.init start
     217        /etc/rc.d/init.d/codasrv.init start
     218}}}
     219
     220 '''BSDs'''::
     221{{{
     222        /etc/rc.vice start, or
     223        /usr/local/etc/rc.vice start
     224}}}
     225
     226 '''Windows NT/XP'''::
     227{{{
     228        codastart
     229}}}
     230
     231Now observe the log:
     232
     233{{{
     234    xterm -e tail -f  /vice/srv/SrvLog &
     235}}}
     236
     237The !SrvLog should show File Server started . If not, you have a problem.
     238
     239Determine with `ps` that `codasrv`, `auth2`, `rpc2portmap`, `updatesrv` and `updateclnt` are running.
     240
     241=== Making your root volume ===
     242
     243During your configuration session, you commmunicated a name for the root volume to the program. This root volume now needs to be created: the precise command to do this was printed out by the vice-setup program, below we assume your file space is in /vicepa , and your root volume is coda:root .
     244
     245{{{
     246    createvol_rep coda:root E0000100 /vicepa
     247}}}
     248
     249NOTE: E0000100 is the Volume Storage Group set up for you by vice-setup. With more servers you can define other groups in /vice/db/VSGDB -- see the Coda User Manual.
     250
     251== Connecting your client to a new Coda server == #Connecting
     252
     253Now you are ready to point a Venus (client) at this server. You do this by typing
     254
     255{{{
     256    venus-setup <server-name> <cache-size-in-kb>
     257}}}
     258
     259NOTE: Windows 95 users should type the IP address and not the hostname of the server.
     260
     261Start Venus as explained above. From the coda client side, the root volume will appear under /coda. To use it you must now authenticate to Coda, since it is write protected.
     262
     263The vice-setup program installed an administrative Coda user on the server. It has a uid you chose and has been assigned password ''changeme''. You may clog into Coda with this uid:
     264
     265{{{
     266    clog "adminuser"
     267}}}
     268
     269Validate that you have tokens with the ctokens utility.
     270
     271You can now create files in Coda, because the administrative user is on the access control list (ACL) of the /coda directory. Read the next section to find out how to do more with Coda.