[netatalk.git] / doc / INSTALL.txt

Installation and Configuration of Netatalk 1.5
Lance Levsen, l.levsen@printwest.com

Prerequisites
=============
1. Libtool (only needed by developers)
Libtool encapsulates the platform specific dependencies for the
creation of libraries. It determines if the local platform can support
shared libraries or if it only supports static libraries.

Documentation: http://www.gnu.org/software/libtool/
Program: (see the GNU mirrors) /gnu/libtool/libtool-1.3.5.tar.gz

2. GNU m4 (only needed by developers)
GNU m4 is an implementation of the Unix macro processor. It reads
stdin and copies to stdout expanding defined macros as it processes
the text.

Documentation: http://www.gnu.org/software/m4/
Program: (see the GNU mirrors) /gnu/m4/m4-1.4.tar.gz

3. Autoconf
Autoconf is a package of m4 macros that produce shell scripts to
configure source code packages.

Documentation: http://www.gnu.org/software/autoconf/
Program: (see the GNU mirrors) /gnu/autoconf/autoconf-2.13.tar.gz

4. Automake
Automake is a tool that generates  'Makefile.in' files.

Documentation: http://www.gnu.org/software/automake/
Program: (see the GNU mirrors) /gnu/automake/automake-1.4.tar.gz

Optional
========
5. OpenSSL
The OpenSSL Project is a collaborative effort to develop a robust,
commercial-grade, full-featured, and Open Source toolkit implementing
the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS
v1) protocols as well as a full-strength general purpose cryptography
library.
This is required to enable DHX login support.

Get everything at http://www.openssl.org/ 

6. TCP Wrappers 
Wietse Venema's network logger, also known as TCPD or LOG_TCP. These
programs log the client host name of incoming telnet, ftp, rsh,
rlogin, finger etc. requests. Security options are: access control per
host, domain and/or service; detection of host name spoofing or host
address spoofing; booby traps to implement an early-warning system.

TCP Wrappers can be gotten at ftp://ftp.porcupine.org/pub/security/

7. PAM (Pluggable Authentication Modules for Linux) 
Linux-PAM provides a flexible mechanism for authenticating
users. PAM was invented by SUN Microsystems.

Author: Andrew Morgan <morgan@linux.kernel.org>

Linux-PAM is a suite of shared libraries that enable the local system
administrator to choose how applications authenticate users.

You can get the Linux PAM documentation and sources from
http://www.kernel.org/pub/linux/libs/pam/


Installing Netatalk
===================

1. Read the configure options.
$> ./configure --help

This prints a listing of the command line options for configure to
use. Notables are:

--prefix: top level src directory for ./bin, ./etc, ./include, ./lib,
./man, ./sbin, ./share.

--disable-admin-group: disable admin group (default on),

--disable-ddp: disable DDP support,

--enable-dropkludge: enable the experimental dropbox fix (INSECURE!)

 --with-pam: enable password authentication modules support,

--with-shadow: enable shadow password support,

--with-tcp-wrappers: enable TCP wrappers support

--with-ssl-dirs=[PATH]: specify path to OpenSSL installation. 
NOTE: This is dependent on the same directory layout as the source
distribution of Openssl. That is: ./include/ and ./lib/ to be on the
same level. Many .rpm formats do not have their files laid out in this
format.

--enable-lastdid: Recreate version 37b behaviour where directory id's
are incrementally calculated versus the new hash method. Unfortunately
for machines that have a lot of devices, and/or a lot of inodes the
hash can fail with multiple directories resolving to the same DID.

Enable/Disable the desired options, make, and make install.

$>./configure --option1 --option2 ....
$> make  (as root or sudo)
$> make install  (as root or sudo)

Assuming you haven't changed the install directories, this will
install the configutation files in /etc/atalk. The uams in
/etc/atalk/uams. The binaries will be in /usr/sbin/.

4. Configure Netatalk (See below 'Configuring Netatalk')
The default location for the configuration files is /etc/atalk/.

5. Setup your rc script so that Netatalk is started on boot.
You can find sample initscripts in ./distrib/initscripts/ from the
source directory.

6. If you enabled PAM, then copy the ./config/netatalk PAM file to
/etc/pam.d/ or where ever your system puts the PAM configuration
files.


Configuring Netatalk
====================

Netatalk supplies two different types of Appletalk servers and both
can run at the same time. Classic Appletalk requires afpd and
atalkd. Appletalk over IP only requires afpd. Classic Appletalk on
GNU/LInux requires that CONFIG_ATALK is compiled into the kernel or as
a kernel module. To check to see if the kernel has Appletalk
installed:

