xref: /mirbsd/src/libexec/anoncvssh/README

$MirOS: src/libexec/anoncvssh/README,v 1.6 2008/11/29 17:03:53 tg Exp $

On MirBSD, the directory structure outlined below, as well
as the anoncvssh and accompanying programmes, are already
installed in /var/anoncvs and its subdirectories.
Just set a password (may be empty) for user "_anoncvs",
pull the CVSROOT into /var/anoncvs/cvs and you are
set up. For empty passwords, remember to configure the SSH
daemon appropiately.

To use anonymous rsync, place a statically linked rsync
executable into /var/anoncvs/bin and make it
chmod 110, chown root:_anoncvs.

Please change the defaults to fit your needs.
_______________________________________________________________________________

	So, you want to run an anoncvs server.

        A summary of the steps you'll need to do is:

1) Find enough disk space to hold the anoncvs tree, and mount it in an
   appropriate place.

2) Compile and install anoncvssh, the shell used for the anoncvs user.
   ( If you aren't using OpenBSD you'll probably need to compile a sup
     client as well. The easier path is to use OpenBSD ;)

3) Add the anoncvs user to the password file, with no password, and
   anoncvssh as it's shell. Decide on a user that will run sup to maintain
   the archive (this is a different user, NOT the anoncvs user)

4) Make a home directory for the anoncvs user. The anoncvs user's
   home directory is a chroot jail in which the anoncvssh processes
   run when servicing anoncvs requests. The jail must contain the
   cvs binary as well as whatever shared libraries and support files
   are needed to run them unless you compile and link everything
   staticly. This example shows what is needed for OpenBSD. If you
   use another platform you'll need to be familiar with what needs
   to go in a chroot jail for your platform.

5) Get permission to use sup to obtain the cvs tree from a server.

6) Set up sup to retrieve the cvs tree from an appropriate place.
   (If you aren't using OpenBSD you will need to compile and install
    a sup client).

7) Run sup to retrieve the distribution from the server

8) Once you get the distribution in, set up a cron job to run sup
   periodically to keep your server up to date.

**********************************************************************
STEP 1) find enough disk space.
    You need roughly 1.6GB.
    Mount it on /open.
    If you are not able to mount it as /open, substitute it's location
	throughout the rest of this description.

**********************************************************************
STEP 2) compile the anoncvssh binary
    In the Makefile, change the variable CVSROOT
    Install the binary setuid-root in /open/anoncvssh.

**********************************************************************
STEP 3) Create the anoncvs account. and decide who will run "sup"
    to maintain the archive. The anoncvs account should *NOT* be the one
    running sup to maintain the archive.

create an account similar to:

    anoncvs::32766:32766:Anonymous CVS User:/open/anoncvs:/open/anoncvssh

Yes, that is right. the account has no password. Be sure that the
uid and gid are unique for your system, if the ones above aren't,
pick different values.

Decide who will run sup to maintain the archive. call that user
$SUPUSER.  Oh, and in case it hasn't been previously mentioned,
$SUPUSER should *NOT* be the anoncvs user :)

**********************************************************************
STEP 4) Build the anoncvs user's home directory chroot jail. This
    example assumes that you're using OpenBSD. If you're not you
    may need different files in the chroot.

mkdir /open/anoncvs
mkdir /open/anoncvs/cvs
mkdir /open/anoncvs/sup
chown -R $SUPUSER /open/anoncvs/cvs /open/anoncvs/sup /open/anoncvs

Start filling the account up with nice stuff. You are building a chroot
jail for anoncvs in /open/anoncvs.

    cd /open/anoncvs
    touch .hushlogin
    touch .profile

Put a message like the following in .plan:
    To use anonymous CVS install the latest version of CVS on your local
    machine.
    Then set your CVSROOT environment variable to the following value:
            anoncvs@anoncvs.openbsd.org:/cvs

    chown root:wheel .hushlogin .profile .plan

    mkdir bin dev tmp etc
    cp /bin/{cat,pwd,rm,sh} bin/
    ln -s . var

Using mknod, make a dev/null that has the same major/minor numbers as
    your /dev/null, and make it mode 666. A dev/zero must be created
    the same way.

Fill etc space for the account
    cp /etc/{group,hosts,passwd,protocols} etc/
    cp /etc/{pwd.db,resolv.conf,services,ttys} etc/
    modify these files to suit your idea of system security

