doc/INSTALL.txt

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