$> dmesg | grep Apple
This just parses the boot messages for any line containing
'Apple'.

To see all the  loaded modules (as root):
$> lsmod

If you don't find it, you may have to compile a kernel and turn on
Appletalk in Networking options -> Appletalk DDP. You have an option
to install as a module or directly into the kernel.

Some default distribution kernels have already compiled Appletalk DDP
as a module, you may have to edit your /etc/modules.conf to include:
"alias net-pf-5 appletalk ".

Note: check your distribution documentation about editing
/etc/modules.conf.

For more complete information about the Linux kernel see the
Kernel-HOWTO:
http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html


1. /etc/atalk/afpd.conf
======================

Edit /etc/atalk/afpd.conf as required. Some options:

Format:
- [options]             to specify options for the default server
and/or
 "Server name" [options]        to specify an additional server

The following options are available:

Transport Protocols:
     -[no]tcp   Make AFP-over-TCP [not] available
     -[no]ddp   Make AFP over AppleTalk [not] available. if you have
                -proxy specified, specify -uamlist "" to prevent ddp
                connections from working. 
     -transall      Make both available (default)

Transport Options:
     -ipaddr <w.x.y.z>  
                Specifies the IP address the server should
                respond to (default is the first IP address of the system). This
                option also allows one machine to advertise TCP/IP for another machine.
     -server_quantum <number> 
                Specifies the DSI server quantum. The minimum
                value is 1MB. The max value is 0xFFFFFFFF. If you specify a value that
                is out of range, you'll get the default value (currently the
                minimum). 
     -admingroup <groupname>
                         Specifies the group of administrators who should all
                         be seen as the superuser when they log in.  Default
                         is disabled.
     -ddpaddr x.y       Specifies the DDP address of the server. the default
                is to auto-assign an address (0.0). this is only
                useful if you're running on a multihomed host.
     -port <number>     Specifies the TCP port the server should
                respond to (default is 548)
     -fqdn <name:port>  Specify a fully-qualified domain name
                        (+optional port). this gets discarded if the
                        server can't resolve it. this is not honored
                        by appleshare clients <= 3.8.3 (default: none)
     -proxy             Run an AppleTalk proxy server for specified AFP/TCP
                server (if address/port aren't given, then first IP
                address of the system/548 will be used). if you don't
                want the proxy server to act as a ddp server as well,
                set -uamlist to an empty string.

Authentication Methods:
     -uampath <path>    Use this path to look for User Authentication
                Modules. (default: /etc/atalk/uams)
     -uamlist <a,b,c> Comma-separated list of UAMs. (default:
                uams_guest.so,uams_clrtxt.so,uams_dhx.so)

        Some Common UAMs
        uams_guest.so: Allow guest logins

        uams_clrtxt.so: (uams_pam.so or uams_passwd.so)
                Allow logins with passwords transmitted in the clear.

        uams_randnum.so:        Allow Random Number and Two-Way Random Number
                        exchange for authentication.

        uams_dhx.so: (uams_dhx_pam.so or uams_dhx_passwd.so)
                        Allow Diffie-Hellman eXchange (DHX) for authentication.