anoncvssh (by setting the environment variable CVSREADONLYFS) uses
an tiny extension provided in the openbsd cvs server code which
permits the use of read-only cvs repositories.  therefore you MUST
compile the openbsd version of cvs.  luckily this is not a problem
on a non-openbsd machine since the cvs sources are imported verbatim
into the openbsd tree.  they are in gnu/usr.bin/cvs.  The sources
are integrated such that Makefile.bsd-wrapper knows how to build
the sources on an OpenBSD machine, using obj directories.

Create tmp space for the account
    # cd var; ln -s ../tmp tmp
    # chmod a+rwx tmp

    # mkdir usr/{bin,lib}
    # cp /usr/bin/cvs usr/bin/

If your system has ld.so in /usr/libexec,
    # mkdir usr/libexec
    # cp /usr/libexec/ld.so usr/libexec/

If using shared libraries, use ldd to find out which shared libs you need:
    # ldd /usr/bin/cvs
    /usr/bin/cvs:
	    -lz.1 => /usr/lib/libz.so.1.4 (0x40097000)
	    -lgssapi.1 => /usr/lib/libgssapi.so.1.0 (0x400a4000)
	    -lkrb.10 => /usr/lib/libkrb.so.10.0 (0x400ae000)
	    -lkrb5.4 => /usr/lib/libkrb5.so.4.0 (0x400c8000)
	    -lasn1.2 => /usr/lib/libasn1.so.2.0 (0x400ff000)
	    -lcrypto.6 => /usr/lib/libcrypto.so.6.0 (0x4011d000)
	    -ldes.7 => /usr/lib/libdes.so.7.0 (0x40203000)
	    -lkafs.10 => /usr/lib/libkafs.so.10.0 (0x4020d000)
	    -lc.28 => /usr/lib/libc.so.28.5 (0x40210000)

    and then copy the required libraries to usr/lib/

As a final pass, make sure that all the files you have just created are
not world writable (except dev/null and dev/zero).

For :pserver: support (optional)
  - Create an entry in /etc/services
     cvspserver		2401/tcp		# CVS client/server operations
  - Create an entry in /etc/inetd.conf
     cvspserver	stream	tcp nowait anoncvs /open/anoncvssh anoncvssh pserver
  - Create a file /open/anoncvs/cvs/CVSROOT/passwd with the following entry
	anoncvs:AHDysQkJIubEc
    which would be a password of "anoncvs" (as per anoncvs.html)
  - Create a file /open/anoncvs/cvs/CVSROOT/readers with a single entry:
	anoncvs
    which tells cvs that user "anoncvs" is allowed readonly access.
  - Create a zero-length file /open/anoncvs/cvs/CVSROOT/writers since you don't
    want anyone to be able to write to the mirror.
	% cp /dev/null /open/anoncvs/cvs/CVSROOT/writers

See the example layout below for full details.

**********************************************************************
STEP 5): Get sup permission.
send mail to sup@openbsd.org
1) to have sup permissions granted on an appropriate machine for you
   to sup from. We will need to know your host's real hostname and
   IP address.
2) to have an anoncvsN.COUNTRY.openbsd.org alias created
3) to have your site mentioned in the http://www.openbsd.org page.

**********************************************************************
STEP 6): Configure sup

If you're running OpenBSD, you already have a sup client in
/usr/bin/sup.  If not you may need to build it. On an IRIX or other
SYSV machine, ensure that your kernel does not allow a user to chown
a file to another user (You may have heard of this particular brand
of evil referred to as "chown giveaway"). this will cause sup to
give away the files to root before chmod'ing them readable.
michaels@openbsd.org knows how to fix this.

The file /open/anoncvs/sup/ss contains a line that tells sup where
to get the cvs tree from. it will normally contain:

    cvs host=anoncvs.ca.openbsd.org hostbase=/usr/OpenBSD base=/open/anoncvs delete

The file /open/anoncvs/sup/cvs/refuse tells sup what files it should not get.
It should contain the following lines:

    cvs/CVSROOT/history
    cvs/CVSROOT/readers
    cvs/CVSROOT/writers
    cvs/CVSROOT/passwd

if you ever fetch the file cvs/CVSROOT/history, delete it. it will
cause you problems.

**********************************************************************
STEP 7): Run sup to retrieve the tree for the first time

Log in as or become the $SUPUSER, and run

sup -v  /open/anoncvs/sup/ss > /tmp/suplog &; tail -f /tmp/suplog

