$Id: testafpd-howto.txt,v 1.2 2002/07/21 12:30:52 dejan Exp $

Installing test netatalk (a mini howto)

The netatalk software has recently seen a lot of important development and it would be helpful if as many people as possible test the new versions and give that way support to the netatalk developers.

Providing a test environment in parallel with the existing production installation is not difficult and, if done properly, it should not in any way disrupt the normal operation. However, as always, it is recommended to make a backup of the existing installation before proceeding.

NB: This procedure has been tested on Debian GNU/Linux woody release. It should work with slight modifications on other platforms.

The usual stuff about no guarantees, express or implied, etc, etc, applies. This is provided in hope that it will be helpful, but you are using it at your own risk.

For the brave and impatient

If you have no time/inclination to read the rest of the document and if you are able to understand the following commands, though it's not really recommended, well, it's your computer, your data, your choice. You have been warned. As you will hopefully notice, one cannot cut and paste all commands verbatim. Still, an enterprising admin can put together a nice script for private use.

  1. Get the source, unpack, and cd to the top dir: 

    
$ wget http://www.marcuscom.com/netatalk/nightly/netatalk-<date>.tar.gz
$ tar xfz netatalk-<date>.tar.gz
$ cd netatalk-<date>

    or 

    
$ cvs \
  -d:pserver:anonymous@cvs.netatalk.sourceforge.net:/cvsroot/netatalk \
  login
$ cvs -z3 \
  -d:pserver:anonymous@cvs.netatalk.sourceforge.net:/cvsroot/netatalk \
  co netatalk
$ cd netatalk
$ ./autogen.sh

  2. Configure, make world, and install: 

    
$ export TESTDIR=/usr/local/netatalk-test
$ ./configure --disable-overwrite \
  --prefix=$TESTDIR --sysconfdir=$TESTDIR/etc \
  --with-did=cnid --enable-debug --with-mangling \
  --with-pam --with-shadow --with-tcp-wrappers
$ make
$ su
# make install

  3. Create the test volume and start the test server: 

    
# mkdir /macdata/testshare
# chown root.macusers /macdata/testshare
# chmod g+wrx,g+s /macdata/testshare
# cd $TESTDIR/etc/netatalk
# ed afpd.conf<<EOF || echo "oops, ed failed"
a
- -noddp -nouservol -port 5480 -loginmsg "WARNING: not a production server"
.
w
q
EOF
# ed AppleVolumes.default <<EOF || echo "oops, ed failed"
/^~$/d
a
/macdata/testshare "Test Volume (not production)"
.
w
q
EOF
# $TESTDIR/sbin/afpd -P /var/run/afpd-test.pid

  4. Make it available in the chooser: 

    
# ed /etc/netatalk/afpd.conf <<EOF || echo "oops, ed failed"
a
"Test server (not production)" -proxy -uamlist "" -port 5480
.
w
q
EOF
# /etc/init.d/netatalk restart

Prerequisites

Note on conventions

