doc/INSTALL.txt

   1 Installation and Configuration of Netatalk 1.5
   2 Lance Levsen, l.levsen@printwest.com
   3 V0.2, 02 March 2001
   4
   5
   6 Prerequisites
   7 =============
   8
   9 1. Libtool (only needed by developers)
  10 Libtool encapsulates the platform specific dependencies for the
  11 creation of libraries. It determines if the local platform can support
  12 shared libraries or if it only supports static libraries.
  13
  14 Documentation: http://www.gnu.org/software/libtool/
  15 Program: (see the GNU mirrors) /gnu/libtool/libtool-1.3.5.tar.gz
  16
  17 2. GNU m4 (only needed by developers)
  18 GNU m4 is an implementation of the Unix macro processor. It reads
  19 stdin and copies to stdout expanding defined macros as it processes
  20 the text.
  21
  22 Documentation: http://www.gnu.org/software/m4/
  23 Program: (see the GNU mirrors) /gnu/m4/m4-1.4.tar.gz
  24
  25 3. Autoconf
  26 Autoconf is a package of m4 macros that produce shell scripts to
  27 configure source code packages.
  28
  29 Documentation: http://www.gnu.org/software/autoconf/
  30 Program: (see the GNU mirrors) /gnu/autoconf/autoconf-2.13.tar.gz
  31
  32 4. Automake
  33 Automake is a tool that generates  'Makefile.in' files.
  34
  35 Documentation: http://www.gnu.org/software/automake/
  36 Program: (see the GNU mirrors) /gnu/automake/automake-1.4.tar.gz
  37
  38 Optional
  39 ========
  40 5. OpenSSL
  41 The OpenSSL Project is a collaborative effort to develop a robust,
  42 commercial-grade, full-featured, and Open Source toolkit implementing
  43 the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS
  44 v1) protocols as well as a full-strength general purpose cryptography
  45 library.
  46 This is required to enable DHX login support.
  47
  48 Get everything at http://www.openssl.org/
  49
  50 6. TCP Wrappers
  51 Wietse Venema's network logger, also known as TCPD or LOG_TCP. These
  52 programs log the client host name of incoming telnet, ftp, rsh,
  53 rlogin, finger etc. requests. Security options are: access control per
  54 host, domain and/or service; detection of host name spoofing or host
  55 address spoofing; booby traps to implement an early-warning system.
  56
  57 TCP Wrappers can be gotten at ftp://ftp.porcupine.org/pub/security/
  58
  59 7. PAM (Pluggable Authentication Modules for Linux)
  60 Linux-PAM is a suite of shared libraries that enable the local system
  61 administrator to choose how applications authenticate users.
  62
  63 You can get the Linux PAM documentation and sources from
  64 http://www.kernel.org/pub/linux/libs/pam/
  65
  66
  67 Installing Netatalk
  68 ===================
  69
  70 1. Read the configure options.
  71 $> ./configure --help
  72
  73 This prints a listing of the command line options for configure to
  74 use. Notables are:
  75
  76 --disable-admin-group: disable admin group (default on),
  77
  78 --disable-ddp: disable DDP support,
  79
  80 --enable-dropkludge: enable the experimental dropbox fix (INSECURE!)
  81
  82  --with-pam: enable password authentication modules support,
  83
  84 --with-shadow: enable shadow password support,
  85
  86 --with-tcp-wrappers: enable TCP wrappers support
  87
  88 --with-ssl-dirs=[PATH]: specify path to OpenSSL installation.
  89 NOTE: This is dependent on the same directory layout as the source
  90 distribution of Openssl. That is: ./include/ and ./lib/ to be on the
  91 same level. Many .rpm formats do not have their files laid out in this
  92 format.
  93
  94 --enable-lastdid: Recreate version 37b behaviour where directory id's
  95 are incrementally calculated versus the new hash method. Unfortunately
  96 for machines that have a lot of devices, and/or a lot of inodes the
  97 hash can fail with multiple directories resolving to the same DID.
  98
  99 Enable/Disable the desired options like this:
 100 $>./configure --option1 --option2 ....
 101
 102 2. Assuming ./configure worked well,
 103 $> make  (as root or sudo)
 104
 105 3. Assuming the program compiled without errors,
 106 $> make install  (as root or sudo)
 107
 108 Assuming you haven't changed the install directories, this will
 109 install the configutation files in /etc/atalk. The uams in
 110 /etc/atalk/uams. The binaries will be in /usr/sbin/.
 111
 112 4. Configure Netatalk (See below 'Configuring Netatalk')
 113 The default location for the configuration files is /etc/atalk/.
 114
 115 5. Setup your rc script so that Netatalk is started on boot.
 116 You can find sample initscripts in ./distrib/initscripts/ from the
 117 source directory.
 118
 119 6. If you enabled PAM, then copy the ./config/netatalk PAM file to
 120 /etc/pam.d/ or where ever your system puts the PAM configuration
 121 files.
 122
 123
 124 Configuring Netatalk
 125 ====================
 126
 127 Netatalk supplies two different types of Appletalk servers and both
 128 can run at the same time. Classic Appletalk requires afpd and
 129 atalkd. Appletalk over IP only requires afpd. Classic Appletalk on
 130 GNU/LInux requires that CONFIG_ATALK is compiled into the kernel or as
 131 a kernel module. To check to see if the kernel has Appletalk
 132 installed:
 133
 134 $> dmesg | grep Apple
 135 This just parses the boot messages for any line containing
 136 'Apple'.
 137
 138 To see all the  loaded modules (as root):
 139 $> lsmod
 140
 141 If you don't find it, you may have to compile a kernel and turn on
 142 Appletalk in Networking options -> Appletalk DDP. You have an option
 143 to install as a module or directly into the kernel.
 144
 145 Some default distribution kernels have already compiled Appletalk DDP
 146 as a module, you may have to edit your /etc/modules.conf to include:
 147 "alias net-pf-5 appletalk ".
 148
 149 Note: check your distribution documentation about editing
 150 /etc/modules.conf.
 151
 152 For more complete information about the Linux kernel see the
 153 Kernel-HOWTO:
 154 http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html
 155
 156
 157 1. /etc/atalk/afpd.conf
 158 Edit /etc/atalk/afpd.conf as required. Some options:
 159
 160 Format:
 161 - [options]             to specify options for the default server
 162 and/or
 163  "Server name" [options]        to specify an additional server
 164
 165 The following options are available:
 166
 167 Transport Protocols:
 168      -[no]tcp   Make AFP-over-TCP [not] available
 169      -[no]ddp   Make AFP over AppleTalk [not] available. if you have
 170                 -proxy specified, specify -uamlist "" to prevent ddp
 171                 connections from working.
 172      -transall      Make both available (default)
 173
 174 Transport Options:
 175      -ipaddr <w.x.y.z>
 176                 Specifies the IP address the server should
 177                 respond to (default is the first IP address of the system). This
 178                 option also allows one machine to advertise TCP/IP for another machine.
 179      -server_quantum <number>
 180                 Specifies the DSI server quantum. The minimum
 181                 value is 1MB. The max value is 0xFFFFFFFF. If you specify a value that
 182                 is out of range, you'll get the default value (currently the
 183                 minimum).
 184      -admingroup <groupname>
 185                          Specifies the group of administrators who should all
 186                          be seen as the superuser when they log in.  Default
 187                          is disabled.
 188      -ddpaddr x.y       Specifies the DDP address of the server. the default
 189                 is to auto-assign an address (0.0). this is only
 190                 useful if you're running on a multihomed host.
 191      -port <number>     Specifies the TCP port the server should
 192                 respond to (default is 548)
 193      -fqdn <name:port>  Specify a fully-qualified domain name
 194                         (+optional port). this gets discarded if the
 195                         server can't resolve it. this is not honored
 196                         by appleshare clients <= 3.8.3 (default: none)
 197      -proxy             Run an AppleTalk proxy server for specified AFP/TCP
 198                 server (if address/port aren't given, then first IP
 199                 address of the system/548 will be used). if you don't
 200                 want the proxy server to act as a ddp server as well,
 201                 set -uamlist to an empty string.
 202
 203 Authentication Methods:
 204      -uampath <path>    Use this path to look for User Authentication
 205                 Modules. (default: /etc/atalk/uams)
 206      -uamlist <a,b,c> Comma-separated list of UAMs. (default:
 207                 uams_guest.so,uams_clrtxt.so,uams_dhx.so)
 208
 209         Some Common UAMs
 210         uams_guest.so: Allow guest logins
 211
 212         uams_clrtxt.so: (uams_pam.so or uams_passwd.so)
 213                 Allow logins with passwords transmitted in the clear.
 214
 215         uams_randnum.so:        Allow Random Number and Two-Way Random Number
 216                         exchange for authentication.
 217
 218         uams_dhx.so: (uams_dhx_pam.so or uams_dhx_passwd.so)
 219                         Allow Diffie-Hellman eXchange (DHX) for authentication.
 220
 221 Password Options:
 222      -[no]savepassword  [Don't] Allow clients to save password locally
 223      -passwdfile <path> Use this path to store Randnum
 224                         passwords. (default: ~/.passwd. the only other
 225                         useful value is /etc/atalk/afppasswd.)
 226      -passwdminlen <#>  Minimum password length. may be ignored.
 227      -[no]setpassword           [Don't] Allow clients to change their passwords.
 228      -loginmaxfail <#>  Maximum number of failed logins. this may be
 229                         ignored if the uam can't handle it.
 230
 231 AppleVolumes files:
 232      -defaultvol <path> Specifies path to AppleVolumes.default file
 233                         (default /etc/atalk/AppleVolumes.default, same
 234                         as -f on command line)
 235      -systemvol <path>  Specifies path to AppleVolumes.system file
 236                         (default /etc/atalk/AppleVolumes.system, same
 237                         as -s on command line)
 238      -[no]uservolfirst  [Don't] read the user's ~/AppleVolumes or
 239                 ~/.AppleVolumes before reading
 240                 /etc/atalk/AppleVolumes.default (same as -u on
 241                         command line)
 242      -[no]uservol       [Don't] Read the user's volume file
 243
 244      -nlspath <path>    Prepend this path to each code page filename in volume
 245                 options (default: /etc/atalk/nls).
 246
 247 Miscellaneous:
 248      -guestname "user"  Specifies the user name for the guest login
 249                         (default "nobody", same as -g on command line)
 250      -loginmesg "Message"       Client will display "Message" upon logging in
 251                         (no default, same as -l "Message" on
 252                         command-line)
 253      -nodebug           Switch off debugging
 254      -tickleval <number>        Specify the tickle timeout interval (in seconds)
 255      -icon                      Use the platform-specific icon.
 256
 257 An example:
 258 "Lance" -transall -uamlist uams_dhx.so -nosavepassword -setpassword
 259 "Lance" is the server name, I enable both TCP and DDP,
 260 all logins via DHX (requires AppleShare 3.8.6), the users cannot save
 261 the password with keychains and it allows the users to set their
 262 passwords.
 263
 264 With no afpd.conf the default is:
 265
 266 - -transall -uamlist uams_guest.so,uams_clrtxt.so,uams_dhx.so
 267 -nosavepassword
 268
 269 No server name, allow afp over tcp and afp over AppleTalk , allow
 270 guest access, logins in clear text and DHX, don't allow the user to
 271 save the password.
 272
 273 2. /etc/atalk/atalkd.conf
 274
 275 Classic Appletalk is configured in atalkd.conf. For detailed
 276 information please reference
 277
 278 http://www.neon.com/atalk_routing.html and
 279 http://www-commeng.cso.uiuc.edu/docs/appletalk/
 280
 281 The whole point of seting up atalkd is to allow appletalk routing to
 282 the localhost as a file and print server. The atalkd.conf file sets up
 283 the appletalk routing by assigning Appletalk zone (or zones)
 284 information to the networks it is attached to.
 285
 286 Within appletalk there are three different types of routers: seed,
 287 nonseed and soft seed.
 288
 289 Seed publishes the network and zone information to the network. In the
 290 case of a conflict, this router takes precedence. Nonseed acts as a
 291 forwarder in that all network and zone information for it's network
 292 segment is pulled from an upstream router. A soft seed router is
 293 configured like a seed router, but will defer and use upstream seeded
 294 zone information if there is a conflict.
 295
 296 Netatalk has the option to behave like a nonseed router or a soft seed
 297 router. Netatalk will defer to an upstream seed if there is a
 298 conflict. Any missing configurations will be filled from the network.
 299
 300 Appletalk phases are of two types. The unused, unsupported, obsolete
 301 phase 1, or the new useful phase 2.
 302
 303 Phase 1 was Apples original protocol for Appletalk over Ethernet. It
 304 treated an entire network segment as one appletalk network capable of
 305 holding 254 nodes. Don't use this.
 306
 307 Phase 2 is the new version. It allows a configurable network range
 308 between the numbers 1 and 65279, each network capable of hosting 253
 309 nodes for a total of 16,515,587 Appletalk interfaces. That's a lot
 310 of iMacs. :-)
 311
 312 Within an Appletalk network addressing is a Network:Node:Socket
 313 triplet. The socket number is general dropped because nothing uses the
 314 information.
 315
 316 Using ethernet and phase 2 the network number can be singular, '1' or
 317 a range, '1-20'. Node assignment is the responsibility of the clients so
 318 you don't have to worry about it. The range of 65280-65534 is called
 319 the startup range and is used by the Mac when it is on a network
 320 without any routers, you probably shouldn't publish a network withing
 321 this range. If you're publishing to a LocalTalk network segment
 322 (Hello? Welcome to Y2K. :) your maximum network range is _one_
 323 network.
 324
 325 Zone's must be less then 32 characters long.
 326
 327 Format of lines in this file:
 328         interface [ -seed ] [ -router | -dontroute ]
 329         [ -phase { 1 | 2 } ] [ -addr net.node ]
 330         [ -net first[-last] ] [ -zone ZoneName ] ...
 331
 332         interface: the interface that is publishing the appletalk server.  eth0
 333
 334         -seed - requires two interfaces. The router is acting as a
 335         bridge between the two networks. A soft seed router.
 336
 337         -router - only requires one interface.
 338
 339         -dontroute - don't publish routing information
 340
 341         -addr this machines network.node address.
 342
 343 Examples:
 344
 345 eth0
 346  - Appletalk network is off eth0, no routing information
 347 published, get it all off the network.
 348
 349 eth0 -router -phase 2 -addr 100.10 -net 100-110 -zone "Upstairs"
 350 - Appletalk network is off eth0, this server is not a bridge, it
 351 publishes zone information for Networks 100-110. The servers appletalk
 352 node address is node 10 of network 100. This zone is called Upstairs.
 353
 354 eth0 -phase 2
 355 eth1 -seed -phase 2 -addr 100.10 -net 100-110 -zone "Upstairs"
 356 - This allows routing between the appletalk networks on eth0 and eth1,
 357 for eth1 this server acts as a soft seed router of a phase 2 network
 358 segment of 100-110 where this machine is 100.10
 359
 360 3. /etc/atalk/papd.conf
 361
 362 To be written by someone who actully uses the print server. :)
 363
 364 4. /etc/atalk/netatalk.conf
 365
 366 To be written.
 367