If you have sup permission, and have specified the correct host and
hostbase in /open/anoncvs/sup/ss you should see a list of files start
coming in after a short while. Don't panic if nothing happens
immediately.  Watch for errors (sup can timeout or die). If you can't
access files contact the sup server maintainer, If you get a timeout
or if sup dies you can restart and it should continue where it left off.

It can take a good while (and a couple of restarts) to obtain the
whole tree for the first time.

**********************************************************************
STEP 8): Set up cron to keep the tree up to date.

You run sup periodically from the cron by setting up the crontab file
of the $SUPUSER.

For example:  To run every three hours 'sup -v supfile', and thrice
weekly 'sup -vo supfile' .. because sup is not reliable ..

0 0,3,6,9,12,15,18,21 * * 0,2,4,5 sup -v  /open/anoncvs/sup/ss > /dev/null
0 0,12,15,18,21       * *  1,3,6  sup -v  /open/anoncvs/sup/ss > /dev/null
0 3                   * *  1,3,6  sup -vo /open/anoncvs/sup/ss > /dev/null

anoncvs5.usa.openbsd.org uses this particular set of entries.  A `sup
-o' is done every few days because sup is not very robust.

**********************************************************************
EXAMPLE LAYOUT

Example layout for OpenBSD. In this example "deraadt" is the $SUPUSER.

[eap open 5 ]> cd /open
[eap open 6 ]> ls -alF
total 46
drwxr-xr-x   7 root     wheel    512 Feb 20 09:58 ./
drwxr-xr-x  17 root     wheel    512 Jun 14 14:05 ../
drwxr-xr-x   9 root     wheel    512 Jan  3 21:55 anoncvs/
---s--x--x   1 root     bin    16384 Nov 30  1995 anoncvssh*
lrwxr-xr-x   1 root     wheel     11 Jan  3 21:52 cvs@ -> anoncvs/cvs
drwxr-xr-x   5 root     wheel    512 Feb 22 13:22 ftp/
drwxrwxrwt   2 anoncvs  wheel   1024 Jan  1 13:18 lost+found/
drwxr-xr-x   4 root     wheel    512 Nov 30  1995 src/
drwxrwxr-x   3 deraadt  wheel    512 Dec  4  1995 sup/
[eap open 7 ]> cd anoncvs
[eap anoncvs 8 ]> ls -alF
total 20
drwxr-xr-x  9 root     wheel  512 Jan  3 21:55 ./
drwxr-xr-x  7 root     wheel  512 Feb 20 09:58 ../
-r--r--r--  1 root     wheel    0 Nov 30  1995 .hushlogin
-r--r--r--  1 root     wheel  188 Nov 30  1995 .plan
-r--r--r--  1 root     wheel    0 Nov 29  1995 .profile
drwxrwxr-x  2 deraadt  wheel  512 Nov 29  1995 bin/
drwxrwxr-x  6 deraadt  cvs    512 Jun 16 20:28 cvs/
drwxr-xr-x  2 root     wheel  512 Nov 30  1995 dev/
drwxr-xr-x  2 root     wheel  512 Nov 29  1995 etc/
drwxrwxrwx  3 root     wheel  512 Jun 22 07:42 tmp/
drwxr-xr-x  5 deraadt  wheel  512 Nov 30  1995 usr/
drwxr-xr-x  2 root     wheel  512 Jan  3 21:55 var/
[eap anoncvs 8 ]> ls -alFR bin usr tmp etc dev
bin:
total 948
drwxrwxr-x  2 deraadt  wheel     512 Nov 29  1995 ./
drwxr-xr-x  9 root     wheel     512 Jan  3 21:55 ../
--wx--x--x  1 deraadt  wheel   40960 Jun 18 09:45 cat*
--wx--x--x  1 deraadt  wheel   40960 Jun 18 09:45 pwd*
--wx--x--x  1 deraadt  wheel  122880 Jun 18 09:45 rm*
--wx--x--x  1 deraadt  wheel  262144 Jun 18 09:45 sh*

dev:
total 4
drwxr-xr-x  2 root  wheel       512 Nov 30  1995 ./
drwxr-xr-x  9 root  wheel       512 Jan  3 21:55 ../
crw-rw-rw-  1 root  wheel    2,   2 Nov 30  1995 null

etc:
total 112
drwxr-xr-x  2 root  wheel    512 Nov 29  1995 ./
drwxr-xr-x  9 root  wheel    512 Jan  3 21:55 ../
-rw-r--r--  1 root  wheel    252 Nov 29  1995 group
-rw-r--r--  1 root  wheel    296 Nov 29  1995 hosts
-rw-r--r--  1 root  wheel    540 Nov 29  1995 passwd
-rw-r--r--  1 root  wheel   1094 Nov 29  1995 protocols
-rw-r--r--  1 root  wheel  40960 Nov 29  1995 pwd.db
-rw-r--r--  1 root  wheel     89 Nov 29  1995 resolv.conf
-rw-r--r--  1 root  wheel   5529 Nov 29  1995 services
-rw-r--r--  1 root  wheel   1361 Nov 29  1995 ttys

usr:
total 10
drwxr-xr-x  5 deraadt  wheel   512 Nov 30  1995 ./
drwxr-xr-x  9 root     wheel   512 Jan  3 21:55 ../
drwxr-xr-x  2 deraadt  wheel   512 Nov 30  1995 bin/
drwxr-xr-x  2 deraadt  wheel  1024 Jun 18 09:50 lib/
drwxr-xr-x  2 deraadt  wheel   512 Nov 29  1995 libexec/

usr/bin:
total 1968
drwxr-xr-x  2 deraadt  wheel     512 Nov 30  1995 ./
drwxr-xr-x  5 deraadt  wheel     512 Nov 30  1995 ../
--wx--x--x  1 deraadt  wheel  317787 Jun 18 09:46 cvs*

usr/lib:
total 5594
drwxr-xr-x  2 deraadt  wheel    1024 Jun 18 09:50 ./
drwxr-xr-x  5 deraadt  wheel     512 Nov 30  1995 ../
-rw-r--r--  1 deraadt  wheel  351730 Jun 18 09:50 libasn1.so.2.0
-rw-r--r--  1 deraadt  wheel  351730 Jun 18 09:50 libc.so.28.5
-rw-r--r--  1 deraadt  wheel   16608 Jun 18 09:50 libcrypto.so.6.0
-rw-r--r--  1 deraadt  wheel   44424 Jun 18 09:50 libdes.so.7.0
-rw-r--r--  1 deraadt  wheel   16665 Jun 18 09:50 libgssapi.so.1.0
-rw-r--r--  1 deraadt  wheel   86198 Jun 18 09:50 libkafs.so.10.0
-rw-r--r--  1 deraadt  wheel   42254 Jun 18 09:50 libkrb.so.10.0
-rw-r--r--  1 deraadt  wheel   66099 Jun 18 09:50 libkrb5.so.4.0
-rw-r--r--  1 deraadt  wheel  387976 Jun 18 09:50 libz.so.1.4

usr/libexec:
total 100
drwxr-xr-x  2 deraadt  wheel    512 Nov 29  1995 ./
drwxr-xr-x  5 deraadt  wheel    512 Nov 30  1995 ../
-rwxr-xr-x  1 deraadt  wheel  49152 Jun 18 09:47 ld.so*

[eap anoncvs 14 ]> ls cvs
CVSROOT/        src/            sup/            www/
[eap anoncvs 15 ]> cd /open
[eap anoncvs 16 ]> ls -alF sup
total 8
drwxrwxr-x  3 deraadt  wheel  512 Dec  4  1995 ./
drwxr-xr-x  7 root     wheel  512 Feb 20 09:58 ../
drwxr-xr-x  2 deraadt  wheel  512 Jun 22 06:05 cvs/
-rw-rw-r--  1 deraadt  wheel   54 Dec  4  1995 ss


***************************************************************
NOTES FOR OTHER PLATFORMS:

If you're not that familiar with your other platform (i.e. you haven't
built a chroot jail for a server on it) you may be better off
finding an OpenBSD machine to use. (and duplicating the example above)

**SunOS 5)
Bob Beck <Bob.Beck@ualberta.ca> has done this. E-mail for
help if you need it.

**OSF 1)
From Todd Fries <toddf@acm.org> to the adventurous.
A note for those installing anoncvs on non-OpenBSD operating systems.
You are in for some fun.

For OSF1, on a DEC alpha, I had to do the following in addition to the
above:

- I do not know how to setup dynamic libraries on osf1 and as a result
  everything had to be compiled statically.
- Therefore, everything but /bin/sh I had to recmpile in order to
  get the chroot setup.  In order that there be no guesswork
  involved, the following packages' binaries must exist in the chroot
  environment:

 GNU
   cvs         (from the OpenBSD source tree)

Some notes on compiling.

   cvs fails to install if you don't have makeinfo ... just search for the
   string ' install-info$' with regex and remove it from the Makefile for the
   install and you'll be fine, or install 'texinfo', your choice.