abeatrix / cvsfs Goto Github PK

This is the first attempt to provide a file system for cvs.


Intention:
----------

The first reason for writing this virtual file system driver was the (in my
opinion) bad usability of cvs. One time i had to check the source of XFree86
to determine what and how it have been changed. To do that i have to checkout
the whole tree of XFree86. This took hours !
My imagination was to access cvs projects as they were ordinary files on
the local disk. So cvsfs was born.

During development some other possible advantages came out.

- When building a package via make it sould be possible to log all file
  accesses to cvs-hosted files. At the end you have a full list of files
  which were required a package. Using a specialized make a subsequent
  run will enable it to analyze the dependencies evaluated during an
  earlier run. This will result in a simplified makefile where each
  target is asigned only the direct source file. The other dependencies
  (*.h files, etc.) can be detected using the file system driver.

- Navigation can be done using ordinary file manager (mc, konquerer, etc.)

- you do not have to checkout files to run make.

- you may use different userids for different modules on the same cvs
  repository.

- you can mount a cvs repository at multiple locations.

- others to come ...


Requirements:
-------------

- Kernel 2.4.10 and later.
  * Tested distributions:
    - SuSE 7.3
    - Debian 3.0
    - RedHat 7.2 (with updated Kernel 2.4.10)
- Installed kernel includes.
- Running network.
- Bash 2.0 and later (for installation)


Building the package:
---------------------

First change to the cvsfs-<version> directory.
Then enter 

  ./configure
  
Next do

  make

This will compile all necessary files.
To install the files you must be root. Enter

  make install

to install them to the proper directories.
Add the script 'cvsfsd' to the apropriate run levels (/etc/rc.x) and start
it (as root):

  /etc/init.d/cvsfsd start


To automate this you have to create symlinks in the different runlevel
directories to /etc/init.d/cvsfsd using (for example) a runlevel editor.


Possible problems:
------------------

Problem: at 'make install' the following message comes out:

  $ depmod -a  
    depmod: *** Unresolved symbols in /lib/modules/<kernel version>/kernel/fs/cvsfs/cvsfs.o

  Check file /usr/src/linux/kernel/ksyms.c. There must be a line
  
    EXPORT_SYMBOL(__wake_up_sync);
    
  A kernel >= 2.4.10 must be used. It is also reported that kernel version
  2.4.19-ac4 has also a problem with that.
    
Solution 1: If missing - add it and recompile the kernel.
Solution 2: Update to a more recent kernel version.


Problem: when starting cvsfsd it aborts with following message:      

  $ /etc/init.d/cvsfsd start
    Starting cvs virtual filesystem daemon:
    /lib/modules/<kernel>/kernel/fs/cvsfs/cvsfs.o: unresolved symbol __wake_up_sync
    /lib/modules/<kernel>/kernel/fs/cvsfs/cvsfs.o: insmod /lib/modules/<kernel>/kernel/fs/cvsfs/cvsfs.o failed
    /lib/modules/<kernel>/kernel/fs/cvsfs/cvsfs.o: insmod cvsfs failed

Solution: same as before.


Problem: deleting a file does not remove the file. The old CVS version comes up.
	 
Solution: This works as designed. If the item you delete is a checked-out file
          the CVS version pops up (but now read-only).
	  If you want to edit it, you have to check-out the file again.


Problem: renaming does only copy the file to the new position. The old CVS
         version comes up at the old location.
	 
Solution: This works as designed. If the item you rename is a checked-out file
          the CVS version pops up at the old location (remainig writeable).
	  It only removes the old version if this was a local file.

	       
Usage (for root users):
-----------------------

  mount -t cvsfs [-o options] //<cvs-pserver>/<module> <mount point>
  
  <cvs-pserver>       The cvs pserver to access. This may be a hostname
                      (with or without domain) or a ip-address.
		      Only ip v4 is actually supported !
		      The module may be a dot ('.') if you want to mount the
		      root of the cvs server.
  <mount point>       The directory where the cvs tree is to be mounted.

Options (comma separated list):
  user=<username>     The username to be used for authentication at the
                      cvs-pserver.
		      Default is 'anaonymous'.
  password=<secret>   The password for the username given above.
                      Default is an empty password.
  cvsroot=<root>      The cvs root directory.
                      Default is '/cvsroot'.
  uid=<userid>        The remote files will be presented unter this user id
                      to the customer. The userid may be given as user number
		      or user name.
		      Default is the current user id.
		      (This option is available for root users only !)
  gid=<groupid>       The remote files will be presented unter this group id
                      to the customer. The userid may be given as group number
		      or group name.
		      Default is the current group id.
		      (This option is available for root users only !)
  fmask=<attribs>     The files mounted will get this file attributes.
		      (for example: umask = 022 is equivalent to fmask=755)
		      Remark: The kernel driver will unmark the 'writeable'
		              attribute as long the file is not checked
			      out for update.
                      Default is the current umask.
  dmask=<attribs>     The directories mounted will get this file attributes.
		      (for example: umask = 022 is equivalent to fmask=755)
                      Default is the current umask.

To unmount the file system simply use umount.
Anyway you may use the cvsmount/cvsumount described below. The options 'uid'
and 'gid' are only accepted from root users.


