doc/CONFIGURE

   1 Configuring Netatalk
   2 ====================
   3
   4 These files should have been copied into the configuration directory
   5 (default: /usr/local/etc)  by the `make install' in step 4 of
   6 the INSTALL file.
   7
   8
   9 Netatalk supplies two different types of AFP servers and both can run at
  10 the same time. Classic AFP over AppleTalk requires afpd and atalkd. AFP
  11 over IP only requires afpd.
  12
  13
  14
  15 1. /usr/local/etc/afpd.conf
  16 ===========================
  17
  18 Edit /usr/local/etc/afpd.conf as required. Some options:
  19
  20 Format:
  21 - [options]             to specify options for the default server
  22 and/or
  23  "Server name" [options]        to specify an additional server
  24
  25 The following options are available:
  26
  27 Transport Protocols:
  28      -[no]tcp   Make AFP-over-TCP [not] available
  29      -[no]ddp   Make AFP over AppleTalk [not] available. if you have
  30                 -proxy specified, specify -uamlist "" to prevent ddp
  31                 connections from working.
  32      -transall      Make both available (default)
  33
  34 Transport Options:
  35      -ipaddr <w.x.y.z>
  36                 Specifies the IP address the server should
  37                 respond to (default is the first IP address of the system).
  38                 This option also allows one machine to advertise TCP/IP for
  39                 another machine.
  40      -server_quantum <number>
  41                 Specifies the DSI server quantum. The minimum
  42                 value is 1MB. The max value is 0xFFFFFFFF. If you specify a
  43                 value that is out of range, you'll get the default value
  44                 (currently the minimum).
  45      -admingroup <groupname>
  46                          Specifies the group of administrators who should all
  47                          be seen as the superuser when they log in.  Default
  48                          is disabled.
  49      -ddpaddr x.y       Specifies the DDP address of the server. the default
  50                 is to auto-assign an address (0.0). this is only
  51                 useful if you're running on a multihomed host.
  52      -port <number>     Specifies the TCP port the server should
  53                 respond to (default is 548)
  54      -fqdn <name:port>  Specify a fully-qualified domain name
  55                         (+optional port). this gets discarded if the
  56                         server can't resolve it. this is not honored
  57                         by appleshare clients <= 3.8.3 (default: none)
  58      -proxy             Run an AppleTalk proxy server for specified AFP/TCP
  59                 server (if address/port aren't given, then first IP
  60                 address of the system/548 will be used). if you don't
  61                 want the proxy server to act as a ddp server as well,
  62                 set -uamlist to an empty string.
  63
  64 Authentication Methods:
  65      -uampath <path>    Use this path to look for User Authentication
  66                 Modules. (default: /etc/atalk/uams)
  67      -uamlist <a,b,c> Comma-separated list of UAMs. (default:
  68                 uams_guest.so,uams_clrtxt.so,uams_dhx.so)
  69
  70         Some Common UAMs
  71         uams_guest.so: Allow guest logins
  72
  73         uams_clrtxt.so: (uams_pam.so or uams_passwd.so)
  74                 Allow logins with passwords transmitted in the clear.
  75
  76         uams_randnum.so:        Allow Random Number and Two-Way Random Number
  77                         exchange for authentication.
  78
  79         uams_dhx.so: (uams_dhx_pam.so or uams_dhx_passwd.so)
  80                         Allow Diffie-Hellman eXchange (DHX) for authentication.
  81
  82 Password Options:
  83      -[no]savepassword  [Don't] Allow clients to save password locally
  84      -passwdfile <path> Use this path to store Randnum
  85                         passwords. (default: ~/.passwd. the only other
  86                         useful value is /etc/atalk/afppasswd.)
  87      -passwdminlen <#>  Minimum password length. may be ignored.
  88      -[no]setpassword           [Don't] Allow clients to change their passwords.
  89      -loginmaxfail <#>  Maximum number of failed logins. this may be
  90                         ignored if the uam can't handle it.
  91
  92 AppleVolumes files:
  93      -defaultvol <path> Specifies path to AppleVolumes.default file
  94                         (default /etc/atalk/AppleVolumes.default, same
  95                         as -f on command line)
  96      -systemvol <path>  Specifies path to AppleVolumes.system file
  97                         (default /etc/atalk/AppleVolumes.system, same
  98                         as -s on command line)
  99      -[no]uservolfirst  [Don't] read the user's ~/AppleVolumes or
 100                 ~/.AppleVolumes before reading
 101                 /etc/atalk/AppleVolumes.default (same as -u on
 102                         command line)
 103      -[no]uservol       [Don't] Read the user's volume file
 104
 105      -nlspath <path>    Prepend this path to each code page filename in volume
 106                 options (default: /etc/atalk/nls).
 107
 108 Miscellaneous:
 109      -guestname "user"  Specifies the user name for the guest login
 110                         (default "nobody", same as -g on command line)
 111      -loginmesg "Message"       Client will display "Message" upon logging in
 112                         (no default, same as -l "Message" on
 113                         command-line)
 114      -nodebug           Switch off debugging
 115      -client_polling    Disable server notifications.  This forces the
 116                         clients to poll every 10 seconds for directory updates.  Note,
 117                         currently this is the only way to get asynchronous updates.
 118      -ticklevel <number>        Specify the tickle timeout interval (in seconds)
 119      -timeout <number>          Specify the number of tickles to miss before tearing
 120                         down a client connection
 121      -icon                      Use the platform-specific icon.
 122
 123 An example:
 124 "Lance" -transall -uamlist uams_dhx.so -nosavepassword -setpassword
 125 "Lance" is the server name, I enable both TCP and DDP, all logins via DHX
 126 (requires AppleShare Client 3.8.6), the users cannot save the password
 127 with keychains and it allows the users to set their passwords.
 128
 129 With no afpd.conf the default is:
 130
 131 - -transall -uamlist uams_guest.so,uams_clrtxt.so,uams_dhx.so
 132 -nosavepassword
 133
 134 No server name, allow afp over tcp and afp over AppleTalk , allow
 135 guest access, logins in clear text and DHX, don't allow the user to
 136 save the password.
 137
 138 Try   man afpd  and  man afpd.conf  for further details.
 139
 140
 141 2. /usr/local/etc/atalkd.conf
 142 =============================
 143
 144 The AppleTalk protocol is configured in atalkd.conf. For detailed
 145 information please reference
 146
 147 http://www.neon.com/atalk_routing.html and
 148 http://www-commeng.cso.uiuc.edu/docs/appletalk/
 149
 150 The whole point of setting up atalkd is to allow AppleTalk routing to
 151 the localhost as a file and print server. The atalkd.conf file sets up
 152 the AppleTalk routing by assigning AppleTalk zone (or zones)
 153 information to the networks it is attached to.
 154
 155 Within AppleTalk there are three different types of routers: seed,
 156 nonseed and soft seed.
 157
 158 Seed publishes the network and zone information to the network. In the
 159 case of a conflict, this router takes precedence. Nonseed acts as a
 160 forwarder in that all network and zone information for its network
 161 segment is pulled from an upstream router. A soft seed router is
 162 configured like a seed router, but will defer and use upstream seeded
 163 zone information if there is a conflict.
 164
 165 Netatalk has the option to behave like a nonseed router or a soft seed
 166 router. Netatalk will defer to an upstream seed if there is a
 167 conflict. Any missing configurations will be filled from the network.
 168
 169 Appletalk phases are of two types. The unused, unsupported, obsolete
 170 phase 1, or the new useful phase 2.
 171
 172 Phase 1 was Apple's original protocol for Appletalk over LocalTalk. It
 173 treated an entire network segment as one AppleTalk network capable of
 174 holding 254 nodes. Don't use this unless you are directly connected to a
 175 LocalTalk network (unlikely these days).
 176
 177 Phase 2 is the new version. It allows a configurable network range
 178 between the numbers 1 and 65279, each network capable of hosting 253
 179 nodes for a total of 16,515,587 AppleTalk interfaces. That's a lot
 180 of iMacs. :-)
 181
 182 Within an AppleTalk network addressing is a Network:Node:Socket
 183 triplet. The socket number is generally dropped because nothing uses the
 184 information.
 185
 186 Using ethernet and phase 2 the network number can be singular, '1' or
 187 a range, '1-20'. Node assignment is the responsibility of the clients so
 188 you don't have to worry about it. The range of 65280-65534 is called
 189 the startup range and is used by the Mac when it is on a network
 190 without any routers, you probably shouldn't publish a network within
 191 this range. If you're publishing to a LocalTalk network segment
 192 (Hello? Welcome to Y2K. :) your maximum network range is _one_
 193 network.
 194
 195 Zones must be less then 32 characters long.
 196
 197 Format of lines in this file:
 198         interface [ -seed ] [ -router | -dontroute ]
 199         [ -phase { 1 | 2 } ] [ -addr net.node ]
 200         [ -net first[-last] ] [ -zone ZoneName ] ...
 201
 202         interface: the interface that is publishing the appletalk server.  eth0
 203
 204         -seed - requires two interfaces. The router is acting as a
 205         bridge between the two networks. A soft seed router.
 206
 207         -router - only requires one interface.
 208
 209         -dontroute - don't publish routing information
 210
 211         -addr this machines network.node address.
 212
 213 Examples:
 214
 215 eth0
 216  - Appletalk network is off eth0, no routing information
 217 published, get it all off the network.
 218
 219 eth0 -router -phase 2 -addr 100.10 -net 100-110 -zone "Upstairs"
 220 - Appletalk network is off eth0, this server is not a bridge, it
 221 publishes zone information for Networks 100-110. The servers appletalk
 222 node address is node 10 of network 100. This zone is called Upstairs.
 223
 224 eth0 -phase 2
 225 eth1 -seed -phase 2 -addr 100.10 -net 100-110 -zone "Upstairs"
 226 - This allows routing between the appletalk networks on eth0 and eth1,
 227 for eth1 this server acts as a soft seed router of a phase 2 network
 228 segment of 100-110 where this machine is 100.10
 229
 230 Try   man atalkd  and  man atalkd.conf  for further details.
 231
 232
 233 3. /usr/local/etc/netatalk.conf
 234 ===============================
 235
 236 Set the options as appropriate:
 237
 238 AFPD_MAX_CLIENTS - Maximum number of concurrent clients.
 239
 240 ATALK_ZONE - Name of the zone. Should match the zone in afpd.conf, or use @zone.
 241
 242 ATALK_NAME - Name of the netatalk server.
 243
 244 AFPD_UAMLIST - List of uams available to the clients. Should match
 245 list in afpd.conf "-U uam1, uam2"
 246
 247 AFPD_GUEST - If guest access is enabled, the id of the afpd process
 248 for the guest client.
 249
 250 ATALKD_RUN, PAPD_RUN, AFPD_RUN - Run these daemons, 'yes/no'.
 251
 252
 253 4. /usr/local/etc/papd.conf     for the Printer Access Protocol (PAP) daemon.
 254 ===========================
 255
 256 See the config/papd.conf file for some examples.
 257 A configuration file that works under Solaris 8 is:
 258 MacLaserJet:\
 259         :pr=|/usr/bin/lp -d fred:\
 260         :op=nobody:\
 261         :pd=/usr/local/etc/HPLJ46_1.PPD:
 262
 263 where
 264   MacLaserJet is some name you have chosen by which Macintoshes will
 265      refer to the printer. This is the name that appears in the Chooser.
 266   pr gives the printer name on the Unix system ('fred' in this example).
 267      On some operating systems you can just specify something like :pr=fred:
 268      while on others (including Solaris) it is necessary to pipe the print
 269      command into lp or lpr as shown above.
 270   op gives the operator name for LPD spooling
 271   pd gives the pathname to the PostScript Printer Description (PPD) file.
 272      PPD files are available from Adobe Inc,  via anonymous ftp
 273      (ftp://ftp.adobe.com//pub/adobe/printerdrivers/mac/all/ppdfiles
 274                or        //pub/adobe/printerdrivers/win/all/ppdfiles)
 275      or http://download.sourceforge.net/lpr/hp-ppd-0.2.tar.gz
 276      or from the printer's manufacturer.
 277
 278 Try   man papd  and  man papd.conf  for further options.