Password Options:
     -[no]savepassword  [Don't] Allow clients to save password locally
     -passwdfile <path> Use this path to store Randnum
                        passwords. (default: ~/.passwd. the only other
                        useful value is /etc/atalk/afppasswd.)
     -passwdminlen <#>  Minimum password length. may be ignored.
     -[no]setpassword           [Don't] Allow clients to change their passwords.
     -loginmaxfail <#>  Maximum number of failed logins. this may be
                        ignored if the uam can't handle it.

AppleVolumes files:
     -defaultvol <path> Specifies path to AppleVolumes.default file
                        (default /etc/atalk/AppleVolumes.default, same
                        as -f on command line)
     -systemvol <path>  Specifies path to AppleVolumes.system file
                        (default /etc/atalk/AppleVolumes.system, same
                        as -s on command line)
     -[no]uservolfirst  [Don't] read the user's ~/AppleVolumes or
                ~/.AppleVolumes before reading
                /etc/atalk/AppleVolumes.default (same as -u on
                        command line)
     -[no]uservol       [Don't] Read the user's volume file

     -nlspath <path>    Prepend this path to each code page filename in volume
                options (default: /etc/atalk/nls).

Miscellaneous:
     -guestname "user"  Specifies the user name for the guest login
                        (default "nobody", same as -g on command line)
     -loginmesg "Message"       Client will display "Message" upon logging in
                        (no default, same as -l "Message" on
                        command-line)
     -nodebug           Switch off debugging
     -tickleval <number>        Specify the tickle timeout interval (in seconds)
     -icon                      Use the platform-specific icon.

An example:
"Lance" -transall -uamlist uams_dhx.so -nosavepassword -setpassword
"Lance" is the server name, I enable both TCP and DDP,
all logins via DHX (requires AppleShare 3.8.6), the users cannot save
the password with keychains and it allows the users to set their
passwords.

With no afpd.conf the default is:

- -transall -uamlist uams_guest.so,uams_clrtxt.so,uams_dhx.so
-nosavepassword 

No server name, allow afp over tcp and afp over AppleTalk , allow
guest access, logins in clear text and DHX, don't allow the user to
save the password.

2. /etc/atalk/atalkd.conf
=========================

Classic Appletalk is configured in atalkd.conf. For detailed
information please reference 

http://www.neon.com/atalk_routing.html and
http://www-commeng.cso.uiuc.edu/docs/appletalk/

The whole point of seting up atalkd is to allow appletalk routing to
the localhost as a file and print server. The atalkd.conf file sets up
the appletalk routing by assigning Appletalk zone (or zones)
information to the networks it is attached to.

Within appletalk there are three different types of routers: seed,
nonseed and soft seed.

Seed publishes the network and zone information to the network. In the
case of a conflict, this router takes precedence. Nonseed acts as a
forwarder in that all network and zone information for it's network
segment is pulled from an upstream router. A soft seed router is
configured like a seed router, but will defer and use upstream seeded
zone information if there is a conflict.

Netatalk has the option to behave like a nonseed router or a soft seed
router. Netatalk will defer to an upstream seed if there is a
conflict. Any missing configurations will be filled from the network.

Appletalk phases are of two types. The unused, unsupported, obsolete
phase 1, or the new useful phase 2. 

Phase 1 was Apples original protocol for Appletalk over Ethernet. It
treated an entire network segment as one appletalk network capable of
holding 254 nodes. Don't use this. 

Phase 2 is the new version. It allows a configurable network range
between the numbers 1 and 65279, each network capable of hosting 253
nodes for a total of 16,515,587 Appletalk interfaces. That's a lot
of iMacs. :-)

Within an Appletalk network addressing is a Network:Node:Socket
triplet. The socket number is general dropped because nothing uses the
information. 

Using ethernet and phase 2 the network number can be singular, '1' or
a range, '1-20'. Node assignment is the responsibility of the clients so
you don't have to worry about it. The range of 65280-65534 is called
the startup range and is used by the Mac when it is on a network
without any routers, you probably shouldn't publish a network withing
this range. If you're publishing to a LocalTalk network segment
(Hello? Welcome to Y2K. :) your maximum network range is _one_
network.

Zone's must be less then 32 characters long.

Format of lines in this file:
        interface [ -seed ] [ -router | -dontroute ] 
        [ -phase { 1 | 2 } ] [ -addr net.node ]
        [ -net first[-last] ] [ -zone ZoneName ] ...

        interface: the interface that is publishing the appletalk server.  eth0

        -seed - requires two interfaces. The router is acting as a
        bridge between the two networks. A soft seed router.

        -router - only requires one interface.
        
        -dontroute - don't publish routing information
        
        -addr this machines network.node address.

Examples: 

eth0
 - Appletalk network is off eth0, no routing information
published, get it all off the network.

eth0 -router -phase 2 -addr 100.10 -net 100-110 -zone "Upstairs"
- Appletalk network is off eth0, this server is not a bridge, it
publishes zone information for Networks 100-110. The servers appletalk
node address is node 10 of network 100. This zone is called Upstairs.

eth0 -phase 2
eth1 -seed -phase 2 -addr 100.10 -net 100-110 -zone "Upstairs"
- This allows routing between the appletalk networks on eth0 and eth1,
for eth1 this server acts as a soft seed router of a phase 2 network
segment of 100-110 where this machine is 100.10

3. /etc/atalk/netatalk.conf
===========================

Set the options as appropriate:

AFPD_MAX_CLIENTS - Maximum number of concurrent clients.

ATALK_ZONE - Name of the zone. Should match the zone in afpd.conf, or use @zone.

ATALK_NAME - Name of the netatalk server.

AFPD_UAMLIST - List of uams available to the clients. Should match
list in afpd.conf "-U uam1, uam2" 

AFPD_GUEST - If guest access is enabled, the id of the afpd process
for the guest client.

ATALKD_RUN, PAPD_RUN, AFPD_RUN - Run these daemons, 'yes/no'.


4. /etc/atalk/papd.conf
=======================

To be written by someone who actully uses the print server. :)