Lines starting with "$" are what should be run without root privileges, unlike lines starting with "#". This is the standard UNIX convention. A backslash sign ("\") at the end of the line means that the next line should be typed in the continuation.

Download the latest source

You should check the netatalk site (http://netatalk.sourceforge.net/) for the recent software releases. Of course, the point of testing and this howto is to go with the most recent software.

You can download the latest netatalk software in one of the two ways: nightly snapshots provided by Joe Clarke or the cvs repository. If you don't have much experience with software development, I would suggest using the snapshots because they are a bit easier to deal with.

  1. Get and unpack a nightly snapshot: 

    
$ wget http://www.marcuscom.com/netatalk/nightly/netatalk-<date>.tar.gz
$ tar xfz netatalk-<date>.tar.gz
$ cd netatalk-<date>

    where <date> stands for YYYYMMDD.

  2. Using cvs. For this you will need a bit more experience, time, and more software installed on your system. In which case perhaps you shouldn't need to read this howto anyway. 

    
$ cvs \
  -d:pserver:anonymous@cvs.netatalk.sourceforge.net:/cvsroot/netatalk \
  login
$ cvs -z3 \
  -d:pserver:anonymous@cvs.netatalk.sourceforge.net:/cvsroot/netatalk \
  co netatalk
$ cd netatalk
$ ./autogen.sh

    (press enter when asked for a password)

    If the last step fails then you're probably missing autoconf, automake, or libtool. Please install them from your distribution.

Compiling

It is important to make sure that the installed production netatalk is undisturbed by the installation of the test release. 


$ export TESTDIR=/usr/local/netatalk-test
$ ./configure --disable-overwrite \
  --prefix=$TESTDIR --sysconfdir=$TESTDIR/etc \
  --with-did=cnid --enable-debug --with-mangling \
  --with-pam --with-shadow --with-tcp-wrappers

The --prefix and --sysconfdir options are essential. Otherwise you may overwrite the existing netatalk installation.

Choose other options depending on your specific requirements. Please read doc/INSTALL and other relevant documents for explanation of the available configure options. I would highly recommend to go with the CNID DID scheme and to enable debugging.

The TESTDIR directory also depends on your preferences. It is a good idea to name it after the downloaded snapshot: 


$ export TESTDIR=/usr/local/netatalk/20020707
$ export TESTDIR=/usr/local/netatalk/1.5.4-20020707

or similar. One more time, never ever fail to specify --prefix and --sysconfdir options or you may overwrite the existing netatalk installation.

If the configure step went well you can compile the package: 


$ make > make.out 2>&1

If everything went fine with the compilation, you can install the netatalk. 


$ su
# make install

The install procedure will copy the compiled server and other stuff to the destination directories specified by the --prefix and --sysconfdir configure options.

Important note:

The pam configuration file (netatalk) will be copied to the /etc/pam.d directory, thus overwriting the existing version. Usually, this file is not changed, but you should nevertheless make a backup copy.

[NB: This should be changed to honor the --disable-overwrite option. Also, what happens with the init script?]

Configuring and running the test afpd

First, you have to provide some space for the test share. Just create a directory on one of your data filesystems. However, this directory must not be accessible from the production afpd server. Don't forget to set appropriate permissions for the share. For example: 


# mkdir /macdata/testshare
# chown root.macusers /macdata/testshare
# chmod g+wrx,g+s /macdata/testshare

The test afpd cannot listen on the standard afpovertcp port, because that one is already bound by the production afpd. 


# cd $TESTDIR/etc/netatalk
# echo \
'- -noddp -nouservol -port 5480 \
-loginmsg "WARNING: this is not a production server"' >> afpd.conf

You also have to present the share to the Mac users by editing the AppleVolumes.default file. Remove the line containing a single "~" at the end of the file and append something like: 


/macdata/testshare "Test Volume (not production)"

That should be the only uncommented line in the file.

In case you have many users and want to restrict access to the test server, there is a provision for that in the AppleVolumes.default file. First, create a group named, say, afpdtest, and put in it all users you would want to enable access to the test volumes. Then, instead of the line above, append a line like this one: 


/macdata/testshare "Test Volume (not production)" allow:@afpdtest

The test afpd server can be started now: 


# $TESTDIR/sbin/afpd -P /var/run/afpd-test.pid

You can also put this line in the production netatalk start script, in the "start" case. In the "stop" case, you should insert 


[ -f /var/run/afpd-test.pid ] && \
        kill `cat /var/run/afpd-test.pid`

The production server has to know about the test server. Otherwise the Mac users would not be able to see the test server in their choosers. Append the following line to the production afpd.conf (usually in /etc/netatalk/afpd.conf): 


"Test server (not production)" -proxy -uamlist "" -port 5480

and restart the production netatalk. Note that the port directive here should match the one which appears above in the test afpd.conf.

IMPORTANT: Note that there is a limit of 31 characters for the server's name. Should the name be longer, the afpd will just refuse to register the server.

The test server should appear in the chooser on Macs. You can also test that from the UNIX command line: 


$ nbplkup :AFPServer

or 


$ netstat -an | grep 5480

If everything went fine spread the word about the test server among your more experienced Mac users. Then, of course, you should provide some feedback about your experience with the test version to the netatalk lists. The lists' addresses are:

Netatalk-devel@lists.sourceforge.net
Netatalk-admins@lists.sourceforge.net

Final notes

There could be more than two afpd servers running on one UNIX box. You just have to be careful to keep them from running into each other:

-
Dejan Muhamedagic <dejan@hello-penguin.com>