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      -ticklevel <number>        Specify the tickle timeout interval (in seconds)
 116      -icon                      Use the platform-specific icon.
 117
 118 An example:
 119 "Lance" -transall -uamlist uams_dhx.so -nosavepassword -setpassword
 120 "Lance" is the server name, I enable both TCP and DDP, all logins via DHX
 121 (requires AppleShare Client 3.8.6), the users cannot save the password
 122 with keychains and it allows the users to set their passwords.
 123
 124 With no afpd.conf the default is:
 125
 126 - -transall -uamlist uams_guest.so,uams_clrtxt.so,uams_dhx.so
 127 -nosavepassword
 128
 129 No server name, allow afp over tcp and afp over AppleTalk , allow
 130 guest access, logins in clear text and DHX, don't allow the user to
 131 save the password.
 132
 133 Try   man afpd  and  man afpd.conf  for further details.
 134
 135
 136 2. /usr/local/etc/atalkd.conf
 137 =============================
 138
 139 The AppleTalk protocol is configured in atalkd.conf. For detailed
 140 information please reference
 141
 142 http://www.neon.com/atalk_routing.html and
 143 http://www-commeng.cso.uiuc.edu/docs/appletalk/
 144
 145 The whole point of setting up atalkd is to allow AppleTalk routing to
 146 the localhost as a file and print server. The atalkd.conf file sets up
 147 the AppleTalk routing by assigning AppleTalk zone (or zones)
 148 information to the networks it is attached to.
 149
 150 Within AppleTalk there are three different types of routers: seed,
 151 nonseed and soft seed.
 152
 153 Seed publishes the network and zone information to the network. In the
 154 case of a conflict, this router takes precedence. Nonseed acts as a
 155 forwarder in that all network and zone information for its network
 156 segment is pulled from an upstream router. A soft seed router is
 157 configured like a seed router, but will defer and use upstream seeded
 158 zone information if there is a conflict.
 159
 160 Netatalk has the option to behave like a nonseed router or a soft seed
 161 router. Netatalk will defer to an upstream seed if there is a
 162 conflict. Any missing configurations will be filled from the network.
 163
 164 Appletalk phases are of two types. The unused, unsupported, obsolete
 165 phase 1, or the new useful phase 2.
 166
 167 Phase 1 was Apple's original protocol for Appletalk over LocalTalk. It
 168 treated an entire network segment as one AppleTalk network capable of
 169 holding 254 nodes. Don't use this unless you are directly connected to a
 170 LocalTalk network (unlikely these days).
 171
 172 Phase 2 is the new version. It allows a configurable network range
 173 between the numbers 1 and 65279, each network capable of hosting 253
 174 nodes for a total of 16,515,587 AppleTalk interfaces. That's a lot
 175 of iMacs. :-)
 176
 177 Within an AppleTalk network addressing is a Network:Node:Socket
 178 triplet. The socket number is generally dropped because nothing uses the
 179 information.
 180
 181 Using ethernet and phase 2 the network number can be singular, '1' or
 182 a range, '1-20'. Node assignment is the responsibility of the clients so
 183 you don't have to worry about it. The range of 65280-65534 is called
 184 the startup range and is used by the Mac when it is on a network
 185 without any routers, you probably shouldn't publish a network within
 186 this range. If you're publishing to a LocalTalk network segment
 187 (Hello? Welcome to Y2K. :) your maximum network range is _one_
 188 network.
 189
 190 Zones must be less then 32 characters long.
 191
 192 Format of lines in this file:
 193         interface [ -seed ] [ -router | -dontroute ]
 194         [ -phase { 1 | 2 } ] [ -addr net.node ]
 195         [ -net first[-last] ] [ -zone ZoneName ] ...
 196
 197         interface: the interface that is publishing the appletalk server.  eth0
 198
 199         -seed - requires two interfaces. The router is acting as a
 200         bridge between the two networks. A soft seed router.
 201
 202         -router - only requires one interface.
 203
 204         -dontroute - don't publish routing information
 205
 206         -addr this machines network.node address.
 207
 208 Examples:
 209
 210 eth0
 211  - Appletalk network is off eth0, no routing information
 212 published, get it all off the network.
 213
 214 eth0 -router -phase 2 -addr 100.10 -net 100-110 -zone "Upstairs"
 215 - Appletalk network is off eth0, this server is not a bridge, it
 216 publishes zone information for Networks 100-110. The servers appletalk
 217 node address is node 10 of network 100. This zone is called Upstairs.
 218
 219 eth0 -phase 2
 220 eth1 -seed -phase 2 -addr 100.10 -net 100-110 -zone "Upstairs"
 221 - This allows routing between the appletalk networks on eth0 and eth1,
 222 for eth1 this server acts as a soft seed router of a phase 2 network
 223 segment of 100-110 where this machine is 100.10
 224
 225 Try   man atalkd  and  man atalkd.conf  for further details.
 226
 227
 228 3. /usr/local/etc/netatalk.conf
 229 ===============================
 230
 231 Set the options as appropriate:
 232
 233 AFPD_MAX_CLIENTS - Maximum number of concurrent clients.
 234
 235 ATALK_ZONE - Name of the zone. Should match the zone in afpd.conf, or use @zone.
 236
 237 ATALK_NAME - Name of the netatalk server.
 238
 239 AFPD_UAMLIST - List of uams available to the clients. Should match
 240 list in afpd.conf "-U uam1, uam2"
 241
 242 AFPD_GUEST - If guest access is enabled, the id of the afpd process
 243 for the guest client.
 244
 245 ATALKD_RUN, PAPD_RUN, AFPD_RUN - Run these daemons, 'yes/no'.
 246
 247
 248 4. /usr/local/etc/papd.conf     for the Printer Access Protocol (PAP) daemon.
 249 ===========================
 250
 251 See the config/papd.conf file for some examples.
 252 A configuration file that works under Solaris 8 is:
 253 MacLaserJet:\
 254         :pr=|/usr/bin/lp -d fred:\
 255         :op=nobody:\
 256         :pd=/usr/local/etc/HPLJ46_1.PPD:
 257
 258 where
 259   MacLaserJet is some name you have chosen by which Macintoshes will
 260      refer to the printer. This is the name that appears in the Chooser.
 261   pr gives the printer name on the Unix system ('fred' in this example).
 262      On some operating systems you can just specify something like :pr=fred:
 263      while on others (including Solaris) it is necessary to pipe the print
 264      command into lp or lpr as shown above.
 265   op gives the operator name for LPD spooling
 266   pd gives the pathname to the PostScript Printer Description (PPD) file.
 267      PPD files are available from Adobe Inc,  via anonymous ftp
 268      (ftp://ftp.adobe.com//pub/adobe/printerdrivers/mac/all/ppdfiles
 269                or        //pub/adobe/printerdrivers/win/all/ppdfiles)
 270      or http://download.sourceforge.net/lpr/hp-ppd-0.2.tar.gz
 271      or from the printer's manufacturer.
 272
 273 Try   man papd  and  man papd.conf  for further options.