Usage (for normal users):
-------------------------

  cvsmount //<cvs-pserver>/<module> <mount point> [-o options]
  cvsumount <mount point>
  
  <cvs-pserver>       The cvs pserver to access. This may be a hostname
                      (with or without domain) or a ip-address.
		      Only ip v4 is actually supported !
		      The module may be a dot ('.') if you want to mount the
		      root of the cvs server.
  <mount point>       The directory where the cvs tree is to be mounted.

The Options are the same as available for the mount command described above.

Due to a check in umount you have to use cvsumount instead of umount if
you want to un-mount it.



Example:
--------

If you specify for the actual cvs tool the environment variable

  CVSROOT=:pserver:[email protected]:/cvsroot/project
  
the password is 'secret', the project is named 'myproject' and the moutpoint
will be /humbia then the following command is required:

  mount -t cvsfs -o user=humbia,password=secret,cvsroot=/cvsroot/project \
        //sourceforge.net/myproject /humbia

or using the cvsmount command:

  cvsmount //sourceforge.net/myproject /humbia \
           -o user=humbia,password=secret,cvsroot=/cvsroot/project


Un-mounting id done via

  umount /humbia

or

  cvsumount /humbia


A working example is this project at SourceForge. The Statement is:

  cvsmount //cvs.cvsfs.sourceforge.net/cvsfs <mountpoint> \
           -o cvsroot=/cvsroot/cvsfs

This will mount the cvsfs CVS repository at <mountpoint>.


Tools:
------

  cvsctl <command>

    <command> may be:
      version <file>			obtain version of file
      checkout <file> [<version>]	checkout file (of specified version)


Working with a cvsfs mounted file system:
-----------------------------------------

You can navigate through the mounted file system with whatever tool you
want. You will see the latest revision of the files.

Remark: Actually you are limited to the latest revision but this will
        change later. You can access directly a special revision of
	a file with the method described below.

If you want to get a special revision of a file you can use the '@@'
delimiter to identify it. For example:

  cat filename@@1.1
  
will retrieve the version 1.1 of the file named 'filename' from cvs and
display it on the screen.
This file notation can also be used with all tools which takes a file name
as parameter, for example:

  diff filename@@1.1 filename@@1.2



Procfs support:
---------------

Under /proc the module wlll, when loaded, create a subdirectory named 'cvsfs'.
Each mount point where a cvsfs file system is mounted will appear under this
subdirectory.
Each mount point gets a unique number. The actual assignments ist listed in
/proc/cvsfs/mounts. Each mount point creates a directory in /proc/cvsfs equal
to the unique number. In there are now 3 files:

  control (write only) - will control the cvsfs (checkout, checkin, etc.)
  status  (read only)  - gives an actual status of the mount point
  view    (read/write) - displays and controls the view to the repository

Using this entries the behaviour of the mounted cvsfs file system is
controlled.

Most parts of the procfs support is in early stage and may not work properly.
There will be tools in future to ease the use of the procfs entries.


Hint:
-----

mount has version (mount -V) mount-2.10q. This mount version looks for unknown
file systems to locate /bin/mount.<filesystem>.
This file (in our case mount.cvsfs) is (at my installation) a one-line script
which himself calls cvsmount which do the real work. Execute cvsmount without
parameters to get a small help. cvsmount itself calls cvsmnt which issues the
system mount call.

If the file mount.cvsfs is found it is executed with the parameters passed to
mount. I don't know whether or not earlier or later versions on mount have
this behaviour. If your version does not do this search then you can use
cvsmount instead.


Environment:
------------

Tested (and developed) with SuSE 7.3 (i386). The kernels used are the
delivered precompiled kernels and the official one 2.4.10.

I have tested the compilation on a Debian 3.1 release.

I can not guarantee that it will compile on other platforms and/or other
linux distributions.

The cvsfs kernel module supports only kernels 2.4.x

The vfs module may have problems on linux builds with versioned kernel
symbols. The driver refuses to load then. This can be seen when doing a
'depmod -ae' after the driver install. It states (for example) the symbol
kmalloc as unresolved.
Actually i am rather new to kernel programming - so a hint to solve this
problem is welcome.


Limitations:
------------

This tool actually only retrieves the file names and directories of the HEAD
branch. Reading of files is supported (hopefully).

Only the pserver method of cvs is supported. May be extended later.

mount allows only root to define mount points and mount options. A normal
user may use the cvsmount command instead. Call cvsmount without parameters
to get the list of options.


Resulting files:
----------------

The following is a list of files generated by make and where they are
installed by calling 'make install'. You must be root to do this.

 source              ! destination
---------------------+--------------------------------------------------------
cvsfs/cvsfs.o        ! /lib/modules/<kernel-version>/kernel/fs/cvsfs/cvsfs.o
cvsfsd/cvsfsd        ! /usr/local/bin/cvsfsd
symlink to cvsmount  ! /bin/mount.cvsfs
cvsmount/cvsmount    ! /usr/local/bin/cvsmount
cvsumount/cvsumount  ! /usr/local/bin/cvsumount
cvsmnt/cvsmnt        ! /usr/local/bin/cvsmnt
script makedevs      ! /dev/cvsfs/0 ... 255  (if no device filesystem is used)
script init/makeinit | /etc/init.d/cvsfsd